Struct iobuf::ROIobuf

pub struct ROIobuf<'a> { /* fields omitted */ }

Read-Only Iobuf

An Iobuf that cannot write into the buffer, but all read-only operations are supported. It is possible to get a RWIobuf by performing a deep_clone of the Iobuf, but this is extremely inefficient.

If your function only needs to do read-only operations on an Iobuf, consider taking a generic Iobuf trait instead. That way, it can be used with either a ROIobuf or a RWIobuf, generically.

Methods

impl<'a> ROIobuf<'a>

fn empty() -> ROIobuf<'static>

Constructs a trivially empty Iobuf, limits and window are 0, and there's an empty backing buffer. This will not allocate.

use iobuf::{ROIobuf,Iobuf};

let mut b = ROIobuf::empty();

assert_eq!(b.cap(), 0);
assert_eq!(b.len(), 0);

fn from_str(s: &'a str) -> Self

Constructs an Iobuf with the same contents as a string. The limits and window will be initially set to cover the whole string.

No copying or allocating will be done by this function.

use iobuf::{ROIobuf,Iobuf};

let mut b = ROIobuf::from_str("hello");

assert_eq!(b.cap(), 5);
assert_eq!(b.len(), 5);
unsafe { assert_eq!(b.as_window_slice(), b"hello"); }
unsafe { assert_eq!(b.as_limit_slice(), b"hello"); }

fn from_str_copy(s: &str) -> Self

Copies a str into a read-only Iobuf. The contents of the str will be copied, so prefer to use the other constructors whenever possible.

use iobuf::{ROIobuf,Iobuf};

let mut b = ROIobuf::from_str_copy("hello");

assert_eq!(b.cap(), 5);
assert_eq!(b.len(), 5);
unsafe { assert_eq!(b.as_window_slice(), b"hello"); }
unsafe { assert_eq!(b.as_limit_slice(), b"hello"); }

fn from_str_copy_with_allocator(
    s: &str,
    allocator: Arc<Box<Allocator>>
) -> ROIobuf<'static>

Copies a str into a read-only Iobuf, whose memory comes from the given allocator.

fn from_slice_copy(s: &[u8]) -> ROIobuf<'static>

Copies the contents of a slice into a read-only Iobuf. The contents of the slice will be copied, so prefer to use the other constructors whenever possible.

use iobuf::{ROIobuf,Iobuf};

let mut v = vec!(1u8, 2, 3, 4, 5, 6);
v[1] = 20;

let mut b = ROIobuf::from_slice_copy(&v[..]);

let expected = [ 1,20,3,4,5,6 ];
unsafe { assert_eq!(b.as_window_slice(), &expected[..]); }

fn from_slice_copy_with_allocator(
    s: &[u8],
    allocator: Arc<Box<Allocator>>
) -> ROIobuf<'static>

Copies a byte vector into a new read-only Iobuf, whose memory comes from the given allocator.

fn from_slice(s: &'a [u8]) -> Self

Constructs an Iobuf from a slice. The Iobuf will not copy the slice contents, and therefore their lifetimes will be linked.

use iobuf::{ROIobuf,Iobuf};

let s = [1,2,3,4];

let mut b = ROIobuf::from_slice(&s[..]);

assert_eq!(b.advance(1), Ok(()));

assert_eq!(s[1], 2); // we can still use the slice!
assert_eq!(b.peek_be(1), Ok(0x0304u16)); // ...and the Iobuf!

Trait Implementations

impl<'a> Clone for ROIobuf<'a>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Drop for ROIobuf<'a>

fn drop(&mut self)

A method called when the value goes out of scope.

impl<'a> Iobuf for ROIobuf<'a>

fn deep_clone(&self) -> RWIobuf<'static>

Copies the data byte-by-byte in the Iobuf into a new, writeable Iobuf. The new Iobuf and the old Iobuf will not share storage.

fn deep_clone_with_allocator(
    &self,
    allocator: Arc<Box<Allocator>>
) -> RWIobuf<'static>

Copies the data byte-by-byte in the Iobuf into a new, writable Iobuf. The new Iobuf will have storage allocated out of allocator, and will not share the buffer with the original Iobuf.

fn unique(self) -> Result<UniqueIobuf, Self>

Returns Ok if the Iobuf is the last to reference the underlying data, and converts it to a UniqueIobuf for sending to another task. This can also be used to safely convert from a ROIobuf to a RWIobuf, and to downgrade atomically refcounted Iobufs to non-atomically refcounted ones.

fn atomic_read_only(self) -> Result<AROIobuf, Self>

Returns Ok if the Iobuf is the last to reference the underlying data, and upgrades it to an AROIobuf which can be sent over channels and Arced with impunity. This is extremely useful in situations where Iobufs are created and written in one thread, and consumed in another.

fn len(&self) -> u32

Returns the size of the window.

fn cap(&self) -> u32

Returns the size of the limits. The capacity of an iobuf can be reduced via narrow.

fn is_empty(&self) -> bool

true if len() == 0.

unsafe fn as_window_slice<'b>(&'b self) -> &'b [u8]

Reads the data in the window as an immutable slice. Note that Peeks and Pokes into the iobuf will change the contents of the slice, even though it advertises itself as immutable. Therefore, this function is unsafe.

unsafe fn as_limit_slice<'b>(&'b self) -> &'b [u8]

