Trait Iter

pub unsafe trait Iter<'a> {
    const IS_CONTIGUOUS: bool;

    // Required methods
    fn get_buffer(&self) -> &'a [u8] ;
    fn cursor(&self) -> usize;
    unsafe fn set_cursor(&mut self, index: usize);
    fn current_count(&self) -> usize;
    unsafe fn step_by_unchecked(&mut self, count: usize);

    // Provided methods
    fn as_ptr(&self) -> *const u8 { ... }
    fn as_slice(&self) -> &'a [u8]  { ... }
    fn buffer_length(&self) -> usize { ... }
    fn is_buffer_empty(&self) -> bool { ... }
    fn is_contiguous(&self) -> bool { ... }
    fn first(&self) -> Option<&'a u8> { ... }
    fn first_is_cased(&self, value: u8) -> bool { ... }
    fn first_is_uncased(&self, value: u8) -> bool { ... }
    fn first_is(&self, value: u8, is_cased: bool) -> bool { ... }
    unsafe fn step_unchecked(&mut self) { ... }
    unsafe fn peek_many_unchecked<V>(&self) -> V { ... }
    fn peek_u32(&self) -> Option<u32> { ... }
    fn peek_u64(&self) -> Option<u64> { ... }
}

A trait for working with iterables of bytes.

These iterators can either be contiguous or not contiguous and provide methods for reading data and accessing underlying data. The readers can either be contiguous or non-contiguous, although performance and some API methods may not be available for both.

Safety

Safe if set_cursor is set to an index <= buffer_length, so no out-of-bounds reads can occur. Also, get_buffer must return a slice of initialized bytes. The caller must also ensure that any calls that increment the cursor, such as step_by_unchecked, step_unchecked, and peek_many_unchecked never exceed buffer_length as well.

Required Associated Constants

const IS_CONTIGUOUS: bool

Determine if the buffer is contiguous in memory.

Required Methods

fn get_buffer(&self) -> &'a [u8]

Get a slice to the full underlying contiguous buffer,

fn cursor(&self) -> usize

Get the current index of the iterator in the slice.

unsafe fn set_cursor(&mut self, index: usize)

Set the current index of the iterator in the slice.

This is NOT the current position of the iterator, since iterators may skip digits: this is the cursor in the underlying buffer. For example, if slc[2] is skipped, set_cursor(3) would be the 3rd element in the iterator, not the 4th.

Safety

Safe if index <= self.buffer_length(). Although this won’t affect safety, the caller also should be careful it does not set the cursor within skipped characters since this could affect correctness: an iterator that only accepts non-consecutive digit separators would pass if the cursor was set between the two.

fn current_count(&self) -> usize

Get the current number of digits returned by the iterator.

For contiguous iterators, this can include the sign character, decimal point, and the exponent sign (that is, it is always the cursor). For non-contiguous iterators, this must always be the only the number of digits returned.

This is never used for indexing but will be used for API detection.

unsafe fn step_by_unchecked(&mut self, count: usize)

Advance the internal slice by N elements.

This does not advance the iterator by N elements for non-contiguous iterators: this just advances the internal, underlying buffer. This is useful for multi-digit optimizations for contiguous iterators.

This does not increment the count of items: returns: this only increments the index, not the total digits returned. You must use this carefully: if stepping over a digit, you must then call increment_count afterwards or else the internal count will be incorrect.

Panics

This will panic if the buffer advances for non-contiguous iterators if the current byte is a digit separator, or if the count is more than 1.

Safety

As long as the iterator is at least N elements, this is safe.

Provided Methods

fn as_ptr(&self) -> *const u8

Get a ptr to the current start of the buffer.

fn as_slice(&self) -> &'a [u8]

Get a slice to the current start of the buffer.

fn buffer_length(&self) -> usize

Get the total number of elements in the underlying buffer.

fn is_buffer_empty(&self) -> bool

Get if no bytes are available in the buffer.

This operators on the underlying buffer: that is, it returns if [as_slice] would return an empty slice.

fn is_contiguous(&self) -> bool

Determine if the buffer is contiguous.

fn first(&self) -> Option<&'a u8>

Get the next value available without consuming it.

This does NOT skip digits, and directly fetches the item from the underlying buffer.

fn first_is_cased(&self, value: u8) -> bool

Check if the next element is a given value.

fn first_is_uncased(&self, value: u8) -> bool

Check if the next element is a given value without case sensitivity.

fn first_is(&self, value: u8, is_cased: bool) -> bool

Check if the next item in buffer is a given value with optional case sensitivity.

unsafe fn step_unchecked(&mut self)

Advance the internal slice by 1 element.

This does not increment the count of items: returns: this only increments the index, not the total digits returned. You must use this carefully: if stepping over a digit, you must then call increment_count afterwards or else the internal count will be incorrect.

Panics

This will panic if the buffer advances for non-contiguous iterators if the current byte is a digit separator.

Safety

Safe as long as the iterator is not empty.

unsafe fn peek_many_unchecked<V>(&self) -> V

Read a value of a difference type from the iterator.

This does not advance the internal state of the iterator. This can only be implemented for contiguous iterators: non- contiguous iterators MUST panic.

Panics

If the iterator is a non-contiguous iterator.

Safety

Safe as long as the number of the buffer is contains as least as many bytes as the size of V. This must be unimplemented for non-contiguous iterators.

fn peek_u32(&self) -> Option<u32>

Try to read a the next four bytes as a u32.

This does not advance the internal state of the iterator.

fn peek_u64(&self) -> Option<u64>

Try to read the next eight bytes as a u64.

This does not advance the internal state of the iterator.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<'a, const FORMAT: u128> Iter<'a> for Bytes<'a, FORMAT>

const IS_CONTIGUOUS: bool = _