glibmm: Glib::VariantBase Class Reference

glibmm 2.89.0

Public Member Functions | Static Public Member Functions | Protected Attributes | Related Symbols | List of all members
Glib::VariantBase Class Reference
Variant Data Types

This is the base class for all Variant types. More...

`#include <glibmm/variant.h>`

Inheritance diagram for Glib::VariantBase:
[legend]

## Public Member Functions
| VariantBase ()
| Constructs an invalid object.
| 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.
| operator bool () const
| Test whether the Variant has an underlying instance.
void | init (const GVariant * cobject, bool take_a_reference=false)
| Replace the underlying GVariant.
VariantType | get_type () const
| Determines the type of value.
std::string | get_type_string () const
| Returns the type string of value.
bool | is_floating () const
| Checks whether value has a floating reference count.
bool | is_of_type (const VariantType & type) const
| Checks if a value has a type matching the provided type.
bool | is_container () const
| Checks if value is a container.
GVariantClass | classify () const
| Classifies value according to its top-level type.
gsize | get_size () const
| Determines the number of bytes that would be required to store value with g_variant_store().
gconstpointer | get_data () const
| Returns a pointer to the serialized form of a Variant instance.
Glib::RefPtr< const Glib::Bytes > | get_data_as_bytes () const
| Returns a pointer to the serialized form of a Variant instance.
void | store (gpointer data) const
| Stores the serialized form of value at data.
Glib::ustring | print (bool type_annotate=false) const
| Pretty-prints value in the format understood by g_variant_parse().
guint | hash () const
| Generates a hash value for a Variant instance.
bool | equal (const VariantBase & other) const
| Checks if *this and other have the same type and value.
bool | operator== (const VariantBase & other) const
| Checks if *this and other have the same type and value.
bool | operator!= (const VariantBase & other) const
| Checks if *this and other have the same type and value.
bool | operator< (const VariantBase & other) const =delete
| Ordering relational operators.
bool | operator<= (const VariantBase & other) const =delete
| See operator<().
bool | operator> (const VariantBase & other) const =delete
| See operator<().
bool | operator>= (const VariantBase & other) const =delete
| See operator<().
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.
bool | is_normal_form () const
| Checks if value is in normal form.
void | byteswap (VariantBase & result) const
| Performs a byteswapping operation on the contents of this variant.
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.
template<typename ValueType>
ValueType | get_dynamic () const
| Cast to a specific variant type and get the value.

## Static Public Member Functions
template<class V_CastTo>
static V_CastTo | cast_dynamic (const VariantBase & v)
| Cast to a specific variant type.
template<>
VariantContainerBase | cast_dynamic (const VariantBase & v)

## Protected Attributes
GVariant * | gobject_

## Related Symbols
(Note that these are not member symbols.)
template<typename T>
Variant< T > | create_variant (const T &data)
| Creates a Glib::Variant instance.
void | swap (VariantBase & lhs, VariantBase & rhs) noexcept
Glib::VariantBase | wrap (GVariant * object, bool take_copy=false)
| A Glib::wrap() method for this object.

## Detailed Description

This is the base class for all Variant types.

If the actual type is known at compile-time then you should use a specific Variant<>, such as Variant<int>. Otherwise, you may use get_type(), is_of_type(), cast_dynamic() or get_dynamic().

Since glibmm 2.28

## Constructor & Destructor Documentation

## ◆ VariantBase() [1/4]

Glib::VariantBase::VariantBase | ( |  | ) |

Constructs an invalid object.

E.g. for output arguments to methods. There is not much you can do with the object before it has been assigned a valid value.

## ◆ VariantBase() [2/4]

Glib::VariantBase::VariantBase | ( | GVariant * | castitem,
|  | bool | make_a_copy = false )
| explicit

## ◆ VariantBase() [3/4]

Glib::VariantBase::VariantBase | ( | const VariantBase & | src | ) |

## ◆ VariantBase() [4/4]

Glib::VariantBase::VariantBase | ( | VariantBase && | other | ) |
| noexcept

## ◆ ~VariantBase()

Glib::VariantBase::~VariantBase | ( |  | ) |
| noexcept

