<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="cutter-Test-Utilities">
<refmeta>
<refentrytitle role="top_of_page" id="cutter-Test-Utilities.top_of_page">Test Utilities</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>
  CUTTER Library
</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Test Utilities</refname>
<refpurpose>Utilities to write tests more easily.</refpurpose>
</refnamediv>

<refsynopsisdiv id="cutter-Test-Utilities.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis><link linkend="char"><returnvalue>char</returnvalue></link> *              <link linkend="cut-build-fixture-data-path">cut_build_fixture_data_path</link>         (<parameter>const <link linkend="char"><type>char</type></link> *path</parameter>,
                                                         <parameter>...</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="cut-build-fixture-path">cut_build_fixture_path</link>              (<parameter>const <link linkend="char"><type>char</type></link> *path</parameter>,
                                                         <parameter>...</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="cut-build-path">cut_build_path</link>                      (<parameter>const <link linkend="char"><type>char</type></link> *path</parameter>,
                                                         <parameter>...</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="cut-build-path-array">cut_build_path_array</link>                (<parameter>const <link linkend="char"><type>char</type></link> **paths</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="cut-get-fixture-data">cut_get_fixture_data</link>                (<parameter><link linkend="size-t"><type>size_t</type></link> *size</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *path</parameter>,
                                                         <parameter>...</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="cut-get-fixture-data-string">cut_get_fixture_data_string</link>         (<parameter>const <link linkend="char"><type>char</type></link> *path</parameter>,
                                                         <parameter>...</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="cut-make-directory">cut_make_directory</link>                  (<parameter>const <link linkend="char"><type>char</type></link> *path</parameter>,
                                                         <parameter>...</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="cut-remove-path">cut_remove_path</link>                     (<parameter>const <link linkend="char"><type>char</type></link> *path</parameter>,
                                                         <parameter>...</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="cut-set-fixture-data-dir">cut_set_fixture_data_dir</link>            (<parameter>const <link linkend="char"><type>char</type></link> *path</parameter>,
                                                         <parameter>...</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link> *              <link linkend="cut-take">cut_take</link>                            (<parameter><link linkend="void"><type>void</type></link> *object</parameter>,
                                                         <parameter><link linkend="CutDestroyFunction"><type>CutDestroyFunction</type></link> destroy_function</parameter>);
#define             <link linkend="cut-take-convert">cut_take_convert</link>                    (string,
                                                         to_code_set,
                                                         from_code_set)
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="cut-take-diff">cut_take_diff</link>                       (<parameter>const <link linkend="char"><type>char</type></link> *from</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *to</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="cut-take-inspect-string">cut_take_inspect_string</link>             (<parameter>const <link linkend="char"><type>char</type></link> *string</parameter>);
const <link linkend="void"><returnvalue>void</returnvalue></link> *        <link linkend="cut-take-memdup">cut_take_memdup</link>                     (<parameter>const <link linkend="void"><type>void</type></link> *memory</parameter>,
                                                         <parameter><link linkend="size-t"><type>size_t</type></link> size</parameter>);
const <link linkend="void"><returnvalue>void</returnvalue></link> *        <link linkend="cut-take-memory">cut_take_memory</link>                     (<parameter><link linkend="void"><type>void</type></link> *memory</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="cut-take-printf">cut_take_printf</link>                     (<parameter>const <link linkend="char"><type>char</type></link> *format</parameter>,
                                                         <parameter>...</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="cut-take-replace">cut_take_replace</link>                    (<parameter>const <link linkend="char"><type>char</type></link> *target</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *pattern</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *replacement</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="cut-take-strdup">cut_take_strdup</link>                     (<parameter>const <link linkend="char"><type>char</type></link> *string</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="cut-take-string">cut_take_string</link>                     (<parameter><link linkend="char"><type>char</type></link> *string</parameter>);
<link linkend="char"><returnvalue>char</returnvalue></link> **             <link linkend="cut-take-string-array">cut_take_string_array</link>               (<parameter><link linkend="char"><type>char</type></link> **strings</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="cut-take-strndup">cut_take_strndup</link>                    (<parameter>const <link linkend="char"><type>char</type></link> *string</parameter>,
                                                         <parameter><link linkend="size-t"><type>size_t</type></link> size</parameter>);
</synopsis>
</refsynopsisdiv>

<refsect1 id="cutter-Test-Utilities.description" role="desc">
<title role="desc.title">Description</title>
<para>
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.
</para>
<para>
The utilities work without GLib support.
</para>
</refsect1>
<refsect1 id="cutter-Test-Utilities.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="cut-build-fixture-data-path" role="function" condition="deprecated:1.1.6: Use cut_build_fixture_path() instead.|since:1.0.2">
<title>cut_build_fixture_data_path ()</title>
<indexterm zone="cut-build-fixture-data-path" role="deprecated"><primary>cut_build_fixture_data_path</primary></indexterm><indexterm zone="cut-build-fixture-data-path" role="1.0.2"><primary>cut_build_fixture_data_path</primary></indexterm>
<programlisting><link linkend="char"><returnvalue>char</returnvalue></link> *              cut_build_fixture_data_path         (<parameter>const <link linkend="char"><type>char</type></link> *path</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<warning><para><literal>cut_build_fixture_data_path</literal> has been deprecated since version 1.1.6 and should not be used in newly-written code. Use <link linkend="cut-build-fixture-path"><function>cut_build_fixture_path()</function></link> instead.</para></warning>
<para>
Builds a path to the fixture data. If <parameter>path</parameter> is relative
path, the path is handled as a relative path from a
directory that is specified by <link linkend="cut-set-fixture-data-dir"><function>cut_set_fixture_data_dir()</function></link>
or the current directory.
</para><variablelist role="params">
<varlistentry><term><parameter>path</parameter>&#160;:</term>
<listitem><simpara>a first element of the path to the fixture data.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>remaining elements in path.
<link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminate is required since 1.0.7.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a path to the fixture data. It should be freed
when no longer needed.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.2</para></refsect2>
<refsect2 id="cut-build-fixture-path" role="function" condition="since:1.1.6">
<title>cut_build_fixture_path ()</title>
<indexterm zone="cut-build-fixture-path" role="1.1.6"><primary>cut_build_fixture_path</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        cut_build_fixture_path              (<parameter>const <link linkend="char"><type>char</type></link> *path</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Builds a path to the fixture data. If <parameter>path</parameter> is relative
path, the path is handled as a relative path from a
directory that is specified by <link linkend="cut-set-fixture-data-dir"><function>cut_set_fixture_data_dir()</function></link>
or the current directory.
</para><variablelist role="params">
<varlistentry><term><parameter>path</parameter>&#160;:</term>
<listitem><simpara>a first element of the path to the fixture data.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>remaining elements in path.
<link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminate is required.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a path to the fixture data. It is owned by
Cutter. Don't free it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.6</para></refsect2>
<refsect2 id="cut-build-path" role="function" condition="since:1.0.7">
<title>cut_build_path ()</title>
<indexterm zone="cut-build-path" role="1.0.7"><primary>cut_build_path</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        cut_build_path                      (<parameter>const <link linkend="char"><type>char</type></link> *path</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Builds path from <parameter>path</parameter> and the following elements.
</para><variablelist role="params">
<varlistentry><term><parameter>path</parameter>&#160;:</term>
<listitem><simpara>a first element of the path.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>remaining elements in path. <link linkend="NULL:CAPS"><literal>NULL</literal></link> terminated.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>built path owned by Cutter. Don't free it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.7</para></refsect2>
<refsect2 id="cut-build-path-array" role="function" condition="since:1.1.5">
<title>cut_build_path_array ()</title>
<indexterm zone="cut-build-path-array" role="1.1.5"><primary>cut_build_path_array</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        cut_build_path_array                (<parameter>const <link linkend="char"><type>char</type></link> **paths</parameter>);</programlisting>
<para>
Builds path from <parameter>paths</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>paths</parameter>&#160;:</term>
<listitem><simpara><link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of strings containing the path elements.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>built path owned by Cutter. Don't free it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.5</para></refsect2>
<refsect2 id="cut-get-fixture-data" role="function" condition="since:1.1.6">
<title>cut_get_fixture_data ()</title>
<indexterm zone="cut-get-fixture-data" role="1.1.6"><primary>cut_get_fixture_data</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        cut_get_fixture_data                (<parameter><link linkend="size-t"><type>size_t</type></link> *size</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *path</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Reads the fixture data at "<parameter>path</parameter>/..." and returns it as a
string that is owned by Cutter. The description of
<link linkend="cut-build-fixture-path"><function>cut_build_fixture_path()</function></link> shows how the fixture data path
is determined.
</para><variablelist role="params">
<varlistentry><term><parameter>size</parameter>&#160;:</term>
<listitem><simpara>return location for a size of the fixture data, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>path</parameter>&#160;:</term>
<listitem><simpara>a first element of the path to the fixture data.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>remaining elements in path.
<link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminate is required.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a content of the fixture data as string owend by
Cutter. Don't free it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.6</para></refsect2>
<refsect2 id="cut-get-fixture-data-string" role="function" condition="since:1.0.2">
<title>cut_get_fixture_data_string ()</title>
<indexterm zone="cut-get-fixture-data-string" role="1.0.2"><primary>cut_get_fixture_data_string</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        cut_get_fixture_data_string         (<parameter>const <link linkend="char"><type>char</type></link> *path</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Reads the fixture data at "<parameter>path</parameter>/..." and returns it as a
string that is owned by Cutter. The description of
<link linkend="cut-build-fixture-path"><function>cut_build_fixture_path()</function></link> shows how the fixture data path
is determined.
</para><variablelist role="params">
<varlistentry><term><parameter>path</parameter>&#160;:</term>
<listitem><simpara>a first element of the path to the fixture data.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>remaining elements in path.
<link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminate is required since 1.0.7.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a content of the fixture data as string owend by
Cutter.  Don't free it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.2</para></refsect2>
<refsect2 id="cut-make-directory" role="function" condition="since:1.1.1">
<title>cut_make_directory ()</title>
<indexterm zone="cut-make-directory" role="1.1.1"><primary>cut_make_directory</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                cut_make_directory                  (<parameter>const <link linkend="char"><type>char</type></link> *path</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Makes <parameter>path</parameter> and it's parents recursively. It doesn't
report any errors.
</para><variablelist role="params">
<varlistentry><term><parameter>path</parameter>&#160;:</term>
<listitem><simpara>a first element of the path to be made.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>remaining elements in path. <link linkend="NULL:CAPS"><literal>NULL</literal></link> terminated.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.1</para></refsect2>
<refsect2 id="cut-remove-path" role="function" condition="since:1.0.2">
<title>cut_remove_path ()</title>
<indexterm zone="cut-remove-path" role="1.0.2"><primary>cut_remove_path</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                cut_remove_path                     (<parameter>const <link linkend="char"><type>char</type></link> *path</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Removes <parameter>path</parameter> and it's children recursively. It doesn't
report any errors.
</para><variablelist role="params">
<varlistentry><term><parameter>path</parameter>&#160;:</term>
<listitem><simpara>a first element of the path to be removed.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>remaining elements in path.
<link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminate is required since 1.0.7.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.2</para></refsect2>
<refsect2 id="cut-set-fixture-data-dir" role="function" condition="since:1.0.2">
<title>cut_set_fixture_data_dir ()</title>
<indexterm zone="cut-set-fixture-data-dir" role="1.0.2"><primary>cut_set_fixture_data_dir</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                cut_set_fixture_data_dir            (<parameter>const <link linkend="char"><type>char</type></link> *path</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Set fixture data directory that is used by
<link linkend="cut-get-fixture-data-string"><function>cut_get_fixture_data_string()</function></link> and so on.
</para><variablelist role="params">
<varlistentry><term><parameter>path</parameter>&#160;:</term>
<listitem><simpara>a first element of the path to the fixture data directory.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>remaining elements in path.
<link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminate is required since 1.0.7.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.2</para></refsect2>
<refsect2 id="cut-take" role="function" condition="since:1.0.5">
<title>cut_take ()</title>
<indexterm zone="cut-take" role="1.0.5"><primary>cut_take</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link> *              cut_take                            (<parameter><link linkend="void"><type>void</type></link> *object</parameter>,
                                                         <parameter><link linkend="CutDestroyFunction"><type>CutDestroyFunction</type></link> destroy_function</parameter>);</programlisting>
<para>
Passes ownership of <parameter>object</parameter> to Cutter and returns <parameter>object</parameter>
itself. <parameter>object</parameter> is destroyed by <parameter>destroy_func</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object to be owned by Cutter.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>destroy_function</parameter>&#160;:</term>
<listitem><simpara>the destroy function for the object.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara><parameter>object</parameter> owned by Cutter. Don't free it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="cut-take-convert" role="macro" condition="since:1.1.3">
<title>cut_take_convert()</title>
<indexterm zone="cut-take-convert" role="1.1.3"><primary>cut_take_convert</primary></indexterm>
<programlisting>#define             cut_take_convert(string, to_code_set, from_code_set)</programlisting>
<para>
Converts <parameter>string</parameter> code set to <parameter>to_code_set</parameter> from
<parameter>from_code_set</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&#160;:</term>
<listitem><simpara>the convert target string. It should be <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>to_code_set</parameter>&#160;:</term>
<listitem><simpara>the code set name which to convert <parameter>string</parameter>.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>from_code_set</parameter>&#160;:</term>
<listitem><simpara>the code set name of <parameter>string</parameter>.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a converted string owned by Cutter. Don't free it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.3</para></refsect2>
<refsect2 id="cut-take-diff" role="function">
<title>cut_take_diff ()</title>
<indexterm zone="cut-take-diff"><primary>cut_take_diff</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        cut_take_diff                       (<parameter>const <link linkend="char"><type>char</type></link> *from</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *to</parameter>);</programlisting>
<para>
Computes diff between <parameter>from</parameter> and <parameter>to</parameter> that is owned by Cutter.
</para><variablelist role="params">
<varlistentry><term><parameter>from</parameter>&#160;:</term>
<listitem><simpara>the original string.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>to</parameter>&#160;:</term>
<listitem><simpara>the modified string.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a diff between <parameter>from</parameter> and <parameter>to</parameter> owned by Cutter. Don't free it.</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="cut-take-inspect-string" role="function" condition="since:1.1.4">
<title>cut_take_inspect_string ()</title>
<indexterm zone="cut-take-inspect-string" role="1.1.4"><primary>cut_take_inspect_string</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        cut_take_inspect_string             (<parameter>const <link linkend="char"><type>char</type></link> *string</parameter>);</programlisting>
<para>
Inspects <parameter>string</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&#160;:</term>
<listitem><simpara>the inspect target string. It should be <link linkend="NULL:CAPS"><literal>NULL</literal></link> or
<link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a inspected string owned by Cutter. Don't free it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.4</para></refsect2>
<refsect2 id="cut-take-memdup" role="function" condition="since:1.0.5">
<title>cut_take_memdup ()</title>
<indexterm zone="cut-take-memdup" role="1.0.5"><primary>cut_take_memdup</primary></indexterm>
<programlisting>const <link linkend="void"><returnvalue>void</returnvalue></link> *        cut_take_memdup                     (<parameter>const <link linkend="void"><type>void</type></link> *memory</parameter>,
                                                         <parameter><link linkend="size-t"><type>size_t</type></link> size</parameter>);</programlisting>
<para>
Duplicates <parameter>size</parameter> bytes of <parameter>memory</parameter>, passes ownership of
the duplicated memory to Cutter and returns the
duplicated memory.
</para><variablelist role="params">
<varlistentry><term><parameter>memory</parameter>&#160;:</term>
<listitem><simpara>the memory to be duplicated.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>size</parameter>&#160;:</term>
<listitem><simpara>the number of bytes to duplicate.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a duplicated memory owned by Cutter. Don't free it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="cut-take-memory" role="function" condition="since:1.0.5">
<title>cut_take_memory ()</title>
<indexterm zone="cut-take-memory" role="1.0.5"><primary>cut_take_memory</primary></indexterm>
<programlisting>const <link linkend="void"><returnvalue>void</returnvalue></link> *        cut_take_memory                     (<parameter><link linkend="void"><type>void</type></link> *memory</parameter>);</programlisting>
<para>
Passes ownership of <parameter>memory</parameter> to Cutter and returns <parameter>memory</parameter>
itself. <parameter>memory</parameter> is destroyed by <link linkend="free"><function>free()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>memory</parameter>&#160;:</term>
<listitem><simpara>the memory to be owned by Cutter.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara><parameter>memory</parameter> owned by Cutter. Don't free it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="cut-take-printf" role="function">
<title>cut_take_printf ()</title>
<indexterm zone="cut-take-printf"><primary>cut_take_printf</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        cut_take_printf                     (<parameter>const <link linkend="char"><type>char</type></link> *format</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Formats a string like <link linkend="printf"><function>printf()</function></link> but the formatted string
is owned by Cutter.
</para><variablelist role="params">
<varlistentry><term><parameter>format</parameter>&#160;:</term>
<listitem><simpara>the message format. See the <link linkend="printf"><function>printf()</function></link> documentation.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>the parameters to insert into the format string.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a formatted string owned by Cutter. Don't free it.</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="cut-take-replace" role="function" condition="since:1.0.6">
<title>cut_take_replace ()</title>
<indexterm zone="cut-take-replace" role="1.0.6"><primary>cut_take_replace</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        cut_take_replace                    (<parameter>const <link linkend="char"><type>char</type></link> *target</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *pattern</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *replacement</parameter>);</programlisting>
<para>
Replaces all occurrences of the <parameter>pattern</parameter> with the
<parameter>replacement</parameter> in the <parameter>target</parameter> string.
</para><variablelist role="params">
<varlistentry><term><parameter>target</parameter>&#160;:</term>
<listitem><simpara>the replace target string.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pattern</parameter>&#160;:</term>
<listitem><simpara>the regular expression pattern as string.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>replacement</parameter>&#160;:</term>
<listitem><simpara>text to replace each match with</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a replaced string owned by Cutter. Don't free it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.6</para></refsect2>
<refsect2 id="cut-take-strdup" role="function" condition="since:1.0.5">
<title>cut_take_strdup ()</title>
<indexterm zone="cut-take-strdup" role="1.0.5"><primary>cut_take_strdup</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        cut_take_strdup                     (<parameter>const <link linkend="char"><type>char</type></link> *string</parameter>);</programlisting>
<para>
Duplicates <parameter>string</parameter>, passes ownership of the duplicated
string to Cutter and returns the duplicated string.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&#160;:</term>
<listitem><simpara>the string to be duplicated.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a duplicated string owned by Cutter. Don't free it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="cut-take-string" role="function">
<title>cut_take_string ()</title>
<indexterm zone="cut-take-string"><primary>cut_take_string</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        cut_take_string                     (<parameter><link linkend="char"><type>char</type></link> *string</parameter>);</programlisting>
<para>
Passes ownership of <parameter>string</parameter> to Cutter and returns <parameter>string</parameter>
itself.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&#160;:</term>
<listitem><simpara>the string to be owned by Cutter.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara><parameter>string</parameter> owned by Cutter. Don't free it.</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="cut-take-string-array" role="function">
<title>cut_take_string_array ()</title>
<indexterm zone="cut-take-string-array"><primary>cut_take_string_array</primary></indexterm>
<programlisting><link linkend="char"><returnvalue>char</returnvalue></link> **             cut_take_string_array               (<parameter><link linkend="char"><type>char</type></link> **strings</parameter>);</programlisting>
<para>
Passes ownership of the array of strings to Cutter and
returns <parameter>strings</parameter> itself.
</para><variablelist role="params">
<varlistentry><term><parameter>strings</parameter>&#160;:</term>
<listitem><simpara>the array of strings to be owned by Cutter.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara><parameter>strings</parameter> owned by Cutter. Don't free it.</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="cut-take-strndup" role="function" condition="since:1.0.5">
<title>cut_take_strndup ()</title>
<indexterm zone="cut-take-strndup" role="1.0.5"><primary>cut_take_strndup</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        cut_take_strndup                    (<parameter>const <link linkend="char"><type>char</type></link> *string</parameter>,
                                                         <parameter><link linkend="size-t"><type>size_t</type></link> size</parameter>);</programlisting>
<para>
Duplicates the first <parameter>size</parameter> bytes of <parameter>string</parameter>, passes
ownership of the duplicated string to Cutter and returns
the duplicated string. The duplicated string is always
<link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&#160;:</term>
<listitem><simpara>the string to be duplicated.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>size</parameter>&#160;:</term>
<listitem><simpara>the number of bytes to duplicate.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a duplicated string owned by Cutter. Don't free it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.5</para></refsect2>

</refsect1>

</refentry>
