JSCValue: JavaScriptCore GLib Reference Manual

## JSCValue JSCValue — JavaScript value |

## Functions

JSCContext * | jsc_value_get_context ()
JSCValue * | jsc_value_new_undefined ()
gboolean | jsc_value_is_undefined ()
JSCValue * | jsc_value_new_null ()
gboolean | jsc_value_is_null ()
JSCValue * | jsc_value_new_number ()
gboolean | jsc_value_is_number ()
double | jsc_value_to_double ()
gint32 | jsc_value_to_int32 ()
JSCValue * | jsc_value_new_boolean ()
gboolean | jsc_value_is_boolean ()
gboolean | jsc_value_to_boolean ()
JSCValue * | jsc_value_new_string ()
JSCValue * | jsc_value_new_string_from_bytes ()
gboolean | jsc_value_is_string ()
char * | jsc_value_to_string ()
GBytes * | jsc_value_to_string_as_bytes ()
JSCValue * | jsc_value_new_array ()
JSCValue * | jsc_value_new_array_from_garray ()
JSCValue * | jsc_value_new_array_from_strv ()
gboolean | jsc_value_is_array ()
JSCValue * | jsc_value_new_object ()
gboolean | jsc_value_is_object ()
gboolean | jsc_value_object_is_instance_of ()
void | jsc_value_object_set_property ()
JSCValue * | jsc_value_object_get_property ()
void | jsc_value_object_set_property_at_index ()
JSCValue * | jsc_value_object_get_property_at_index ()
gboolean | jsc_value_object_has_property ()
gboolean | jsc_value_object_delete_property ()
gchar ** | jsc_value_object_enumerate_properties ()
JSCValue * | jsc_value_object_invoke_method ()
JSCValue * | jsc_value_object_invoke_methodv ()
void | jsc_value_object_define_property_data ()
void | jsc_value_object_define_property_accessor ()
JSCValue * | jsc_value_new_function ()
JSCValue * | jsc_value_new_functionv ()
JSCValue * | jsc_value_new_function_variadic ()
gboolean | jsc_value_is_function ()
JSCValue * | jsc_value_function_call ()
JSCValue * | jsc_value_function_callv ()
gboolean | jsc_value_is_constructor ()
JSCValue * | jsc_value_constructor_call ()
JSCValue * | jsc_value_constructor_callv ()

## Properties

JSCContext * | context | Read / Write / Construct Only

## Types and Values

struct | JSCValue
enum | JSCValuePropertyFlags

## Object Hierarchy

        GObject
        ╰── JSCValue

## Description

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

## Functions

### jsc_value_get_context ()

    JSCContext *
    jsc_value_get_context (JSCValue *value);

Get the JSCContext in which `value` was created.

#### Parameters

value | a JSCValue |

#### Returns

the JSCValue context.

[transfer none]

### jsc_value_new_undefined ()

    JSCValue *
    jsc_value_new_undefined (JSCContext *context);

Create a new JSCValue referencing `undefined` in `context` .

#### Parameters

context | a JSCContext |

#### Returns

a JSCValue.

[transfer full]

### jsc_value_is_undefined ()

    gboolean
    jsc_value_is_undefined (JSCValue *value);

Get whether the value referenced by `value` is `undefined`.

#### Parameters

value | a JSCValue |

#### Returns

whether the value is undefined.

### jsc_value_new_null ()

    JSCValue *
    jsc_value_new_null (JSCContext *context);

Create a new JSCValue referencing `null` in `context` .

#### Parameters

context | a JSCContext |

#### Returns

a JSCValue.

[transfer full]

### jsc_value_is_null ()

    gboolean
    jsc_value_is_null (JSCValue *value);

Get whether the value referenced by `value` is `null`.

#### Parameters

value | a JSCValue |

#### Returns

whether the value is null.

### jsc_value_new_number ()

    JSCValue *
    jsc_value_new_number (JSCContext *context,
                          double number);

Create a new JSCValue from `number` .

#### Parameters

context | a JSCContext |
number | a number |

#### Returns

a JSCValue.

[transfer full]

### jsc_value_is_number ()

    gboolean
    jsc_value_is_number (JSCValue *value);

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

