Class

GLib-2.0 ▶ GLib ▶ VariantSince 2.24

GLib.Variant is a value container whose types are determined at construction.

It serves as a reliable and efficient format for storing structured data that can be serialized while preserving type information. Comparable to JSON, but with strong typing and support for special values like file handles.

GVariant is used throughout the GNOME Platform including GDBus, GSettings, GAction, GMenu and many other APIs. All D-Bus method, property and signal values are GVariant objects.

// Create variants using constructor with type signature
const stringVariant = new GLib.Variant('s', 'Hello World');
const numberVariant = new GLib.Variant('i', 42);
const boolVariant = new GLib.Variant('b', true);

// Create complex variants like dictionaries
const dictVariant = new GLib.Variant('a{sv}', {
  'name': GLib.Variant.new_string('Mario'),
  'lives': GLib.Variant.new_uint32(3),
  'active': GLib.Variant.new_boolean(true)
});

// Unpack variants to JavaScript values
const stringValue = stringVariant.unpack(); // → "Hello World"
const dictValue = dictVariant.deepUnpack(); // → { name: Variant<"s">, lives: Variant<"u">, active: Variant<"b"> }

Type Parameters

  • S extends string = any
Index

Constructors

constructor

Properties

$gtype

Methods

_init byteswap check_format_string classify compare deep_unpack deepUnpack dup_bytestring dup_bytestring_array dup_objv dup_string dup_strv equal get_boolean get_byte get_bytestring get_bytestring_array get_child_value get_data get_data_as_bytes get_double get_handle get_int16 get_int32 get_int64 get_maybe get_normal_form get_objv get_size get_string get_strv get_type get_type_string get_uint16 get_uint32 get_uint64 get_variant hash is_container is_floating is_normal_form is_of_type lookup_value n_children print recursiveUnpack ref ref_sink store take_ref unpack unref _new_internal is_object_path is_signature new new_array new_boolean new_byte new_bytestring new_bytestring_array new_dict_entry new_double new_fixed_array new_from_bytes new_from_data new_handle new_int16 new_int32 new_int64 new_maybe new_object_path new_objv new_signature new_string new_strv new_tuple new_uint16 new_uint32 new_uint64 new_variant parse parse_error_print_context parse_error_quark parser_get_error_quark

Constructors

Properties

$gtype: GType<GLib.Variant<any>>

Methods

