glibmm: Glib::VariantContainerBase Class Reference

glibmm 2.68.1

Public Types | Public Member Functions | Static Public Member Functions | List of all members
Glib::VariantContainerBase Class Reference
Variant Data Types

The base class for multiple-item Variants, such as Variants containing tuples or arrays, and also for maybe-typed (that is, nullable) Variant types. More...

`#include <glibmm/variant.h>`

Inheritance diagram for Glib::VariantContainerBase:
[legend]

## Public Types
using | CType = GVariant*
using | CppType = VariantContainerBase

## Public Member Functions
| VariantContainerBase ()
| Default constructor. More...
| VariantContainerBase (GVariant* castitem, bool take_a_reference=false)
| GVariant constructor. More...
gsize | get_n_children () const
| Determines the number of children in a container Variant instance. More...
void | get_child (VariantBase& child, gsize index=0) const
| Reads a child item out of this instance. More...
VariantBase | get_child (gsize index=0)
| Reads a child item out of a container Variant instance. More...
bool | get_maybe (VariantBase& maybe) const
| If this is a maybe-typed instance, try to extract its value. More...
Public Member Functions inherited from Glib::VariantBase
| VariantBase ()
| Constructs an invalid object. More...
| VariantBase (GVariant* castitem, bool make_a_copy=false)
| VariantBase (const VariantBase& src)
VariantBase& | operator= (const VariantBase& src)
| VariantBase (VariantBase&& other) noexcept
VariantBase& | operator= (VariantBase&& other) noexcept
| ~VariantBase () noexcept
void | swap (VariantBase& other) noexcept
GVariant* | gobj ()
const GVariant* | gobj () const
GVariant* | gobj_copy () const
| Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs. More...
| operator bool () const
| Test whether the Variant has an underlying instance. More...
void | init (const GVariant* cobject, bool take_a_reference=false)
| Replace the underlying GVariant. More...
VariantType | get_type () const
| Determines the type of value. More...
std::string | get_type_string () const
| Returns the type string of value. More...
bool | is_floating () const
| Checks whether value has a floating reference count. More...
bool | is_of_type (const VariantType& type) const
| Checks if a value has a type matching the provided type. More...
bool | is_container () const
| Checks if value is a container. More...
GVariantClass | classify () const
| Classifies value according to its top-level type. More...
gsize | get_size () const
| Determines the number of bytes that would be required to store value with g_variant_store(). More...
gconstpointer | get_data () const
| Returns a pointer to the serialised form of a Variant instance. More...
Glib::RefPtr< const Glib::Bytes > | get_data_as_bytes () const
| Returns a pointer to the serialised form of a Variant instance. More...
void | store (gpointer data) const
| Stores the serialised form of value at data. More...
Glib::ustring | print (bool type_annotate=false) const
| Pretty-prints value in the format understood by g_variant_parse(). More...
guint | hash () const
| Generates a hash value for a Variant instance. More...
bool | equal (const VariantBase& other) const
| Checks if *this and other have the same type and value. More...
bool | operator== (const VariantBase& other) const
| Checks if *this and other have the same type and value. More...
bool | operator!= (const VariantBase& other) const
| Checks if *this and other have the same type and value. More...
bool | operator< (const VariantBase& other) const =delete
| Ordering relational operators. More...
bool | operator<= (const VariantBase& other) const =delete
| See operator<(). More...
bool | operator> (const VariantBase& other) const =delete
| See operator<(). More...
bool | operator>= (const VariantBase& other) const =delete
| See operator<(). More...
void | get_normal_form (VariantBase& result) const
| Gets a VariantBase instance that has the same value as this variant and is trusted to be in normal form. More...
bool | is_normal_form () const
| Checks if value is in normal form. More...
void | byteswap (VariantBase& result) const
| Performs a byteswapping operation on the contents of this variant. More...
bool | check_format_string (const std::string& format_string, bool copy_only=false) const
| Checks if calling g_variant_get() with format_string on value would be valid from a type-compatibility standpoint. More...

## Static Public Member Functions
static VariantContainerBase | create_tuple (const std::vector< VariantBase >& children)
| Create a tuple variant from a vector of its variant children. More...
static VariantContainerBase | create_tuple (const VariantBase& child)
| Create a tuple variant with a single variant child. More...
static VariantContainerBase | create_maybe (const VariantType& child_type, const VariantBase& child={})
| Depending on if child is `nullptr`, either wraps child inside of a maybe container or creates a Nothing instance for the given type. More...
Static Public Member Functions inherited from Glib::VariantBase
template<class V_CastTo >
static V_CastTo | cast_dynamic (const VariantBase& v)
| Cast to a specific variant type. More...
template<>
VariantContainerBase | cast_dynamic (const VariantBase& v)

## Additional Inherited Members
Protected Attributes inherited from Glib::VariantBase
GVariant* | gobject_
Related Functions inherited from Glib::VariantBase
void | swap (VariantBase& lhs, VariantBase& rhs) noexcept
Glib::VariantBase | wrap (GVariant* object, bool take_copy=false)
| A Glib::wrap() method for this object. More...