#### Parameters

value | a JSCValue |

#### Returns

whether the value is a number.

### jsc_value_to_double ()

    double
    jsc_value_to_double (JSCValue *value);

Convert `value` to a double.

#### Parameters

value | a JSCValue |

#### Returns

a gdouble result of the conversion.

### jsc_value_to_int32 ()

    gint32
    jsc_value_to_int32 (JSCValue *value);

Convert `value` to a gint32.

#### Parameters

value | a JSCValue |

#### Returns

a gint32 result of the conversion.

### jsc_value_new_boolean ()

    JSCValue *
    jsc_value_new_boolean (JSCContext *context,
                           gboolean value);

Create a new JSCValue from `value`

#### Parameters

context | a JSCContext |
value | a gboolean |

#### Returns

a JSCValue.

[transfer full]

### jsc_value_is_boolean ()

    gboolean
    jsc_value_is_boolean (JSCValue *value);

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

#### Parameters

value | a JSCValue |

#### Returns

whether the value is a boolean.

### jsc_value_to_boolean ()

    gboolean
    jsc_value_to_boolean (JSCValue *value);

Convert `value` to a boolean.

#### Parameters

value | a JSCValue |

#### Returns

a gboolean result of the conversion.

### jsc_value_new_string ()

    JSCValue *
    jsc_value_new_string (JSCContext *context,
                          const char *string);

Create a new JSCValue from `string` . If you need to create a JSCValue from a string containing null characters, use `jsc_value_new_string_from_bytes()` instead.

#### Parameters

context | a JSCContext |
string | a null-terminated string. | [nullable]

#### Returns

a JSCValue.

[transfer full]

### jsc_value_new_string_from_bytes ()

    JSCValue *
    jsc_value_new_string_from_bytes (JSCContext *context,
                                     GBytes *bytes);

Create a new JSCValue from `bytes` .

#### Parameters

context | a JSCContext |
bytes | a GBytes. | [nullable]

#### Returns

a JSCValue.

[transfer full]

### jsc_value_is_string ()

    gboolean
    jsc_value_is_string (JSCValue *value);

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

#### Parameters

value | a JSCValue |

#### Returns

whether the value is a string

### jsc_value_to_string ()

    char *
    jsc_value_to_string (JSCValue *value);

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

#### Parameters

value | a JSCValue |

#### Returns

a null-terminated string result of the conversion.

[transfer full]

### jsc_value_to_string_as_bytes ()

    GBytes *
    jsc_value_to_string_as_bytes (JSCValue *value);

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

#### Parameters

value | a JSCValue |

#### Returns

a GBytes with the result of the conversion.

[transfer full]

### jsc_value_new_array ()

    JSCValue *
    jsc_value_new_array (JSCContext *context,
                         GType first_item_type,
                         ...);

Create a new JSCValue referencing an array with the given items. If `first_item_type` is `G_TYPE_NONE` an empty array is created.

[skip]

#### Parameters

context | a JSCContext |
first_item_type | GType of first item, or `G_TYPE_NONE` |
... | value of the first item, followed optionally by more type/value pairs, followed by `G_TYPE_NONE`. |

#### Returns

a JSCValue.

[transfer full]

### jsc_value_new_array_from_garray ()

    JSCValue *
    jsc_value_new_array_from_garray (JSCContext *context,
                                     GPtrArray *array);

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

#### Parameters

context | a JSCContext |
array | a GPtrArray. | [nullable][element-type JSCValue]

#### Returns

a JSCValue.

[transfer full]

### jsc_value_new_array_from_strv ()

    JSCValue *
    jsc_value_new_array_from_strv (JSCContext *context,
                                   const char *const *strv);

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

#### Parameters

context | a JSCContext |
strv | a `NULL`-terminated array of strings. | [array zero-terminated=1][element-type utf8]

#### Returns

a JSCValue.

[transfer full]

### jsc_value_is_array ()

    gboolean
    jsc_value_is_array (JSCValue *value);

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

#### Parameters

value | a JSCValue |

#### Returns

whether the value is an array.

