## Type Conversion Type Conversion — Moving between JavaScript and C intrinsic types |

## Synopsis

    #include <seed/seed.h>

    typedef             SeedValue;
    enum                SeedType;
    SeedValue           seed_make_undefined                 (SeedContext ctx);
    SeedValue           seed_make_null                      (SeedContext ctx);
    gboolean            seed_value_to_boolean               (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);
    SeedValue           seed_value_from_boolean             (SeedContext ctx,
                                                             gboolean val,
                                                             SeedException *exception);
    guint               seed_value_to_uint                  (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);
    SeedValue           seed_value_from_uint                (SeedContext ctx,
                                                             guint val,
                                                             SeedException *exception);
    gint                seed_value_to_int                   (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);
    SeedValue           seed_value_from_int                 (SeedContext ctx,
                                                             gint val,
                                                             SeedException *exception);
    gchar               seed_value_to_char                  (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);
    SeedValue           seed_value_from_char                (SeedContext ctx,
                                                             gchar val,
                                                             SeedException *exception);
    guchar              seed_value_to_uchar                 (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);
    SeedValue           seed_value_from_uchar               (SeedContext ctx,
                                                             guchar val,
                                                             SeedException *exception);
    glong               seed_value_to_long                  (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);
    SeedValue           seed_value_from_long                (SeedContext ctx,
                                                             glong val,
                                                             SeedException *exception);
    gulong              seed_value_to_ulong                 (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);
    SeedValue           seed_value_from_ulong               (SeedContext ctx,
                                                             gulong val,
                                                             SeedException *exception);
    gint64              seed_value_to_int64                 (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);
    SeedValue           seed_value_from_int64               (SeedContext ctx,
                                                             gint64 val,
                                                             SeedException *exception);
    guint64             seed_value_to_uint64                (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);
    SeedValue           seed_value_from_uint64              (SeedContext ctx,
                                                             guint64 val,
                                                             SeedException *exception);
    gfloat              seed_value_to_float                 (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);
    SeedValue           seed_value_from_float               (SeedContext ctx,
                                                             gfloat val,
                                                             SeedException *exception);
    gdouble             seed_value_to_double                (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);
    SeedValue           seed_value_from_double              (SeedContext ctx,
                                                             gdouble val,
                                                             SeedException *exception);
    gchar *             seed_value_to_string                (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);
    SeedValue           seed_value_from_string              (SeedContext ctx,
                                                             const gchar *val,
                                                             SeedException *exception);
    SeedValue           seed_value_from_binary_string       (SeedContext ctx,
                                                             const gchar *bytes,
                                                             gint n_bytes,
                                                             SeedException *exception);
    GObject *           seed_value_to_object                (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);
    SeedValue           seed_value_from_object              (SeedContext ctx,
                                                             GObject *val,
                                                             SeedException *exception);
    gchar *             seed_value_to_filename              (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedValue *exception);
    SeedValue           seed_value_from_filename            (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedValue *exception);
    gboolean            seed_value_to_format                (SeedContext ctx,
                                                             const gchar *format,
                                                             SeedValue *values,
                                                             SeedValue *exception,
                                                             ...);
    gpointer            seed_pointer_get_pointer            (SeedContext ctx,
                                                             SeedValue pointer);
    SeedValue           seed_make_pointer                   (SeedContext ctx,
                                                             gpointer pointer);
    typedef             SeedString;
    SeedString          seed_string_ref                     (SeedString string);
    void                seed_string_unref                   (SeedString string);
    gsize               seed_string_get_maximum_size        (SeedString string);
    gsize               seed_string_to_utf8_buffer          (SeedString string,
                                                             gchar *buffer,
                                                             size_t buffer_size);
    gboolean            seed_string_is_equal                (SeedString a,
                                                             SeedString b);
    gboolean            seed_string_is_equal_utf8           (SeedString a,
                                                             const gchar *b);

## Description

Long description

## Details

### SeedValue

    typedef gpointer SeedValue;