Reads the data in the limits as an immutable slice. Note that Peeks and Pokes into the iobuf will change the contents of the slice, even though it advertises itself as immutable. Therefore, this function is unsafe.

fn sub_window(&mut self, pos: u32, len: u32) -> Result<(), ()>

Changes the Iobuf's bounds to the subrange specified by pos and len, which must lie within the current window.

fn sub_window_from(&mut self, pos: u32) -> Result<(), ()>

Changes the Iobuf's bounds to start at pos, and go to the end of the current window.

fn sub_window_to(&mut self, len: u32) -> Result<(), ()>

Changes the Iobuf's bounds to extend for only len bytes.

unsafe fn unsafe_sub_window(&mut self, pos: u32, len: u32)

The same as sub_window, but no bounds checks are performed. You should probably just use sub_window.

unsafe fn unsafe_sub_window_from(&mut self, pos: u32)

The same as sub_window_from, but no bounds checks are performed. You should probably just use sub_window_from.

unsafe fn unsafe_sub_window_to(&mut self, len: u32)

The same as sub_window_to, but no bounds checks are performed. You should probably just use sub_window_to.

fn sub(&mut self, pos: u32, len: u32) -> Result<(), ()>

Changes the Iobuf's limits and bounds to the subrange specified by pos and len, which must lie within the current window.

fn sub_from(&mut self, pos: u32) -> Result<(), ()>

Changes the Iobuf's limits and bounds to start from pos and extend to the end of the current window.

fn sub_to(&mut self, len: u32) -> Result<(), ()>

Changes the Iobuf's limits and bounds to start at the beginning of the current window, and extend for len bytes.

unsafe fn unsafe_sub(&mut self, pos: u32, len: u32)

The same as sub, but no bounds checks are performed. You should probably just use sub.

unsafe fn unsafe_sub_from(&mut self, pos: u32)

The same as sub_from, but no bounds checks are performed. You should probably just use sub_from.

unsafe fn unsafe_sub_to(&mut self, len: u32)

The same as sub_to, but no bounds checks are performed. You should probably just use sub_to.

fn set_limits_and_window(
    &mut self,
    limits: (u32, u32),
    window: (u32, u32)
) -> Result<(), ()>

Overrides the existing limits and window of the Iobuf, returning Err(()) if attempting to widen either of them.

fn narrow(&mut self)

Sets the limits to the current window.

fn advance(&mut self, len: u32) -> Result<(), ()>

Advances the lower bound of the window by len. Err(()) will be returned if you advance past the upper bound of the window.

unsafe fn unsafe_advance(&mut self, len: u32)

Advances the lower bound of the window by len. No bounds checking will be performed.

fn extend(&mut self, len: u32) -> Result<(), ()>

Advances the upper bound of the window by len. Err(()) will be returned if you advance past the upper limit.

unsafe fn unsafe_extend(&mut self, len: u32)

Advances the upper bound of the window by len. No bounds checking will be performed.

fn is_extended_by<Buf: Iobuf>(&self, other: &Buf) -> bool

Returns true if the other Iobuf's window is the region directly after our window. This does not inspect the buffer -- it only compares raw pointers.

fn extend_with<Buf: Iobuf>(&mut self, other: &Buf) -> Result<(), ()>

Attempts to extend an Iobuf with the contents of another Iobuf. If this Iobuf's window is not the region directly before the other Iobuf's window, no extension will be performed and Err(()) will be returned. If the operation was successful, Ok(()) will be returned.

fn resize(&mut self, len: u32) -> Result<(), ()>

Sets the length of the window, provided it does not exceed the limits.

unsafe fn unsafe_resize(&mut self, len: u32)

Sets the length of the window. No bounds checking will be performed.

fn split_at(&self, pos: u32) -> Result<(Self, Self), ()>

Splits an Iobuf around an index.

unsafe fn unsafe_split_at(&self, pos: u32) -> (Self, Self)

Like split_at, but does not perform bounds checking.

fn split_start_at(&mut self, pos: u32) -> Result<Self, ()>

Splits out the start of an Iobuf at an index.

unsafe fn unsafe_split_start_at(&mut self, pos: u32) -> Self

