Test Utilities

## 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);
    #define             cut_take_convert                    (string,
                                                             to_code_set,
                                                             from_code_set)
    const char *        cut_take_inspect_string             (const char *string);
    void                cut_set_fixture_data_dir            (const char *path,
                                                             ...);
    char *              cut_build_fixture_data_path         (const char *path,
                                                             ...);
    const char *        cut_build_fixture_path              (const char *path,
                                                             ...);
    const char *        cut_get_fixture_data_string         (const char *path,
                                                             ...);
    const char *        cut_get_fixture_data                (size_t *size,
                                                             const char *path,
                                                             ...);
    void                cut_remove_path                     (const char *path,
                                                             ...);
    const char *        cut_build_path                      (const char *path,
                                                             ...);
    const char *        cut_build_path_array                (const char **paths);
    void                cut_make_directory                  (const char *path,
                                                             ...);

## 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_take_convert()

    #define             cut_take_convert(string, to_code_set, from_code_set)

Converts `string` code set to `to_code_set` from `from_code_set`.

`string` : | the convert target string. It should be `NULL`-terminated.
`to_code_set` : | the code set name which to convert `string`.
`from_code_set` : | the code set name of `string`.
Returns : | a converted string owned by Cutter. Don't free it.

Since 1.1.3

### cut_take_inspect_string ()

    const char *        cut_take_inspect_string             (const char *string);

Inspects `string`.

`string` : | the inspect target string. It should be `NULL` or `NULL`-terminated.
Returns : | a inspected string owned by Cutter. Don't free it.

Since 1.1.4

### 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,
                                                             ...);

### Warning

`cut_build_fixture_data_path` has been deprecated since version 1.1.6 and should not be used in newly-written code. Use `cut_build_fixture_path()` instead.

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_build_fixture_path ()

    const char *        cut_build_fixture_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.
Returns : | a path to the fixture data. It is owned by Cutter. Don't free it.

Since 1.1.6

### 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_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 owend by Cutter. Don't free it.

Since 1.0.2

### cut_get_fixture_data ()

    const char *        cut_get_fixture_data                (size_t *size,
                                                             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_path()` shows how the fixture data path is determined.

`size` : | return location for a size of the fixture data, or `NULL`.
`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 string owend by Cutter. Don't free it.

Since 1.1.6

### 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.
`...` : | remaining elements in path. `NULL` terminated.
Returns : | built path owned by Cutter. Don't free it.

Since 1.0.7

### cut_build_path_array ()

    const char *        cut_build_path_array                (const char **paths);

Builds path from `paths`.

`paths` : | `NULL`-terminated array of strings containing the path elements.
Returns : | built path owned by Cutter. Don't free it.

Since 1.1.5

### cut_make_directory ()

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

Makes `path` and it's parents recursively. It doesn't report any errors.

`path` : | a first element of the path to be made.
`...` : | remaining elements in path. `NULL` terminated.

Since 1.1.1