### enum SeedType

    typedef enum {
      SEED_TYPE_UNDEFINED,
      SEED_TYPE_NULL,
      SEED_TYPE_BOOLEAN,
      SEED_TYPE_NUMBER,
      SEED_TYPE_STRING,
      SEED_TYPE_OBJECT
    } SeedType;

### seed_make_undefined ()

    SeedValue           seed_make_undefined                 (SeedContext ctx);

Note that this function returns a valid SeedValue, representing the undefined JavaScript value, and not an undefined SeedValue.

`ctx` : | A valid SeedContext
Returns : | A SeedValue of the 'undefined' type.

### seed_make_null ()

    SeedValue           seed_make_null                      (SeedContext ctx);

Note that this function returns a valid SeedValue, representing the null JavaScript value, and not a null SeedValue.

`ctx` : | A valid SeedContext
Returns : | A SeedValue of the 'null' type.

### seed_value_to_boolean ()

    gboolean            seed_value_to_boolean               (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);

Converts the given SeedValue into a gboolean. Keep in mind that this will not convert a JavaScript number type, only a boolean.

`ctx` : | A SeedContext.
`val` : | The SeedValue to convert.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | The gboolean represented by `val`.

### seed_value_from_boolean ()

    SeedValue           seed_value_from_boolean             (SeedContext ctx,
                                                             gboolean val,
                                                             SeedException *exception);

Converts the given gboolean into a SeedValue.

`ctx` : | A SeedContext.
`val` : | The gboolean to represent.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | A SeedValue which represents `val`.

### seed_value_to_uint ()

    guint               seed_value_to_uint                  (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);

Converts the given SeedValue into a guint.

`ctx` : | A SeedContext.
`val` : | The SeedValue to convert.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | The guint represented by `val`.

### seed_value_from_uint ()

    SeedValue           seed_value_from_uint                (SeedContext ctx,
                                                             guint val,
                                                             SeedException *exception);

Converts the given guint into a SeedValue.

`ctx` : | A SeedContext.
`val` : | The guint to represent.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | A SeedValue which represents `val`.

### seed_value_to_int ()

    gint                seed_value_to_int                   (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);

Converts the given SeedValue into a gint.

`ctx` : | A SeedContext.
`val` : | The SeedValue to convert.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | The gint represented by `val`.

### seed_value_from_int ()

    SeedValue           seed_value_from_int                 (SeedContext ctx,
                                                             gint val,
                                                             SeedException *exception);

Converts the given gint into a SeedValue.

`ctx` : | A SeedContext.
`val` : | The gint to represent.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | A SeedValue which represents `val`.

### seed_value_to_char ()

    gchar               seed_value_to_char                  (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);

Converts the given SeedValue into a gchar.

`ctx` : | A SeedContext.
`val` : | The SeedValue to convert.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | The gchar represented by `val`.

### seed_value_from_char ()

    SeedValue           seed_value_from_char                (SeedContext ctx,
                                                             gchar val,
                                                             SeedException *exception);

Converts the given gchar into a SeedValue.

`ctx` : | A SeedContext.
`val` : | The gchar to represent.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | A SeedValue which represents `val`.

### seed_value_to_uchar ()

    guchar              seed_value_to_uchar                 (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);

Converts the given SeedValue into a guchar.

`ctx` : | A SeedContext.
`val` : | The SeedValue to convert.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | The guchar represented by `val`.

### seed_value_from_uchar ()

    SeedValue           seed_value_from_uchar               (SeedContext ctx,
                                                             guchar val,
                                                             SeedException *exception);

Converts the given guchar into a SeedValue.

`ctx` : | A SeedContext.
`val` : | The guchar to represent.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | A SeedValue which represents `val`.

### seed_value_to_long ()

    glong               seed_value_to_long                  (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);

Converts the given SeedValue into a glong.

`ctx` : | A SeedContext.
`val` : | The SeedValue to convert.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | The glong represented by `val`.

### seed_value_from_long ()

    SeedValue           seed_value_from_long                (SeedContext ctx,
                                                             glong val,
                                                             SeedException *exception);

Converts the given glong into a SeedValue.

`ctx` : | A SeedContext.
`val` : | The glong to represent.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | A SeedValue which represents `val`.

