Struct GenRef

pub struct GenRef<'s, M: Mutability, T: ?Sized> { /* private fields */ }

This is the main type of this crate. It is the generic-mutability equivalent of safe reference types (& and &mut).

Usage for end users

You need to interface with an API that is generic over mutability, but you do not use generic mutability to call it.

You will need to create a GenRef<'_, Mutable, T> or GenRef<'_, Shared, T> via the From<&mut T> or From<&T> implementations, respectively. Then pass the GenRef to the function(s) you would like to call. At the end, you can use the resulting GenRef mostly the same way you would use a reference, but you can also unwrap it into a normal reference using the into_mut or into_shared functions.

For example:

let v = vec![1, 2, 3];

let gen_r: GenRef<'_, Shared, i32> = gen_index(GenRef::from(&v), 1);

let r: &i32 = GenRef::into_shared(gen_r);

assert_eq!(gen_r, &2);
assert_eq!(r, &2);

Usage for libraries

You are implementing an API that is supposed to be generic over mutability.

You should start by introducing a mutability parameter. It is a generic argument (usually named M) with a M: Mutability bound on it .

Then you can take a GenRef as an argument.

GenRef always provides immutable access to the pointed-to value through the Deref trait.

Then, to map the generic reference into one of another type, you can do one of these:

• If the API you are calling has generic mutability accessors, you can pass the GenRef directly to them. Unlike normal references, which are automatically reborrowed, you may need to use GenRef::reborrow to perform a reborrow manually. You can also call map_deref to perform a dereference.

• If the API you’re calling does not have generic mutability, you can use one of the following ways to unwrap and reconstruct the GenRef:

  • map
  • field! macro for accessing fields
  • gen_mut! macro
  • branch to cases on Mutability::mutability() and use gen_{into,from}_{mut,shared} with the proof provided by the return value of Mutability::mutability(). See the Examples section on how to do this.

Examples

When you need to map a generic GenRef through an API that doesn’t support it, you can use the following pattern:

