## Test Utilities Test Utilities — Utilities to write tests more easily. |

## Synopsis

    void *              cut_take                            (void *object,
                                                             CutDestroyFunction destroy_function);
    const void *        cut_take_memory                     (void *memory);
    const char *        cut_take_string                     (char *string);
    const char *        cut_take_strdup                     (const char *string);
    const char *        cut_take_strndup                    (const char *string,
                                                             size_t size);
    const void *        cut_take_memdup                     (const void *memory,
                                                             size_t size);
    const char *        cut_take_printf                     (const char *format,
                                                             ...);
    char **             cut_take_string_array               (char **strings);
    const char *        cut_take_diff                       (const char *from,
                                                             const char *to);
    const char *        cut_take_replace                    (const char *target,
                                                             const char *pattern,
                                                             const char *replacement);
    const char *        cut_append_diff                     (const char *message,
                                                             const char *from,
                                                             const char *to);
    const char *        cut_inspect_string_array            (const char **strings);
    void                cut_set_fixture_data_dir            (const char *path,
                                                             ...);
    char *              cut_build_fixture_data_path         (const char *path,
                                                             ...);
    const char *        cut_get_fixture_data_string         (const char *path,
                                                             ...);
    void                cut_remove_path                     (const char *path,
                                                             ...);
    const char *        cut_build_path                      (const char *path,
                                                             ...);
    cut_boolean         cut_equal_string                    (const char *string1,
                                                             const char *string2);
    cut_boolean         cut_equal_double                    (double double1,
                                                             double double2,
                                                             double error);

## 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 without GLib support.

## Details

### cut_take ()

    void *              cut_take                            (void *object,
                                                             CutDestroyFunction destroy_function);

Passes ownership of `object` to Cutter and returns `object` itself. `object` is destroyed by `destroy_func`.

`object` : | the object to be owned by Cutter.
`destroy_function` : | the destroy function for the object.
Returns : | `object` owned by Cutter. Don't free it.

Since 1.0.5

### cut_take_memory ()

    const void *        cut_take_memory                     (void *memory);

Passes ownership of `memory` to Cutter and returns `memory` itself. `memory` is destroyed by `free()`.

`memory` : | the memory to be owned by Cutter.
Returns : | `memory` owned by Cutter. Don't free it.

Since 1.0.5

### cut_take_string ()

    const char *        cut_take_string                     (char *string);

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

`string` : | the string to be owned by Cutter.
Returns : | `string` owned by Cutter. Don't free it.

### cut_take_strdup ()

    const char *        cut_take_strdup                     (const char *string);

Duplicates `string`, passes ownership of the duplicated string to Cutter and returns the duplicated string.

`string` : | the string to be duplicated.
Returns : | a duplicated string owned by Cutter. Don't free it.

Since 1.0.5

### cut_take_strndup ()

    const char *        cut_take_strndup                    (const char *string,
                                                             size_t size);

Duplicates the first `size` bytes of `string`, passes ownership of the duplicated string to Cutter and returns the duplicated string. The duplicated string is always `NULL`-terminated.

`string` : | the string to be duplicated.
`size` : | the number of bytes to duplicate.
Returns : | a duplicated string owned by Cutter. Don't free it.

Since 1.0.5

### cut_take_memdup ()

    const void *        cut_take_memdup                     (const void *memory,
                                                             size_t size);

Duplicates `size` bytes of `memory`, passes ownership of the duplicated memory to Cutter and returns the duplicated memory.

`memory` : | the memory to be duplicated.
`size` : | the number of bytes to duplicate.
Returns : | a duplicated memory owned by Cutter. Don't free it.

Since 1.0.5

### cut_take_printf ()

    const char *        cut_take_printf                     (const char *format,
                                                             ...);

Formats a string like `printf()` but the formatted string is owned by Cutter.

`format` : | the message format. See the `printf()` documentation.
`...` : | the parameters to insert into the format string.
Returns : | a formatted string owned by Cutter. Don't free it.

### cut_take_string_array ()

    char **             cut_take_string_array               (char **strings);

Passes ownership of the array of strings to Cutter and returns `strings` itself.

