Struct LengthHint

#[non_exhaustive]
pub struct LengthHint(pub usize, pub Option<usize>);

A hint to help consumers of Writeable pre-allocate bytes before they call write_to.

This behaves like Iterator::size_hint: it is a tuple where the first element is the lower bound, and the second element is the upper bound. If the upper bound is None either there is no known upper bound, or the upper bound is larger than usize.

LengthHint implements std::ops::{Add, Mul} and similar traits for easy composition. During computation, the lower bound will saturate at usize::MAX, while the upper bound will become None if usize::MAX is exceeded.

Tuple Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

0: usize

1: Option<usize>

Implementations

impl LengthHint

pub fn undefined() -> Self

pub fn exact(n: usize) -> Self

write_to will use exactly n bytes.

pub fn at_least(n: usize) -> Self

write_to will use at least n bytes.

pub fn at_most(n: usize) -> Self

write_to will use at most n bytes.

pub fn between(n: usize, m: usize) -> Self

write_to will use between n and m bytes.

pub fn capacity(&self) -> usize

Returns a recommendation for the number of bytes to pre-allocate. If an upper bound exists, this is used, otherwise the lower bound (which might be 0).

Examples

use writeable::Writeable;

fn pre_allocate_string(w: &impl Writeable) -> String {
    String::with_capacity(w.writeable_length_hint().capacity())
}

pub fn is_zero(&self) -> bool

Returns whether the LengthHint indicates that the string is exactly 0 bytes long.

Trait Implementations

impl Add<usize> for LengthHint

type Output = LengthHint

The resulting type after applying the + operator.

fn add(self, other: usize) -> Self

Performs the + operation.

impl Add for LengthHint

type Output = LengthHint

The resulting type after applying the + operator.

fn add(self, other: LengthHint) -> Self

Performs the + operation.

impl AddAssign<usize> for LengthHint

fn add_assign(&mut self, other: usize)

Performs the += operation.

impl AddAssign for LengthHint

fn add_assign(&mut self, other: Self)

Performs the += operation.

impl BitOr for LengthHint

fn bitor(self, other: LengthHint) -> Self

Returns a new hint that is correct wherever self is correct, and wherever other is correct.

Example:

struct NonDeterministicWriteable(String, String);

impl Writeable for NonDeterministicWriteable {
    fn write_to<W: fmt::Write + ?Sized>(
        &self,
        sink: &mut W,
    ) -> fmt::Result {
        sink.write_str(if coin_flip() { &self.0 } else { &self.1 })
    }

    fn writeable_length_hint(&self) -> LengthHint {
        LengthHint::exact(self.0.len()) | LengthHint::exact(self.1.len())
    }
}

writeable::impl_display_with_writeable!(NonDeterministicWriteable);

type Output = LengthHint

The resulting type after applying the | operator.

impl BitOrAssign for LengthHint

fn bitor_assign(&mut self, other: Self)

Performs the |= operation.

impl Clone for LengthHint

fn clone(&self) -> LengthHint

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for LengthHint

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

Formats the value using the given formatter.

impl Mul<usize> for LengthHint

type Output = LengthHint

The resulting type after applying the * operator.

fn mul(self, other: usize) -> Self

Performs the * operation.

impl MulAssign<usize> for LengthHint

fn mul_assign(&mut self, other: usize)

Performs the *= operation.

impl PartialEq for LengthHint

fn eq(&self, other: &LengthHint) -> 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 Sum<usize> for LengthHint

fn sum<I>(iter: I) -> Self

where I: Iterator<Item = usize>,

Takes an iterator and generates Self from the elements by “summing up” the items.

impl Sum for LengthHint

fn sum<I>(iter: I) -> Self

where I: Iterator<Item = LengthHint>,

Takes an iterator and generates Self from the elements by “summing up” the items.

impl Copy for LengthHint

impl Eq for LengthHint

impl StructuralPartialEq for LengthHint