fn gen_index<M: Mutability, T>(gen_slice: GenRef<'_, M, [T]>, index: usize) -> GenRef<'_, M, T> {
    match M::mutability() {
        Mutable(proof) => {
            let mut_slice: &mut [T] = GenRef::gen_into_mut(gen_slice, proof);
            let mut_elem: &mut T = &mut mut_slice[index];
            GenRef::gen_from_mut(mut_elem, proof)
        },
        Shared(proof) => {
            let ref_slice: &[T] = GenRef::gen_into_shared(gen_slice, proof);
            let ref_elem: &T = &ref_slice[index];
            GenRef::gen_from_shared(ref_elem, proof)
        }
    }
}

In most cases, the mutable and shared cases share most of the code. When that is the case, it is often possible to use the gen_mut! macro, which expands to the same as above:

fn gen_index<M: Mutability, T>(gen_slice: GenRef<'_, M, [T]>, index: usize) -> GenRef<'_, M, T> {
    gen_mut!(M => {
        let ref_slice = from_gen!(gen_slice);
        into_gen!(&gen ref_slice[index])
    })
}

When performing a one-to-one mapping with two separate functions (often when calling into an API), the GenRef::map can come handy:

fn gen_index<M: Mutability, T>(gen_slice: GenRef<'_, M, [T]>, index: usize) -> GenRef<'_, M, T> {
    GenRef::map(gen_slice, |r| &r[index], |r| &mut r[index])
}

Finally, when accessing fields or performing indexing, the field! macro can be helpful as well:

fn gen_index<M: Mutability, T>(gen_slice: GenRef<'_, M, [T]>, index: usize) -> GenRef<'_, M, T> {
    field!(&gen gen_slice[index])
}

Implementations

impl<'s, M: Mutability, T: ?Sized> GenRef<'s, M, T>

pub unsafe fn from_ptr_unchecked(ptr: NonNull<T>) -> Self

Creates a GenRef<'s, M, T> from a pointer with the chosen mutability M and lifetime 's, without checking.

To create a non-generic GenRef from a reference, use the From implementation.

To convert a reference into a GenRef in a generic context, use the gen_from_shared and gen_from_mut methods with a proof or the gen_from_mut_downgrading method instead.

Safety

GenRef is a safe reference type. Using this method is equivalent to dereferencing the pointer and creating a reference from it. As such:

• The pointer must be properly aligned.
• The pointer must point to an initialized instance of T.
• The lifetime 's and mutability M are arbitrarily chosen and do not necessarily reflect the actual lifetime and mutability of the data. Extra care must be taken to ensure that the correct lifetime and mutability parameters are used.
• Furthermore:
  • If the mutability is Immutable:
    • The pointer must be valid for reads for lifetime 's.
    • The pointed-to value must not be written to by other pointers and no mutable references to it may exist during 's.
  • If the mutability is Mutable:
    • The pointer must be valid for reads and writes for lifetime 's.
    • The pointed-to value must not be accessed (read or written) by other pointers, and no other references to it may exist during 's.

pub fn as_ptr(genref: &Self) -> NonNull<T>

Casts the reference into a NonNull pointer.

Safety

The GenRef must not be used while the pointer is active. The exact semantics of this depend on the memory model adopted by Rust.

Guarantees

The returned pointer is guaranteed to be valid for reads for 's, and also for writes if M is Mutable.

pub fn gen_from_mut_downgrading(reference: &'s mut T) -> Self

Converts a &mut T into a generic GenRef<'_, M, T>, downgrading the reference if M is Shared.

If M is Mutable it behaves exactly the same way as gen_from_mut without requiring a proof for mutability. In this case, the difference between the two is purely semantic: if you have proof that M is Mutable, you should use gen_from_mut.

pub fn gen_into_shared_downgrading(genref: Self) -> &'s T

Converts a generic GenRef<'_, M, T> into &T, downgrading the reference if M is Mutable.

If M is Shared it behaves exactly the same way as gen_into_shared without requiring a proof for sharedness. In this case, the difference between the two is purely semantic: if you have proof that M is Shared, you should use gen_into_shared.

pub fn gen_into_mut(genref: Self, _proof: IsMutable<M>) -> &'s mut T

Converts a generic GenRef<'_, M, T> into &mut T. This is available in a generic context.

Once the transformations are done, the result can be converted back into a GenRef using the gen_from_mut function.

The conversion requires that M is Mutable, this must be proven by passing an IsMutable<M> value. That can be obtained by matching on M::mutability().

pub fn gen_from_mut(reference: &'s mut T, _proof: IsMutable<M>) -> Self

Converts a &mut T into a generic GenRef<'_, M, T>. This is available in a generic context.

The conversion requires that M is Mutable, this must be proven by passing an IsMutable<M> value. That can be obtained by matching on M::mutability().

If you want to force the conversion even if M is Shared, you can use the gen_from_mut_downgrading function.

pub fn gen_into_shared(genref: Self, _proof: IsShared<M>) -> &'s T

Converts a generic GenRef<'_, M, T> into &T. This is available in a generic context.

Once the transformations are done, the result can be converted back into a GenRef using the gen_from_shared function.

The conversion requires that M is Shared, this must be proven by passing an IsShared<M> value. That can be obtained by matching on M::mutability().

If you want to force the conversion even if M is Mutable, you can use the gen_into_shared_downgrading function.

pub fn gen_from_shared(reference: &'s T, _proof: IsShared<M>) -> Self

Converts a &T into a generic GenRef<'_, M, T>. This is available in a generic context.

The conversion requires that M is Shared, this must be proven by passing an IsShared<M> value. That can be obtained by matching on M::mutability().

pub fn reborrow(genref: &mut Self) -> GenRef<'_, M, T>

Generically reborrows a GenRef. That is, it creates a shorter-lived owned GenRef from a &mut GenRef. This is available in a generic context.

This requires the variable to be marked mut, even if M is Shared and thus no mutation takes place.

pub fn map<U: ?Sized>( genref: Self, f_shared: impl FnOnce(&T) -> &U, f_mut: impl FnOnce(&mut T) -> &mut U, ) -> GenRef<'s, M, U>

Maps a generic GenRef into another one using either f_mut or f_shared. This is available in a generic context.

Using this function is usually sufficient. For mapping over field access, you can use the field! macro instead. If you need more flexibility, you can use the gen_mut! macro or matching over M::mutability().

pub fn map_deref(genref: Self) -> GenRef<'s, M, T::Target>

where T: Deref + DerefMut,

Generically dereferences the value contained in the GenRef. This is available in a generic context.

impl<'s, T: ?Sized> GenRef<'s, Shared, T>

pub fn into_shared(genref: Self) -> &'s T

Converts a GenRef<'_, Shared, T> into &T in a non-generic context.

This is used to unwrap the reference in end-user code.

To perform the same operation in a generic context, use gen_into_shared or gen_into_shared_downgrading.

impl<'s, T: ?Sized> GenRef<'s, Mutable, T>

pub fn into_mut(genref: Self) -> &'s mut T

Converts a GenRef<'_, Mutable T> into &mut T in a non-generic context.

This is used to unwrap the reference in end-user code.

To perform the same operation in a generic context, use gen_into_mut.

Trait Implementations

impl<'s, M: Mutability, T> Binary for GenRef<'s, M, T>

where T: Binary + ?Sized,

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

Formats the value using the given formatter.

impl<M: Mutability, T: ?Sized> Borrow<T> for GenRef<'_, M, T>

fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<T: ?Sized> BorrowMut<T> for GenRef<'_, Mutable, T>

This is only implemented for GenRef<'_, Mutable, T>, and is not available in a generic context.

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value.

impl<T> BufRead for GenRef<'_, Mutable, T>

where T: BufRead + ?Sized,

This is only implemented for GenRef<'_, Mutable, T>, and is not available in a generic context.

This is only available with the feature flag std.

fn fill_buf(&mut self) -> Result<&[u8]>

Returns the contents of the internal buffer, filling it with more data, via Read methods, if empty.

fn consume(&mut self, amt: usize)

Marks the given amount of additional bytes from the internal buffer as having been read. Subsequent calls to read only return bytes that have not been marked as read.

fn has_data_left(&mut self) -> Result<bool, Error>

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

Checks if there is any data left to be read.

fn read_until(&mut self, byte: u8, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes into buf until the delimiter byte or EOF is reached.

fn skip_until(&mut self, byte: u8) -> Result<usize, Error>

Skips all bytes until the delimiter byte or EOF is reached.

fn read_line(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until a newline (the 0xA byte) is reached, and append them to the provided String buffer.

fn split(self, byte: u8) -> Split<Self>

where Self: Sized,

Returns an iterator over the contents of this reader split on the byte byte.

fn lines(self) -> Lines<Self>

where Self: Sized,

Returns an iterator over the lines of this reader.

impl<T: ?Sized> Clone for GenRef<'_, Shared, T>

This is only implemented for GenRef<'_, Shared, T>, and is not available in a generic context.

fn clone(&self) -> Self

Copies the reference. This does not call clone on the pointed-to value.

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

Performs copy-assignment from source.

impl<'s, M: Mutability, T> Debug for GenRef<'s, M, T>

where T: Debug + ?Sized,

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

Formats the value using the given formatter.

impl<M: Mutability, T: ?Sized> Deref for GenRef<'_, M, T>

This is available in a generic context.

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T: ?Sized> DerefMut for GenRef<'_, Mutable, T>

This is only implemented for GenRef<'_, Mutable, T>, and is not available in a generic context.

To get mutable access to the value, call reborrow followed by gen_into_mut (this requires proving that M is mutable).

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'s, M: Mutability, T> Display for GenRef<'s, M, T>

where T: Display + ?Sized,

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

Formats the value using the given formatter.

impl<T> DoubleEndedIterator for GenRef<'_, Mutable, T>

where T: DoubleEndedIterator + ?Sized,

This is only implemented for GenRef<'_, Mutable, T>, and is not available in a generic context.

fn next_back(&mut self) -> Option<Self::Item>

Removes and returns an element from the end of the iterator.

fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero<usize>>

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

Advances the iterator from the back by n elements.

fn nth_back(&mut self, n: usize) -> Option<Self::Item>

Returns the nth element from the end of the iterator.

fn try_rfold<B, F, R>(&mut self, init: B, f: F) -> R

where Self: Sized, F: FnMut(B, Self::Item) -> R, R: Try<Output = B>,

This is the reverse version of Iterator::try_fold(): it takes elements starting from the back of the iterator.

fn rfold<B, F>(self, init: B, f: F) -> B

where Self: Sized, F: FnMut(B, Self::Item) -> B,

An iterator method that reduces the iterator’s elements to a single, final value, starting from the back.

fn rfind<P>(&mut self, predicate: P) -> Option<Self::Item>

where Self: Sized, P: FnMut(&Self::Item) -> bool,

Searches for an element of an iterator from the back that satisfies a predicate.

impl<T> ExactSizeIterator for GenRef<'_, Mutable, T>

where T: ExactSizeIterator + ?Sized,

This is only implemented for GenRef<'_, Mutable, T>, and is not available in a generic context.

fn len(&self) -> usize

Returns the exact remaining length of the iterator.

fn is_empty(&self) -> bool

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

Returns true if the iterator is empty.

impl<'s, T: ?Sized> From<&'s T> for GenRef<'s, Shared, T>

Creates a non-generic GenRef<'_, Shared, T> from a &T.

This is used to create a GenRef in end-user code.

To create a generic GenRef<'_, M, T>, use gen_from_shared.

fn from(reference: &'s T) -> Self

Converts to this type from the input type.

impl<'s, T: ?Sized> From<&'s mut T> for GenRef<'s, Mutable, T>

Creates a non-generic GenRef<'_, Mutable, T> from a &mut T.

This is used to create a GenRef in end-user code.

To create a generic GenRef<'_, M, T>, use gen_from_mut or gen_from_mut_downgrading.

fn from(reference: &'s mut T) -> Self

Converts to this type from the input type.

impl<'s, M: Mutability, T: ?Sized> GenRefMethods<'s, M, T> for GenRef<'s, M, T>

fn as_ptr(&self) -> NonNull<T>

This is a method variant of the equivalent associated function on GenRef. Casts the reference into a NonNull pointer.

fn gen_into_shared_downgrading(self) -> &'s T

This is a method variant of the equivalent associated function on GenRef. Converts a generic GenRef<'_, M, T> into &T, downgrading the reference if M is Mutable.

fn gen_into_mut(self, proof: IsMutable<M>) -> &'s mut T

This is a method variant of the equivalent associated function on GenRef. Converts a generic GenRef<'_, M, T> into &mut T. This is available in a generic context.

fn gen_into_shared(self, proof: IsShared<M>) -> &'s T

This is a method variant of the equivalent associated function on GenRef. Converts a generic GenRef<'_, M, T> into &T. This is available in a generic context.

fn reborrow(&mut self) -> GenRef<'_, M, T>

This is a method variant of the equivalent associated function on GenRef. Generically reborrows a GenRef. That is, it creates a shorter-lived owned GenRef from a &mut GenRef. This is available in a generic context.

fn map<U: ?Sized>( self, f_mut: impl FnOnce(&mut T) -> &mut U, f_shared: impl FnOnce(&T) -> &U, ) -> GenRef<'s, M, U>

This is a method variant of the equivalent associated function on GenRef. Maps a generic GenRef into another one using either f_mut or f_shared. This is available in a generic context.

fn map_deref(self) -> GenRef<'s, M, T::Target>

where T: Deref + DerefMut,

This is a method variant of the equivalent associated function on GenRef. Generically dereferences the value contained in the GenRef. This is available in a generic context.

fn deref(&self) -> &T

Dereferences the GenRef. Same as Deref::deref(self). This method allows you to call methods on the referenced value explicitly.

impl<M: Mutability, T> Hash for GenRef<'_, M, T>

where T: Hash + ?Sized,

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<T> Iterator for GenRef<'_, Mutable, T>

where T: Iterator + ?Sized,

This is only implemented for GenRef<'_, Mutable, T>, and is not available in a generic context.

type Item = <T as Iterator>::Item

The type of the elements being iterated over.

fn next(&mut self) -> Option<Self::Item>

Advances the iterator and returns the next value.

fn nth(&mut self, n: usize) -> Option<Self::Item>

Returns the nth element of the iterator.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the iterator.

fn next_chunk<const N: usize>( &mut self, ) -> Result<[Self::Item; N], IntoIter<Self::Item, N>>

where Self: Sized,

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

Advances the iterator and returns an array containing the next N values.

fn count(self) -> usize

where Self: Sized,

Consumes the iterator, counting the number of iterations and returning it.

fn last(self) -> Option<Self::Item>

where Self: Sized,

Consumes the iterator, returning the last element.

fn advance_by(&mut self, n: usize) -> Result<(), NonZero<usize>>

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

Advances the iterator by n elements.

fn step_by(self, step: usize) -> StepBy<Self>

where Self: Sized,

Creates an iterator starting at the same point, but stepping by the given amount at each iteration.

fn chain<U>(self, other: U) -> Chain<Self, <U as IntoIterator>::IntoIter>

where Self: Sized, U: IntoIterator<Item = Self::Item>,

Takes two iterators and creates a new iterator over both in sequence.

fn zip<U>(self, other: U) -> Zip<Self, <U as IntoIterator>::IntoIter>

where Self: Sized, U: IntoIterator,

‘Zips up’ two iterators into a single iterator of pairs.

fn intersperse(self, separator: Self::Item) -> Intersperse<Self>

where Self: Sized, Self::Item: Clone,

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

Creates a new iterator which places a copy of separator between adjacent items of the original iterator.

fn intersperse_with<G>(self, separator: G) -> IntersperseWith<Self, G>

where Self: Sized, G: FnMut() -> Self::Item,

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

Creates a new iterator which places an item generated by separator between adjacent items of the original iterator.

fn map<B, F>(self, f: F) -> Map<Self, F>

where Self: Sized, F: FnMut(Self::Item) -> B,

Takes a closure and creates an iterator which calls that closure on each element.

fn for_each<F>(self, f: F)

where Self: Sized, F: FnMut(Self::Item),

Calls a closure on each element of an iterator.

fn filter<P>(self, predicate: P) -> Filter<Self, P>

where Self: Sized, P: FnMut(&Self::Item) -> bool,

Creates an iterator which uses a closure to determine if an element should be yielded.

fn filter_map<B, F>(self, f: F) -> FilterMap<Self, F>

where Self: Sized, F: FnMut(Self::Item) -> Option<B>,

Creates an iterator that both filters and maps.

fn enumerate(self) -> Enumerate<Self>

where Self: Sized,

Creates an iterator which gives the current iteration count as well as the next value.

fn peekable(self) -> Peekable<Self>

where Self: Sized,

Creates an iterator which can use the peek and peek_mut methods to look at the next element of the iterator without consuming it. See their documentation for more information.

fn skip_while<P>(self, predicate: P) -> SkipWhile<Self, P>

where Self: Sized, P: FnMut(&Self::Item) -> bool,

Creates an iterator that skips elements based on a predicate.

fn take_while<P>(self, predicate: P) -> TakeWhile<Self, P>

where Self: Sized, P: FnMut(&Self::Item) -> bool,

Creates an iterator that yields elements based on a predicate.

fn map_while<B, P>(self, predicate: P) -> MapWhile<Self, P>

where Self: Sized, P: FnMut(Self::Item) -> Option<B>,

Creates an iterator that both yields elements based on a predicate and maps.

fn skip(self, n: usize) -> Skip<Self>

where Self: Sized,

Creates an iterator that skips the first n elements.

fn take(self, n: usize) -> Take<Self>

where Self: Sized,

Creates an iterator that yields the first n elements, or fewer if the underlying iterator ends sooner.

fn scan<St, B, F>(self, initial_state: St, f: F) -> Scan<Self, St, F>

where Self: Sized, F: FnMut(&mut St, Self::Item) -> Option<B>,

An iterator adapter which, like fold, holds internal state, but unlike fold, produces a new iterator.

fn flat_map<U, F>(self, f: F) -> FlatMap<Self, U, F>

where Self: Sized, U: IntoIterator, F: FnMut(Self::Item) -> U,

Creates an iterator that works like map, but flattens nested structure.

fn flatten(self) -> Flatten<Self>

where Self: Sized, Self::Item: IntoIterator,

Creates an iterator that flattens nested structure.

fn map_windows<F, R, const N: usize>(self, f: F) -> MapWindows<Self, F, N>

where Self: Sized, F: FnMut(&[Self::Item; N]) -> R,

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

Calls the given function f for each contiguous window of size N over self and returns an iterator over the outputs of f. Like slice::windows(), the windows during mapping overlap as well.

fn fuse(self) -> Fuse<Self>

where Self: Sized,

Creates an iterator which ends after the first None.

fn inspect<F>(self, f: F) -> Inspect<Self, F>

where Self: Sized, F: FnMut(&Self::Item),

Does something with each element of an iterator, passing the value on.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Iterator.

fn collect<B>(self) -> B

where B: FromIterator<Self::Item>, Self: Sized,

Transforms an iterator into a collection.

fn try_collect<B>( &mut self, ) -> <<Self::Item as Try>::Residual as Residual<B>>::TryType

where Self: Sized, Self::Item: Try, <Self::Item as Try>::Residual: Residual<B>, B: FromIterator<<Self::Item as Try>::Output>,

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

Fallibly transforms an iterator into a collection, short circuiting if a failure is encountered.

fn collect_into<E>(self, collection: &mut E) -> &mut E

where E: Extend<Self::Item>, Self: Sized,

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

Collects all the items from an iterator into a collection.

fn partition<B, F>(self, f: F) -> (B, B)

where Self: Sized, B: Default + Extend<Self::Item>, F: FnMut(&Self::Item) -> bool,

Consumes an iterator, creating two collections from it.

fn partition_in_place<'a, T, P>(self, predicate: P) -> usize

where T: 'a, Self: Sized + DoubleEndedIterator<Item = &'a mut T>, P: FnMut(&T) -> bool,

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

Reorders the elements of this iterator in-place according to the given predicate, such that all those that return true precede all those that return false. Returns the number of true elements found.

fn is_partitioned<P>(self, predicate: P) -> bool

where Self: Sized, P: FnMut(Self::Item) -> bool,

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

Checks if the elements of this iterator are partitioned according to the given predicate, such that all those that return true precede all those that return false.

fn try_fold<B, F, R>(&mut self, init: B, f: F) -> R

where Self: Sized, F: FnMut(B, Self::Item) -> R, R: Try<Output = B>,

An iterator method that applies a function as long as it returns successfully, producing a single, final value.

fn try_for_each<F, R>(&mut self, f: F) -> R

where Self: Sized, F: FnMut(Self::Item) -> R, R: Try<Output = ()>,

An iterator method that applies a fallible function to each item in the iterator, stopping at the first error and returning that error.

fn fold<B, F>(self, init: B, f: F) -> B

where Self: Sized, F: FnMut(B, Self::Item) -> B,

Folds every element into an accumulator by applying an operation, returning the final result.

fn reduce<F>(self, f: F) -> Option<Self::Item>

where Self: Sized, F: FnMut(Self::Item, Self::Item) -> Self::Item,

Reduces the elements to a single one, by repeatedly applying a reducing operation.

fn try_reduce<R>( &mut self, f: impl FnMut(Self::Item, Self::Item) -> R, ) -> <<R as Try>::Residual as Residual<Option<<R as Try>::Output>>>::TryType

where Self: Sized, R: Try<Output = Self::Item>, <R as Try>::Residual: Residual<Option<Self::Item>>,

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

Reduces the elements to a single one by repeatedly applying a reducing operation. If the closure returns a failure, the failure is propagated back to the caller immediately.

fn all<F>(&mut self, f: F) -> bool

where Self: Sized, F: FnMut(Self::Item) -> bool,

Tests if every element of the iterator matches a predicate.

fn any<F>(&mut self, f: F) -> bool

where Self: Sized, F: FnMut(Self::Item) -> bool,

Tests if any element of the iterator matches a predicate.

fn find<P>(&mut self, predicate: P) -> Option<Self::Item>

where Self: Sized, P: FnMut(&Self::Item) -> bool,

Searches for an element of an iterator that satisfies a predicate.

fn find_map<B, F>(&mut self, f: F) -> Option<B>

where Self: Sized, F: FnMut(Self::Item) -> Option<B>,

Applies function to the elements of iterator and returns the first non-none result.

fn try_find<R>( &mut self, f: impl FnMut(&Self::Item) -> R, ) -> <<R as Try>::Residual as Residual<Option<Self::Item>>>::TryType

where Self: Sized, R: Try<Output = bool>, <R as Try>::Residual: Residual<Option<Self::Item>>,

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

Applies function to the elements of iterator and returns the first true result or the first error.

fn position<P>(&mut self, predicate: P) -> Option<usize>

where Self: Sized, P: FnMut(Self::Item) -> bool,

Searches for an element in an iterator, returning its index.

fn rposition<P>(&mut self, predicate: P) -> Option<usize>

where P: FnMut(Self::Item) -> bool, Self: Sized + ExactSizeIterator + DoubleEndedIterator,

Searches for an element in an iterator from the right, returning its index.

fn max(self) -> Option<Self::Item>

where Self: Sized, Self::Item: Ord,

Returns the maximum element of an iterator.

fn min(self) -> Option<Self::Item>

where Self: Sized, Self::Item: Ord,

Returns the minimum element of an iterator.

fn max_by_key<B, F>(self, f: F) -> Option<Self::Item>

where B: Ord, Self: Sized, F: FnMut(&Self::Item) -> B,

Returns the element that gives the maximum value from the specified function.

fn max_by<F>(self, compare: F) -> Option<Self::Item>

where Self: Sized, F: FnMut(&Self::Item, &Self::Item) -> Ordering,

Returns the element that gives the maximum value with respect to the specified comparison function.

fn min_by_key<B, F>(self, f: F) -> Option<Self::Item>

where B: Ord, Self: Sized, F: FnMut(&Self::Item) -> B,

Returns the element that gives the minimum value from the specified function.

fn min_by<F>(self, compare: F) -> Option<Self::Item>

where Self: Sized, F: FnMut(&Self::Item, &Self::Item) -> Ordering,

Returns the element that gives the minimum value with respect to the specified comparison function.

fn rev(self) -> Rev<Self>

where Self: Sized + DoubleEndedIterator,

Reverses an iterator’s direction.

fn unzip<A, B, FromA, FromB>(self) -> (FromA, FromB)

where FromA: Default + Extend<A>, FromB: Default + Extend<B>, Self: Sized + Iterator<Item = (A, B)>,

Converts an iterator of pairs into a pair of containers.

fn copied<'a, T>(self) -> Copied<Self>

where T: 'a + Copy, Self: Sized + Iterator<Item = &'a T>,

Creates an iterator which copies all of its elements.

fn cloned<'a, T>(self) -> Cloned<Self>

where T: 'a + Clone, Self: Sized + Iterator<Item = &'a T>,

Creates an iterator which clones all of its elements.

fn array_chunks<const N: usize>(self) -> ArrayChunks<Self, N>

where Self: Sized,

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

Returns an iterator over N elements of the iterator at a time.

fn sum<S>(self) -> S

where Self: Sized, S: Sum<Self::Item>,

Sums the elements of an iterator.

fn product<P>(self) -> P

where Self: Sized, P: Product<Self::Item>,

Iterates over the entire iterator, multiplying all the elements

fn cmp<I>(self, other: I) -> Ordering

where I: IntoIterator<Item = Self::Item>, Self::Item: Ord, Self: Sized,

Lexicographically compares the elements of this Iterator with those of another.

fn cmp_by<I, F>(self, other: I, cmp: F) -> Ordering

where Self: Sized, I: IntoIterator, F: FnMut(Self::Item, <I as IntoIterator>::Item) -> Ordering,

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

Lexicographically compares the elements of this Iterator with those of another with respect to the specified comparison function.

fn partial_cmp<I>(self, other: I) -> Option<Ordering>

where I: IntoIterator, Self::Item: PartialOrd<<I as IntoIterator>::Item>, Self: Sized,

Lexicographically compares the PartialOrd elements of this Iterator with those of another. The comparison works like short-circuit evaluation, returning a result without comparing the remaining elements. As soon as an order can be determined, the evaluation stops and a result is returned.

fn partial_cmp_by<I, F>(self, other: I, partial_cmp: F) -> Option<Ordering>

where Self: Sized, I: IntoIterator, F: FnMut(Self::Item, <I as IntoIterator>::Item) -> Option<Ordering>,

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

Lexicographically compares the elements of this Iterator with those of another with respect to the specified comparison function.

fn eq<I>(self, other: I) -> bool

where I: IntoIterator, Self::Item: PartialEq<<I as IntoIterator>::Item>, Self: Sized,

Determines if the elements of this Iterator are equal to those of another.

fn eq_by<I, F>(self, other: I, eq: F) -> bool

where Self: Sized, I: IntoIterator, F: FnMut(Self::Item, <I as IntoIterator>::Item) -> bool,

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

Determines if the elements of this Iterator are equal to those of another with respect to the specified equality function.

fn ne<I>(self, other: I) -> bool

where I: IntoIterator, Self::Item: PartialEq<<I as IntoIterator>::Item>, Self: Sized,

Determines if the elements of this Iterator are not equal to those of another.

fn lt<I>(self, other: I) -> bool

where I: IntoIterator, Self::Item: PartialOrd<<I as IntoIterator>::Item>, Self: Sized,

Determines if the elements of this Iterator are lexicographically less than those of another.

fn le<I>(self, other: I) -> bool

where I: IntoIterator, Self::Item: PartialOrd<<I as IntoIterator>::Item>, Self: Sized,

Determines if the elements of this Iterator are lexicographically less or equal to those of another.

fn gt<I>(self, other: I) -> bool

where I: IntoIterator, Self::Item: PartialOrd<<I as IntoIterator>::Item>, Self: Sized,

Determines if the elements of this Iterator are lexicographically greater than those of another.

fn ge<I>(self, other: I) -> bool

where I: IntoIterator, Self::Item: PartialOrd<<I as IntoIterator>::Item>, Self: Sized,

Determines if the elements of this Iterator are lexicographically greater than or equal to those of another.

fn is_sorted(self) -> bool

where Self: Sized, Self::Item: PartialOrd,

Checks if the elements of this iterator are sorted.

fn is_sorted_by<F>(self, compare: F) -> bool

where Self: Sized, F: FnMut(&Self::Item, &Self::Item) -> bool,

Checks if the elements of this iterator are sorted using the given comparator function.

fn is_sorted_by_key<F, K>(self, f: F) -> bool

where Self: Sized, F: FnMut(Self::Item) -> K, K: PartialOrd,

Checks if the elements of this iterator are sorted using the given key extraction function.

impl<'s, M: Mutability, T> LowerExp for GenRef<'s, M, T>

where T: LowerExp + ?Sized,

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

Formats the value using the given formatter.

impl<'s, M: Mutability, T> LowerHex for GenRef<'s, M, T>

where T: LowerHex + ?Sized,

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

Formats the value using the given formatter.

impl<'s, M: Mutability, T> Octal for GenRef<'s, M, T>

where T: Octal + ?Sized,

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

Formats the value using the given formatter.

impl<MT: Mutability, T> Ord for GenRef<'_, MT, T>

where T: Ord + ?Sized,

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<MT: Mutability, T, U: ?Sized> PartialEq<&U> for GenRef<'_, MT, T>

where T: PartialEq<U> + ?Sized,

fn eq(&self, other: &&'_ U) -> 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<MT: Mutability, T, U: ?Sized> PartialEq<&mut U> for GenRef<'_, MT, T>

where T: PartialEq<U> + ?Sized,

fn eq(&self, other: &&'_ mut U) -> 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<MT: Mutability, MU: Mutability, T, U: ?Sized> PartialEq<GenRef<'_, MU, U>> for GenRef<'_, MT, T>

where T: PartialEq<U> + ?Sized,

fn eq(&self, other: &GenRef<'_, MU, U>) -> 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<MT: Mutability, T, U: ?Sized> PartialOrd<&U> for GenRef<'_, MT, T>

where T: PartialOrd<U> + ?Sized,

fn partial_cmp(&self, other: &&'_ U) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<MT: Mutability, T, U: ?Sized> PartialOrd<&mut U> for GenRef<'_, MT, T>

where T: PartialOrd<U> + ?Sized,

fn partial_cmp(&self, other: &&'_ mut U) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<MT: Mutability, MU: Mutability, T, U: ?Sized> PartialOrd<GenRef<'_, MU, U>> for GenRef<'_, MT, T>

where T: PartialOrd<U> + ?Sized,

fn partial_cmp(&self, other: &GenRef<'_, MU, U>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<M: Mutability, T: ?Sized> Pointer for GenRef<'_, M, T>

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

Formats the value using the given formatter.

impl<T> Read for GenRef<'_, Mutable, T>

where T: Read + ?Sized,

This is only implemented for GenRef<'_, Mutable, T>, and is not available in a generic context.

This is only available with the feature flag std.

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

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

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

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

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

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

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl<T> Seek for GenRef<'_, Mutable, T>

where T: Seek + ?Sized,

This is only implemented for GenRef<'_, Mutable, T>, and is not available in a generic context.

This is only available with the feature flag std.

fn seek(&mut self, pos: SeekFrom) -> Result<u64>

Seek to an offset, in bytes, in a stream.

fn rewind(&mut self) -> Result<(), Error>

Rewind to the beginning of a stream.

fn stream_len(&mut self) -> Result<u64, Error>

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

Returns the length of this stream (in bytes).

fn stream_position(&mut self) -> Result<u64, Error>

Returns the current seek position from the start of the stream.

fn seek_relative(&mut self, offset: i64) -> Result<(), Error>

Seeks relative to the current position.

impl<T> ToSocketAddrs for GenRef<'_, Shared, T>

where T: ToSocketAddrs + ?Sized,

This is only implemented for GenRef<'_, Shared, T>, and is not available in a generic context.

This is only available with the feature flag std.

type Iter = <T as ToSocketAddrs>::Iter

Returned iterator over socket addresses which this type may correspond to.

fn to_socket_addrs(&self) -> Result<Self::Iter>

Converts this object to an iterator of resolved SocketAddrs.

impl<'s, M: Mutability, T> UpperExp for GenRef<'s, M, T>

where T: UpperExp + ?Sized,

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

Formats the value using the given formatter.

impl<'s, M: Mutability, T> UpperHex for GenRef<'s, M, T>

where T: UpperHex + ?Sized,

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

Formats the value using the given formatter.

impl<T> Write for GenRef<'_, Mutable, T>

where T: Write + ?Sized,

This is only implemented for GenRef<'_, Mutable, T>, and is not available in a generic context.

fn write_str(&mut self, s: &str) -> Result

Writes a string slice into this writer, returning whether the write succeeded.

fn write_char(&mut self, c: char) -> Result

Writes a char into this writer, returning whether the write succeeded.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result

Glue for usage of the write! macro with implementors of this trait.

impl<T> Write for GenRef<'_, Mutable, T>

where T: Write + ?Sized,

This is only implemented for GenRef<'_, Mutable, T>, and is not available in a generic context.

This is only available with the feature flag std.

fn write(&mut self, buf: &[u8]) -> Result<usize>

Writes a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

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

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

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

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.

impl<T: ?Sized> Copy for GenRef<'_, Shared, T>

This is only implemented for GenRef<'_, Shared, T>, and is not available in a generic context.

impl<M: Mutability, T> Eq for GenRef<'_, M, T>

where T: Eq + ?Sized,

impl<T> FusedIterator for GenRef<'_, Mutable, T>

where T: FusedIterator + ?Sized,

This is only implemented for GenRef<'_, Mutable, T>, and is not available in a generic context.

impl<M: Mutability, T> Send for GenRef<'_, M, T>

where T: Send + Sync + ?Sized,

This implementation requires T: Sync even when M is Mutable. With specialisation, this requirement could be lifted.

impl<M: Mutability, T> Sync for GenRef<'_, M, T>

where T: Sync + ?Sized,