:right-sidebar: True

Value
===================================================================

.. currentmodule:: gi.repository.JavaScriptCore





.. class:: Value(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.GObject.Object`





JSCValue represents a reference to a value in a :obj:`~gi.repository.JavaScriptCore.Context`\. The JSCValue
protects the referenced value from being garbage collected.


Constructors
------------

.. rst-class:: interim-class

.. class:: Value
   :no-index:


   .. classmethod:: new_array_buffer(context: ~gi.repository.JavaScriptCore.Context, data: ~typing.Any, size: int, destroy_notify: ~typing.Callable[[~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> ~gi.repository.JavaScriptCore.Value | None

      Creates a new %ArrayBuffer from existing ``data`` in memory.

      The ``data`` is not copied: while this allows sharing data with JavaScript
      efficiently, the caller must ensure that the memory region remains valid
      until the newly created object is released by JSC.

      Optionally, a ``destroy_notify`` callback can be provided, which will be
      invoked with ``user_data`` as parameter when the %ArrayBuffer object is
      released. This is intended to be used for freeing resources related to
      the memory region which contains the data:


      .. code-block:: !<-- language="C" -->
          :dedent:

          GMappedFile *f = g_mapped_file_new (file_path, TRUE, NULL);
          JSCValue *value = jsc_value_new_array_buffer (context,
              g_mapped_file_get_contents (f), g_mapped_file_get_length (f),
              (GDestroyNotify) g_mapped_file_unref, f);

      Note that the ``user_data`` can be the same value as ``data``\:


      .. code-block:: !<-- language="C" -->
          :dedent:

          void *bytes = g_malloc0 (100);
          JSCValue *value = jsc_value_new_array_buffer (context, bytes, 100, g_free, bytes);


      .. versionadded:: 2.38





      :param context: A :obj:`~gi.repository.JavaScriptCore.Context`

      :param data: Pointer to a region of memory.

      :param size: Size in bytes of the memory region.

      :param destroy_notify: destroy notifier for ``user_data``\.

      :param user_data: user data.




   .. classmethod:: new_array_from_garray(context: ~gi.repository.JavaScriptCore.Context, array: list[~gi.repository.JavaScriptCore.Value] | None = None) -> ~gi.repository.JavaScriptCore.Value

      Create a new :obj:`~gi.repository.JavaScriptCore.Value` referencing an array with the items from ``array``\. If ``array``
      is :const:`None` or empty a new empty array will be created. Elements of ``array`` should be
      pointers to a :obj:`~gi.repository.JavaScriptCore.Value`\.






      :param context: a :obj:`~gi.repository.JavaScriptCore.Context`

      :param array: a ``GPtrArray``




   .. classmethod:: new_array_from_strv(context: ~gi.repository.JavaScriptCore.Context, strv: list[str]) -> ~gi.repository.JavaScriptCore.Value

      Create a new :obj:`~gi.repository.JavaScriptCore.Value` referencing an array of strings with the items from ``strv``\. If ``array``
      is :const:`None` or empty a new empty array will be created.






      :param context: a :obj:`~gi.repository.JavaScriptCore.Context`

      :param strv: a :const:`None`-terminated array of strings




   .. classmethod:: new_boolean(context: ~gi.repository.JavaScriptCore.Context, value: bool) -> ~gi.repository.JavaScriptCore.Value

      Create a new :obj:`~gi.repository.JavaScriptCore.Value` from ``value``






      :param context: a :obj:`~gi.repository.JavaScriptCore.Context`

      :param value: a :obj:`~gi.repository.gboolean`




   .. classmethod:: new_from_json(context: ~gi.repository.JavaScriptCore.Context, json: str) -> ~gi.repository.JavaScriptCore.Value

      Create a new :obj:`~gi.repository.JavaScriptCore.Value` referencing a new value created by parsing ``json``\.


      .. versionadded:: 2.28





      :param context: a :obj:`~gi.repository.JavaScriptCore.Context`

      :param json: the JSON string to be parsed




   .. classmethod:: new_function(context: ~gi.repository.JavaScriptCore.Context, name: str | None, callback: ~typing.Callable[[], None], user_data: ~typing.Any, return_type: ~gobject.GType, parameter_types: list[~gobject.GType] | None = None) -> ~gi.repository.JavaScriptCore.Value

      Create a function in ``context``\. If ``name`` is :const:`None` an anonymous function will be created.
      When the function is called by JavaScript or :func:`~gi.repository.JavaScriptCore.Value.function_call`, ``callback`` is called
      receiving the function parameters and then ``user_data`` as last parameter. When the function is
      cleared in ``context``\, ``destroy_notify`` is called with ``user_data`` as parameter.

      Note that the value returned by ``callback`` must be fully transferred. In case of boxed types, you could use
      %G_TYPE_POINTER instead of the actual boxed :obj:`~gi.repository.GObject.Type` to ensure that the instance owned by :obj:`~gi.repository.JavaScriptCore.Class` is used.
      If you really want to return a new copy of the boxed type, use ``JSC_TYPE_VALUE`` and return a :obj:`~gi.repository.JavaScriptCore.Value` created
      with :func:`~gi.repository.JavaScriptCore.Value.new_object` that receives the copy as instance parameter.






      :param context: a :obj:`~gi.repository.JavaScriptCore.Context`\:

      :param name: the function name or :const:`None`

      :param callback: a :obj:`~gi.repository.GObject.Callback`\.

      :param user_data: user data to pass to ``callback``\.

      :param return_type: the :obj:`~gi.repository.GObject.Type` of the function return value, or %G_TYPE_NONE if the function is void.

      :param parameter_types: 




   .. classmethod:: new_function_variadic(context: ~gi.repository.JavaScriptCore.Context, name: str | None, callback: ~typing.Callable[[], None], user_data: ~typing.Any, return_type: ~gobject.GType) -> ~gi.repository.JavaScriptCore.Value

      Create a function in ``context``\. If ``name`` is :const:`None` an anonymous function will be created.
      When the function is called by JavaScript or :func:`~gi.repository.JavaScriptCore.Value.function_call`, ``callback`` is called
      receiving an ``GPtrArray`` of :obj:`~gi.repository.JavaScriptCore.Value`\<!-- -->s with the arguments and then ``user_data`` as last parameter.
      When the function is cleared in ``context``\, ``destroy_notify`` is called with ``user_data`` as parameter.

      Note that the value returned by ``callback`` must be fully transferred. In case of boxed types, you could use
      %G_TYPE_POINTER instead of the actual boxed :obj:`~gi.repository.GObject.Type` to ensure that the instance owned by :obj:`~gi.repository.JavaScriptCore.Class` is used.
      If you really want to return a new copy of the boxed type, use ``JSC_TYPE_VALUE`` and return a :obj:`~gi.repository.JavaScriptCore.Value` created
      with :func:`~gi.repository.JavaScriptCore.Value.new_object` that receives the copy as instance parameter.






      :param context: a :obj:`~gi.repository.JavaScriptCore.Context`

      :param name: the function name or :const:`None`

      :param callback: a :obj:`~gi.repository.GObject.Callback`\.

      :param user_data: user data to pass to ``callback``\.

      :param return_type: the :obj:`~gi.repository.GObject.Type` of the function return value, or %G_TYPE_NONE if the function is void.




   .. classmethod:: new_null(context: ~gi.repository.JavaScriptCore.Context) -> ~gi.repository.JavaScriptCore.Value

      Create a new :obj:`~gi.repository.JavaScriptCore.Value` referencing <function>null</function> in ``context``\.






      :param context: a :obj:`~gi.repository.JavaScriptCore.Context`




   .. classmethod:: new_number(context: ~gi.repository.JavaScriptCore.Context, number: float) -> ~gi.repository.JavaScriptCore.Value

      Create a new :obj:`~gi.repository.JavaScriptCore.Value` from ``number``\.






      :param context: a :obj:`~gi.repository.JavaScriptCore.Context`

      :param number: a number




   .. classmethod:: new_object(context: ~gi.repository.JavaScriptCore.Context, instance: ~typing.Any = None, jsc_class: ~gi.repository.JavaScriptCore.Class | None = None) -> ~gi.repository.JavaScriptCore.Value

      Create a new :obj:`~gi.repository.JavaScriptCore.Value` from ``instance``\. If ``instance`` is :const:`None` a new empty object is created.
      When ``instance`` is provided, ``jsc_class`` must be provided too. ``jsc_class`` takes ownership of
      ``instance`` that will be freed by the :obj:`~gi.repository.GLib.DestroyNotify` passed to :func:`~gi.repository.JavaScriptCore.Context.register_class`.






      :param context: a :obj:`~gi.repository.JavaScriptCore.Context`

      :param instance: an object instance or :const:`None`

      :param jsc_class: the :obj:`~gi.repository.JavaScriptCore.Class` of ``instance``




   .. classmethod:: new_string(context: ~gi.repository.JavaScriptCore.Context, string: str | None = None) -> ~gi.repository.JavaScriptCore.Value

      Create a new :obj:`~gi.repository.JavaScriptCore.Value` from ``string``\. If you need to create a :obj:`~gi.repository.JavaScriptCore.Value` from a
      string containing null characters, use :func:`~gi.repository.JavaScriptCore.Value.new_string_from_bytes` instead.






      :param context: a :obj:`~gi.repository.JavaScriptCore.Context`

      :param string: a null-terminated string




   .. classmethod:: new_string_from_bytes(context: ~gi.repository.JavaScriptCore.Context, bytes: ~gi.repository.GLib.Bytes | None = None) -> ~gi.repository.JavaScriptCore.Value

      Create a new :obj:`~gi.repository.JavaScriptCore.Value` from ``bytes``\.






      :param context: a :obj:`~gi.repository.JavaScriptCore.Context`

      :param bytes: a :obj:`~gi.repository.GLib.Bytes`




   .. classmethod:: new_typed_array(context: ~gi.repository.JavaScriptCore.Context, type: ~gi.repository.JavaScriptCore.TypedArrayType, length: int) -> ~gi.repository.JavaScriptCore.Value

      Create a new typed array containing a given amount of elements.

      Create a :obj:`~gi.repository.JavaScriptCore.Value` referencing a new typed array with space for ``length``
      elements of a given ``type``\. As all typed arrays must have an associated
      ``ArrayBuffer``\, a new one of suitable size will be allocated to store
      the elements, which will be initialized to zero.

      The ``type`` must *not* be :const:`~gi.repository.JavaScriptCore.TypedArrayType.NONE`.


      .. versionadded:: 2.38





      :param context: a :obj:`~gi.repository.JavaScriptCore.Context`

      :param type: the type of array elements

      :param length: number of elements in the array




   .. classmethod:: new_undefined(context: ~gi.repository.JavaScriptCore.Context) -> ~gi.repository.JavaScriptCore.Value

      Create a new :obj:`~gi.repository.JavaScriptCore.Value` referencing <function>undefined</function> in ``context``\.






      :param context: a :obj:`~gi.repository.JavaScriptCore.Context`








Methods
-------

.. rst-class:: interim-class

.. class:: Value
   :no-index:


   .. method:: array_buffer_get_data(size: int | None = None) -> ~typing.Any | None

      Gets a pointer to memory that contains the array buffer data.

      Obtains a pointer to the memory region that holds the contents of the
      %ArrayBuffer; modifications done to the data will be visible to JavaScript
      code. If ``size`` is not :const:`None`, the size in bytes of the memory region
      will also be stored in the pointed location.

      Note that the pointer returned by this function is not guaranteed to remain
      the same after calls to other JSC API functions. If you plan to access the
      data of the %ArrayBuffer later, you can keep a reference to the ``value`` and
      obtain the data pointer at a later point. Keep in mind that if JavaScript
      code has a chance to run, for example due to main loop events that result
      in JSC being called, the contents of the memory region might be modified in
      the meantime. Consider taking a copy of the data and using the copy instead
      in asynchronous code.


      .. versionadded:: 2.38





      :param size: location where to store the size of the memory region.




   .. method:: array_buffer_get_size() -> int

      Gets the size in bytes of the array buffer.

      Obtains the size in bytes of the memory region that holds the contents of
      an %ArrayBuffer.


      .. versionadded:: 2.38








   .. method:: constructor_call(parameters: list[~gi.repository.JavaScriptCore.Value] | None = None) -> ~gi.repository.JavaScriptCore.Value

      Invoke <function>new</function> with constructor referenced by ``value``\. If ``first_parameter_type``
      is %G_TYPE_NONE no parameters will be passed to the constructor.






      :param parameters: 




   .. method:: function_call(parameters: list[~gi.repository.JavaScriptCore.Value] | None = None) -> ~gi.repository.JavaScriptCore.Value

      Call function referenced by ``value``\, passing the given parameters. If ``first_parameter_type``
      is %G_TYPE_NONE no parameters will be passed to the function.

      This function always returns a :obj:`~gi.repository.JavaScriptCore.Value`\, in case of void functions a :obj:`~gi.repository.JavaScriptCore.Value` referencing
      <function>undefined</function> is returned






      :param parameters: 




   .. method:: get_context() -> ~gi.repository.JavaScriptCore.Context

      Get the :obj:`~gi.repository.JavaScriptCore.Context` in which ``value`` was created.









   .. method:: is_array() -> bool

      Get whether the value referenced by ``value`` is an array.









   .. method:: is_array_buffer() -> bool

      Check whether the ``value`` is an %ArrayBuffer.


      .. versionadded:: 2.38








   .. method:: is_boolean() -> bool

      Get whether the value referenced by ``value`` is a boolean.









   .. method:: is_constructor() -> bool

      Get whether the value referenced by ``value`` is a constructor.









   .. method:: is_function() -> bool

      Get whether the value referenced by ``value`` is a function









   .. method:: is_null() -> bool

      Get whether the value referenced by ``value`` is <function>null</function>.









   .. method:: is_number() -> bool

      Get whether the value referenced by ``value`` is a number.









   .. method:: is_object() -> bool

      Get whether the value referenced by ``value`` is an object.









   .. method:: is_string() -> bool

      Get whether the value referenced by ``value`` is a string









   .. method:: is_typed_array() -> bool

      Determines whether a value is a typed array.


      .. versionadded:: 2.38








   .. method:: is_undefined() -> bool

      Get whether the value referenced by ``value`` is <function>undefined</function>.









   .. method:: new_typed_array_with_buffer(type: ~gi.repository.JavaScriptCore.TypedArrayType, offset: int, length: int) -> ~gi.repository.JavaScriptCore.Value

      Create a new typed array value with elements from an array buffer.

      Create a :obj:`~gi.repository.JavaScriptCore.Value` referencing a new typed array value containing
      elements of the given ``type``\, where the elements are stored at the memory
      region represented by the ``array_buffer``\.

      The ``type`` must *not* be :const:`~gi.repository.JavaScriptCore.TypedArrayType.NONE`.

      The ``offset`` and ``length`` parameters can be used to indicate which part of
      the array buffer can be accessed through the typed array. If both are
      omitted (passing zero as ``offset``\, and ``-1`` as ``length``\), the whole
      ``array_buffer`` is exposed through the typed array. Omitting the ``length``
      with a non-zero ``offset`` will expose the remainder of the ``array_buffer``
      starting at the indicated offset.


      .. versionadded:: 2.38





      :param type: type of array elements.

      :param offset: offset, in bytes.

      :param length: number of array elements, or ``-1``\.




   .. method:: object_define_property_accessor(property_name: str, flags: ~gi.repository.JavaScriptCore.ValuePropertyFlags, property_type: ~gobject.GType, getter: ~typing.Callable[[], None] | None = None, setter: ~typing.Callable[[], None] | None = None, user_data: ~typing.Any = None) -> None

      Define or modify a property with ``property_name`` in object referenced by ``value``\. When the
      property value needs to be getted or set, ``getter`` and ``setter`` callbacks will be called.
      When the property is cleared in the :obj:`~gi.repository.JavaScriptCore.Class` context, ``destroy_notify`` is called with
      ``user_data`` as parameter. This is equivalent to JavaScript <function>Object.defineProperty()</function>
      when used with an accessor descriptor.

      Note that the value returned by ``getter`` must be fully transferred. In case of boxed types, you could use
      %G_TYPE_POINTER instead of the actual boxed :obj:`~gi.repository.GObject.Type` to ensure that the instance owned by :obj:`~gi.repository.JavaScriptCore.Class` is used.
      If you really want to return a new copy of the boxed type, use ``JSC_TYPE_VALUE`` and return a :obj:`~gi.repository.JavaScriptCore.Value` created
      with :func:`~gi.repository.JavaScriptCore.Value.new_object` that receives the copy as instance parameter.

      Note that ``getter`` and ``setter`` are called as functions and not methods, so they don't receive an instance as
      first parameter. Use :func:`~gi.repository.JavaScriptCore.Class.add_property` if you want to add property accessor invoked as a method.






      :param property_name: the name of the property to define

      :param flags: :obj:`~gi.repository.JavaScriptCore.ValuePropertyFlags`

      :param property_type: the :obj:`~gi.repository.GObject.Type` of the property

      :param getter: a :obj:`~gi.repository.GObject.Callback` to be called to get the property value

      :param setter: a :obj:`~gi.repository.GObject.Callback` to be called to set the property value

      :param user_data: user data to pass to ``getter`` and ``setter``




   .. method:: object_define_property_data(property_name: str, flags: ~gi.repository.JavaScriptCore.ValuePropertyFlags, property_value: ~gi.repository.JavaScriptCore.Value | None = None) -> None

      Define or modify a property with ``property_name`` in object referenced by ``value``\. This is equivalent to
      JavaScript <function>Object.defineProperty()</function> when used with a data descriptor.






      :param property_name: the name of the property to define

      :param flags: :obj:`~gi.repository.JavaScriptCore.ValuePropertyFlags`

      :param property_value: the default property value




   .. method:: object_delete_property(name: str) -> bool

      Try to delete property with ``name`` from ``value``\. This function will return :const:`False` if
      the property was defined without :const:`~gi.repository.JavaScriptCore.ValuePropertyFlags.CONFIGURABLE` flag.






      :param name: the property name




   .. method:: object_enumerate_properties() -> list[str] | None

      Get the list of property names of ``value``\. Only properties defined with :const:`~gi.repository.JavaScriptCore.ValuePropertyFlags.ENUMERABLE`
      flag will be collected.









   .. method:: object_get_property(name: str) -> ~gi.repository.JavaScriptCore.Value

      Get property with ``name`` from ``value``\.






      :param name: the property name




   .. method:: object_get_property_at_index(index: int) -> ~gi.repository.JavaScriptCore.Value

      Get property at ``index`` from ``value``\.






      :param index: the property index




   .. method:: object_has_property(name: str) -> bool

      Get whether ``value`` has property with ``name``\.






      :param name: the property name




   .. method:: object_invoke_method(name: str, parameters: list[~gi.repository.JavaScriptCore.Value] | None = None) -> ~gi.repository.JavaScriptCore.Value

      Invoke method with ``name`` on object referenced by ``value``\, passing the given parameters. If
      ``first_parameter_type`` is %G_TYPE_NONE no parameters will be passed to the method.
      The object instance will be handled automatically even when the method is a custom one
      registered with :func:`~gi.repository.JavaScriptCore.Class.add_method`, so it should never be passed explicitly as parameter
      of this function.

      This function always returns a :obj:`~gi.repository.JavaScriptCore.Value`\, in case of void methods a :obj:`~gi.repository.JavaScriptCore.Value` referencing
      <function>undefined</function> is returned.






      :param name: the method name

      :param parameters: 




   .. method:: object_is_instance_of(name: str) -> bool

      Get whether the value referenced by ``value`` is an instance of class ``name``\.






      :param name: a class name




   .. method:: object_set_property(name: str, property: ~gi.repository.JavaScriptCore.Value) -> None

      Set ``property`` with ``name`` on ``value``\.






      :param name: the property name

      :param property: the :obj:`~gi.repository.JavaScriptCore.Value` to set




   .. method:: object_set_property_at_index(index: int, property: ~gi.repository.JavaScriptCore.Value) -> None

      Set ``property`` at ``index`` on ``value``\.






      :param index: the property index

      :param property: the :obj:`~gi.repository.JavaScriptCore.Value` to set




   .. method:: to_boolean() -> bool

      Convert ``value`` to a boolean.









   .. method:: to_double() -> float

      Convert ``value`` to a double.









   .. method:: to_int32() -> int

      Convert ``value`` to a :obj:`int`.









   .. method:: to_json(indent: int) -> str

      Create a JSON string of ``value`` serialization. If ``indent`` is 0, the resulting JSON will
      not contain newlines. The size of the indent is clamped to 10 spaces.


      .. versionadded:: 2.28





      :param indent: The number of spaces to indent when nesting.




   .. method:: to_string() -> str

      Convert ``value`` to a string. Use :func:`~gi.repository.JavaScriptCore.Value.to_string_as_bytes` instead, if you need to
      handle strings containing null characters.









   .. method:: to_string_as_bytes() -> ~gi.repository.GLib.Bytes

      Convert ``value`` to a string and return the results as :obj:`~gi.repository.GLib.Bytes`\. This is needed
      to handle strings with null characters.









   .. method:: typed_array_get_buffer() -> ~gi.repository.JavaScriptCore.Value

      Obtain the %ArrayBuffer for the memory region of the typed array elements.


      .. versionadded:: 2.38








   .. method:: typed_array_get_data() -> ~typing.Tuple[~typing.Any | None, int | None]

      Obtains a pointer to the memory region that holds the elements of the typed
      array; modifications done to them will be visible to JavaScript code. If
      ``length`` is not :const:`None`, the number of elements contained in the typed array
      are also stored in the pointed location.

      The returned pointer needs to be casted to the appropriate type (see
      :obj:`~gi.repository.JavaScriptCore.TypedArrayType`\), and has the ``offset`` over the underlying array
      buffer data applied—that is, points to the first element of the typed
      array:


      .. code-block:: C
          :dedent:

          if (jsc_value_typed_array_get_type(value) != JSC_TYPED_ARRAY_UINT32)
              g_error ("Only arrays of uint32_t are supported");

          gsize count = 0;
          uint32_t *elements = jsc_value_typed_array_get_contents (value, &count);
          for (gsize i = 0; i < count; i++)
               g_print ("index %zu, value %" PRIu32 "\n", i, elements[i]);

      Note that the pointer returned by this function is not guaranteed to remain
      the same after calls to other JSC API functions. See
      :func:`~gi.repository.JavaScriptCore.Value.array_buffer_get_data` for details.


      .. versionadded:: 2.38








   .. method:: typed_array_get_length() -> int

      Gets the number of elements in a typed array.


      .. versionadded:: 2.38








   .. method:: typed_array_get_offset() -> int

      Gets the offset over the underlying array buffer data.


      .. versionadded:: 2.38








   .. method:: typed_array_get_size() -> int

      Gets the size of a typed array.


      .. versionadded:: 2.38








   .. method:: typed_array_get_type() -> ~gi.repository.JavaScriptCore.TypedArrayType

      Gets the type of elements contained in a typed array.


      .. versionadded:: 2.38












Properties
----------

.. rst-class:: interim-class

.. class:: Value
   :no-index:
   

   .. attribute:: props.context
      :type: ~gi.repository.JavaScriptCore.Context

      The type of the None singleton.