## Member Function Documentation

## ◆ byteswap()

void Glib::VariantBase::byteswap | ( | VariantBase & | result | ) | const

Performs a byteswapping operation on the contents of this variant.

The result is that all multi-byte numeric data contained in the variant is byteswapped. That includes 16, 32, and 64bit signed and unsigned integers as well as file handles and double precision floating point values.

This function is an identity mapping on any value that does not contain multi-byte numeric data. That include strings, booleans, bytes and containers containing only these things (recursively).

The returned value is always in normal form and is marked as trusted.

Parameters

  result | A location in which to store the byteswapped form of this variant.

Since glibmm 2.24

## ◆ cast_dynamic() [1/2]

template <>

VariantContainerBase Glib::VariantBase::cast_dynamic | ( | const VariantBase & | v | ) |
| static

## ◆ cast_dynamic() [2/2]

template <class V_CastTo>

V_CastTo Glib::VariantBase::cast_dynamic | ( | const VariantBase & | v | ) |
| static

Cast to a specific variant type.

For instance:

auto derived = Glib::VariantBase::cast_dynamic<Glib::Variant<std::string>>(base);
Glib::VariantBase::cast_dynamic
static V_CastTo cast_dynamic(const VariantBase &v)
Cast to a specific variant type.
Definition variant.h:615

Template Parameters

  V_CastTo | A subtype of VariantBase.

Parameters

  v | The variant to cast to a specific type.

Returns
  The variant as a specific type.

Exceptions

  std::bad_cast | if the Variant was not of the expected type.

## ◆ check_format_string()

bool Glib::VariantBase::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.

format_string is assumed to be a valid format string (from a syntactic standpoint).

If copy_only is true then this function additionally checks that it would be safe to call g_variant_unref() on value immediately after the call to g_variant_get() without invalidating the result. This is only possible if deep copies are made (ie: there are no pointers to the data inside of the soon-to-be-freed Variant instance). If this check fails then a Glib::critical() is printed and false is returned.

This function is meant to be used by functions that wish to provide varargs accessors to Variant values of uncertain values (eg: g_variant_lookup() or Glib::menu_model_get_item_attribute()).

Since glibmm 2.34

Parameters

  format_string | A valid Variant format string.
  copy_only | true to ensure the format string makes deep copies.

Returns
  true if format_string is safe to use.

## ◆ classify()

GVariantClass Glib::VariantBase::classify | ( |  | ) | const

Classifies value according to its top-level type.

Since glibmm 2.24

Returns
  The VariantClass of value.

## ◆ equal()

bool Glib::VariantBase::equal | ( | const VariantBase & | other | ) | const

Checks if *this and other have the same type and value.

Since glibmm 2.24

Parameters

  other | The Variant to compare with.

Returns
  true if *this and other are equal.

## ◆ get_data()

gconstpointer Glib::VariantBase::get_data | ( |  | ) | const

Returns a pointer to the serialized form of a Variant instance.

The returned data may not be in fully-normalised form if read from an untrusted source. The returned data must not be freed; it remains valid for as long as value exists.

If value is a fixed-sized value that was deserialized from a corrupted serialized container then nullptr may be returned. In this case, the proper thing to do is typically to use the appropriate number of nul bytes in place of value. If value is not fixed-sized then nullptr is never returned.

In the case that value is already in serialized form, this function is O(1). If the value is not already in serialized form, serialization occurs implicitly and is approximately O(n) in the size of the result.

