Module glib::variant

Variant binding and helper traits.

Variant is an immutable dynamically-typed generic container. Its type and value are defined at construction and never change.

Variant types are described by VariantType “type strings”.

GVariant supports arbitrarily complex types built from primitives like integers, floating point numbers, strings, arrays, tuples and dictionaries. See ToVariant for a full list of supported types. You may also implement ToVariant and FromVariant manually, or derive them using the Variant derive macro.

Portability Warning

Variant conversion traits are also implemented for certain platform-specific data types from the standard library like PathBuf and OsString. These types will be serialized to their platform-specific representation and should not be deserialized on a different machine from where they were serialized.

Examples

use glib::prelude::*; // or `use gtk::prelude::*;`
use glib::{Variant, FromVariant, ToVariant};
use std::collections::HashMap;

// Using the `ToVariant` trait.
let num = 10.to_variant();

// `is` tests the type of the value.
assert!(num.is::<i32>());

// `get` tries to extract the value.
assert_eq!(num.get::<i32>(), Some(10));
assert_eq!(num.get::<u32>(), None);

// `get_str` tries to borrow a string slice.
let hello = "Hello!".to_variant();
assert_eq!(hello.str(), Some("Hello!"));
assert_eq!(num.str(), None);

// `fixed_array` tries to borrow a fixed size array (u8, bool, i16, etc.),
// rather than creating a deep copy which would be expensive for
// nontrivially sized arrays of fixed size elements.
// The test data here is the zstd compression header, which
// stands in for arbitrary binary data (e.g. not UTF-8).
let bufdata = b"\xFD\x2F\xB5\x28";
let bufv = glib::Variant::array_from_fixed_array(&bufdata[..]);
assert_eq!(bufv.fixed_array::<u8>().unwrap(), bufdata);
assert!(num.fixed_array::<u8>().is_err());

// Variant carrying a Variant
let variant = Variant::from_variant(&hello);
let variant = variant.as_variant().unwrap();
assert_eq!(variant.str(), Some("Hello!"));

// Variant carrying an array
let array = ["Hello", "there!"];
let variant = array.into_iter().collect::<Variant>();
assert_eq!(variant.n_children(), 2);
assert_eq!(variant.child_value(0).str(), Some("Hello"));
assert_eq!(variant.child_value(1).str(), Some("there!"));

// You can also convert from and to a Vec
let variant = vec!["Hello", "there!"].to_variant();
assert_eq!(variant.n_children(), 2);
let vec = <Vec<String>>::from_variant(&variant).unwrap();
assert_eq!(vec[0], "Hello");

// Conversion to and from HashMap and BTreeMap is also possible
let mut map: HashMap<u16, &str> = HashMap::new();
map.insert(1, "hi");
map.insert(2, "there");
let variant = map.to_variant();
assert_eq!(variant.n_children(), 2);
let map: HashMap<u16, String> = HashMap::from_variant(&variant).unwrap();
assert_eq!(map[&1], "hi");
assert_eq!(map[&2], "there");

// And conversion to and from tuples.
let variant = ("hello", 42u16, vec![ "there", "you" ],).to_variant();
assert_eq!(variant.n_children(), 3);
assert_eq!(variant.type_().as_str(), "(sqas)");
let tuple = <(String, u16, Vec<String>)>::from_variant(&variant).unwrap();
assert_eq!(tuple.0, "hello");
assert_eq!(tuple.1, 42);
assert_eq!(tuple.2, &[ "there", "you"]);

// `Option` is supported as well, through maybe types
let variant = Some("hello").to_variant();
assert_eq!(variant.n_children(), 1);
let mut s = <Option<String>>::from_variant(&variant).unwrap();
assert_eq!(s.unwrap(), "hello");
s = None;
let variant = s.to_variant();
assert_eq!(variant.n_children(), 0);
let s = <Option<String>>::from_variant(&variant).unwrap();
assert!(s.is_none());

// Paths may be converted, too. Please note the portability warning above!
use std::path::{Path, PathBuf};
let path = Path::new("foo/bar");
let path_variant = path.to_variant();
assert_eq!(PathBuf::from_variant(&path_variant).as_deref(), Some(path));

Structs

DictEntry

A Dictionary entry.

FixedSizeVariantArray

Wrapper type for fixed size type arrays.

Variant

A generic immutable value capable of carrying various types.

VariantTypeMismatchError

An error returned from the try_get function on a Variant when the expected type does not match the actual type.

Traits

FixedSizeVariantType

Trait for fixed size variant types.

FromVariant

Extracts a value.

StaticVariantType

Returns VariantType of Self.

ToVariant

Converts to Variant.