#[repr(transparent)]
pub struct Structure(_);
Expand description

A Structure is a collection of key/value pairs. The keys are expressed as GQuarks and the values can be of any GType.

In addition to the key/value pairs, a Structure also has a name. The name starts with a letter and can be filled by letters, numbers and any of “/-_.:”.

Structure is used by various GStreamer subsystems to store information in a flexible and extensible way. A Structure does not have a refcount because it usually is part of a higher level object such as Caps, Message, Event, Query. It provides a means to enforce mutability using the refcount of the parent with the gst_structure_set_parent_refcount() method.

A Structure can be created with new_empty() or new(), which both take a name and an optional set of key/value pairs along with the types of the values.

Field values can be changed with gst_structure_set_value() or gst_structure_set().

Field values can be retrieved with gst_structure_get_value() or the more convenient gst_structure_get_*() functions.

Fields can be removed with gst_structure_remove_field() or gst_structure_remove_fields().

Strings in structures must be ASCII or UTF-8 encoded. Other encodings are not allowed. Strings may be None however.

The serialization format

GstStructure serialization format serialize the GstStructure name, keys/GType/values in a comma separated list with the structure name as first field without value followed by separated key/value pairs in the form key=value, for example:

a-structure, key=value

The values type will be inferred if not explicitly specified with the (GTypeName)value syntax, for example the following struct will have one field called ‘is-string’ which has the string ‘true’ as a value:

a-struct, field-is-string=(string)true, field-is-boolean=true

Note: without specifying (string), field-is-string` type would have been inferred as boolean.

Note: we specified (string) as a type even if gchararray is the actual GType name as for convenience some well known types have been aliased or abbreviated.

To avoid specifying the type, you can give some hints to the “type system”. For example to specify a value as a double, you should add a decimal (ie. 1 is an int while 1.0 is a double).

Note: when a structure is serialized with gst_structure_to_string, all values are explicitly typed.

Some types have special delimiters:

  • GstValueArray are inside curly brackets ({ and }). For example a-structure, array={1, 2, 3}
  • Ranges are inside brackets ([ and ]). For example a-structure, range=[1, 6, 2] 1 being the min value, 6 the maximum and 2 the step. To specify a GST_TYPE_INT64_RANGE you need to explicitly specify it like: a-structure, a-int64-range=(gint64) [1, 5]
  • GstValueList are inside “less and greater than” (< and >). For example `a-structure, list=<1, 2, 3>

Structures are delimited either by a null character \0 or a semicolon ; the latter allowing to store multiple structures in the same string (see Caps).

Quotes are used as “default” delimiters and can be used around any types that don’t use other delimiters (for example a-struct, i=(int)"1"). They are use to allow adding spaces or special characters (such as delimiters, semicolumns, etc..) inside strings and you can use backslashes \ to escape characters inside them, for example:

a-struct, special="\"{[(;)]}\" can be used inside quotes"

They also allow for nested structure, such as:

a-struct, nested=(GstStructure)"nested-struct, nested=true"

Since 1.20, nested structures and caps can be specified using brackets ([ and ]), for example:

a-struct, nested=[nested-struct, nested=true]

note: [to_str()][Self::to_str()] won’t use that syntax for backward compatibility reason, [serialize()][Self::serialize()] has been added for that purpose.

Implementations

Creates a new, empty Structure with the given name.

See gst_structure_set_name() for constraints on the name parameter.

Free-function: gst_structure_free

name

name of new structure

Returns

a new, empty Structure

Creates a new Structure with the given name. Parses the list of variable arguments and sets fields to the values listed. Variable arguments should be passed as field name, field type, and value. Last variable argument should be None.

Free-function: gst_structure_free

name

name of new structure

firstfield

name of first field to set

Returns

a new Structure

Methods from Deref<Target = StructureRef>

This is supported on crate feature v1_20 only.

Trait Implementations

Performs the conversion.

Performs the conversion.

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

The resulting type after dereferencing.

Dereferences the value.

Mutably dereferences the value.

Deserialize this value from the given Serde deserializer. Read more

Formats the value using the given formatter. Read more

Executes the destructor for this type. Read more

Extends a collection with the contents of an iterator. Read more

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements. Read more

Safety Read more

Safety Read more

Safety Read more

Safety Read more

Creates a value from an iterator. Read more

The associated error which can be returned from parsing.

Parses a string s to return a value of this type. Read more

Value type checker.

Get the contained value from a Value. Read more

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

Serialize this value into the given Serde serializer. Read more

Returns the type identifier of Self.

Transfer: none. Read more

Transfer: full. Read more

Transfer: container. Read more

Transfer: none. Read more

Transfer: full. Read more

Transfer: container. Read more

Transfer: none. Read more

Convert a value to a Value.

Returns the type identifer of self. Read more

Convert an Option to a Value.

Type to get the Type from. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Performs the conversion.

Ensures that the type has been registered with the type system.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

Returns a SendValue clone of self.

Converts the given value to a String. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.