To deserialize the data returned by this function, in addition to the serialized data, you must know the type of the Variant, and (if the machine might be different) the endianness of the machine that stored it. As a result, file formats or network messages that incorporate serialized Variants must include this information either implicitly (for instance "the file always contains a G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or explicitly (by storing the type and/or endianness in addition to the serialized data).

Since glibmm 2.46

Returns
  The serialized form of value, or nullptr.

## ◆ get_data_as_bytes()

Glib::RefPtr< const Glib::Bytes > Glib::VariantBase::get_data_as_bytes | ( |  | ) | const

Returns a pointer to the serialized form of a Variant instance.

The semantics of this function are exactly the same as g_variant_get_data(), except that the returned Bytes holds a reference to the variant data.

Since glibmm 2.46

Returns
  A new Bytes representing the variant data.

## ◆ get_dynamic()

template <typename ValueType>

ValueType Glib::VariantBase::get_dynamic | ( |  | ) | const

Cast to a specific variant type and get the value.

For instance:

auto str = variant_base.get_dynamic<std::string>();
std::string
basic_string< char > string

If you have a Variant<T> instance of the correct type, use its get() method instead. It's easier and faster.

Since glibmm 2.78

Template Parameters

  ValueType | The expected type of the variant's value.

Returns
  The value of the variant.

Exceptions

  std::invalid_argument | if *this is empty (does not contain a GVariant).
  std::bad_cast | if *this could not be cast to Variant<ValueType>.

## ◆ get_normal_form()

void Glib::VariantBase::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.

If this variant is already trusted to be in normal form then a new reference to the variant is returned.

If this variant is not already trusted, then it is scanned to check if it is in normal form. If it is found to be in normal form then it is marked as trusted and a new reference to it is returned.

If this variant is found not to be in normal form then a new trusted VariantBase is created with the same value as this variant.

It makes sense to call this function if you've received variant data from untrusted sources and you want to ensure your serialised output is definitely in normal form.

Parameters

  result | A location in which to store the trusted VariantBase.

Since glibmm 2.24

## ◆ get_size()

gsize Glib::VariantBase::get_size | ( |  | ) | const

Determines the number of bytes that would be required to store value with g_variant_store().

If value has a fixed-sized type then this function always returned that fixed size.

In the case that value is already in serialized form or the size has already been calculated (ie: this function has been called before) then this function is O(1). Otherwise, the size is calculated, an operation which is approximately O(n) in the number of values involved.

Since glibmm 2.24

Returns
  The serialized size of value.

## ◆ get_type()

VariantType Glib::VariantBase::get_type | ( |  | ) | const

Determines the type of value.

The return value is valid for the lifetime of value and must not be freed.

Since glibmm 2.24

Returns
  A VariantType.

## ◆ get_type_string()

std::string Glib::VariantBase::get_type_string | ( |  | ) | const

Returns the type string of value.

Unlike the result of calling g_variant_type_peek_string(), this string is nul-terminated. This string belongs to Variant and must not be freed.

Since glibmm 2.24

Returns
  The type string for the type of value.

## ◆ gobj() [1/2]

GVariant * Glib::VariantBase::gobj | ( |  | ) |
| inline

## ◆ gobj() [2/2]

const GVariant * Glib::VariantBase::gobj | ( |  | ) | const
| inline

## ◆ gobj_copy()

GVariant * Glib::VariantBase::gobj_copy | ( |  | ) | const

Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs.

## ◆ hash()

guint Glib::VariantBase::hash | ( |  | ) | const

Generates a hash value for a Variant instance.

The output of this function is guaranteed to be the same for a given value only per-process. It may change between different processor architectures or even different versions of GLib. Do not use this function as a basis for building protocols or file formats.

The type of value is #gconstpointer only to allow use of this function with HashTable. value must be a Variant.

Since glibmm 2.24

Returns
  A hash value corresponding to value.

## ◆ init()

void Glib::VariantBase::init | ( | const GVariant * | cobject,
|  | bool | take_a_reference = false )

Replace the underlying GVariant.

This is for use by methods that take a VariantBase& as an output parameter.

Parameters

  cobject | The GVariant* obtained from a C function.
  take_a_reference | Whether this method should take a reference, for instance if the C function has not given one.

## ◆ is_container()

bool Glib::VariantBase::is_container | ( |  | ) | const

Checks if value is a container.

Since glibmm 2.24

Returns
  true if value is a container.

## ◆ is_floating()

bool Glib::VariantBase::is_floating | ( |  | ) | const

Checks whether value has a floating reference count.

This function should only ever be used to assert that a given variant is or is not floating, or for debug purposes. To acquire a reference to a variant that might be floating, always use g_variant_ref_sink() or g_variant_take_ref().

See g_variant_ref_sink() for more information about floating reference counts.

Since glibmm 2.26

Returns
  Whether value is floating.

## ◆ is_normal_form()

bool Glib::VariantBase::is_normal_form | ( |  | ) | const

Checks if value is in normal form.

The main reason to do this is to detect if a given chunk of serialized data is in normal form: load the data into a Variant using g_variant_new_from_data() and then use this function to check.

If value is found to be in normal form then it will be marked as being trusted. If the value was already marked as being trusted then this function will immediately return true.

There may be implementation specific restrictions on deeply nested values. GVariant is guaranteed to handle nesting up to at least 64 levels.

Since glibmm 2.24

Returns
  true if value is in normal form.

## ◆ is_of_type()

bool Glib::VariantBase::is_of_type | ( | const VariantType & | type | ) | const

Checks if a value has a type matching the provided type.

Since glibmm 2.24

Parameters

  type | A VariantType.

Returns
  true if the type of value matches type.

## ◆ operator bool()

Glib::VariantBase::operator bool | ( |  | ) | const
| explicit

Test whether the Variant has an underlying instance.

Since glibmm 2.50

## ◆ operator!=()

bool Glib::VariantBase::operator!= | ( | const VariantBase & | other | ) | const

Checks if *this and other have the same type and value.

Since glibmm 2.58

Parameters

  other | The Variant to compare with.

Returns
  true if *this and other are not equal.

## ◆ operator<()

bool Glib::VariantBase::operator< | ( | const VariantBase & | other | ) | const
| delete

Ordering relational operators.

These are explicitly deleted to prevent the compiler from generating error messages containing long lists of operators that can't be used.

## ◆ operator<=()

bool Glib::VariantBase::operator<= | ( | const VariantBase & | other | ) | const
| delete

See operator<().

## ◆ operator=() [1/2]

VariantBase & Glib::VariantBase::operator= | ( | const VariantBase & | src | ) |

## ◆ operator=() [2/2]

VariantBase & Glib::VariantBase::operator= | ( | VariantBase && | other | ) |
| noexcept

## ◆ operator==()

bool Glib::VariantBase::operator== | ( | const VariantBase & | other | ) | const

Checks if *this and other have the same type and value.

Since glibmm 2.58

Parameters

  other | The Variant to compare with.

Returns
  true if *this and other are equal.

## ◆ operator>()

bool Glib::VariantBase::operator> | ( | const VariantBase & | other | ) | const
| delete

See operator<().

## ◆ operator>=()

bool Glib::VariantBase::operator>= | ( | const VariantBase & | other | ) | const
| delete

See operator<().

## ◆ print()

Glib::ustring Glib::VariantBase::print | ( | bool | type_annotate = false | ) | const

Pretty-prints value in the format understood by g_variant_parse().

The format is described here.

If type_annotate is true, then type information is included in the output.

Since glibmm 2.24

Parameters

  type_annotate | true if type information should be included in the output.

Returns
  A newly-allocated string holding the result.

## ◆ store()

void Glib::VariantBase::store | ( | gpointer | data | ) | const

Stores the serialized form of value at data.

data should be large enough. See g_variant_get_size().

The stored data is in machine native byte order but may not be in fully-normalised form if read from an untrusted source. See g_variant_get_normal_form() for a solution.

As with g_variant_get_data(), to be able to deserialize the serialized variant successfully, its type and (if the destination machine might be different) its endianness must also be available.

This function is approximately O(n) in the size of data.

Since glibmm 2.24

Parameters

  data | The location to store the serialized data at.

## ◆ swap()

void Glib::VariantBase::swap | ( | VariantBase & | other | ) |
| noexcept

## Friends And Related Symbol Documentation

## ◆ swap()

void swap | ( | VariantBase & | lhs,
|  | VariantBase & | rhs )
| related

Parameters

  lhs | The left-hand side
  rhs | The right-hand side

## ◆ wrap()

Glib::VariantBase wrap | ( | GVariant * | object,
|  | bool | take_copy = false )
| related

A Glib::wrap() method for this object.

Parameters

  object | The C instance.
  take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns
  A C++ instance that wraps this C instance.

## Member Data Documentation

## ◆ gobject_

GVariant* Glib::VariantBase::gobject_
| protected