_init

  • Parameters

    • format_string: string
    • copy_only: boolean

    Returns boolean

  • Alias for deepUnpack method.

    Recursively unpacks the variant's data into JavaScript values up to one level deep. This is the snake_case version of the same functionality.

    Returns $ParseDeepVariant<S>

    The deeply unpacked JavaScript value

    deepUnpack for the camelCase version with full documentation

  • Alias for deepUnpack method.

    Recursively unpacks the variant's data into JavaScript values up to one level deep. This is the snake_case version of the same functionality.

    Type Parameters

    • T

    Returns T

    The deeply unpacked JavaScript value

    deepUnpack for the camelCase version with full documentation

  • Alias for deepUnpack method.

    Recursively unpacks the variant's data into JavaScript values up to one level deep. This is the snake_case version of the same functionality.

    Returns $ParseDeepVariant<S>

    The deeply unpacked JavaScript value

    deepUnpack for the camelCase version with full documentation

  • Recursively unpacks the variant's data into JavaScript values.

    This method unpacks a variant and its direct children, but only up to one level deep. It's the most commonly used unpacking method for D-Bus operations and GSettings.

    With advanced variants enabled, this method provides automatic type inference based on the variant's type signature. You can also explicitly specify a type parameter for backward compatibility.

    Returns $ParseDeepVariant<S>

    The deeply unpacked JavaScript value with one level of children unpacked

    // Simple dictionary (a{ss}) - fully unpacked
    const simpleDict = new GLib.Variant('a{ss}', {
      'key1': 'value1',
      'key2': 'value2'
    });
    const simple = simpleDict.deepUnpack(); // → { key1: "value1", key2: "value2" }

    // Complex dictionary (a{sv}) - values remain as Variants
    const complexDict = new GLib.Variant('a{sv}', {
      'name': GLib.Variant.new_string('Mario'),
      'active': GLib.Variant.new_boolean(true)
    });
    const complex = complexDict.deepUnpack(); // → { name: Variant<"s">, active: Variant<"b"> }

    // Automatic type inference (Advanced Variants)
    const autoInferred = variant.deepUnpack(); // Types inferred from signature

    // Explicit type parameter (backward compatibility)
    const explicit = variant.deepUnpack<{ [key: string]: GLib.Variant }>();

    // String arrays are fully unpacked
    const strArray = GLib.Variant.new_strv(['one', 'two']);
    const strings = strArray.deepUnpack(); // → ["one", "two"]

  • Recursively unpacks the variant's data into JavaScript values.

    This method unpacks a variant and its direct children, but only up to one level deep. It's the most commonly used unpacking method for D-Bus operations and GSettings.

    With advanced variants enabled, this method provides automatic type inference based on the variant's type signature. You can also explicitly specify a type parameter for backward compatibility.

    Type Parameters

    • T

      The expected return type (defaults to automatically inferred type)

    Returns T

    The deeply unpacked JavaScript value with one level of children unpacked

    // Simple dictionary (a{ss}) - fully unpacked
    const simpleDict = new GLib.Variant('a{ss}', {
      'key1': 'value1',
      'key2': 'value2'
    });
    const simple = simpleDict.deepUnpack(); // → { key1: "value1", key2: "value2" }

    // Complex dictionary (a{sv}) - values remain as Variants
    const complexDict = new GLib.Variant('a{sv}', {
      'name': GLib.Variant.new_string('Mario'),
      'active': GLib.Variant.new_boolean(true)
    });
    const complex = complexDict.deepUnpack(); // → { name: Variant<"s">, active: Variant<"b"> }

    // Automatic type inference (Advanced Variants)
    const autoInferred = variant.deepUnpack(); // Types inferred from signature

    // Explicit type parameter (backward compatibility)
    const explicit = variant.deepUnpack<{ [key: string]: GLib.Variant }>();

    // String arrays are fully unpacked
    const strArray = GLib.Variant.new_strv(['one', 'two']);
    const strings = strArray.deepUnpack(); // → ["one", "two"]

  • Recursively unpacks the variant's data into JavaScript values.

    This method unpacks a variant and its direct children, but only up to one level deep. It's the most commonly used unpacking method for D-Bus operations and GSettings.

    With advanced variants enabled, this method provides automatic type inference based on the variant's type signature. You can also explicitly specify a type parameter for backward compatibility.

    Returns $ParseDeepVariant<S>

    The deeply unpacked JavaScript value with one level of children unpacked

    // Simple dictionary (a{ss}) - fully unpacked
    const simpleDict = new GLib.Variant('a{ss}', {
      'key1': 'value1',
      'key2': 'value2'
    });
    const simple = simpleDict.deepUnpack(); // → { key1: "value1", key2: "value2" }

    // Complex dictionary (a{sv}) - values remain as Variants
    const complexDict = new GLib.Variant('a{sv}', {
      'name': GLib.Variant.new_string('Mario'),
      'active': GLib.Variant.new_boolean(true)
    });
    const complex = complexDict.deepUnpack(); // → { name: Variant<"s">, active: Variant<"b"> }

    // Automatic type inference (Advanced Variants)
    const autoInferred = variant.deepUnpack(); // Types inferred from signature

    // Explicit type parameter (backward compatibility)
    const explicit = variant.deepUnpack<{ [key: string]: GLib.Variant }>();

    // String arrays are fully unpacked
    const strArray = GLib.Variant.new_strv(['one', 'two']);
    const strings = strArray.deepUnpack(); // → ["one", "two"]

  • Checks if two variants are equal.

    Parameters

    Returns boolean

    true if the variants are equal, false otherwise

    const variant1 = GLib.Variant.new_string('test');
    const variant2 = GLib.Variant.new_string('test');
    const areEqual = variant1.equal(variant2); // → true

  • Extracts a boolean value from a boolean variant.

    Returns boolean

    The boolean value

    Error if the variant is not of type 'b'

  • Extracts a bytestring from a bytestring variant.

    Returns Uint8Array

    The byte array

  • Gets a child variant by index from a container variant.

    Parameters

    • index_: number

      The index of the child to retrieve

    Returns GLib.Variant

    The child variant at the specified index

    const tuple = new GLib.Variant('(si)', ['hello', 42]);
    const firstChild = tuple.get_child_value(0); // → Variant<'s'> containing 'hello'
    const secondChild = tuple.get_child_value(1); // → Variant<'i'> containing 42

  • Extracts a 32-bit signed integer from an integer variant.

    Returns number

    The integer value

    Error if the variant is not of type 'i'

  • Extracts a string value from a string variant.

    Returns [string, number]

    A tuple containing the string value and its length

    const variant = GLib.Variant.new_string('hello');
    const [value, length] = variant.get_string(); // → ['hello', 5]

  • Extracts a string array from a string array variant.

    Returns string[]

    Array of strings

  • Gets the type signature string of the variant.

    This is very useful for debugging and type checking.

    Returns string

    The type signature string (e.g., 's', 'i', 'a{sv}')

    const stringVariant = GLib.Variant.new_string('test');
    const typeString = stringVariant.get_type_string(); // → 's'

    const dictVariant = new GLib.Variant('a{sv}', {});
    const dictType = dictVariant.get_type_string(); // → 'a{sv}'

  • Checks if the variant is a container type.

    Container types include arrays, tuples, dictionaries, and maybes.

    Returns boolean

    true if the variant is a container

  • Gets the number of children in a container variant.

    Returns number

    The number of child elements

    const tuple = new GLib.Variant('(si)', ['hello', 42]);
    const childCount = tuple.n_children(); // → 2

    const array = GLib.Variant.new_strv(['a', 'b', 'c']);
    const arrayLength = array.n_children(); // → 3

  • Creates a string representation of the variant.

    This is extremely useful for debugging GVariant structures.

    Parameters

    • type_annotate: boolean

      Whether to include type annotations in the output

    Returns string

    A string representation of the variant

    const variant = new GLib.Variant('a{sv}', {
      'name': GLib.Variant.new_string('Mario'),
      'lives': GLib.Variant.new_uint32(3)
    });

    // Without type annotations
    print(variant.print(false)); // → "{'name': 'Mario', 'lives': 3}"

    // With type annotations
    print(variant.print(true)); // → "{'name': <'Mario'>, 'lives': <uint32 3>}"

  • Recursively unpacks the variant and all its descendants into native JavaScript values.

    Available since GJS 1.64 (GNOME 3.36)

    This method performs complete recursive unpacking, converting all nested Variants to their native JavaScript equivalents. Type information may be lost during this process, so you'll need to know the original types to repack values.

    Returns $ParseRecursiveVariant<S>

    The recursively unpacked JavaScript value with all Variants converted to native types

    // Complex nested structure fully unpacked
    const complexDict = new GLib.Variant('a{sv}', {
      'name': GLib.Variant.new_string('Mario'),
      'lives': GLib.Variant.new_uint32(3),
      'active': GLib.Variant.new_boolean(true)
    });

    const fullyUnpacked = complexDict.recursiveUnpack();
    // → { name: "Mario", lives: 3, active: true }

    // All nested Variants are converted to native values
    const nestedTuple = new GLib.Variant('(sa{sv})', [
      'player',
      { 'score': GLib.Variant.new_int32(100) }
    ]);
    const result = nestedTuple.recursiveUnpack();
    // → ["player", { score: 100 }]
    • deepUnpack for one-level unpacking with type preservation
    • unpack for shallow unpacking only

    1.64

  • Recursively unpacks the variant and all its descendants into native JavaScript values.

    Available since GJS 1.64 (GNOME 3.36)

    This method performs complete recursive unpacking, converting all nested Variants to their native JavaScript equivalents. Type information may be lost during this process, so you'll need to know the original types to repack values.

    Type Parameters

    • T

    Returns T

    The recursively unpacked JavaScript value with all Variants converted to native types

    // Complex nested structure fully unpacked
    const complexDict = new GLib.Variant('a{sv}', {
      'name': GLib.Variant.new_string('Mario'),
      'lives': GLib.Variant.new_uint32(3),
      'active': GLib.Variant.new_boolean(true)
    });

    const fullyUnpacked = complexDict.recursiveUnpack();
    // → { name: "Mario", lives: 3, active: true }

    // All nested Variants are converted to native values
    const nestedTuple = new GLib.Variant('(sa{sv})', [
      'player',
      { 'score': GLib.Variant.new_int32(100) }
    ]);
    const result = nestedTuple.recursiveUnpack();
    // → ["player", { score: 100 }]
    • deepUnpack for one-level unpacking with type preservation
    • unpack for shallow unpacking only

    1.64

  • Recursively unpacks the variant and all its descendants into native JavaScript values.

    Available since GJS 1.64 (GNOME 3.36)

    This method performs complete recursive unpacking, converting all nested Variants to their native JavaScript equivalents. Type information may be lost during this process, so you'll need to know the original types to repack values.

    Returns $ParseRecursiveVariant<S>

    The recursively unpacked JavaScript value with all Variants converted to native types

    // Complex nested structure fully unpacked
    const complexDict = new GLib.Variant('a{sv}', {
      'name': GLib.Variant.new_string('Mario'),
      'lives': GLib.Variant.new_uint32(3),
      'active': GLib.Variant.new_boolean(true)
    });

    const fullyUnpacked = complexDict.recursiveUnpack();
    // → { name: "Mario", lives: 3, active: true }

    // All nested Variants are converted to native values
    const nestedTuple = new GLib.Variant('(sa{sv})', [
      'player',
      { 'score': GLib.Variant.new_int32(100) }
    ]);
    const result = nestedTuple.recursiveUnpack();
    // → ["player", { score: 100 }]
    • deepUnpack for one-level unpacking with type preservation
    • unpack for shallow unpacking only

    1.64

  • Unpacks the variant's data into a JavaScript value.

    This performs a shallow unpacking operation - only unpacking the top level. For containers like arrays or dictionaries, child elements remain as Variant objects.

    Returns $ParseShallowVariant<S>

    The unpacked JavaScript value with child Variants preserved

    // Simple types are fully unpacked
    const boolVariant = GLib.Variant.new_boolean(true);
    const boolValue = boolVariant.unpack(); // → true

    // String values are unpacked (discarding length information)
    const stringVariant = GLib.Variant.new_string("hello");
    const stringValue = stringVariant.unpack(); // → "hello"

    // Arrays are unpacked but elements remain as Variants
    const arrayVariant = GLib.Variant.new_strv(["one", "two"]);
    const arrayValue = arrayVariant.unpack(); // → [Variant<"s">, Variant<"s">]

  • Unpacks the variant's data into a JavaScript value.

    This performs a shallow unpacking operation - only unpacking the top level. For containers like arrays or dictionaries, child elements remain as Variant objects.

    Type Parameters

    • T

    Returns T

    The unpacked JavaScript value with child Variants preserved

    // Simple types are fully unpacked
    const boolVariant = GLib.Variant.new_boolean(true);
    const boolValue = boolVariant.unpack(); // → true

    // String values are unpacked (discarding length information)
    const stringVariant = GLib.Variant.new_string("hello");
    const stringValue = stringVariant.unpack(); // → "hello"

    // Arrays are unpacked but elements remain as Variants
    const arrayVariant = GLib.Variant.new_strv(["one", "two"]);
    const arrayValue = arrayVariant.unpack(); // → [Variant<"s">, Variant<"s">]

  • Unpacks the variant's data into a JavaScript value.

    This performs a shallow unpacking operation - only unpacking the top level. For containers like arrays or dictionaries, child elements remain as Variant objects.

    Returns $ParseShallowVariant<S>

    The unpacked JavaScript value with child Variants preserved

    // Simple types are fully unpacked
    const boolVariant = GLib.Variant.new_boolean(true);
    const boolValue = boolVariant.unpack(); // → true

    // String values are unpacked (discarding length information)
    const stringVariant = GLib.Variant.new_string("hello");
    const stringValue = stringVariant.unpack(); // → "hello"

    // Arrays are unpacked but elements remain as Variants
    const arrayVariant = GLib.Variant.new_strv(["one", "two"]);
    const arrayValue = arrayVariant.unpack(); // → [Variant<"s">, Variant<"s">]

