## NABoxed

NABoxed — The NABoxed Structure

## Synopsis

    #include <nautilus-actions/na-boxed.h>

    #define             NA_TYPE_BOXED
    #define             NA_BOXED                            (object)
    #define             NA_IS_BOXED                         (object)
                        NABoxed;
    void                na_boxed_set_type                   (NABoxed *boxed,
                                                             guint type);
    gboolean            na_boxed_are_equal                  (const NABoxed *a,
                                                             const NABoxed *b);
    NABoxed *           na_boxed_copy                       (const NABoxed *boxed);
    void                na_boxed_dump                       (const NABoxed *boxed);
    gboolean            na_boxed_get_boolean                (const NABoxed *boxed);
    gconstpointer       na_boxed_get_pointer                (const NABoxed *boxed);
    gchar *             na_boxed_get_string                 (const NABoxed *boxed);
    GSList *            na_boxed_get_string_list            (const NABoxed *boxed);
    guint               na_boxed_get_uint                   (const NABoxed *boxed);
    GList *             na_boxed_get_uint_list              (const NABoxed *boxed);
    void                na_boxed_get_as_value               (const NABoxed *boxed,
                                                             GValue *value);
    void *              na_boxed_get_as_void                (const NABoxed *boxed);
    NABoxed *           na_boxed_new_from_string            (guint type,
                                                             const gchar *string);
    void                na_boxed_set_from_boxed             (NABoxed *boxed,
                                                             const NABoxed *value);
    void                na_boxed_set_from_string            (NABoxed *boxed,
                                                             const gchar *value);
    void                na_boxed_set_from_value             (NABoxed *boxed,
                                                             const GValue *value);
    void                na_boxed_set_from_void              (NABoxed *boxed,
                                                             const void *value);

## Object Hierarchy

      GObject
       +----NABoxed
             +----NADataBoxed

## Description

The NABoxed structure is a way of handling various types of data in an opaque structure.

## Details

### NA_TYPE_BOXED

    #define NA_TYPE_BOXED                ( na_boxed_get_type())

### NA_BOXED()

    #define NA_BOXED( object )           ( G_TYPE_CHECK_INSTANCE_CAST( object, NA_TYPE_BOXED, NABoxed ))

### NA_IS_BOXED()

    #define NA_IS_BOXED( object )        ( G_TYPE_CHECK_INSTANCE_TYPE( object, NA_TYPE_BOXED ))

### NABoxed

    typedef struct _NABoxed NABoxed;

### na_boxed_set_type ()

    void                na_boxed_set_type                   (NABoxed *boxed,
                                                             guint type);

Set the type of the just-allocated `boxed` object.

`boxed` : | this NABoxed object.
`type` : | the required type as defined in na-data-types.h

Since 3.1

### na_boxed_are_equal ()

    gboolean            na_boxed_are_equal                  (const NABoxed *a,
                                                             const NABoxed *b);

`a` : | the first NABoxed object.
`b` : | the second NABoxed object.
Returns : | `TRUE` if `a` and `b` are equal, `FALSE` else.

Since 3.1

### na_boxed_copy ()

    NABoxed *           na_boxed_copy                       (const NABoxed *boxed);

`boxed` : | the source NABoxed box.
Returns : | a copy of `boxed`, as a newly allocated NABoxed which should be `g_object_unref()` by the caller.

Since 3.1

### na_boxed_dump ()

    void                na_boxed_dump                       (const NABoxed *boxed);

Dumps the `boxed` box.

`boxed` : | the NABoxed box to be dumped.

Since 3.1

### na_boxed_get_boolean ()

    gboolean            na_boxed_get_boolean                (const NABoxed *boxed);

`boxed` : | the NABoxed structure.
Returns : | the boolean value if `boxed` is of `NA_DATA_TYPE_BOOLEAN` type, `FALSE` else.

Since 3.1

### na_boxed_get_pointer ()

    gconstpointer       na_boxed_get_pointer                (const NABoxed *boxed);

