## Convenience test data API Convenience test data API — API to create test data without structure definition. |

## Synopsis

    void                gcut_add_datum                      (const gchar *name,
                                                             const gchar *first_field_name,
                                                             ...);
    gboolean            gcut_data_has_field                 (gconstpointer data,
                                                             const gchar *field_name);
    #define             gcut_data_get_char                  (data,
                                                             field_name)
    const gchar *       gcut_data_get_string                (gconstpointer data,
                                                             const gchar *field_name);
    gint                gcut_data_get_int                   (gconstpointer data,
                                                             const gchar *field_name);
    guint               gcut_data_get_uint                  (gconstpointer data,
                                                             const gchar *field_name);
    #define             gcut_data_get_int64                 (data,
                                                             field_name)
    #define             gcut_data_get_uint64                (data,
                                                             field_name)
    #define             gcut_data_get_size                  (data,
                                                             field_name)
    GType               gcut_data_get_type                  (gconstpointer data,
                                                             const gchar *field_name);
    guint               gcut_data_get_flags                 (gconstpointer data,
                                                             const gchar *field_name);
    gint                gcut_data_get_enum                  (gconstpointer data,
                                                             const gchar *field_name);
    gconstpointer       gcut_data_get_pointer               (gconstpointer data,
                                                             const gchar *field_name);
    gconstpointer       gcut_data_get_boxed                 (gconstpointer data,
                                                             const gchar *field_name);
    #define             gcut_data_get_object                (data,
                                                             field_name)
    #define             gcut_data_get_boolean               (data,
                                                             field_name)
    #define             gcut_data_get_double                (data,
                                                             field_name)

## Description

`cut_add_data()` requires custom data type for complex test data. But it's not easy to write. `gcut_add_datum()` provides API to use complex test data without custom data type. It uses GType for providing complex data.

## Details

### gcut_add_datum ()

    void                gcut_add_datum                      (const gchar *name,
                                                             const gchar *first_field_name,
                                                             ...);

Adds a datum to be used in data driven test. It's convenient rather than `cut_add_data()` because you doesn't need to define a new structure for a complex test data.

e.g.:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    #include <gcutter.h>

    void data_translate (void);
    void test_translate (gconstpointer data);

    static const gchar*
    translate (gint input)
    {
       switch(input) {
       case 1:
           return "first";
       case 111:
           return "a hundred eleven";
       default:
           return "unsupported";
       }
    }

    void
    data_translate(void)
    {
        gcut_add_datum("simple data",
                       "translated", G_TYPE_STRING, "first",
                       "input", G_TYPE_INT, 1,
                       NULL);
        gcut_add_datum("complex data",
                       "translated", G_TYPE_STRING, "a hundred eleven",
                       "input", G_TYPE_INT, 111,
                       NULL);
    }

    void
    test_translate(gconstpointer data)
    {
        cut_assert_equal_string(gcut_data_get_string(data, "translated"),
                                gcut_data_get_int(data, "input"));
    }

Available types and their values are the followings:

G_TYPE_CHAR | gchar value e.g.:
    1
    2
    3
    gcut_add_datum("data name",
                   "field-name", G_TYPE_CHAR, 'X',
                   NULL);
G_TYPE_STRING | const gchar *value e.g.:
    1
    2
    3
    gcut_add_datum("data name",
                   "field-name", G_TYPE_STRING, "string value",
                   NULL);
G_TYPE_INT | gint value e.g.:
    1
    2
    3
    gcut_add_datum("data name",
                   "field-name", G_TYPE_INT, 100,
                   NULL);
G_TYPE_UINT | guint value e.g.:
    1
    2
    3
    gcut_add_datum("data name",
                   "field-name", G_TYPE_UINT, 100,
                   NULL);
G_TYPE_INT64 | gint64 value e.g.:
    1
    2
    3
    gcut_add_datum("data name",
                   "field-name", G_TYPE_INT64, G_GINT64_CONSTANT(100),
                   NULL);
G_TYPE_UINT64 | guint64 value e.g.:
    1
    2
    3
    gcut_add_datum("data name",
                   "field-name", G_TYPE_UINT64, G_GUINT64_CONSTANT(100),
                   NULL);
G_TYPE_GTYPE | GType value e.g.:
    1
    2
    3
    gcut_add_datum("data name",
                   "field-name", G_TYPE_GTYPE, G_TYPE_OBJECT,
                   NULL);
GFlags types | its type value. e.g.:
    1
    2
    3
    gcut_add_datum("data name",
                   "field-name", GTK_TYPE_WIDGET_FLAGS, GTK_TOPLEVEL | GTK_MAPPED,
                   NULL);
GEnum types | its type value. e.g.:
    1
    2
    3
    gcut_add_datum("data name",
                   "field-name", GTK_TYPE_WRAP_MODE, GTK_WRAP_NONE,
                   NULL);
G_TYPE_POINTER | gconstpointer value, GDestroyNotify notify notify is called when value is destroyed. e.g.:
    1
    2
    3
    gcut_add_datum("data name",
                   "field-name", G_TYPE_POINTER, my_structure_new(...), my_structure_free,
                   NULL);
NOTE: value's ownership is passed to Cutter. Don't free it.
GBoxed types | its type value. e.g.:
    1
    2
    3
    4
    5
    6
    gcut_add_datum("data name",
                   "field-name", G_TYPE_HASH_TABLE,
                   gcut_hash_table_string_string_new("name1", "value1",
                                                     "name2", "value2",
                                                     NULL),
                   NULL);
NOTE: value's ownership is passed to Cutter. Don't free it.
G_TYPE_BOOLEAN | gboolean value e.g.:
    1
    2
    3
    gcut_add_datum("data name",
                   "field-name", G_TYPE_BOOLEAN, TRUE,
                   NULL);