Like split_start_at, but does not perform bounds checking.

fn rewind(&mut self)

Sets the lower bound of the window to the lower limit.

fn reset(&mut self)

Sets the window to the limits.

fn flip_lo(&mut self)

Sets the window to range from the lower limit to the lower bound of the old window. This is typically called after a series of Fills, to reposition the window in preparation to Consume the newly written data.

fn flip_hi(&mut self)

Sets the window to range from the upper bound of the old window to the upper limit. This is a dual to flip_lo, and is typically called when the data in the current (narrowed) window has been processed and the window needs to be positioned over the remaining data in the buffer.

fn lo_space(&self) -> u32

Returns the number of bytes between the lower limit and the lower bound.

fn hi_space(&self) -> u32

Returns the number of bytes between the upper bound and the upper limit.

fn peek(&self, pos: u32, dst: &mut [u8]) -> Result<(), ()>

Reads the bytes at a given offset from the beginning of the window, into the supplied buffer. Either the entire buffer is filled, or an error is returned because bytes outside of the window were requested.

fn peek_be<T: IntLike>(&self, pos: u32) -> Result<T, ()>

Reads a big-endian primitive at a given offset from the beginning of the window.

fn peek_le<T: IntLike>(&self, pos: u32) -> Result<T, ()>

Reads a little-endian primitive at a given offset from the beginning of the window.

fn consume(&mut self, dst: &mut [u8]) -> Result<(), ()>

Reads bytes, starting from the front of the window, into the supplied buffer. Either the entire buffer is filled, or an error is returned because bytes outside the window were requested.

fn consume_be<T: IntLike>(&mut self) -> Result<T, ()>

Reads a big-endian primitive from the beginning of the window.

fn consume_le<T: IntLike>(&mut self) -> Result<T, ()>

Reads a little-endian primitive from the beginning of the window.

fn check_range(&self, pos: u32, len: u32) -> Result<(), ()>

Returns an Err(()) if the len bytes, starting at pos, are not all in the window. To be used with the try! macro.

fn check_range_usize(&self, pos: u32, len: usize) -> Result<(), ()>

The same as check_range, but with a usize length. If you're checking the range of something which might overflow an i32, use this version instead of check_range.

fn check_range_fail(&self, pos: u32, len: u32)

The same as check_range, but fails if the bounds check returns Err(()).

fn check_range_usize_fail(&self, pos: u32, len: usize)

The same as check_range_usize, but fails if the bounds check returns Err(()).

unsafe fn unsafe_peek(&self, pos: u32, dst: &mut [u8])

Reads the bytes at a given offset from the beginning of the window, into the supplied buffer. It is undefined behavior to read outside the iobuf window.

unsafe fn unsafe_peek_be<T: IntLike>(&self, pos: u32) -> T

Reads a big-endian primitive at a given offset from the beginning of the window. It is undefined behavior to read outside the iobuf window.

unsafe fn unsafe_peek_le<T: IntLike>(&self, pos: u32) -> T

Reads a little-endian primitive at a given offset from the beginning of the window. It is undefined behavior to read outside the iobuf window.

unsafe fn unsafe_consume(&mut self, dst: &mut [u8])

Reads bytes, starting from the front of the window, into the supplied buffer. After the bytes have been read, the window will be moved to no longer include then.

unsafe fn unsafe_consume_be<T: IntLike>(&mut self) -> T

Reads a big-endian primitive at the beginning of the window.

unsafe fn unsafe_consume_le<T: IntLike>(&mut self) -> T

Reads a little-endian primitive at the beginning of the window.

unsafe fn as_raw<'b>(&'b self) -> &'b RawIobuf<'b>

For internal use only.

fn invariant(&self) -> Result<(), Box<String>>

Checks internal state of the iobuf, to ensure that internal invariants are satisified. Returns Err(msg) if any invariant isn't satisfied.

fn ptr(&self) -> NonZero<*mut u8>

Gets a pointer to the start of the internal backing buffer. This is extremely low level, and it is not recommended you use this interface.

fn is_owned(&self) -> bool

Returns true if the Iobuf points to owned memory (i.e. has to do a refcount modification on clone or drop) or borrowed memory.

fn lo_min(&self) -> u32

Returns an index into the buffer returned by ptr that represents the inclusive lower bound of the limits.

fn lo(&self) -> u32

Returns an index into the buffer returned by ptr that represents the inclusive lower bound of the window.

fn hi(&self) -> u32

Returns an index into the buffer returned by ptr that represents the exclusive upper bound of the window.

fn hi_max(&self) -> u32

Returns an index into the buffer returned by ptr that represents the exclusive upper bound of the limits.

impl<'a> Debug for ROIobuf<'a>

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

Formats the value using the given formatter.