Test Utilities with GLib support: Cutter Reference Manual

## Test Utilities with GLib support Test Utilities with GLib support — Utilities to write tests more easily with GLib support. |

## Functions

GObject * | gcut_take_object ()
GError * | gcut_take_error ()
const GList * | gcut_take_list ()
GHashTable * | gcut_take_hash_table ()
#define | gcut_take_string()
#define | gcut_take_new_string()
#define | gcut_take_bytes()
GList * | gcut_list_new ()
GList * | gcut_list_int_new ()
GList * | gcut_list_uint_new ()
GList * | gcut_list_string_new ()
GList * | gcut_list_string_new_array ()
const GList * | gcut_take_new_list_int ()
const GList * | gcut_take_new_list_uint ()
const GList * | gcut_take_new_list_string ()
#define | gcut_take_new_list_string_backward_compatibility()
const GList * | gcut_take_new_list_string_array ()
#define | gcut_take_new_list_object()
void | gcut_list_string_free ()
void | gcut_list_object_free ()
GHashTable * | gcut_hash_table_string_string_new ()
GHashTable * | gcut_hash_table_string_string_new_va_list ()
GHashTable * | gcut_take_new_hash_table_string_string ()
#define | gcut_get_fixture_data()

## Description

To write tests, you need to write codes that set up/tear down test environment, prepare expected and actual values and so on. Cutter provides test utilities to you write your tests more easily.

The utilities work with GLib.

## Functions

### gcut_take_object ()

    GObject *
    gcut_take_object (GObject *object);

Passes ownership of `object` to Cutter and returns `object` .

#### Parameters

object | the GObject to be owned by Cutter. |

#### Returns

`object` owned by Cutter. Don't `g_object_unref()` it.

Since: 1.0.3

### gcut_take_error ()

    GError *
    gcut_take_error (GError *error);

Passes ownership of `error` to Cutter and returns a `error` itself.

#### Parameters

error | the GError to be owned by Cutter. |

#### Returns

a GError owned by Cutter. Don't `g_error_free()` it.

Since: 1.0.3

### gcut_take_list ()

    const GList *
    gcut_take_list (const GList *list,
                    CutDestroyFunction destroy_function);

Passes ownership of `list` to Cutter and returns `list` itself.

#### Parameters

list | the GList to be owned by Cutter. |
destroy_function | the destroy function that destroys the elements of `list` , or `NULL`. |

#### Returns

a GList owned by Cutter. Don't `g_list_free()` it.

Since: 1.0.3

### gcut_take_hash_table ()

    GHashTable *
    gcut_take_hash_table (GHashTable *hash_table);

Passes ownership of `hash_table` to Cutter and returns `hash_table` itself.

#### Parameters

hash_table | the GHashTable to be owned by Cutter. |

#### Returns

a GHashTable owned by Cutter. Don't `g_hash_table_unref()` it.

Since: 1.0.4

### gcut_take_string()

    #define             gcut_take_string(string)

Passes ownership of `string` to Cutter and returns `string` itself.

#### Parameters

string | the GString to be owned by Cutter. |

#### Returns

a GString owned by Cutter. Don't `g_string_free()` it.

Since: 1.1.6

### gcut_take_new_string()

    #define             gcut_take_new_string(string)

Creates a GString object from passed string.

#### Parameters

string | the string. It can be `NULL`. |

#### Returns

a GString owned by Cutter. Don't `g_string_free()` it.

Since: 1.1.6

### gcut_take_bytes()

    #define             gcut_take_bytes(bytes)

Passes ownership of `bytes` to Cutter and returns `bytes` itself.

#### Parameters

bytes | the GBytes to be owned by Cutter. |

#### Returns

a GBytes owned by Cutter. Don't `g_bytes_unref()` it.

Since: 1.2.8

### gcut_list_new ()

    GList *
    gcut_list_new (const gpointer element,
                   ...);

Creates a list from passed elements.

e.g.:

    1
    2
    3
    4
    5
    GCutEgg *echo_egg, *cat_egg;

    echo_egg = gcut_egg_new("echo", "Hello", NULL);
    cat_egg = gcut_egg_new("cat", "/etc/hosts", NULL);
    egg_list = gcut_list_new(echo_egg, cat_egg, NULL);

#### Parameters

element | the first gpointer. |
... | remaining elements in list. `NULL`-terminate. |

#### Returns

a newly-allocated GList that contains passed elements.

Since: 1.1.1

### gcut_list_int_new ()

    GList *
    gcut_list_int_new (guint n,
                       gint value,
                       ...);

Creates a list from passed integer values.

e.g.:

    1
    gcut_list_int_new(3, -10, 1, 29); -> (-10, 1, 29)

#### Parameters

n | the number of integer values. |
value | the first integer value. |
... | remaining integer values in list. |

#### Returns

a newly-allocated GList that contains passed integer values and must be freed with `g_list_free()`.

Since: 1.1.5

### gcut_list_uint_new ()

    GList *
    gcut_list_uint_new (guint n,
                        guint value,
                        ...);

Creates a list from passed unsigned integer values.

e.g.:

    1
    gcut_list_uint_new(3, 0, 1, 2); -> (0, 1, 2)

#### Parameters

n | the number of unsigned integer values. |
value | the first unsigned integer value. |
... | remaining unsigned integer values in list. |

#### Returns

a newly-allocated GList that contains passed unsigned integer values and must be freed with `g_list_free()`.

Since: 1.1.5

### gcut_list_string_new ()

    GList *
    gcut_list_string_new (const gchar *value,
                          ...);