### jsc_value_new_object ()

    JSCValue *
    jsc_value_new_object (JSCContext *context,
                          gpointer instance,
                          JSCClass *jsc_class);

Create a new JSCValue from `instance` . If `instance` is `NULL` 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 GDestroyNotify passed to `jsc_context_register_class()`.

#### Parameters

context | a JSCContext |
instance | an object instance or `NULL`. | [nullable][transfer full]
jsc_class | the JSCClass of `instance` . | [nullable]

#### Returns

a JSCValue.

[transfer full]

### jsc_value_is_object ()

    gboolean
    jsc_value_is_object (JSCValue *value);

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

#### Parameters

value | a JSCValue |

#### Returns

whether the value is an object.

### jsc_value_object_is_instance_of ()

    gboolean
    jsc_value_object_is_instance_of (JSCValue *value,
                                     const char *name);

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

#### Parameters

value | a JSCValue |
name | a class name |

#### Returns

whether the value is an object instance of class `name` .

### jsc_value_object_set_property ()

    void
    jsc_value_object_set_property (JSCValue *value,
                                   const char *name,
                                   JSCValue *property);

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

#### Parameters

value | a JSCValue |
name | the property name |
property | the JSCValue to set |

### jsc_value_object_get_property ()

    JSCValue *
    jsc_value_object_get_property (JSCValue *value,
                                   const char *name);

Get property with `name` from `value` .

#### Parameters

value | a JSCValue |
name | the property name |

#### Returns

the property JSCValue.

[transfer full]

### jsc_value_object_set_property_at_index ()

    void
    jsc_value_object_set_property_at_index
                                   (JSCValue *value,
                                    guint index,
                                    JSCValue *property);

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

#### Parameters

value | a JSCValue |
index | the property index |
property | the JSCValue to set |

### jsc_value_object_get_property_at_index ()

    JSCValue *
    jsc_value_object_get_property_at_index
                                   (JSCValue *value,
                                    guint index);

Get property at `index` from `value` .

#### Parameters

value | a JSCValue |
index | the property index |

#### Returns

the property JSCValue.

[transfer full]

### jsc_value_object_has_property ()

    gboolean
    jsc_value_object_has_property (JSCValue *value,
                                   const char *name);

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

#### Parameters

value | a JSCValue |
name | the property name |

#### Returns

`TRUE` if `value` has a property with `name` , or `FALSE` otherwise

### jsc_value_object_delete_property ()

    gboolean
    jsc_value_object_delete_property (JSCValue *value,
                                      const char *name);

Try to delete property with `name` from `value` . This function will return `FALSE` if the property was defined without `JSC_VALUE_PROPERTY_CONFIGURABLE` flag.

#### Parameters

value | a JSCValue |
name | the property name |

#### Returns

`TRUE` if the property was deleted, or `FALSE` otherwise.

### jsc_value_object_enumerate_properties ()

    gchar **
    jsc_value_object_enumerate_properties (JSCValue *value);

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

#### Parameters

value | a JSCValue |

#### Returns

a `NULL`-terminated array of strings containing the property names, or `NULL` if `value` doesn't have enumerable properties. Use `g_strfreev()` to free.

[array zero-terminated=1][transfer full][nullable]

### jsc_value_object_invoke_method ()

    JSCValue *
    jsc_value_object_invoke_method (JSCValue *value,
                                    const char *name,
                                    GType first_parameter_type,
                                    ...);

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 `jsc_class_add_method()`, so it should never be passed explicitly as parameter of this function.

This function always returns a JSCValue, in case of void methods a JSCValue referencing `undefined` is returned.

[skip]

#### Parameters

value | a JSCValue |
name | the method name |
first_parameter_type | GType of first parameter, or `G_TYPE_NONE` |
... | value of the first parameter, followed optionally by more type/value pairs, followed by `G_TYPE_NONE` |

#### Returns

a JSCValue with the return value of the method.

[transfer full]

### jsc_value_object_invoke_methodv ()

    JSCValue *
    jsc_value_object_invoke_methodv (JSCValue *value,
                                     const char *name,
                                     guint n_parameters,
                                     JSCValue **parameters);