Static_new_internal

  • Creates a new boolean GVariant instance.

    Parameters

    • value: boolean

      The boolean value to pack

    Returns GLib.Variant<"b">

    A new GVariant with type signature 'b'

    const variant = GLib.Variant.new_boolean(true);
    const unpacked = variant.get_boolean(); // → true

  • Creates a new bytestring GVariant instance from a Uint8Array or string.

    Parameters

    • string: string | Uint8Array<ArrayBufferLike>

      The string or byte array to pack

    Returns GLib.Variant<"ay">

    A new GVariant with type signature 'ay'

Staticnew_dict_entry

  • Creates a new double-precision floating point GVariant.

    Parameters

    • value: number

      The number value to pack

    Returns GLib.Variant<"d">

    A new GVariant with type signature 'd'

  • Creates a new 32-bit signed integer GVariant.

    Parameters

    • value: number

      The integer value to pack

    Returns GLib.Variant<"i">

    A new GVariant with type signature 'i'

    const variant = GLib.Variant.new_int32(-42);
    const unpacked = variant.get_int32(); // → -42

  • Creates a new 64-bit signed integer GVariant.

    Note: As of GJS v1.68, all numeric types are still Number values, so some 64-bit values may not be fully supported. BigInt support to come.

    Parameters

    • value: number

      The integer value to pack

    Returns GLib.Variant<"x">

    A new GVariant with type signature 'x'

  • Creates a new object path GVariant.

    Parameters

    • object_path: string

      A valid D-Bus object path string

    Returns GLib.Variant<"o">

    A new GVariant with type signature 'o'

  • Creates a new D-Bus signature GVariant.

    Parameters

    • signature: string

      A valid D-Bus type signature string

    Returns GLib.Variant<"g">

    A new GVariant with type signature 'g'

  • Creates a new string GVariant instance.

    Parameters

    • string: string

      The string value to pack

    Returns GLib.Variant<"s">

    A new GVariant with type signature 's'

    const variant = GLib.Variant.new_string('Hello World');
    const [value, length] = variant.get_string(); // → ['Hello World', 11]
    const unpacked = variant.unpack(); // → 'Hello World'

  • Creates a new string array GVariant instance.

    Parameters

    • strv: string[]

      Array of strings to pack

    Returns GLib.Variant<"as">

    A new GVariant with type signature 'as'

    const variant = GLib.Variant.new_strv(['one', 'two', 'three']);
    const unpacked = variant.get_strv(); // → ['one', 'two', 'three']
    const deepUnpacked = variant.deepUnpack(); // → ['one', 'two', 'three']

  • Creates a new 32-bit unsigned integer GVariant.

    Parameters

    • value: number

      The unsigned integer value to pack

    Returns GLib.Variant<"u">

    A new GVariant with type signature 'u'