Value

class Value(value_type=None, py_value=None)

An opaque structure used to hold different types of values.

The data within the structure has protected scope: it is accessible only to functions within a TypeValueTable structure, or implementations of the g_value_*() API. That is, code portions which implement new fundamental types.

Value users cannot make any assumptions about how data is stored within the 2 element data union, and the g_type member should only be accessed through the VALUE_TYPE() macro.

Methods

class Value

dup_object() → Object | None

Get the contents of a object derived Value, increasing its reference count. If the contents of the Value are None, then None will be returned.

dup_string() → str | None

Get a copy the contents of a str Value.

dup_variant() → Variant | None

Get the contents of a variant Value, increasing its refcount. The returned Variant is never floating.

Added in version 2.26.

fits_pointer() → bool

Determines if value will fit inside the size of a pointer value. This is an internal function introduced mainly for C marshallers.

get_boolean() → bool

Get the contents of a bool Value.

get_boxed()

Get the contents of a Boxed derived Value.

get_char() → int

Do not use this function; it is broken on platforms where the %char type is unsigned, such as ARM and PowerPC. See get_schar().

Get the contents of a int Value.

Deprecated since version 2.32: This function’s return type is broken, see get_schar()

get_double() → float

Get the contents of a float Value.

get_enum() → int

Get the contents of a Enum Value.

get_flags() → int

Get the contents of a Flags Value.

get_float() → float

Get the contents of a float Value.

get_gtype() → GType

Get the contents of a GType Value.

Added in version 2.12.

get_int() → int

Get the contents of a int Value.

get_int64() → int

Get the contents of a int Value.

get_long() → int

Get the contents of a int Value.

get_object() → Object | None

Get the contents of a object derived Value.

get_param() → ParamSpec

Get the contents of a ParamSpec Value.

get_pointer() → Any | None

Get the contents of a pointer Value.

get_schar() → int

Get the contents of a int Value.

Added in version 2.32.

get_string() → str | None

Get the contents of a str Value.

get_uchar() → int

Get the contents of a unsigned int Value.

get_uint() → int

Get the contents of a unsigned int Value.

get_uint64() → int

Get the contents of a unsigned int Value.

get_ulong() → int

Get the contents of a unsigned int Value.

get_value()

get_variant() → Variant | None

Get the contents of a variant Value.

Added in version 2.26.

init(g_type: GType) → Value

Initializes value with the default value of type.

Parameters:

g_type – Type the Value should hold values of.

init_from_instance(instance: TypeInstance) → None

Initializes and sets value from an instantiatable type via the value_table’s collect_value() function.

Note: The value will be initialised with the exact type of instance. If you wish to set the value's type to a different GType (such as a parent class GType), you need to manually call init() and set_instance().

Added in version 2.42.

Parameters:

instance – the instance

peek_pointer() → Any | None

Returns the value contents as pointer. This function asserts that fits_pointer() returned True for the passed in value. This is an internal function introduced mainly for C marshallers.

reset() → Value

Clears the current value in value and resets it to the default value (as if the value had just been initialized).

set_boolean(v_boolean: bool) → None

Set the contents of a bool Value to v_boolean.

Parameters:

v_boolean – boolean value to be set

set_boxed(boxed)

Set the contents of a Boxed derived Value to v_boxed.

Parameters:

boxed

set_boxed_take_ownership(v_boxed: Any = None) → None

This is an internal function introduced mainly for C marshallers.

Deprecated since version 2.4: Use take_boxed() instead.

Parameters:

v_boxed – duplicated unowned boxed value to be set

set_char(v_char: int) → None

Set the contents of a int Value to v_char.

Deprecated since version 2.32: This function’s input type is broken, see set_schar()

Parameters:

v_char – character value to be set

set_double(v_double: float) → None

Set the contents of a float Value to v_double.

Parameters:

v_double – double value to be set

set_enum(v_enum: int) → None

Set the contents of a Enum Value to v_enum.

Parameters:

v_enum – enum value to be set

set_flags(v_flags: int) → None

Set the contents of a Flags Value to v_flags.

Parameters:

v_flags – flags value to be set

set_float(v_float: float) → None

Set the contents of a float Value to v_float.

Parameters:

v_float – float value to be set

set_gtype(v_gtype: GType) → None

Set the contents of a GType Value to v_gtype.

Added in version 2.12.

Parameters:

v_gtype – Type to be set

set_instance(instance: Any = None) → None

Sets value from an instantiatable type via the value_table’s collect_value() function.

Parameters:

instance – the instance

set_int(v_int: int) → None

Set the contents of a int Value to v_int.

Parameters:

v_int – integer value to be set

set_int64(v_int64: int) → None

Set the contents of a int Value to v_int64.

Parameters:

v_int64 – 64bit integer value to be set

set_interned_string(v_string: str | None = None) → None

