Test Utilities: Cutter Reference Manual

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

## Functions

void * | cut_take ()
const void * | cut_take_memory ()
const char * | cut_take_string ()
const char * | cut_take_strdup ()
const char * | cut_take_strndup ()
const void * | cut_take_memdup ()
const char * | cut_take_printf ()
char ** | cut_take_string_array ()
const char * | cut_take_diff ()
const char * | cut_take_replace ()
#define | cut_take_convert()
const char * | cut_take_inspect_string ()
void | cut_set_fixture_data_dir ()
char * | cut_build_fixture_data_path ()
#define | cut_build_fixture_path()
const char * | cut_get_fixture_data_string ()
#define | cut_get_fixture_data()
void | cut_remove_path ()
const char * | cut_build_path ()
const char * | cut_build_path_array ()
void | cut_make_directory ()

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

## Functions

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

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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

`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.

#### Parameters

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

    #define             cut_build_fixture_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.

#### Parameters

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.

#### Parameters

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

    #define             cut_get_fixture_data(size, ...)

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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

Since: 1.1.1