<?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-with-GLib-support">
<refmeta>
<refentrytitle role="top_of_page" id="cutter-Test-Utilities-with-GLib-support.top_of_page">Test Utilities with GLib support</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>
  CUTTER Library
</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Test Utilities with GLib support</refname>
<refpurpose>Utilities to write tests more easily
with GLib support.</refpurpose>
</refnamediv>

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

<synopsis><link linkend="GString"><returnvalue>GString</returnvalue></link> *           <link linkend="gcut-get-fixture-data">gcut_get_fixture_data</link>               (<parameter>const <link linkend="gchar"><type>gchar</type></link> *path</parameter>,
                                                         <parameter>...</parameter>);
<link linkend="GHashTable"><returnvalue>GHashTable</returnvalue></link> *        <link linkend="gcut-hash-table-string-string-new">gcut_hash_table_string_string_new</link>   (<parameter>const <link linkend="gchar"><type>gchar</type></link> *key</parameter>,
                                                         <parameter>...</parameter>);
<link linkend="GHashTable"><returnvalue>GHashTable</returnvalue></link> *        <link linkend="gcut-hash-table-string-string-new-va-list">gcut_hash_table_string_string_new_va_list</link>
                                                        (<parameter>const <link linkend="gchar"><type>gchar</type></link> *key</parameter>,
                                                         <parameter><link linkend="va-list"><type>va_list</type></link> args</parameter>);
<link linkend="GList"><returnvalue>GList</returnvalue></link> *             <link linkend="gcut-list-int-new">gcut_list_int_new</link>                   (<parameter><link linkend="guint"><type>guint</type></link> n</parameter>,
                                                         <parameter><link linkend="gint"><type>gint</type></link> value</parameter>,
                                                         <parameter>...</parameter>);
<link linkend="GList"><returnvalue>GList</returnvalue></link> *             <link linkend="gcut-list-new">gcut_list_new</link>                       (<parameter>const <link linkend="gpointer"><type>gpointer</type></link> element</parameter>,
                                                         <parameter>...</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="gcut-list-object-free">gcut_list_object_free</link>               (<parameter><link linkend="GList"><type>GList</type></link> *list</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="gcut-list-string-free">gcut_list_string_free</link>               (<parameter><link linkend="GList"><type>GList</type></link> *list</parameter>);
<link linkend="GList"><returnvalue>GList</returnvalue></link> *             <link linkend="gcut-list-string-new">gcut_list_string_new</link>                (<parameter>const <link linkend="gchar"><type>gchar</type></link> *value</parameter>,
                                                         <parameter>...</parameter>);
<link linkend="GList"><returnvalue>GList</returnvalue></link> *             <link linkend="gcut-list-string-new-array">gcut_list_string_new_array</link>          (<parameter>const <link linkend="gchar"><type>gchar</type></link> **strings</parameter>);
<link linkend="GList"><returnvalue>GList</returnvalue></link> *             <link linkend="gcut-list-uint-new">gcut_list_uint_new</link>                  (<parameter><link linkend="guint"><type>guint</type></link> n</parameter>,
                                                         <parameter><link linkend="guint"><type>guint</type></link> value</parameter>,
                                                         <parameter>...</parameter>);
<link linkend="GError"><returnvalue>GError</returnvalue></link> *            <link linkend="gcut-take-error">gcut_take_error</link>                     (<parameter><link linkend="GError"><type>GError</type></link> *error</parameter>);
<link linkend="GHashTable"><returnvalue>GHashTable</returnvalue></link> *        <link linkend="gcut-take-hash-table">gcut_take_hash_table</link>                (<parameter><link linkend="GHashTable"><type>GHashTable</type></link> *hash_table</parameter>);
const <link linkend="GList"><returnvalue>GList</returnvalue></link> *       <link linkend="gcut-take-list">gcut_take_list</link>                      (<parameter>const <link linkend="GList"><type>GList</type></link> *list</parameter>,
                                                         <parameter><link linkend="CutDestroyFunction"><type>CutDestroyFunction</type></link> destroy_function</parameter>);
<link linkend="GHashTable"><returnvalue>GHashTable</returnvalue></link> *        <link linkend="gcut-take-new-hash-table-string-string">gcut_take_new_hash_table_string_string</link>
                                                        (<parameter>const <link linkend="gchar"><type>gchar</type></link> *key</parameter>,
                                                         <parameter>...</parameter>);
const <link linkend="GList"><returnvalue>GList</returnvalue></link> *       <link linkend="gcut-take-new-list-int">gcut_take_new_list_int</link>              (<parameter><link linkend="guint"><type>guint</type></link> n</parameter>,
                                                         <parameter><link linkend="gint"><type>gint</type></link> value</parameter>,
                                                         <parameter>...</parameter>);
#define             <link linkend="gcut-take-new-list-object">gcut_take_new_list_object</link>           (object,
                                                         ...)
const <link linkend="GList"><returnvalue>GList</returnvalue></link> *       <link linkend="gcut-take-new-list-string">gcut_take_new_list_string</link>           (<parameter>const <link linkend="gchar"><type>gchar</type></link> *value</parameter>,
                                                         <parameter>...</parameter>);
const <link linkend="GList"><returnvalue>GList</returnvalue></link> *       <link linkend="gcut-take-new-list-string-array">gcut_take_new_list_string_array</link>     (<parameter>const <link linkend="gchar"><type>gchar</type></link> **strings</parameter>);
#define             <link linkend="gcut-take-new-list-string-backward-compatibility">gcut_take_new_list_string_backward_compatibility</link>(value,
                                                         ...)