Invoke method with `name` on object referenced by `value` , passing the given `parameters` . If `n_parameters` is 0 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 `jsc_class_add_method()`, so it should never be passed explicitly as parameter of this function.

This function always returns a JSCValue, in case of void methods a JSCValue referencing `undefined` is returned.

[rename-to jsc_value_object_invoke_method]

#### Parameters

value | a JSCValue |
name | the method name |
n_parameters | the number of parameters |
parameters | the JSCValues to pass as parameters to the method, or `NULL`. | [nullable][array length=n_parameters][element-type JSCValue]

#### Returns

a JSCValue with the return value of the method.

[transfer full]

### jsc_value_object_define_property_data ()

    void
    jsc_value_object_define_property_data (JSCValue *value,
                                           const char *property_name,
                                           JSCValuePropertyFlags flags,
                                           JSCValue *property_value);

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

#### Parameters

value | a JSCValue |
property_name | the name of the property to define |
flags | JSCValuePropertyFlags |
property_value | the default property value. | [nullable]

### jsc_value_object_define_property_accessor ()

    void
    jsc_value_object_define_property_accessor
                                   (JSCValue *value,
                                    const char *property_name,
                                    JSCValuePropertyFlags flags,
                                    GType property_type,
                                    GCallback getter,
                                    GCallback setter,
                                    gpointer user_data,
                                    GDestroyNotify destroy_notify);

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 JSCClass context, `destroy_notify` is called with `user_data` as parameter. This is equivalent to JavaScript `Object.defineProperty()` 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 GType to ensure that the instance owned by JSCClass is used. If you really want to return a new copy of the boxed type, use JSC_TYPE_VALUE and return a JSCValue created with `jsc_value_new_object()` that receives the copy as instance parameter.

#### Parameters

value | a JSCValue |
property_name | the name of the property to define |
flags | JSCValuePropertyFlags |
property_type | the GType of the property |
getter | a GCallback to be called to get the property value. | [scope async][nullable]
setter | a GCallback to be called to set the property value. | [scope async][nullable]
user_data | user data to pass to `getter` and `setter` . | [closure]
destroy_notify | destroy notifier for `user_data` . | [nullable]

### jsc_value_new_function ()

    JSCValue *
    jsc_value_new_function (JSCContext *context,
                            const char *name,
                            GCallback callback,
                            gpointer user_data,
                            GDestroyNotify destroy_notify,
                            GType return_type,
                            guint n_params,
                            ...);

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

[skip]

#### Parameters

context | a JSCContext: |
name | the function name or `NULL`. | [nullable]
callback | a GCallback. | [scope async]
user_data | user data to pass to `callback` . | [closure]
destroy_notify | destroy notifier for `user_data` . | [nullable]
return_type | the GType of the function return value, or `G_TYPE_NONE` if the function is void. |
n_params | the number of parameter types to follow or 0 if the function doesn't receive parameters. |
... | a list of GTypes, one for each parameter. |

#### Returns

a JSCValue.

[transfer full]

### jsc_value_new_functionv ()

    JSCValue *
    jsc_value_new_functionv (JSCContext *context,
                             const char *name,
                             GCallback callback,
                             gpointer user_data,
                             GDestroyNotify destroy_notify,
                             GType return_type,
                             guint n_parameters,
                             GType *parameter_types);

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

[rename-to jsc_value_new_function]

#### Parameters

context | a JSCContext |
name | the function name or `NULL`. | [nullable]
callback | a GCallback. | [scope async]
user_data | user data to pass to `callback` . | [closure]
destroy_notify | destroy notifier for `user_data` . | [nullable]
return_type | the GType of the function return value, or `G_TYPE_NONE` if the function is void. |
n_parameters | the number of parameters |
parameter_types | a list of GTypes, one for each parameter, or `NULL`. | [nullable][array length=n_parameters][element-type GType]

#### Returns

a JSCValue.

[transfer full]

### jsc_value_new_function_variadic ()

    JSCValue *
    jsc_value_new_function_variadic (JSCContext *context,
                                     const char *name,
                                     GCallback callback,
                                     gpointer user_data,
                                     GDestroyNotify destroy_notify,
                                     GType return_type);

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