Set the contents of a str Value to v_string. The string is assumed to be static and interned (canonical, for example from intern_string()), and is thus not duplicated when setting the Value.

Added in version 2.66.

Parameters:

v_string – static string to be set

set_long(v_long: int) → None

Set the contents of a int Value to v_long.

Parameters:

v_long – long integer value to be set

set_object(v_object: Object | None = None) → None

Set the contents of a object derived Value to v_object.

set_object() increases the reference count of v_object (the Value holds a reference to v_object). If you do not wish to increase the reference count of the object (i.e. you wish to pass your current reference to the Value because you no longer need it), use take_object() instead.

It is important that your Value holds a reference to v_object (either its own, or one it has taken) to ensure that the object won’t be destroyed while the Value still exists).

Parameters:

v_object – object value to be set

set_param(param: ParamSpec | None = None) → None

Set the contents of a ParamSpec Value to param.

Parameters:

param – the ParamSpec to be set

set_pointer(v_pointer: Any = None) → None

Set the contents of a pointer Value to v_pointer.

Parameters:

v_pointer – pointer value to be set

set_schar(v_char: int) → None

Set the contents of a int Value to v_char.

Added in version 2.32.

Parameters:

v_char – signed 8 bit integer to be set

set_static_boxed(v_boxed: Any = None) → None

Set the contents of a Boxed derived Value to v_boxed.

The boxed value is assumed to be static, and is thus not duplicated when setting the Value.

Parameters:

v_boxed – static boxed value to be set

set_static_string(v_string: str | None = None) → None

Set the contents of a str Value to v_string. The string is assumed to be static, and is thus not duplicated when setting the Value.

If the the string is a canonical string, using set_interned_string() is more appropriate.

Parameters:

v_string – static string to be set

set_string(v_string: str | None = None) → None

Set the contents of a str Value to a copy of v_string.

Parameters:

v_string – caller-owned string to be duplicated for the Value

set_string_take_ownership(v_string: str | None = None) → None

This is an internal function introduced mainly for C marshallers.

Deprecated since version 2.4: Use take_string() instead.

Parameters:

v_string – duplicated unowned string to be set

set_uchar(v_uchar: int) → None

Set the contents of a unsigned int Value to v_uchar.

Parameters:

v_uchar – unsigned character value to be set

set_uint(v_uint: int) → None

Set the contents of a unsigned int Value to v_uint.

Parameters:

v_uint – unsigned integer value to be set

set_uint64(v_uint64: int) → None

Set the contents of a unsigned int Value to v_uint64.

Parameters:

v_uint64 – unsigned 64bit integer value to be set

set_ulong(v_ulong: int) → None

Set the contents of a unsigned int Value to v_ulong.

Parameters:

v_ulong – unsigned long integer value to be set

set_value(py_value)

Parameters:

py_value

set_variant(variant: Variant | None = None) → None

Set the contents of a variant Value to variant. If the variant is floating, it is consumed.

Added in version 2.26.

Parameters:

variant – a Variant, or None

take_boxed(v_boxed: Any = None) → None

Sets the contents of a Boxed derived Value to v_boxed and takes over the ownership of the caller’s reference to v_boxed; the caller doesn’t have to unref it any more.

Added in version 2.4.

Parameters:

v_boxed – duplicated unowned boxed value to be set

take_string(v_string: str | None = None) → None

Sets the contents of a str Value to v_string.

Added in version 2.4.

Parameters:

v_string – string to take ownership of

take_variant(variant: Variant | None = None) → None

Set the contents of a variant Value to variant, and takes over the ownership of the caller’s reference to variant; the caller doesn’t have to unref it any more (i.e. the reference count of the variant is not increased).

If variant was floating then its floating reference is converted to a hard reference.

If you want the Value to hold its own reference to variant, use set_variant() instead.

This is an internal function introduced mainly for C marshallers.

Added in version 2.26.

Parameters:

variant – a Variant, or None

transform(dest_value: Value) → bool

Tries to cast the contents of src_value into a type appropriate to store in dest_value, e.g. to transform a int value into a float value. Performing transformations between value types might incur precision lossage. Especially transformations into strings might reveal seemingly arbitrary results and shouldn’t be relied upon for production code (such as rcfile value or object property serialization).

Parameters:

dest_value – Target value.

classmethod type_compatible(dest_type: GType) → bool

Returns whether a Value of type src_type can be copied into a Value of type dest_type.

Parameters:

dest_type – destination type for copying.

classmethod type_transformable(dest_type: GType) → bool

Check whether transform() is able to transform values of type src_type into values of type dest_type. Note that for the types to be transformable, they must be compatible or a transformation function must be registered.

Parameters:

dest_type – Target type.

unset() → None

Clears the current value in value (if any) and “unsets” the type, this releases all resources associated with this GValue. An unset value is the same as an uninitialized (zero-filled) Value structure.

Fields

class Value

data

g_type