G_TYPE_DOUBLE | gdouble value e.g.:
    1
    2
    3
    gcut_add_datum("data name",
                   "field-name", G_TYPE_DOUBLE, 2.9,
                   NULL);

`name` : | the name of the data.
`first_field_name` : | the first field name.
`...` : | the type and value pair of the first field, followed optionally by the next field name, type and value triples. `NULL`-terminated. See description for more details.

Since 1.0.6

### gcut_data_has_field ()

    gboolean            gcut_data_has_field                 (gconstpointer data,
                                                             const gchar *field_name);

`data` : | the data added by `gcut_add_datum()`.
`field_name` : | the field name.
Returns : | `TRUE` if `data` has a `field_name` field is available, `FALSE` otherwise.

Since 1.1.5

### gcut_data_get_char()

    #define             gcut_data_get_char(data, field_name)

Gets a field value identified by `field_name` as char.

`data` : | the data added by `gcut_add_datum()`.
`field_name` : | the field name.
Returns : | a field value corresponded to `field_name`.

Since 1.1.3

### gcut_data_get_string ()

    const gchar *       gcut_data_get_string                (gconstpointer data,
                                                             const gchar *field_name);

Gets a field value identified by `field_name` as string.

`data` : | the data added by `gcut_add_datum()`.
`field_name` : | the field name.
Returns : | a field value corresponded to `field_name`.

Since 1.0.6

### gcut_data_get_int ()

    gint                gcut_data_get_int                   (gconstpointer data,
                                                             const gchar *field_name);

Gets a field value identified by `field_name` as integer.

`data` : | the data added by `gcut_add_datum()`.
`field_name` : | the field name.
Returns : | a field value corresponded to `field_name`.

Since 1.0.6

### gcut_data_get_uint ()

    guint               gcut_data_get_uint                  (gconstpointer data,
                                                             const gchar *field_name);

Gets a field value identified by `field_name` as unsigned integer.

`data` : | the data added by `gcut_add_datum()`.
`field_name` : | the field name.
Returns : | a field value corresponded to `field_name`.

Since 1.0.6

### gcut_data_get_int64()

    #define             gcut_data_get_int64(data, field_name)

Gets a field value identified by `field_name` as 64-bit integer.

`data` : | the data added by `gcut_add_datum()`.
`field_name` : | the field name.
Returns : | a field value corresponded to `field_name`.

Since 1.1.3

### gcut_data_get_uint64()

    #define             gcut_data_get_uint64(data, field_name)

Gets a field value identified by `field_name` as 64-bit unsigned integer.

`data` : | the data added by `gcut_add_datum()`.
`field_name` : | the field name.
Returns : | a field value corresponded to `field_name`.

Since 1.1.3

### gcut_data_get_size()

    #define             gcut_data_get_size(data, field_name)

Gets a field value identified by `field_name` as size_t.

`data` : | the data added by `gcut_add_datum()`.
`field_name` : | the field name.
Returns : | a field value corresponded to `field_name`.

Since 1.1.3

### gcut_data_get_type ()

    GType               gcut_data_get_type                  (gconstpointer data,
                                                             const gchar *field_name);

Gets a field value identified by `field_name` as GType.

`data` : | the data added by `gcut_add_datum()`.
`field_name` : | the field name.
Returns : | a field value corresponded to `field_name`.

Since 1.0.6

### gcut_data_get_flags ()

    guint               gcut_data_get_flags                 (gconstpointer data,
                                                             const gchar *field_name);

Gets a field value identified by `field_name` as unsigned integer of GFlags.

`data` : | the data added by `gcut_add_datum()`.
`field_name` : | the field name.
Returns : | a field value corresponded to `field_name`.

Since 1.0.6

### gcut_data_get_enum ()

    gint                gcut_data_get_enum                  (gconstpointer data,
                                                             const gchar *field_name);

Gets a field value identified by `field_name` as integer of GEnum type.

`data` : | the data added by `gcut_add_datum()`.
`field_name` : | the field name.
Returns : | a field value corresponded to `field_name`.

Since 1.0.6

### gcut_data_get_pointer ()

    gconstpointer       gcut_data_get_pointer               (gconstpointer data,
                                                             const gchar *field_name);

Gets a field value identified by `field_name` as pointer.

`data` : | the data added by `gcut_add_datum()`.
`field_name` : | the field name.
Returns : | a field value corresponded to `field_name`.

Since 1.0.6

### gcut_data_get_boxed ()

    gconstpointer       gcut_data_get_boxed                 (gconstpointer data,
                                                             const gchar *field_name);

Gets a field value identified by `field_name` as GBoxed type value.

`data` : | the data added by `gcut_add_datum()`.
`field_name` : | the field name.
Returns : | a field value corresponded to `field_name`.

Since 1.0.7

### gcut_data_get_object()

    #define             gcut_data_get_object(data, field_name)

Gets a field value identified by `field_name` as GObject type value.

`data` : | the data added by `gcut_add_datum()`.
`field_name` : | the field name.
Returns : | a field value corresponded to `field_name`.

Since 1.1.1

### gcut_data_get_boolean()

    #define             gcut_data_get_boolean(data, field_name)

Gets a field value identified by `field_name` as boolean.

`data` : | the data added by `gcut_add_datum()`.
`field_name` : | the field name.
Returns : | a field value corresponded to `field_name`.

Since 1.1.3

### gcut_data_get_double()

    #define             gcut_data_get_double(data, field_name)

Gets a field value identified by `field_name` as double floating point number.

`data` : | the data added by `gcut_add_datum()`.
`field_name` : | the field name.
Returns : | a field value corresponded to `field_name`.

Since 1.1.3