### seed_value_to_ulong ()

    gulong              seed_value_to_ulong                 (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);

Converts the given SeedValue into a gulong.

`ctx` : | A SeedContext.
`val` : | The SeedValue to convert.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | The gulong represented by `val`.

### seed_value_from_ulong ()

    SeedValue           seed_value_from_ulong               (SeedContext ctx,
                                                             gulong val,
                                                             SeedException *exception);

Converts the given gulong into a SeedValue.

`ctx` : | A SeedContext.
`val` : | The gulong to represent.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | A SeedValue which represents `val`.

### seed_value_to_int64 ()

    gint64              seed_value_to_int64                 (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);

Converts the given SeedValue into a gint64.

`ctx` : | A SeedContext.
`val` : | The SeedValue to convert.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | The gint64 represented by `val`.

### seed_value_from_int64 ()

    SeedValue           seed_value_from_int64               (SeedContext ctx,
                                                             gint64 val,
                                                             SeedException *exception);

Converts the given gint64 into a SeedValue.

`ctx` : | A SeedContext.
`val` : | The gint64 to represent.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | A SeedValue which represents `val`.

### seed_value_to_uint64 ()

    guint64             seed_value_to_uint64                (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);

Converts the given SeedValue into a guint64.

`ctx` : | A SeedContext.
`val` : | The SeedValue to convert.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | The guint64 represented by `val`.

### seed_value_from_uint64 ()

    SeedValue           seed_value_from_uint64              (SeedContext ctx,
                                                             guint64 val,
                                                             SeedException *exception);

Converts the given guint64 into a SeedValue.

`ctx` : | A SeedContext.
`val` : | The guint64 to represent.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | A SeedValue which represents `val`.

### seed_value_to_float ()

    gfloat              seed_value_to_float                 (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);

Converts the given SeedValue into a gfloat.

`ctx` : | A SeedContext.
`val` : | The SeedValue to convert.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | The gfloat represented by `val`.

### seed_value_from_float ()

    SeedValue           seed_value_from_float               (SeedContext ctx,
                                                             gfloat val,
                                                             SeedException *exception);

Converts the given gfloat into a SeedValue.

`ctx` : | A SeedContext.
`val` : | The gfloat to represent.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | A SeedValue which represents `val`.

### seed_value_to_double ()

    gdouble             seed_value_to_double                (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);

Converts the given SeedValue into a gdouble.

`ctx` : | A SeedContext.
`val` : | The SeedValue to convert.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | The gdouble represented by `val`.

### seed_value_from_double ()

    SeedValue           seed_value_from_double              (SeedContext ctx,
                                                             gdouble val,
                                                             SeedException *exception);

Converts the given gdouble into a SeedValue.

`ctx` : | A SeedContext.
`val` : | The gdouble to represent.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | A SeedValue which represents `val`.

### seed_value_to_string ()

    gchar *             seed_value_to_string                (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);

Converts the given SeedValue into a gchar* string. Keep in mind that it's up to the caller to free the string.

If the SeedValue represents JavaScript's undefined value, this returns "[undefined]"; if it represents JavaScript's null value, this returns "[null]".

If the SeedValue is a number or a boolean, it is printed as a double, with the printf format string "%.15g".

If the SeedValue is an object, the string returned is that obtained by calling .toString() on said object.

`ctx` : | A SeedContext.
`val` : | The SeedValue to convert.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | The gchar* represented by `val`.

### seed_value_from_string ()

    SeedValue           seed_value_from_string              (SeedContext ctx,
                                                             const gchar *val,
                                                             SeedException *exception);

Converts the given gchar* string into a SeedValue.

`ctx` : | A SeedContext.
`val` : | The gchar* to represent.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | A SeedValue which represents `val`.

### seed_value_from_binary_string ()

    SeedValue           seed_value_from_binary_string       (SeedContext ctx,
                                                             const gchar *bytes,
                                                             gint n_bytes,
                                                             SeedException *exception);

Converts a string representation of the given binary string into a SeedValue.

FIXME - should use BinaryArray really

`ctx` : | A SeedContext.
`bytes` : | A string of bytes to represent as a string.
`n_bytes` : | The number of bytes from `bytes` to convert.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | A SeedValue which represents `bytes` as a string.

