Struct ZBytes 

pub struct ZBytes(/* private fields */);

ZBytes contains the raw bytes data.

This type is intended to represent the data payload with minimized copying. Zenoh may construct a single ZBytes instance from pointers to multiple buffers in cases where data is received fragmented from the network.

To directly access raw data as a contiguous slice, it is preferable to convert ZBytes into a [std::borrow::Cow<[u8]>] using to_bytes. If ZBytes contains all the data in a single memory location, this is guaranteed to be zero-copy. This is the common case for small messages. If ZBytes contains data scattered in different memory regions, this operation will do an allocation and a copy. This is the common case for large messages.

It is also possible to iterate over the raw data that may be scattered across different memory regions using slices.

Another way to access raw data is to use a ZBytesReader obtained from reader that implements the standard std::io::Read trait. This is useful when deserializing data using libraries that operate on std::io::Read.

The creation of a ZBytes instance using the std::io::Write trait is also possible using the static writer method that creates a ZBytesWriter.

Examples

ZBytes can be converted from/to raw bytes:

use std::borrow::Cow;
use zenoh::bytes::ZBytes;

let buf = b"some raw bytes";
let payload = ZBytes::from(buf);
assert_eq!(payload.to_bytes(), buf.as_slice());

Create a ZBytes with a writer and read it back with a reader:

use std::io::{Read, Write};
use zenoh::bytes::ZBytes;

let mut writer = ZBytes::writer();
writer.write_all(b"some raw bytes").unwrap();
let payload = writer.finish();
let mut reader = payload.reader();
let mut buf = [0; 14];
reader.read_exact(&mut buf).unwrap();
assert_eq!(&buf, b"some raw bytes");

Implementations

impl ZBytes

pub const fn new() -> Self

Create an empty ZBytes.

pub fn is_empty(&self) -> bool

Returns whether the ZBytes is empty or not.

pub fn len(&self) -> usize

Returns the total number of bytes in the ZBytes.

pub fn to_bytes(&self) -> Cow<'_, [u8]>

Access raw bytes contained in the ZBytes.

In the case ZBytes contains non-contiguous regions of memory, an allocation and a copy will be done; that’s why the method returns a Cow. It’s also possible to use ZBytes::slices instead to avoid this copy.

pub fn try_to_string(&self) -> Result<Cow<'_, str>, Utf8Error>

Tries to access a string contained in the ZBytes, and fails if it contains non-UTF-8 bytes.

In the case ZBytes contains non-contiguous regions of memory, an allocation and a copy will be done; that’s why the method returns a Cow. It’s also possible to use ZBytes::slices instead to avoid this copy, but then the UTF-8 check has to be done manually.

pub fn reader(&self) -> ZBytesReader<'_>

Get a ZBytesReader implementing the std::io::Read trait.

See ZBytesWriter on how to chain the deserialization of different types from a single ZBytes.

pub fn from_reader<R>(reader: R) -> Result<Self, Error>

where R: Read,

Build a ZBytes from a generic reader implementing std::io::Read. This operation copies data from the reader.

pub fn writer() -> ZBytesWriter

Get a ZBytesWriter implementing std::io::Write trait.

See ZBytesWriter on how to chain the serialization of different types into a single ZBytes.

pub fn slices(&self) -> ZBytesSliceIterator<'_>

Return an iterator over raw byte slices contained in the ZBytes.

ZBytes may store data in non-contiguous regions of memory; this iterator then allows accessing raw data directly without any attempt at deserializing it. Please note that no guarantee is provided on the internal memory layout of ZBytes. The only provided guarantee is that the byte order is preserved.

use std::io::Write;
use zenoh::bytes::ZBytes;

let buf1: Vec<u8> = vec![1, 2, 3];
let buf2: Vec<u8> = vec![4, 5, 6, 7, 8];
let mut writer = ZBytes::writer();
writer.write(&buf1);
writer.write(&buf2);
let zbytes = writer.finish();

// Access the raw content
for slice in zbytes.slices() {
    println!("{:02x?}", slice);
}

// Concatenate input in a single vector
let buf: Vec<u8> = buf1.into_iter().chain(buf2.into_iter()).collect();
// Concatenate raw bytes in a single vector
let out: Vec<u8> = zbytes.slices().fold(Vec::new(), |mut b, x| { b.extend_from_slice(x); b });
// The previous line is the equivalent of
// let out: Vec<u8> = zbs.into();
assert_eq!(buf, out);

