Value#

class Value(**properties: Any)#

Superclasses: Object

JSCValue represents a reference to a value in a Context. The JSCValue protects the referenced value from being garbage collected.

Constructors#

class Value
classmethod new_array_buffer(context: Context, data: Any, size: int, destroy_notify: Callable[[Any], None] | None = None, user_data: Any = None) → 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:

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

Added in version 2.38.

Parameters:

  • context – A Context

  • data – Pointer to a region of memory.

  • size – Size in bytes of the memory region.

  • destroy_notify – destroy notifier for user_data.

  • user_data – user data.

classmethod new_array_from_garray(context: Context, array: list[Value] | None = None) → Value#

Create a new Value referencing an array with the items from array. If array is None or empty a new empty array will be created. Elements of array should be pointers to a Value.

Parameters:

  • context – a Context

  • array – a GPtrArray

classmethod new_array_from_strv(context: Context, strv: list[str]) → Value#

Create a new Value referencing an array of strings with the items from strv. If array is None or empty a new empty array will be created.

Parameters:

  • context – a Context

  • strv – a None-terminated array of strings

classmethod new_boolean(context: Context, value: bool) → Value#

Create a new Value from value

Parameters:

  • context – a Context

  • value – a gboolean

classmethod new_from_json(context: Context, json: str) → Value#

Create a new Value referencing a new value created by parsing json.

Added in version 2.28.

Parameters:

  • context – a Context

  • json – the JSON string to be parsed

classmethod new_function(context: Context, name: str | None, callback: Callable[[], None], user_data: Any, return_type: GType, parameter_types: list[GType] | None = None) → Value#

Create a function in context. If name is None an anonymous function will be created. When the function is called by JavaScript or 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 Type to ensure that the instance owned by Class is used. If you really want to return a new copy of the boxed type, use JSC_TYPE_VALUE and return a Value created with new_object() that receives the copy as instance parameter.

Parameters:

  • context – a Context:

  • name – the function name or None

  • callback – a Callback.

  • user_data – user data to pass to callback.

  • return_type – the Type of the function return value, or %G_TYPE_NONE if the function is void.

  • parameter_types

classmethod new_function_variadic(context: Context, name: str | None, callback: Callable[[], None], user_data: Any, return_type: GType) → Value#

Create a function in context. If name is None an anonymous function will be created. When the function is called by JavaScript or function_call(), callback is called receiving an GPtrArray of 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 Type to ensure that the instance owned by Class is used. If you really want to return a new copy of the boxed type, use JSC_TYPE_VALUE and return a Value created with new_object() that receives the copy as instance parameter.

Parameters:

  • context – a Context

  • name – the function name or None

  • callback – a Callback.

  • user_data – user data to pass to callback.

  • return_type – the Type of the function return value, or %G_TYPE_NONE if the function is void.

classmethod new_null(context: Context) → Value#

Create a new Value referencing <function>null</function> in context.

Parameters:

context – a Context

classmethod new_number(context: Context, number: float) → Value#

Create a new Value from number.

Parameters:

  • context – a Context

  • number – a number

classmethod new_object(context: Context, instance: Any = None, jsc_class: Class | None = None) → Value#

Create a new Value from instance. If instance is 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 DestroyNotify passed to register_class().

Parameters:

  • context – a Context

  • instance – an object instance or None

  • jsc_class – the Class of instance

classmethod new_string(context: Context, string: str | None = None) → Value#

Create a new Value from string. If you need to create a Value from a string containing null characters, use new_string_from_bytes() instead.

Parameters:

  • context – a Context

  • string – a null-terminated string

classmethod new_string_from_bytes(context: Context, bytes: Bytes | None = None) → Value#

Create a new Value from bytes.

Parameters:
classmethod new_typed_array(context: Context, type: TypedArrayType, length: int) → Value#

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

Create a 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 NONE.

Added in version 2.38.

Parameters:

  • context – a Context

  • type – the type of array elements

  • length – number of elements in the array

classmethod new_undefined(context: Context) → Value#

Create a new Value referencing <function>undefined</function> in context.

Parameters:

context – a Context

Methods#

class Value
array_buffer_get_data(size: int | None = None) → 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 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.

Added in version 2.38.

Parameters:

size – location where to store the size of the memory region.

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.

Added in version 2.38.

constructor_call(parameters: list[Value] | None = None) → 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.

Parameters:

parameters