### seed_value_to_object ()

    GObject *           seed_value_to_object                (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedException *exception);

Given a SeedValue which is wrapping a GObject, retrieve the wrapped GObject.

`ctx` : | A SeedContext.
`val` : | The SeedValue to unwrap.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | The GObject wrapped within `val`, or `NULL` if an exception is raised during the conversion.

### seed_value_from_object ()

    SeedValue           seed_value_from_object              (SeedContext ctx,
                                                             GObject *val,
                                                             SeedException *exception);

Wraps `val` in a SeedValue.

`ctx` : | A SeedContext.
`val` : | The GObject to wrap.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | A SeedValue which wraps `val`.

### seed_value_to_filename ()

    gchar *             seed_value_to_filename              (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedValue *exception);

Converts the given SeedValue into a gchar*, properly converting to the character set used for filenames on the local machine.

`ctx` : | A SeedContext.
`val` : | The SeedValue to convert.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | The gchar* represented by `val`, or `NULL` if an exception is raised during the conversion.

### seed_value_from_filename ()

    SeedValue           seed_value_from_filename            (SeedContext ctx,
                                                             SeedValue val,
                                                             SeedValue *exception);

Converts the given gchar* filename into a SeedValue, respecting the character set used for filenames on the local machine.

`ctx` : | A SeedContext.
`val` : | The gchar* filename to represent.
`exception` : | A reference to a SeedValue in which to store any exceptions. Pass `NULL` to ignore exceptions.
Returns : | A SeedValue which represents `val`.

### seed_value_to_format ()

    gboolean            seed_value_to_format                (SeedContext ctx,
                                                             const gchar *format,
                                                             SeedValue *values,
                                                             SeedValue *exception,
                                                             ...);

A convenience API for converting multiple values at once, the format string is composed of single characters specifying types, for example: i: gint u: guint o: GObject * s: gchar * f: gdouble c: gchar

and a valid format string could be "iuo".

This function may be in particular useful in converting arguments in a SeedFunctionCallback.

`ctx` : | A valid SeedContext
`format` : | Format string to use.
`values` : | The values to convert.
`exception` : | Location to store an exception.
Returns : | Whether conversion was successful.

### seed_pointer_get_pointer ()

    gpointer            seed_pointer_get_pointer            (SeedContext ctx,
                                                             SeedValue pointer);

### seed_make_pointer ()

    SeedValue           seed_make_pointer                   (SeedContext ctx,
                                                             gpointer pointer);

### SeedString

    typedef gpointer SeedString;

### seed_string_ref ()

    SeedString          seed_string_ref                     (SeedString string);

Increments the reference count of `string`.

`string` : | A SeedString.
Returns : | `string`

### seed_string_unref ()

    void                seed_string_unref                   (SeedString string);

Decrements the reference count of `string`.

`string` : | A SeedString.

### seed_string_get_maximum_size ()

    gsize               seed_string_get_maximum_size        (SeedString string);

`string` : | A SeedString.
Returns : | The maximum number of bytes `string` will take up if converted to a null-terminated UTF8 string.

### seed_string_to_utf8_buffer ()

    gsize               seed_string_to_utf8_buffer          (SeedString string,
                                                             gchar *buffer,
                                                             size_t buffer_size);

`string` : | A SeedString.
`buffer` : | An allocated string.
`buffer_size` : | The length of `buffer`, in bytes.
Returns : | A the number of bytes copied into `buffer`.

### seed_string_is_equal ()

    gboolean            seed_string_is_equal                (SeedString a,
                                                             SeedString b);

`a` : | The first SeedString to compare.
`b` : | The second SeedString to compare.
Returns : | true, if a and b are equal, false otherwise.

### seed_string_is_equal_utf8 ()

    gboolean            seed_string_is_equal_utf8           (SeedString a,
                                                             const gchar *b);

Tests the equality of a SeedString and a UTF-8 C-style string.

`a` : | The SeedString to compare.
`b` : | A gchar* to compare to.
Returns : | true, if a and b are equal, false otherwise.