Struct zvariant::Structure

pub struct Structure(_);

An ordered collection of items of arbitrary types.

This is mostly just a way to support custom data structures. In the future, we'll hopefully provide a way to easily map a Rust struct into a Structure (probably through an attribute macro).

Example

use core::convert::TryInto;

use zvariant::{Array, Decode, Encode, EncodingFormat};
use zvariant::Structure;

// Create a complex structure
let top_struct = Structure::new()
    // top-most simple fields
    .add_field(u8::max_value())
    .add_field(u32::max_value())
    // top-most inner structure
    .add_field(
        Structure::new()
            // 2nd level simple fields
            .add_field(i64::max_value())
            .add_field(true)
            .add_field(i64::max_value())
            // 2nd level array field
            .add_field(Array::from(vec!["Hello", "World"])),
    )
    // one more top-most simple field
    .add_field("hello");
assert!(top_struct.signature() == "(yu(xbxas)s)");

// Encode it
let format = EncodingFormat::default();
let encoding = top_struct.encode(format);
assert!(encoding.len() == 70);

// Then decode it
let top_struct = Structure::decode(encoding, top_struct.signature(), format).unwrap();

// Now check if everything is as expected
let fields = top_struct.fields();

// top-most simple fields
assert!(*u8::from_variant(&fields[0]).unwrap() == u8::max_value());
assert!(*u32::from_variant(&fields[1]).unwrap() == u32::max_value());
assert!(String::from_variant(&fields[3]).unwrap() == "hello");

// top-most inner structure
let inner = Structure::from_variant(&fields[2]).unwrap();
let inner_fields = inner.fields();

// 2nd level simple fields
assert!(*i64::from_variant(&inner_fields[0]).unwrap() == i64::max_value());
assert!(*bool::from_variant(&inner_fields[1]).unwrap() == true);

// 2nd level array field
let array = Array::from_variant(&inner_fields[3]).unwrap();
let as_: Vec<&String> = array.try_into().unwrap();
assert!(as_ == ["Hello", "World"]);

Methods

impl Structure

pub fn take_fields(self) -> Vec<Variant>

Get all the fields, consuming self.

pub fn fields(&self) -> &[Variant]

Get a reference to all the fields of self.

pub fn new() -> Self

Create a new Structure.

Same as Structure::default().

pub fn add_field<T>(self, field: T) -> Self where
    T: Encode, 

Append field to self.

This method returns Self so that you can use the builder pattern to create a complex structure.

Trait Implementations

impl Clone for Structure

fn clone(&self) -> Structure

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Structure

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

Formats the value using the given formatter.

impl Decode for Structure

fn slice_data(
    data: impl Into<SharedData>,
    signature: impl Into<Signature>,
    format: EncodingFormat
) -> Result<SharedData, VariantError>

Get the slice of data that belongs to implementing type.

fn decode(
    data: impl Into<SharedData>,
    signature: impl Into<Signature>,
    format: EncodingFormat
) -> Result<Self, VariantError>

Decode instance of implementing type from the data slice.

fn ensure_correct_signature(
    signature: impl Into<Signature>
) -> Result<Signature, VariantError>

Ensure given signature is correct and of the implementing type.

fn slice_signature(
    signature: impl Into<Signature>
) -> Result<Signature, VariantError>

Get the slice of signature that belongs to implementing type.

fn take_from_variant(variant: Variant) -> Result<Self, VariantError>

Flatten the variant to enclosed value of the implementing type.

fn from_variant(variant: &Variant) -> Result<&Self, VariantError>

Flatten the variant reference to a reference of the enclosed value of the implementing type.

fn slice_for_decoding(
    data: impl Into<SharedData>,
    signature: impl Into<Signature>,
    format: EncodingFormat
) -> Result<SharedData, VariantError>

A helper for [decode] implementation. Removes any leading padding bytes.

impl Default for Structure

fn default() -> Structure

Returns the "default value" for a type.

impl Encode for Structure

const SIGNATURE_CHAR: char

The signature charachter of the implementing type.

const SIGNATURE_STR: &'static str

The signature charachter of the implementing type, in string format.

const ALIGNMENT: usize

The alignment required for encoding of the implementing type, as number of bytes.

fn encode_into(&self, bytes: &mut Vec<u8>, format: EncodingFormat)

Encode self and append to the end of bytes buffer.

fn signature(&self) -> Signature

Get the signature.

fn to_variant(self) -> Variant

Unflatten self into a [Variant].

fn is(variant: &Variant) -> bool

Checks if variant value is of the generic type T.

fn encode(&self, format: EncodingFormat) -> Vec<u8>

Encode self into a new byte buffer and return it.

fn add_padding(bytes: &mut Vec<u8>, format: EncodingFormat)

Append required padding to bytes buffer.

fn padding(n_bytes_before: usize, _format: EncodingFormat) -> usize

The required padding for the implementing type.