function_call(parameters: list[Value] | None = None) → 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 Value, in case of void functions a Value referencing <function>undefined</function> is returned

Parameters:

parameters

get_context() → Context#

Get the Context in which value was created.

is_array() → bool#

Get whether the value referenced by value is an array.

is_array_buffer() → bool#

Check whether the value is an %ArrayBuffer.

Added in version 2.38.

is_boolean() → bool#

Get whether the value referenced by value is a boolean.

is_constructor() → bool#

Get whether the value referenced by value is a constructor.

is_function() → bool#

Get whether the value referenced by value is a function

is_null() → bool#

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

is_number() → bool#

Get whether the value referenced by value is a number.

is_object() → bool#

Get whether the value referenced by value is an object.

is_string() → bool#

Get whether the value referenced by value is a string

is_typed_array() → bool#

Determines whether a value is a typed array.

Added in version 2.38.

is_undefined() → bool#

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

new_typed_array_with_buffer(type: TypedArrayType, offset: int, length: int) → Value#

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

Create a 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 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.

Added in version 2.38.

Parameters:

  • type – type of array elements.

  • offset – offset, in bytes.

  • length – number of array elements, or -1.

object_define_property_accessor(property_name: str, flags: ValuePropertyFlags, property_type: GType, getter: Callable[[], None] | None = None, setter: Callable[[], None] | None = None, user_data: 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 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 Type to ensure that the instance owned by Class is used. If you really want to return a new copy of the boxed type, use JSC_TYPE_VALUE and return a Value created with 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 add_property() if you want to add property accessor invoked as a method.

Parameters:

  • property_name – the name of the property to define

  • flags – ValuePropertyFlags

  • property_type – the Type of the property

  • getter – a Callback to be called to get the property value

  • setter – a Callback to be called to set the property value

  • user_data – user data to pass to getter and setter

object_define_property_data(property_name: str, flags: ValuePropertyFlags, property_value: 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.

Parameters:

  • property_name – the name of the property to define

  • flags – ValuePropertyFlags

  • property_value – the default property value

object_delete_property(name: str) → bool#

Try to delete property with name from value. This function will return False if the property was defined without CONFIGURABLE flag.

Parameters:

name – the property name

object_enumerate_properties() → list[str] | None#

Get the list of property names of value. Only properties defined with ENUMERABLE flag will be collected.

object_get_property(name: str) → Value#

Get property with name from value.

Parameters:

name – the property name

object_get_property_at_index(index: int) → Value#

Get property at index from value.

Parameters:

index – the property index

object_has_property(name: str) → bool#

Get whether value has property with name.

Parameters:

name – the property name

object_invoke_method(name: str, parameters: list[Value] | None = None) → 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 add_method(), so it should never be passed explicitly as parameter of this function.

This function always returns a Value, in case of void methods a Value referencing <function>undefined</function> is returned.

Parameters:

  • name – the method name

  • parameters

object_is_instance_of(name: str) → bool#

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

Parameters:

name – a class name

object_set_property(name: str, property: Value) → None#

Set property with name on value.

Parameters:

  • name – the property name

  • property – the Value to set

object_set_property_at_index(index: int, property: Value) → None#

Set property at index on value.

Parameters:

  • index – the property index

  • property – the Value to set

to_boolean() → bool#

Convert value to a boolean.

to_double() → float#

Convert value to a double.

to_int32() → int#

Convert value to a int.

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.

Added in version 2.28.

Parameters:

indent – The number of spaces to indent when nesting.

to_string() → str#

Convert value to a string. Use to_string_as_bytes() instead, if you need to handle strings containing null characters.

to_string_as_bytes() → Bytes#

Convert value to a string and return the results as Bytes. This is needed to handle strings with null characters.

typed_array_get_buffer() → Value#

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

Added in version 2.38.

typed_array_get_data() → Tuple[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 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 TypedArrayType), and has the offset over the underlying array buffer data applied—that is, points to the first element of the typed array:

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 array_buffer_get_data() for details.

Added in version 2.38.

typed_array_get_length() → int#

Gets the number of elements in a typed array.

Added in version 2.38.

typed_array_get_offset() → int#

Gets the offset over the underlying array buffer data.

Added in version 2.38.

typed_array_get_size() → int#

Gets the size of a typed array.

Added in version 2.38.

typed_array_get_type() → TypedArrayType#

Gets the type of elements contained in a typed array.

Added in version 2.38.

Properties#

class Value
props.context: Context#

The type of the None singleton.