Test Utilities 3 CUTTER Library
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

### 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_memory

### 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_string

### 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_strdup

### 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_strndup

### 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_memdup

### 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_printf

### 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_string_array

### 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_diff

### 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_replace

### 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_convert

### 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_take_inspect_string

### 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_set_fixture_data_dir

### cut_build_fixture_data_path ()

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

`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_data_path
cut_build_fixture_data_path

### 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_build_fixture_path

### 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_string

### 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_get_fixture_data

### 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_remove_path

### 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

### 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_build_path_array

### 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

cut_make_directory