`boxed` : | the NABoxed structure.
Returns : | a const pointer to the data if `boxed` is of `NA_DATA_TYPE_POINTER` type, `NULL` else.

Since 3.1

### na_boxed_get_string ()

    gchar *             na_boxed_get_string                 (const NABoxed *boxed);

`boxed` : | the NABoxed structure.
Returns : | a newly allocated string if `boxed` is of `NA_DATA_TYPE_STRING` type, which should be `g_free()` by the caller, `NULL` else.

Since 3.1

### na_boxed_get_string_list ()

    GSList *            na_boxed_get_string_list            (const NABoxed *boxed);

`boxed` : | the NABoxed structure.
Returns : | a newly allocated string list if `boxed` is of `NA_DATA_TYPE_STRING_LIST` type, which should be `na_core_utils_slist_free()` by the caller, `NULL` else.

Since 3.1

### na_boxed_get_uint ()

    guint               na_boxed_get_uint                   (const NABoxed *boxed);

`boxed` : | the NABoxed structure.
Returns : | an unsigned integer if `boxed` is of `NA_DATA_TYPE_UINT` type, zero else.

Since 3.1

### na_boxed_get_uint_list ()

    GList *             na_boxed_get_uint_list              (const NABoxed *boxed);

`boxed` : | the NABoxed structure.
Returns : | a newly allocated list if `boxed` is of `NA_DATA_TYPE_UINT_LIST` type, which should be `g_list_free()` by the caller, `FALSE` else.

Since 3.1

### na_boxed_get_as_value ()

    void                na_boxed_get_as_value               (const NABoxed *boxed,
                                                             GValue *value);

Setup `value` with the content of the `boxed`.

`boxed` : | the NABoxed whose value is to be got.
`value` : | the GValue which holds the string to be set.

Since 3.1

### na_boxed_get_as_void ()

    void *              na_boxed_get_as_void                (const NABoxed *boxed);

`boxed` : | the NABoxed whose value is to be got.
Returns : | the content of the `boxed`. If of type NA_DATA_TYPE_STRING (resp. NA_DATA_TYPE_LOCALE_STRING, NA_DATA_TYPE_STRING_LIST or NA_DATA_TYPE_UINT_LIST), then the content is returned in a newly allocated value, which should be `g_free()` (resp. `g_free()`, `na_core_utils_slist_free()`, `g_list_free()`) by the caller.

Since 3.1

### na_boxed_new_from_string ()

    NABoxed *           na_boxed_new_from_string            (guint type,
                                                             const gchar *string);

Allocates a new NABoxed of the specified `type`, and initializes it with `string`.

If the type is a list, then the last separator is automatically stripped.

`type` : | the type of the NABoxed to be allocated.
`string` : | the initial value of the NABoxed as a string.
Returns : | a newly allocated NABoxed, which should be `g_object_unref()` by the caller, or `NULL` if the type is unknowned, or does not provide the 'from_string' function.

Since 3.1

### na_boxed_set_from_boxed ()

    void                na_boxed_set_from_boxed             (NABoxed *boxed,
                                                             const NABoxed *value);

Copy value from `value` to `boxed`.

`boxed` : | the NABoxed whose value is to be set.
`value` : | the source NABoxed.

Since 3.1

### na_boxed_set_from_string ()

    void                na_boxed_set_from_string            (NABoxed *boxed,
                                                             const gchar *value);

Evaluates the `value` and set it to the `boxed`.

`boxed` : | the NABoxed whose value is to be set.
`value` : | the string to be set.

Since 3.1

### na_boxed_set_from_value ()

    void                na_boxed_set_from_value             (NABoxed *boxed,
                                                             const GValue *value);

Evaluates the `value` and set it to the `boxed`.

`boxed` : | the NABoxed whose value is to be set.
`value` : | the value whose content is to be got.

Since 3.1

### na_boxed_set_from_void ()

    void                na_boxed_set_from_void              (NABoxed *boxed,
                                                             const void *value);

Evaluates the `value` and set it to the `boxed`.

`boxed` : | the NABoxed whose value is to be set.
`value` : | the value whose content is to be got.

Since 3.1