Creates a list from passed strings.

#### Parameters

value | the first string. |
... | remaining strings in list. `NULL`-terminate. |

#### Returns

a newly-allocated GList that contains passed strings and must be freed with `gcut_list_string_free()`.

Since: 1.0.3

### gcut_list_string_new_array ()

    GList *
    gcut_list_string_new_array (const gchar **strings);

Creates a list from passed string array.

#### Parameters

strings | the string array. `NULL`-terminate. |

#### Returns

a newly-allocated GList that contains passed string array and must be freed with `gcut_list_string_free()`.

Since: 1.0.6

### gcut_take_new_list_int ()

    const GList *
    gcut_take_new_list_int (guint n,
                            gint value,
                            ...);

Creates a list from passed integer values that is owned by Cutter.

e.g.:

    1
    gcut_take_new_list_int(3, -10, 1, 29); -> (-10, 1, 29)

#### Parameters

n | the number of integer values. |
value | the first integer value. |
... | remaining strings in list. |

#### Returns

a newly-allocated GList that contains passed integer values and is owned by Cutter.

Since: 1.1.5

### gcut_take_new_list_uint ()

    const GList *
    gcut_take_new_list_uint (guint n,
                             guint value,
                             ...);

Creates a list from passed unsigned integer values that is owned by Cutter.

e.g.:

    1
    gcut_take_new_list_uint(3, 0, 1, 2); -> (0, 1, 2)

#### Parameters

n | the number of unsigned integer values. |
value | the first unsigned integer value. |
... | remaining strings in list. |

#### Returns

a newly-allocated GList that contains passed unsigned integer values and is owned by Cutter.

Since: 1.1.5

### gcut_take_new_list_string ()

    const GList *
    gcut_take_new_list_string (const gchar *value,
                               ...);

Creates a list from passed strings that is owned by Cutter.

#### Parameters

value | the first string. |
... | remaining strings in list. `NULL`-terminate. |

#### Returns

a newly-allocated GList that contains passed strings and is owned by Cutter.

Since: 1.0.5

### gcut_take_new_list_string_backward_compatibility()

    #define             gcut_take_new_list_string_backward_compatibility(value, ...)

`gcut_take_new_list_string_backward_compatibility` is deprecated and should not be used in newly-written code.

### gcut_take_new_list_string_array ()

    const GList *
    gcut_take_new_list_string_array (const gchar **strings);

Creates a list from passed string array that is owned by Cutter.

#### Parameters

strings | the string array. `NULL`-terminate. |

#### Returns

a newly-allocated GList that contains passed string array and is owned by Cutter.

Since: 1.0.6

### gcut_take_new_list_object()

    #define             gcut_take_new_list_object(object, ...)

Creates a list from passed objects that is owned by Cutter.

#### Parameters

object | the first GObject. |
... | remaining objects in list. `NULL`-terminate. |

#### Returns

a newly-allocated GList that contains passed objects and is owned by Cutter.

Since: 1.1.1

### gcut_list_string_free ()

    void
    gcut_list_string_free (GList *list);

Frees `list` and contained strings.

#### Parameters

list | the list that contains strings to be freed. |

Since: 1.0.3

### gcut_list_object_free ()

    void
    gcut_list_object_free (GList *list);

Frees `list` and contained objects. It's safe that `list` contains `NULL`.

#### Parameters

list | the list that contains GObject's to be unrefed. |

Since: 1.1.1

### gcut_hash_table_string_string_new ()

    GHashTable *
    gcut_hash_table_string_string_new (const gchar *key,
                                       ...);

Creates a hash table that has string key and string value from passed key/value pairs.

#### Parameters

key | The first key string. |
... | A `NULL`-terminated list of rest arguments. The first item is the string value of the first key, followed optionally by more key/value pairs. It must end with `NULL`. |

#### Returns

a newly-allocated GHashTable that contains passed key/value pairs and must be freed with `g_hash_table_unref()`.

Since: 1.0.4

### gcut_hash_table_string_string_new_va_list ()

    GHashTable *
    gcut_hash_table_string_string_new_va_list
                                   (const gchar *key,
                                    va_list args);

Creates a hash table that has string key and string value from passed key/value pairs.

#### Parameters

key | The first key string. |
args | A `NULL`-terminated list of rest arguments. The first item is the string value of the first key, followed optionally by more key/value pairs. It must end with `NULL`. |

#### Returns

a newly-allocated GHashTable that contains passed key/value pairs and must be freed with `g_hash_table_unref()`.

Since: 1.0.5

### gcut_take_new_hash_table_string_string ()

    GHashTable *
    gcut_take_new_hash_table_string_string
                                   (const gchar *key,
                                    ...);

Creates a hash table that has string key and string value from passed key/value pairs. The created hash table is owned by Cutter. So don't `g_hash_table_unref()` it.

#### Parameters

key | The first key string. |
... | A `NULL`-terminated list of rest arguments. The string value of the first key, followed optionally by more key/value pairs. It must end with `NULL`. |

#### Returns

a newly-allocated GHashTable that contains passed key/value pairs.

Since: 1.0.5

### gcut_get_fixture_data()

    #define             gcut_get_fixture_data(...)

Reads the fixture data at "`path` /..." and returns it as a GString that is owned by Cutter. The description of `cut_build_fixture_path()` shows how the fixture data path is determined.

#### Parameters

path | a first element of the path to the fixture data. |
... | remaining elements in path. `NULL`-terminate is required. |

#### Returns

a content of the fixture data as GString owend by Cutter. Don't free it.

Since: 1.1.6