Struct SizeHint 

pub struct SizeHint {
    pub lower: usize,
    pub upper: Option<usize>,
}

A size hint for an iterator.

This is an immutable wrapper around the standard iterator size hint tuple (usize, Option<usize>), providing strong gurantees about the bound values (ie. lower <= upper), and additional functionality and conversions.

A size hint describes the range of possible values for the length of an iterator, that is, the number of elements that it will return when enumerated to exhaustion from its current state. While this count does not have to be exact (unless the size hint describes an exact bounds, one where the upper and lower bounds are equal) it is an error for the iterator to then produce a number of elements that violates the bounds established by the hint.

A size hint can never describe an empty range, as 0 is always a valid number of elements remaining for an iterator.

Fields

lower: usize

The inclusive lower bound of the size hint.

upper: Option<usize>

The inclusive upper bound of the size hint, or None if the upper bound is unbounded.

Implementations

impl SizeHint

pub const UNIVERSAL: Self

A size hint that is always valid, never changes, and conveys no information.

pub const ZERO: Self

A size hint that indicates that the iterator will yield no elements.

pub const fn new(lower: usize, upper: Option<usize>) -> Self

Creates a new size hint with the given lower and optional upper bounds.

Panics

Panics if the upper bound is present and less than the lower bound.

Examples

let hint = SizeHint::new(5, Some(10));
assert_eq!(hint.lower, 5);
assert_eq!(hint.upper, Some(10));

pub const fn try_new( lower: usize, upper: Option<usize>, ) -> Result<Self, InvalidSizeHint>

Tries to create a new size hint with the given lower and optional upper bounds.

Errors

Returns InvalidSizeHint if the upper bound is present and less than the lower bound.

Examples

let hint = SizeHint::try_new(5, Some(10))?;
assert_eq!(hint.lower, 5);
assert_eq!(hint.upper, Some(10));

let err: InvalidSizeHint = SizeHint::try_new(10, Some(5)).expect_err("Lower bound is greater than upper bound");

pub const fn bounded(lower: usize, upper: usize) -> Self

Creates a new size hint with the given lower and optional upper bounds.

Panics

Panics if lower is greater than upper.

Examples

let hint = SizeHint::bounded(5, 10);
assert_eq!(hint.lower, 5);
assert_eq!(hint.upper, Some(10));

pub const fn try_bounded( lower: usize, upper: usize, ) -> Result<Self, InvalidSizeHint>

Tries to create a new bounded SizeHint with the given lower and upper bounds.

Errors

Returns InvalidSizeHint if lower is greater than upper.

Examples

let hint = SizeHint::try_bounded(5, 10)?;
assert_eq!(hint.lower, 5);
assert_eq!(hint.upper, Some(10));

let err: InvalidSizeHint = SizeHint::try_bounded(10, 5).expect_err("SizeHint should be invalid");

pub const fn unbounded(lower: usize) -> Self

Creates a new size hint with the given lower bound and no upper bound.

let hint = SizeHint::unbounded(5);
assert_eq!(hint.lower, 5);
assert_eq!(hint.upper, None);

pub const fn exact(len: usize) -> Self

Creates a new size hint with an exact count.

let hint = SizeHint::exact(5);
assert_eq!(hint.lower, 5);
assert_eq!(hint.upper, Some(5));

pub const fn at_most(upper: usize) -> Self

Creates a new size hint with the given upper bound and a lower bound of 0.

A common use case for this is Filter.

let hint = SizeHint::at_most(5);
assert_eq!(hint.lower, 0);
assert_eq!(hint.upper, Some(5));

pub const fn lower(self) -> usize

Returns the inclusive lower bound of the size hint.

Examples

let hint = SizeHint::new(5, Some(10));
assert_eq!(hint.lower(), 5);

pub const fn upper(self) -> Option<usize>

Returns the optional inclusive upper bound of the size hint.

Examples

let hint = SizeHint::new(5, Some(10));
assert_eq!(hint.upper(), Some(10));

pub const fn as_hint(self) -> (usize, Option<usize>)

Returns the size hint as a tuple (lower, upper).

Examples

let hint = SizeHint::new(5, Some(10));
assert_eq!(hint.as_hint(), (5, Some(10)));

pub fn decrement(self) -> Self

Returns a new SizeHint with the lower and upper bounds (if present) decremented by 1.

This is useful for decrementing the size hint of an iterator after it has been advanced.

Examples

let hint = SizeHint::bounded(5, 10);
assert_eq!(hint.decrement(), SizeHint::bounded(4, 9));

pub const fn overlaps(self, other: Self) -> bool

Returns true if this size hint range overlaps with another size hint range.

Two ranges overlap if there exists at least one value that could be contained in both. This operation is the negation of Self::disjoint, and is also commutative.