`strings` : | the array of strings to be owned by Cutter.
Returns : | `strings` owned by Cutter. Don't free it.

### cut_take_diff ()

    const char *        cut_take_diff                       (const char *from,
                                                             const char *to);

Computes diff between `from` and `to` that is owned by Cutter.

`from` : | the original string.
`to` : | the modified string.
Returns : | a diff between `from` and `to` owned by Cutter. Don't free it.

### cut_take_replace ()

    const char *        cut_take_replace                    (const char *target,
                                                             const char *pattern,
                                                             const char *replacement);

Replaces all occurrences of the `pattern` with the `replacement` in the `target` string.

`target` : | the replace target string.
`pattern` : | the regular expression pattern as string.
`replacement` : | text to replace each match with
Returns : | a replaced string owned by Cutter. Don't free it.

Since 1.0.6

### cut_append_diff ()

    const char *        cut_append_diff                     (const char *message,
                                                             const char *from,
                                                             const char *to);

Computes diff between `from` and `to` and append the diff to `message`. Returned string is owned by Cutter.

`message` : | the string to be appended diff.
`from` : | the original string.
`to` : | the modified string.
Returns : | `message` with diff between `from` and `to` or same as `message` if the diff not interested. Don't free it.

Since 1.0.3

### cut_inspect_string_array ()

    const char *        cut_inspect_string_array            (const char **strings);

Formats `strings` as human readable string that is owned by Cutter.

`strings` : | the array of strings to be inspected.
Returns : | a inspected string owned by Cutter. Don't free it.

### cut_set_fixture_data_dir ()

    void                cut_set_fixture_data_dir            (const char *path,
                                                             ...);

Set fixture data directory that is used by `cut_get_fixture_data_string()` and so on.

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

Since 1.0.2

### cut_build_fixture_data_path ()

    char *              cut_build_fixture_data_path         (const char *path,
                                                             ...);

Builds a path to the fixture data. If `path` is relative path, the path is handled as a relative path from a directory that is specified by `cut_set_fixture_data_dir()` or the current directory.

`path` : | a first element of the path to the fixture data.
`...` : | remaining elements in path. `NULL`-terminate is required since 1.0.7.
Returns : | a path to the fixture data. It should be freed when no longer needed.

Since 1.0.2

### cut_get_fixture_data_string ()

    const char *        cut_get_fixture_data_string         (const char *path,
                                                             ...);

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

`path` : | a first element of the path to the fixture data.
`...` : | remaining elements in path. `NULL`-terminate is required since 1.0.7.
Returns : | a content of the fixture data as string. Don't free it.

Since 1.0.2

### cut_remove_path ()

    void                cut_remove_path                     (const char *path,
                                                             ...);

Removes `path` and it's children recursively. It doesn't report any errors.

`path` : | a first element of the path to be removed.
`...` : | remaining elements in path. `NULL`-terminate is required since 1.0.7.

Since 1.0.2

### cut_build_path ()

    const char *        cut_build_path                      (const char *path,
                                                             ...);

Builds path from `path` and the following elements.

`path` : | a first element of the path to be removed.
`...` : | remaining elements in path. `NULL` terminated.
Returns : | built path owned by Cutter. Don't free it.

Since 1.0.7

### cut_equal_string ()

    cut_boolean         cut_equal_string                    (const char *string1,
                                                             const char *string2);

Compare `string1` to `string2`. `string1` and/or `string2` maybe `NULL`.

`string1` : | a string.
`string2` : | a string.
Returns : | `CUT_TRUE` if both `string1` and `string2` are `NULL` or have the same contents; `CUT_FALSE` otherwise.

Since 1.0.5

### cut_equal_double ()

    cut_boolean         cut_equal_double                    (double double1,
                                                             double double2,
                                                             double error);

Compare `double1` to `double2` with `error` range.

`double1` : | a double value.
`double2` : | a double value.
`error` : | a double value that specifies error range.
Returns : | `CUT_TRUE` if |`double1` - `double2`| <= `error`; `CUT_FALSE` otherwise.

Since 1.0.5