The example below shows how the ZBytesWriter::append simply appends the slices of one ZBytes to another and how those slices can be iterated over to access the raw data.

use std::io::Write;
use zenoh::bytes::ZBytes;

let buf1: Vec<u8> = vec![1, 2, 3];
let buf2: Vec<u8> = vec![4, 5, 6, 7, 8];

let mut writer = ZBytes::writer();
writer.append(ZBytes::from(buf1.clone()));
writer.append(ZBytes::from(buf2.clone()));
let zbytes = writer.finish();

let mut iter = zbytes.slices();
assert_eq!(buf1.as_slice(), iter.next().unwrap());
assert_eq!(buf2.as_slice(), iter.next().unwrap());

impl ZBytes

pub fn as_shm(&self) -> Option<&zshm>

Available on crate features unstable and shared-memory only.

pub fn as_shm_mut(&mut self) -> Option<&mut zshm>

Available on crate features unstable and shared-memory only.

Trait Implementations

impl Clone for ZBytes

fn clone(&self) -> ZBytes

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ZBytes

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

Formats the value using the given formatter.

impl Default for ZBytes

fn default() -> ZBytes

Returns the “default value” for a type.

impl From<&[u8]> for ZBytes

fn from(value: &[u8]) -> Self

Converts to this type from the input type.

impl<const N: usize> From<&[u8; N]> for ZBytes

fn from(value: &[u8; N]) -> Self

Converts to this type from the input type.

impl From<&Cow<'_, [u8]>> for ZBytes

fn from(value: &Cow<'_, [u8]>) -> Self

Converts to this type from the input type.

impl From<&Cow<'_, str>> for ZBytes

fn from(value: &Cow<'_, str>) -> Self

Converts to this type from the input type.

impl From<&String> for ZBytes

fn from(value: &String) -> Self

Converts to this type from the input type.

impl From<&Vec<u8>> for ZBytes

fn from(value: &Vec<u8>) -> Self

Converts to this type from the input type.

impl From<&str> for ZBytes

fn from(value: &str) -> Self

Converts to this type from the input type.

impl<const N: usize> From<[u8; N]> for ZBytes

fn from(value: [u8; N]) -> Self

Converts to this type from the input type.

impl<const ID: u8> From<AttachmentType<ID>> for ZBytes

fn from(this: AttachmentType<ID>) -> Self

Converts to this type from the input type.

impl From<Bytes> for ZBytes

fn from(value: Bytes) -> Self

Converts to this type from the input type.

impl From<Cow<'_, [u8]>> for ZBytes

fn from(value: Cow<'_, [u8]>) -> Self

Converts to this type from the input type.

impl From<Cow<'_, str>> for ZBytes

fn from(value: Cow<'_, str>) -> Self

Converts to this type from the input type.

impl From<String> for ZBytes

fn from(value: String) -> Self

Converts to this type from the input type.

impl<T, Buf: Into<ZBytes>> From<Typed<T, Buf>> for ZBytes

Available on crate features unstable and shared-memory only.

fn from(value: Typed<T, Buf>) -> Self

Converts to this type from the input type.

impl From<Vec<u8>> for ZBytes

fn from(value: Vec<u8>) -> Self

Converts to this type from the input type.

impl From<ZBuf> for ZBytes

fn from(value: ZBuf) -> Self

Converts to this type from the input type.

impl<const ID: u8> From<ZBytes> for AttachmentType<ID>

fn from(this: ZBytes) -> Self

Converts to this type from the input type.

impl From<ZBytes> for ZBuf

fn from(value: ZBytes) -> Self

Converts to this type from the input type.

impl From<ZBytesWriter> for ZBytes

fn from(value: ZBytesWriter) -> Self

Converts to this type from the input type.

impl From<ZShm> for ZBytes

Available on crate features unstable and shared-memory only.

fn from(value: ZShm) -> Self

Converts to this type from the input type.

impl From<ZShmMut> for ZBytes

Available on crate features unstable and shared-memory only.

fn from(value: ZShmMut) -> Self

Converts to this type from the input type.

impl PartialEq for ZBytes

fn eq(&self, other: &ZBytes) -> 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 Eq for ZBytes

impl StructuralPartialEq for ZBytes