const <link linkend="GList"><returnvalue>GList</returnvalue></link> *       <link linkend="gcut-take-new-list-uint">gcut_take_new_list_uint</link>             (<parameter><link linkend="guint"><type>guint</type></link> n</parameter>,
                                                         <parameter><link linkend="guint"><type>guint</type></link> value</parameter>,
                                                         <parameter>...</parameter>);
<link linkend="GString"><returnvalue>GString</returnvalue></link> *           <link linkend="gcut-take-new-string">gcut_take_new_string</link>                (<parameter>const <link linkend="gchar"><type>gchar</type></link> *string</parameter>);
<link linkend="GObject"><returnvalue>GObject</returnvalue></link> *           <link linkend="gcut-take-object">gcut_take_object</link>                    (<parameter><link linkend="GObject"><type>GObject</type></link> *object</parameter>);
<link linkend="GString"><returnvalue>GString</returnvalue></link> *           <link linkend="gcut-take-string">gcut_take_string</link>                    (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>);
</synopsis>
</refsynopsisdiv>

<refsect1 id="cutter-Test-Utilities-with-GLib-support.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 with GLib.
</para>
</refsect1>
<refsect1 id="cutter-Test-Utilities-with-GLib-support.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="gcut-get-fixture-data" role="function" condition="since:1.1.6">
<title>gcut_get_fixture_data ()</title>
<indexterm zone="gcut-get-fixture-data" role="1.1.6"><primary>gcut_get_fixture_data</primary></indexterm>
<programlisting><link linkend="GString"><returnvalue>GString</returnvalue></link> *           gcut_get_fixture_data               (<parameter>const <link linkend="gchar"><type>gchar</type></link> *path</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Reads the fixture data at "<parameter>path</parameter>/..." and returns it as a
<link linkend="GString"><type>GString</type></link> 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.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a content of the fixture data as <link linkend="GString"><type>GString</type></link> owend by
Cutter. Don't free it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.6</para></refsect2>
<refsect2 id="gcut-hash-table-string-string-new" role="function" condition="since:1.0.4">
<title>gcut_hash_table_string_string_new ()</title>
<indexterm zone="gcut-hash-table-string-string-new" role="1.0.4"><primary>gcut_hash_table_string_string_new</primary></indexterm>
<programlisting><link linkend="GHashTable"><returnvalue>GHashTable</returnvalue></link> *        gcut_hash_table_string_string_new   (<parameter>const <link linkend="gchar"><type>gchar</type></link> *key</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Creates a hash table that has string key and string value
from passed key/value pairs.
</para><variablelist role="params">
<varlistentry><term><parameter>key</parameter>&#160;:</term>
<listitem><simpara>The first key string.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>A <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated list of rest arguments. The
first item is the string value of the first key,
followed optionally by more key/value pairs. It
must end with <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a newly-allocated <link linkend="GHashTable"><type>GHashTable</type></link> that contains
passed key/value pairs and must be freed with
<link linkend="g-hash-table-unref"><function>g_hash_table_unref()</function></link>.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.4</para></refsect2>
<refsect2 id="gcut-hash-table-string-string-new-va-list" role="function" condition="since:1.0.5">
<title>gcut_hash_table_string_string_new_va_list ()</title>
<indexterm zone="gcut-hash-table-string-string-new-va-list" role="1.0.5"><primary>gcut_hash_table_string_string_new_va_list</primary></indexterm>
<programlisting><link linkend="GHashTable"><returnvalue>GHashTable</returnvalue></link> *        gcut_hash_table_string_string_new_va_list
                                                        (<parameter>const <link linkend="gchar"><type>gchar</type></link> *key</parameter>,
                                                         <parameter><link linkend="va-list"><type>va_list</type></link> args</parameter>);</programlisting>
<para>
Creates a hash table that has string key and string value
from passed key/value pairs.
</para><variablelist role="params">
<varlistentry><term><parameter>key</parameter>&#160;:</term>
<listitem><simpara>The first key string.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>args</parameter>&#160;:</term>
<listitem><simpara>A <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated list of rest arguments. The
first item is the string value of the first key,
followed optionally by more key/value pairs. It
must end with <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a newly-allocated <link linkend="GHashTable"><type>GHashTable</type></link> that contains
passed key/value pairs and must be freed with
<link linkend="g-hash-table-unref"><function>g_hash_table_unref()</function></link>.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="gcut-list-int-new" role="function" condition="since:1.1.5">
<title>gcut_list_int_new ()</title>
<indexterm zone="gcut-list-int-new" role="1.1.5"><primary>gcut_list_int_new</primary></indexterm>
<programlisting><link linkend="GList"><returnvalue>GList</returnvalue></link> *             gcut_list_int_new                   (<parameter><link linkend="guint"><type>guint</type></link> n</parameter>,
                                                         <parameter><link linkend="gint"><type>gint</type></link> value</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Creates a list from passed integer values.
</para>
<para>
e.g.:
<informalexample><programlisting>
gcut_list_int_new(3, -10, 1, 29); -> (-10, 1, 29)
</programlisting></informalexample>
</para><variablelist role="params">
<varlistentry><term><parameter>n</parameter>&#160;:</term>
<listitem><simpara>the number of integer values.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara>the first integer value.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>remaining integer values in list.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a newly-allocated <link linkend="GList"><type>GList</type></link> that contains passed
integer values and must be freed with <link linkend="g-list-free"><function>g_list_free()</function></link>.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.5</para></refsect2>
<refsect2 id="gcut-list-new" role="function" condition="since:1.1.1">
<title>gcut_list_new ()</title>
<indexterm zone="gcut-list-new" role="1.1.1"><primary>gcut_list_new</primary></indexterm>
<programlisting><link linkend="GList"><returnvalue>GList</returnvalue></link> *             gcut_list_new                       (<parameter>const <link linkend="gpointer"><type>gpointer</type></link> element</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Creates a list from passed elements.
</para>
<para>
e.g.:
<informalexample><programlisting>
GCutEgg *echo_egg, *cat_egg;

echo_egg = gcut_egg_new("echo", "Hello", NULL);
cat_egg = gcut_egg_new("cat", "/etc/hosts", NULL);
egg_list = gcut_list_new(echo_egg, cat_egg, NULL);
</programlisting></informalexample>
</para><variablelist role="params">
<varlistentry><term><parameter>element</parameter>&#160;:</term>
<listitem><simpara>the first <link linkend="gpointer"><type>gpointer</type></link>.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>remaining elements in list. <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminate.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a newly-allocated <link linkend="GList"><type>GList</type></link> that contains passed
elements.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.1</para></refsect2>
<refsect2 id="gcut-list-object-free" role="function" condition="since:1.1.1">
<title>gcut_list_object_free ()</title>
<indexterm zone="gcut-list-object-free" role="1.1.1"><primary>gcut_list_object_free</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                gcut_list_object_free               (<parameter><link linkend="GList"><type>GList</type></link> *list</parameter>);</programlisting>
<para>
Frees <parameter>list</parameter> and contained objects. It's safe that <parameter>list</parameter>
contains <link linkend="NULL:CAPS"><literal>NULL</literal></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>list</parameter>&#160;:</term>
<listitem><simpara>the list that contains <link linkend="GObject"><type>GObject</type></link>'s to be unrefed.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.1</para></refsect2>
<refsect2 id="gcut-list-string-free" role="function" condition="since:1.0.3">
<title>gcut_list_string_free ()</title>
<indexterm zone="gcut-list-string-free" role="1.0.3"><primary>gcut_list_string_free</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                gcut_list_string_free               (<parameter><link linkend="GList"><type>GList</type></link> *list</parameter>);</programlisting>
<para>
Frees <parameter>list</parameter> and contained strings.
</para><variablelist role="params">
<varlistentry><term><parameter>list</parameter>&#160;:</term>
<listitem><simpara>the list that contains strings to be freed.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.3</para></refsect2>
<refsect2 id="gcut-list-string-new" role="function" condition="since:1.0.3">
<title>gcut_list_string_new ()</title>
<indexterm zone="gcut-list-string-new" role="1.0.3"><primary>gcut_list_string_new</primary></indexterm>
<programlisting><link linkend="GList"><returnvalue>GList</returnvalue></link> *             gcut_list_string_new                (<parameter>const <link linkend="gchar"><type>gchar</type></link> *value</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Creates a list from passed strings.
</para><variablelist role="params">
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara>the first string.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>remaining strings in list. <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminate.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a newly-allocated <link linkend="GList"><type>GList</type></link> that contains passed
strings and must be freed with <link linkend="gcut-list-string-free"><function>gcut_list_string_free()</function></link>.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.3</para></refsect2>
<refsect2 id="gcut-list-string-new-array" role="function" condition="since:1.0.6">
<title>gcut_list_string_new_array ()</title>
<indexterm zone="gcut-list-string-new-array" role="1.0.6"><primary>gcut_list_string_new_array</primary></indexterm>
<programlisting><link linkend="GList"><returnvalue>GList</returnvalue></link> *             gcut_list_string_new_array          (<parameter>const <link linkend="gchar"><type>gchar</type></link> **strings</parameter>);</programlisting>
<para>
Creates a list from passed string array.
</para><variablelist role="params">
<varlistentry><term><parameter>strings</parameter>&#160;:</term>
<listitem><simpara>the string array. <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminate.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a newly-allocated <link linkend="GList"><type>GList</type></link> that contains passed
string array and must be freed with <link linkend="gcut-list-string-free"><function>gcut_list_string_free()</function></link>.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.6</para></refsect2>
<refsect2 id="gcut-list-uint-new" role="function" condition="since:1.1.5">
<title>gcut_list_uint_new ()</title>
<indexterm zone="gcut-list-uint-new" role="1.1.5"><primary>gcut_list_uint_new</primary></indexterm>
<programlisting><link linkend="GList"><returnvalue>GList</returnvalue></link> *             gcut_list_uint_new                  (<parameter><link linkend="guint"><type>guint</type></link> n</parameter>,
                                                         <parameter><link linkend="guint"><type>guint</type></link> value</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Creates a list from passed unsigned integer values.
</para>
<para>
e.g.:
<informalexample><programlisting>
gcut_list_uint_new(3, 0, 1, 2); -> (0, 1, 2)
</programlisting></informalexample>
</para><variablelist role="params">
<varlistentry><term><parameter>n</parameter>&#160;:</term>
<listitem><simpara>the number of unsigned integer values.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara>the first unsigned integer value.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>remaining unsigned integer values in list.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a newly-allocated <link linkend="GList"><type>GList</type></link> that contains passed
unsigned integer values and must be freed with
<link linkend="g-list-free"><function>g_list_free()</function></link>.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.5</para></refsect2>
<refsect2 id="gcut-take-error" role="function" condition="since:1.0.3">
<title>gcut_take_error ()</title>
<indexterm zone="gcut-take-error" role="1.0.3"><primary>gcut_take_error</primary></indexterm>
<programlisting><link linkend="GError"><returnvalue>GError</returnvalue></link> *            gcut_take_error                     (<parameter><link linkend="GError"><type>GError</type></link> *error</parameter>);</programlisting>
<para>
Passes ownership of <parameter>error</parameter> to Cutter and returns
a <parameter>error</parameter> itself.
</para><variablelist role="params">
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="GError"><type>GError</type></link> to be owned by Cutter.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a <link linkend="GError"><type>GError</type></link> owned by Cutter. Don't <link linkend="g-error-free"><function>g_error_free()</function></link>
it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.3</para></refsect2>
<refsect2 id="gcut-take-hash-table" role="function" condition="since:1.0.4">
<title>gcut_take_hash_table ()</title>
<indexterm zone="gcut-take-hash-table" role="1.0.4"><primary>gcut_take_hash_table</primary></indexterm>
<programlisting><link linkend="GHashTable"><returnvalue>GHashTable</returnvalue></link> *        gcut_take_hash_table                (<parameter><link linkend="GHashTable"><type>GHashTable</type></link> *hash_table</parameter>);</programlisting>
<para>
Passes ownership of <parameter>hash_table</parameter> to Cutter and returns
<parameter>hash_table</parameter> itself.
</para><variablelist role="params">
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="GHashTable"><type>GHashTable</type></link> to be owned by Cutter.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a <link linkend="GHashTable"><type>GHashTable</type></link> owned by Cutter. Don't
<link linkend="g-hash-table-unref"><function>g_hash_table_unref()</function></link> it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.4</para></refsect2>
<refsect2 id="gcut-take-list" role="function" condition="since:1.0.3">
<title>gcut_take_list ()</title>
<indexterm zone="gcut-take-list" role="1.0.3"><primary>gcut_take_list</primary></indexterm>
<programlisting>const <link linkend="GList"><returnvalue>GList</returnvalue></link> *       gcut_take_list                      (<parameter>const <link linkend="GList"><type>GList</type></link> *list</parameter>,
                                                         <parameter><link linkend="CutDestroyFunction"><type>CutDestroyFunction</type></link> destroy_function</parameter>);</programlisting>
<para>
Passes ownership of <parameter>list</parameter> to Cutter and returns
<parameter>list</parameter> itself.
</para><variablelist role="params">
<varlistentry><term><parameter>list</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="GList"><type>GList</type></link> to be owned by Cutter.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>destroy_function</parameter>&#160;:</term>
<listitem><simpara>the destroy function that destroys the
elements of <parameter>list</parameter>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a <link linkend="GList"><type>GList</type></link> owned by Cutter. Don't <link linkend="g-list-free"><function>g_list_free()</function></link>
it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.3</para></refsect2>
<refsect2 id="gcut-take-new-hash-table-string-string" role="function" condition="since:1.0.5">
<title>gcut_take_new_hash_table_string_string ()</title>
<indexterm zone="gcut-take-new-hash-table-string-string" role="1.0.5"><primary>gcut_take_new_hash_table_string_string</primary></indexterm>
<programlisting><link linkend="GHashTable"><returnvalue>GHashTable</returnvalue></link> *        gcut_take_new_hash_table_string_string
                                                        (<parameter>const <link linkend="gchar"><type>gchar</type></link> *key</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Creates a hash table that has string key and string value
from passed key/value pairs. The created hash table is
owned by Cutter. So don't <link linkend="g-hash-table-unref"><function>g_hash_table_unref()</function></link> it.
</para><variablelist role="params">
<varlistentry><term><parameter>key</parameter>&#160;:</term>
<listitem><simpara>The first key string.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>A <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated list of rest arguments. The
string value of the first key, followed optionally
by more key/value pairs. It must end with <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a newly-allocated <link linkend="GHashTable"><type>GHashTable</type></link> that contains
passed key/value pairs.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="gcut-take-new-list-int" role="function" condition="since:1.1.5">
<title>gcut_take_new_list_int ()</title>
<indexterm zone="gcut-take-new-list-int" role="1.1.5"><primary>gcut_take_new_list_int</primary></indexterm>
<programlisting>const <link linkend="GList"><returnvalue>GList</returnvalue></link> *       gcut_take_new_list_int              (<parameter><link linkend="guint"><type>guint</type></link> n</parameter>,
                                                         <parameter><link linkend="gint"><type>gint</type></link> value</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Creates a list from passed integer values that is owned
by Cutter.
</para>
<para>
e.g.:
<informalexample><programlisting>
gcut_take_new_list_int(3, -10, 1, 29); -> (-10, 1, 29)
</programlisting></informalexample>
</para><variablelist role="params">
<varlistentry><term><parameter>n</parameter>&#160;:</term>
<listitem><simpara>the number of integer values.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara>the first integer value.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>remaining strings in list.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a newly-allocated <link linkend="GList"><type>GList</type></link> that contains passed
integer values and is owned by Cutter.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.5</para></refsect2>
<refsect2 id="gcut-take-new-list-object" role="macro" condition="since:1.1.1">
<title>gcut_take_new_list_object()</title>
<indexterm zone="gcut-take-new-list-object" role="1.1.1"><primary>gcut_take_new_list_object</primary></indexterm>
<programlisting>#define             gcut_take_new_list_object(object, ...)</programlisting>
<para>
Creates a list from passed objects that is owned by
Cutter.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the first <link linkend="GObject"><type>GObject</type></link>.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>remaining objects in list. <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminate.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a newly-allocated <link linkend="GList"><type>GList</type></link> that contains passed
objects and is owned by Cutter.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.1</para></refsect2>
<refsect2 id="gcut-take-new-list-string" role="function" condition="since:1.0.5">
<title>gcut_take_new_list_string ()</title>
<indexterm zone="gcut-take-new-list-string" role="1.0.5"><primary>gcut_take_new_list_string</primary></indexterm>
<programlisting>const <link linkend="GList"><returnvalue>GList</returnvalue></link> *       gcut_take_new_list_string           (<parameter>const <link linkend="gchar"><type>gchar</type></link> *value</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Creates a list from passed strings that is owned by
Cutter.
</para><variablelist role="params">
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara>the first string.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>remaining strings in list. <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminate.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a newly-allocated <link linkend="GList"><type>GList</type></link> that contains passed
strings and is owned by Cutter.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="gcut-take-new-list-string-array" role="function" condition="since:1.0.6">
<title>gcut_take_new_list_string_array ()</title>
<indexterm zone="gcut-take-new-list-string-array" role="1.0.6"><primary>gcut_take_new_list_string_array</primary></indexterm>
<programlisting>const <link linkend="GList"><returnvalue>GList</returnvalue></link> *       gcut_take_new_list_string_array     (<parameter>const <link linkend="gchar"><type>gchar</type></link> **strings</parameter>);</programlisting>
<para>
Creates a list from passed string array that is owned by
Cutter.
</para><variablelist role="params">
<varlistentry><term><parameter>strings</parameter>&#160;:</term>
<listitem><simpara>the string array. <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminate.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a newly-allocated <link linkend="GList"><type>GList</type></link> that contains passed
string array and is owned by Cutter.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.6</para></refsect2>
<refsect2 id="gcut-take-new-list-string-backward-compatibility" role="macro" condition="deprecated:">
<title>gcut_take_new_list_string_backward_compatibility()</title>
<indexterm zone="gcut-take-new-list-string-backward-compatibility" role="deprecated"><primary>gcut_take_new_list_string_backward_compatibility</primary></indexterm>
<programlisting>#define             gcut_take_new_list_string_backward_compatibility(value, ...)</programlisting>
<warning><para><literal>gcut_take_new_list_string_backward_compatibility</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>
</para></refsect2>
<refsect2 id="gcut-take-new-list-uint" role="function" condition="since:1.1.5">
<title>gcut_take_new_list_uint ()</title>
<indexterm zone="gcut-take-new-list-uint" role="1.1.5"><primary>gcut_take_new_list_uint</primary></indexterm>
<programlisting>const <link linkend="GList"><returnvalue>GList</returnvalue></link> *       gcut_take_new_list_uint             (<parameter><link linkend="guint"><type>guint</type></link> n</parameter>,
                                                         <parameter><link linkend="guint"><type>guint</type></link> value</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Creates a list from passed unsigned integer values that
is owned by Cutter.
</para>
<para>
e.g.:
<informalexample><programlisting>
gcut_take_new_list_uint(3, 0, 1, 2); -> (0, 1, 2)
</programlisting></informalexample>
</para><variablelist role="params">
<varlistentry><term><parameter>n</parameter>&#160;:</term>
<listitem><simpara>the number of unsigned integer values.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara>the first unsigned integer value.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>remaining strings in list.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a newly-allocated <link linkend="GList"><type>GList</type></link> that contains passed
unsigned integer values and is owned by Cutter.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.5</para></refsect2>
<refsect2 id="gcut-take-new-string" role="function" condition="since:1.1.6">
<title>gcut_take_new_string ()</title>
<indexterm zone="gcut-take-new-string" role="1.1.6"><primary>gcut_take_new_string</primary></indexterm>
<programlisting><link linkend="GString"><returnvalue>GString</returnvalue></link> *           gcut_take_new_string                (<parameter>const <link linkend="gchar"><type>gchar</type></link> *string</parameter>);</programlisting>
<para>
Creates a <link linkend="GString"><type>GString</type></link> object from passed string.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&#160;:</term>
<listitem><simpara>the string. It can be <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a <link linkend="GString"><type>GString</type></link> owned by Cutter. Don't
<link linkend="g-string-free"><function>g_string_free()</function></link> it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.6</para></refsect2>
<refsect2 id="gcut-take-object" role="function" condition="since:1.0.3">
<title>gcut_take_object ()</title>
<indexterm zone="gcut-take-object" role="1.0.3"><primary>gcut_take_object</primary></indexterm>
<programlisting><link linkend="GObject"><returnvalue>GObject</returnvalue></link> *           gcut_take_object                    (<parameter><link linkend="GObject"><type>GObject</type></link> *object</parameter>);</programlisting>
<para>
Passes ownership of <parameter>object</parameter> to Cutter and returns <parameter>object</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="GObject"><type>GObject</type></link> to be owned by Cutter.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara><parameter>object</parameter> owned by Cutter. Don't <link linkend="g-object-unref"><function>g_object_unref()</function></link> it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.3</para></refsect2>
<refsect2 id="gcut-take-string" role="function" condition="since:1.1.6">
<title>gcut_take_string ()</title>
<indexterm zone="gcut-take-string" role="1.1.6"><primary>gcut_take_string</primary></indexterm>
<programlisting><link linkend="GString"><returnvalue>GString</returnvalue></link> *           gcut_take_string                    (<parameter><link linkend="GString"><type>GString</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 <link linkend="GString"><type>GString</type></link> to be owned by Cutter.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a <link linkend="GString"><type>GString</type></link> owned by Cutter. Don't
<link linkend="g-string-free"><function>g_string_free()</function></link> it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.6</para></refsect2>

</refsect1>

</refentry>