Examples

assert!(SizeHint::overlaps(SizeHint::bounded(3, 6), SizeHint::bounded(5, 10)), "should overlap at 5 and 6");
assert!(SizeHint::overlaps(SizeHint::exact(5), SizeHint::UNIVERSAL), "Universal should overlap with any size hint");
assert!(!SizeHint::overlaps(SizeHint::unbounded(11), SizeHint::exact(5)), "should not overlap");
assert!(SizeHint::overlaps(SizeHint::unbounded(11), SizeHint::UNIVERSAL), "two unbounded hints should overlap");

pub const fn disjoint(self, other: Self) -> bool

Returns true if this size hint range is disjoint with another range.

Two ranges are disjoint if there exists no value that could be contained in both. This operation is the negation of Self::overlaps, and is also commutative.

Examples

assert!(SizeHint::disjoint(SizeHint::exact(5), SizeHint::unbounded(10)), "should be disjoint");
assert!(SizeHint::disjoint(SizeHint::exact(5), SizeHint::bounded(6, 10)), "should be disjoint");
assert!(!SizeHint::disjoint(SizeHint::unbounded(11), SizeHint::UNIVERSAL), "two unbounded hints should never be disjoint");

pub const fn subset_of(self, other: Self) -> bool

Returns true if this size hint range is completely contained within another range.

This operation is not commutative, i.e. a.subset_of(b) does not imply b.subset_of(a).

Examples

assert!(SizeHint::bounded(4, 6).subset_of(SizeHint::bounded(4, 6)), "should be a subset (equal ranges)");
assert!(SizeHint::bounded(4, 6).subset_of(SizeHint::bounded(3, 9)), "should be a subset");
assert!(!SizeHint::bounded(3, 9).subset_of(SizeHint::bounded(4, 6)), "should not be a subset (not commutative)");
assert!(!SizeHint::bounded(2, 6).subset_of(SizeHint::bounded(3, 6)), "should not be a subset (lower bound)");
assert!(!SizeHint::bounded(4, 7).subset_of(SizeHint::bounded(3, 6)), "should not be a subset (upper bound)");

Trait Implementations

impl Clone for SizeHint

fn clone(&self) -> SizeHint

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SizeHint

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SizeHint

fn default() -> SizeHint

Returns the “default value” for a type.

impl From<RangeFrom<usize>> for SizeHint

fn from(range: RangeFrom<usize>) -> Self

Converts to this type from the input type.

impl From<RangeFull> for SizeHint

fn from(_: RangeFull) -> Self

Converts to this type from the input type.

impl From<RangeToInclusive<usize>> for SizeHint

fn from(range: RangeToInclusive<usize>) -> Self

Converts to this type from the input type.

impl From<SizeHint> for (usize, Option<usize>)

fn from(hint: SizeHint) -> Self

Converts to this type from the input type.

impl Hash for SizeHint

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq<(usize, Option<usize>)> for SizeHint

fn eq(&self, other: &(usize, Option<usize>)) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<SizeHint> for (usize, Option<usize>)

fn eq(&self, other: &SizeHint) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for SizeHint

fn eq(&self, other: &SizeHint) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RangeBounds<usize> for SizeHint

A SizeHint represents a range of possible iterator lengths.

fn start_bound(&self) -> Bound<&usize>

Returns the smallest possible iterator length. Always Bound::Included.

fn end_bound(&self) -> Bound<&usize>

Returns the largest possible iterator length. Either Bound::Included or Bound::Unbounded.

fn contains<U>(&self, item: &U) -> bool

where T: PartialOrd<U>, U: PartialOrd<T> + ?Sized,

Returns true if item is contained in the range.

fn is_empty(&self) -> bool

where T: PartialOrd,

🔬This is a nightly-only experimental API. (range_bounds_is_empty)

Returns true if the range contains no items. One-sided ranges (RangeFrom, etc) always return false.

impl TryFrom<(usize, Option<usize>)> for SizeHint

type Error = InvalidSizeHint

The type returned in the event of a conversion error.

fn try_from(hint: (usize, Option<usize>)) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Range<usize>> for SizeHint

type Error = InvalidSizeHint

The type returned in the event of a conversion error.

fn try_from(range: Range<usize>) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<RangeInclusive<usize>> for SizeHint

type Error = InvalidSizeHint

The type returned in the event of a conversion error.

fn try_from(range: RangeInclusive<usize>) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<RangeTo<usize>> for SizeHint

type Error = InvalidSizeHint

The type returned in the event of a conversion error.

fn try_from(range: RangeTo<usize>) -> Result<Self, Self::Error>

Performs the conversion.

impl Copy for SizeHint

impl Eq for SizeHint

impl StructuralPartialEq for SizeHint