#### Parameters

context | a JSCContext |
name | the function name or `NULL`. | [nullable]
callback | a GCallback. | [scope async]
user_data | user data to pass to `callback` . | [closure]
destroy_notify | destroy notifier for `user_data` . | [nullable]
return_type | the GType of the function return value, or `G_TYPE_NONE` if the function is void. |

#### Returns

a JSCValue.

[transfer full]

### jsc_value_is_function ()

    gboolean
    jsc_value_is_function (JSCValue *value);

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

#### Parameters

value | a JSCValue |

#### Returns

whether the value is a function.

### jsc_value_function_call ()

    JSCValue *
    jsc_value_function_call (JSCValue *value,
                             GType first_parameter_type,
                             ...);

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 JSCValue, in case of void functions a JSCValue referencing `undefined` is returned

[skip]

#### Parameters

value | a JSCValue |
first_parameter_type | GType of first parameter, or `G_TYPE_NONE` |
... | value of the first parameter, followed optionally by more type/value pairs, followed by `G_TYPE_NONE` |

#### Returns

a JSCValue with the return value of the function.

[transfer full]

### jsc_value_function_callv ()

    JSCValue *
    jsc_value_function_callv (JSCValue *value,
                              guint n_parameters,
                              JSCValue **parameters);

Call function referenced by `value` , passing the given `parameters` . If `n_parameters` is 0 no parameters will be passed to the function.

This function always returns a JSCValue, in case of void functions a JSCValue referencing `undefined` is returned

[rename-to jsc_value_function_call]

#### Parameters

value | a JSCValue |
n_parameters | the number of parameters |
parameters | the JSCValues to pass as parameters to the function, or `NULL`. | [nullable][array length=n_parameters][element-type JSCValue]

#### Returns

a JSCValue with the return value of the function.

[transfer full]

### jsc_value_is_constructor ()

    gboolean
    jsc_value_is_constructor (JSCValue *value);

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

#### Parameters

value | a JSCValue |

#### Returns

whether the value is a constructor.

### jsc_value_constructor_call ()

    JSCValue *
    jsc_value_constructor_call (JSCValue *value,
                                GType first_parameter_type,
                                ...);

Invoke `new` with constructor referenced by `value` . If `first_parameter_type` is `G_TYPE_NONE` no parameters will be passed to the constructor.

[skip]

#### Parameters

value | a JSCValue |
first_parameter_type | GType of first parameter, or `G_TYPE_NONE` |
... | value of the first parameter, followed optionally by more type/value pairs, followed by `G_TYPE_NONE` |

#### Returns

a JSCValue referencing the newly created object instance.

[transfer full]

### jsc_value_constructor_callv ()

    JSCValue *
    jsc_value_constructor_callv (JSCValue *value,
                                 guint n_parameters,
                                 JSCValue **parameters);

Invoke `new` with constructor referenced by `value` . If `n_parameters` is 0 no parameters will be passed to the constructor.

[rename-to jsc_value_constructor_call]

#### Parameters

value | a JSCValue |
n_parameters | the number of parameters |
parameters | the JSCValues to pass as parameters to the constructor, or `NULL`. | [nullable][array length=n_parameters][element-type JSCValue]

#### Returns

a JSCValue referencing the newly created object instance.

[transfer full]

## Types and Values

### struct JSCValue

    struct JSCValue;

### enum JSCValuePropertyFlags

Flags used when defining properties with `jsc_value_object_define_property_data()` and `jsc_value_object_define_property_accessor()`.

#### Members

JSC_VALUE_PROPERTY_CONFIGURABLE | the type of the property descriptor may be changed and the property may be deleted from the corresponding object. |
JSC_VALUE_PROPERTY_ENUMERABLE | the property shows up during enumeration of the properties on the corresponding object. |
JSC_VALUE_PROPERTY_WRITABLE | the value associated with the property may be changed with an assignment operator. This doesn't have any effect when passed to `jsc_value_object_define_property_accessor()`. |

## Property Details

### The `“context”` property

      “context”                  JSCContext *

The JSCContext in which the value was created.

Flags: Read / Write / Construct Only

## See Also

JSCContext