## Detailed Description

The base class for multiple-item Variants, such as Variants containing tuples or arrays, and also for maybe-typed (that is, nullable) Variant types.

Since glibmm 2.28:

## Member Typedef Documentation

## ◆ CppType

using Glib::VariantContainerBase::CppType = VariantContainerBase

## ◆ CType

using Glib::VariantContainerBase::CType = GVariant*

## Constructor & Destructor Documentation

## ◆ VariantContainerBase() [1/2]

Glib::VariantContainerBase::VariantContainerBase | ( |  | ) |

Default constructor.

## ◆ VariantContainerBase() [2/2]

Glib::VariantContainerBase::VariantContainerBase | ( | GVariant * | castitem,
|  | bool | take_a_reference = `false`
| ) |  |
| explicit

GVariant constructor.

Parameters

  castitem | The GVariant to wrap.
  take_a_reference | Whether to take an extra reference of the GVariant or not (not taking one could destroy the GVariant with the wrapper).

## Member Function Documentation

## ◆ create_maybe()

static VariantContainerBase Glib::VariantContainerBase::create_maybe | ( | const VariantType& | child_type,
|  | const VariantBase& | child = `{}`
| ) |  |
| static

Depending on if child is `nullptr`, either wraps child inside of a maybe container or creates a Nothing instance for the given type.

At least one of child_type and child must be non-`nullptr`. If child_type is non-`nullptr` then it must be a definite type. If they are both non-`nullptr` then child_type must be the type of child.

If child is a floating reference (see g_variant_ref_sink()), the new instance takes ownership of child.

Since glibmm 2.24:

Parameters

  child_type | The VariantType of the child, or `nullptr`.
  child | The child value, or `nullptr`.

Returns
  A floating reference to a new Variant maybe instance.

## ◆ create_tuple() [1/2]

static VariantContainerBase Glib::VariantContainerBase::create_tuple | ( | const std::vector< VariantBase >& | children | ) |
| static

Create a tuple variant from a vector of its variant children.

Parameters

  children | The vector containing the children of the container.

Returns
  The newly created tuple variant (as a VariantContainerBase).

## ◆ create_tuple() [2/2]

static VariantContainerBase Glib::VariantContainerBase::create_tuple | ( | const VariantBase& | child | ) |
| static

Create a tuple variant with a single variant child.

Parameters

  child | The child variant.

Returns
  The newly created tuple variant (as a VariantContainerBase).

## ◆ get_child() [1/2]

VariantBase Glib::VariantContainerBase::get_child | ( | gsize | index = `0` | ) |

Reads a child item out of a container Variant instance.

This includes variants, maybes, arrays, tuples and dictionary entries. It is an error to call this function on any other type of Variant.

It is an error if index is greater than the number of child items in the container. See g_variant_n_children().

The returned value is never floating. You should free it with g_variant_unref() when you're done with it.

Note that values borrowed from the returned child are not guaranteed to still be valid after the child is freed even if you still hold a reference to value, if value has not been serialised at the time this function is called. To avoid this, you can serialize value by calling g_variant_get_data() and optionally ignoring the return value.

There may be implementation specific restrictions on deeply nested values, which would result in the unit tuple being returned as the child value, instead of further nested children. Variant is guaranteed to handle nesting up to at least 64 levels.

This function is O(1).

Since glibmm 2.24:

Parameters

  index | The index of the child to fetch.

Returns
  The child at the specified index.

## ◆ get_child() [2/2]

void Glib::VariantContainerBase::get_child | ( | VariantBase& | child,
|  | gsize | index = `0`
| ) |  | const

Reads a child item out of this instance.

This method is valid for variants, maybes, arrays, tuples and dictionary entries.

It is an error if index is greater than the number of child items in the container. See get_n_children().

This function is O(1).

Parameters

  index | The index of the child to fetch.
  child | A location in which to store the child at the specified index.

Exceptions

  std::out_of_range |

Since glibmm 2.28:

## ◆ get_maybe()

bool Glib::VariantContainerBase::get_maybe | ( | VariantBase& | maybe | ) | const

If this is a maybe-typed instance, try to extract its value.

If there is no value (the value is `nothing`), return `false`. Otherwise, the value is copied to the supplied Variant and `true` is returned.

Parameters

  maybe | A place in which to return the value, if it isn’t `nothing`.

Since glibmm 2.28:

## ◆ get_n_children()

gsize Glib::VariantContainerBase::get_n_children | ( |  | ) | const

Determines the number of children in a container Variant instance.

This includes variants, maybes, arrays, tuples and dictionary entries. It is an error to call this function on any other type of Variant.

For variants, the return value is always 1. For values with maybe types, it is always zero or one. For arrays, it is the length of the array. For tuples it is the number of tuple items (which depends only on the type). For dictionary entries, it is always 2

This function is O(1).

Since glibmm 2.24:

Returns
  The number of children in the container.