<?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-Assertion-writing-helper">
<refmeta>
<refentrytitle role="top_of_page" id="cutter-Assertion-writing-helper.top_of_page">Assertion writing helper</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>
  CUTTER Library
</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Assertion writing helper</refname>
<refpurpose>Symbols in this section help you
                    writing your own assertions.</refpurpose>
</refnamediv>

<refsect1 id="cutter-Assertion-writing-helper.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_return" colwidth="150px"/>
<colspec colname="functions_name"/>
<tbody>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cut-test-pass">cut_test_pass</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cut-test-fail">cut_test_fail</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cut-test-fail-va-list">cut_test_fail_va_list</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cut-push-backtrace">cut_push_backtrace</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cut-pop-backtrace">cut_pop_backtrace</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="cut-trace">cut_trace</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="cut-trace-with-info-expression">cut_trace_with_info_expression</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="char"><returnvalue>char</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="cut-append-diff">cut_append_diff</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="cut-set-expected">cut_set_expected</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="cut-set-actual">cut_set_actual</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="char"><returnvalue>char</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="cut-inspect-string-array">cut_inspect_string_array</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="cut-boolean"><returnvalue>cut_boolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="cut-equal-string">cut_equal_string</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="cut-boolean"><returnvalue>cut_boolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="cut-equal-double">cut_equal_double</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="cut-equal-sockaddr">cut_equal_sockaddr</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="cut-inspect-sockaddr">cut_inspect_sockaddr</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="char"><returnvalue>char</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="cut-get-test-directory">cut_get_test_directory</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="char"><returnvalue>char</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="cut-get-source-directory">cut_get_source_directory</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="cutter-Assertion-writing-helper.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable role="enum_members_table" pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="name" colwidth="150px"/>
<colspec colname="description"/>
<tbody>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CUT-RELATIVE-PATH:CAPS">CUT_RELATIVE_PATH</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="cutter-Assertion-writing-helper.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<screen>
</screen>
</refsect1>


<refsect1 id="cutter-Assertion-writing-helper.description" role="desc">
<title role="desc.title">Description</title>
<para>You will need to write your own assertions for writing
easy to read test. Symbols in this section help you
writing your own assertions.</para>
<para>e.g.:</para>
<para>my-assertions.h:</para>
<informalexample><programlisting><![CDATA[
#ifndef __MY_ASSERTIONS_H__
#define __MY_ASSERTIONS_H__

#include <cutter.h>

#ifdef __cplusplus
extern "C" {
#endif

#define my_assert_equal_int(expected, actual)                    \
    cut_trace_with_info_expression(                              \
        my_assert_equal_int_helper((expected), (actual),         \
                                   # expected, # actual),        \
        my_assert_equal_int(expected, actual, __VA_ARGS__))

void my_assert_equal_int_help (long expected,
                               long actual,
                               const char *expression_expected,
                               const char *expression_actual);

#ifdef __cplusplus
}
#endif

#endif
]]></programlisting></informalexample>
<para></para>
<para>my-assertions.c:</para>
<informalexample><programlisting><![CDATA[
#include "my-assertions.h"

void
my_assert_equal_int_helper (long expected,
                            long actual,
                            const char *expression_expected,
                            const char *expression_actual)
{
    if (expected == actual) {
        cut_test_pass();
    } else {
        cut_test_fail(cut_take_printf("<%s == %s>\n"
                                      "expected: <%ld>\n"
                                      "  actual: <%ld>",
                                      expression_expected,
                                      expression_actual,
                                      expected, actual));
    }
}
]]></programlisting></informalexample>
<para></para>
<para>Makefile.am:</para>
<informalexample><programlisting><![CDATA[
AM_CFLAGS = $(CUTTER_CFLAGS)
LIBS = $(CUTTER_LIBS)
noinst_LTLIBRARIES = libmy-assertions.la
libmy_assertions_la_SOURCES = my-assertions.c my-assertions.h
AM_LDFLAGS = -module -rpath $(libdir) -avoid-version -no-undefined
]]></programlisting></informalexample>
<para></para>

</refsect1>
<refsect1 id="cutter-Assertion-writing-helper.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="cut-test-pass" role="function" condition="since:1.0.5">
<title>cut_test_pass&#160;()</title>
<indexterm zone="cut-test-pass" role="1.0.5"><primary>cut_test_pass</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cut_test_pass (<parameter><type>void</type></parameter>);</programlisting>
<para>Call <link linkend="cut-test-pass"><function>cut_test_pass()</function></link> if an assertion is
passed. <link linkend="cut-test-pass"><function>cut_test_pass()</function></link> counts up n-assertions.</para>
<para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="cut-test-fail" role="function" condition="since:1.0.5">
<title>cut_test_fail&#160;()</title>
<indexterm zone="cut-test-fail" role="1.0.5"><primary>cut_test_fail</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cut_test_fail (<parameter>const <link linkend="char"><type>char</type></link> *system_message</parameter>,
               <parameter>...</parameter>);</programlisting>
<para>Call <link linkend="cut-test-fail"><function>cut_test_fail()</function></link> if an assertion is failed.
<link linkend="cut-test-fail"><function>cut_test_fail()</function></link> counts up n-failures and terminate the
current test.</para>
<refsect3 role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>system_message</para></entry>
<entry role="parameter_description"><para>a failure message from testing system.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>...</para></entry>
<entry role="parameter_description"><para>optional format string, followed by parameters to insert
into the format string. (as with <link linkend="printf"><function>printf()</function></link>) This is
deprecated since 0.1.6. Use <link linkend="cut-set-message"><function>cut_set_message()</function></link> instead.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="cut-test-fail-va-list" role="function" condition="deprecated:1.0.6: Use cut_test_fail() instead.|since:1.0.5">
<title>cut_test_fail_va_list&#160;()</title>
<indexterm zone="cut-test-fail-va-list" role="deprecated"><primary>cut_test_fail_va_list</primary></indexterm><indexterm zone="cut-test-fail-va-list" role="1.0.5"><primary>cut_test_fail_va_list</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cut_test_fail_va_list (<parameter>const <link linkend="char"><type>char</type></link> *system_message</parameter>,
                       <parameter>const <link linkend="char"><type>char</type></link> *user_message_format</parameter>);</programlisting>
<warning><para><literal>cut_test_fail_va_list</literal> has been deprecated since version 1.0.6 and should not be used in newly-written code.</para> <para>Use <link linkend="cut-test-fail"><function>cut_test_fail()</function></link> instead.</para>
</warning>
<para>See <link linkend="cut-test-fail"><function>cut_test_fail()</function></link> for <link linkend="cut-test-fail-va-list"><function>cut_test_fail_va_list()</function></link>'s
behavior. <parameter>user_message_format</parameter>
 is the prior variable of
variable length arguments.</para>
<para>e.g.:</para>
<informalexample><programlisting><![CDATA[
void
my_assert(cut_boolean result,
          const gchar *user_message_format,
          ...)
{
    if (result) {
        cut_test_pass();
    } else {
        cut_test_fail_va_list("Fail!", user_message_format);
    }
}
]]></programlisting></informalexample>
<para></para>
<refsect3 role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>system_message</para></entry>
<entry role="parameter_description"><para>a failure message from testing
system.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>user_message_format</para></entry>
<entry role="parameter_description"><para>a failure message from user.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="cut-push-backtrace" role="function" condition="since:1.0.6">
<title>cut_push_backtrace&#160;()</title>
<indexterm zone="cut-push-backtrace" role="1.0.6"><primary>cut_push_backtrace</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cut_push_backtrace (<parameter>const <link linkend="char"><type>char</type></link> *expression</parameter>);</programlisting>
<para>Pushes <parameter>expression</parameter>
 and the current source place to the
backtrace stack.</para>
<para>Normally, you don't need to use it directory. <link linkend="cut-trace"><function>cut_trace()</function></link>
is enough.</para>
<refsect3 role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>expression</para></entry>
<entry role="parameter_description"><para>an expression to be traced.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since 1.0.6</para></refsect2>
<refsect2 id="cut-pop-backtrace" role="function" condition="since:1.0.6">
<title>cut_pop_backtrace&#160;()</title>
<indexterm zone="cut-pop-backtrace" role="1.0.6"><primary>cut_pop_backtrace</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cut_pop_backtrace (<parameter><type>void</type></parameter>);</programlisting>
<para>Pops a backtrace from the backtrace stack.</para>
<para>Normally, you don't need to use it directory. <link linkend="cut-trace"><function>cut_trace()</function></link>
is enough.</para>
<para role="since">Since 1.0.6</para></refsect2>
<refsect2 id="cut-trace" role="macro" condition="since:1.0.5">
<title>cut_trace()</title>
<indexterm zone="cut-trace" role="1.0.5"><primary>cut_trace</primary></indexterm>
<programlisting language="C">#define             cut_trace(expression)</programlisting>
<para>Mark the current file, line, function and <parameter>expression</parameter>
 and
show it when assertion is failed in
<parameter>expression</parameter>
. Most of <parameter>expression</parameter>
 will be function call.</para>
<para>Note that you can't get return value of <parameter>expression</parameter>
.</para>
<para>Here is an example of <link linkend="cut-trace"><function>cut_trace()</function></link>. If
cut_assert_not_null(object) is failed, you will get a
backtrace that contains two line;
cut_assert_not_null(object) and create_my_object("my-name").</para>
<para>e.g.:</para>
<informalexample><programlisting><![CDATA[
static MyObject *object;

static void
create_my_object(const char *name)
{
    object = my_object_new(name);
    cut_assert_not_null(object);
}

void
test_my_object_name(void)
{
    cut_trace(create_my_object("my-name"));
    cut_assert_equal_string("my-name",
                            my_object_get_name(object));
}
]]></programlisting></informalexample>
<para></para>
<para>You will use <link linkend="cut-trace"><function>cut_trace()</function></link> with macro for test readability:</para>
<informalexample><programlisting><![CDATA[
static MyObject *object;

static void
create_my_object_helper(const char *name)
{
    object = my_object_new(name);
    cut_assert_not_null(object);
}

#define create_my_object(...)                        \
    cut_trace(create_my_object_helper(__VA_ARGS__))

void
test_my_object_name(void)
{
    create_my_object("my-name");
    cut_assert_equal_string("my-name",
                            my_object_get_name(object));
}
]]></programlisting></informalexample>
<para></para>
<refsect3 role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>expression</para></entry>
<entry role="parameter_description"><para>an expression to be traced.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="cut-trace-with-info-expression" role="macro" condition="since:1.0.5">
<title>cut_trace_with_info_expression()</title>
<indexterm zone="cut-trace-with-info-expression" role="1.0.5"><primary>cut_trace_with_info_expression</primary></indexterm>
<programlisting language="C">#define             cut_trace_with_info_expression(expression, info_expression)</programlisting>
<para>It's difference between <link linkend="cut-trace"><function>cut_trace()</function></link> and
<link linkend="cut-trace-with-info-expression"><function>cut_trace_with_info_expression()</function></link> that traced expression
is the same expression as <parameter>expression</parameter>
 or
not. <link linkend="cut-trace-with-info-expression"><function>cut_trace_with_info_expression()</function></link> is useful when you
want to hide some information in <parameter>expression</parameter>
 for
backtrace readability.</para>
<para>Here is an example of
<link linkend="cut-trace-with-info-expression"><function>cut_trace_with_info_expression()</function></link>. If
cut_assert_not_null(object) is failed, you will get a
backtrace that contains two line:</para>
<itemizedlist>
  <listitem><para>cut_assert_not_null(object)</para></listitem>
  <listitem><para>create_my_object("my-name") not
create_my_object_helper("my-name")</para></listitem>
</itemizedlist>
<para>If you use <link linkend="cut-trace"><function>cut_trace()</function></link> instead of
<link linkend="cut-trace-with-info-expression"><function>cut_trace_with_info_expression()</function></link>, you will get
create_my_object_helper("my-name"). You may be confused
about 'Where is create_my_object_helper("my-name") from?
<link linkend="test-my-object-name"><function>test_my_object_name()</function></link> uses create_my_object("my-name")
but does not use create_my_object_helper("my-name").'.</para>
<para>e.g.:</para>
<informalexample><programlisting><![CDATA[
static MyObject *object;

static void
create_my_object_helper(const char *name)
{
    object = my_object_new(name);
    cut_assert_not_null(object);
}

#define create_my_object(...)                        \
    cut_trace_with_info_expression(                  \
        create_my_object_helper(__VA_ARGS__),        \
        create_my_object(__VA_ARGS__))

void
test_my_object_name(void)
{
    create_my_object("my-name");
    cut_assert_equal_string("my-name",
                            my_object_get_name(object));
}
]]></programlisting></informalexample>
<para></para>
<refsect3 role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>expression</para></entry>
<entry role="parameter_description"><para>an expression to be traced.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>info_expression</para></entry>
<entry role="parameter_description"><para>a traced expression.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="cut-append-diff" role="function" condition="deprecated|since:1.0.3">
<title>cut_append_diff&#160;()</title>
<indexterm zone="cut-append-diff" role="deprecated"><primary>cut_append_diff</primary></indexterm><indexterm zone="cut-append-diff" role="1.0.3"><primary>cut_append_diff</primary></indexterm>
<programlisting language="C">const <link linkend="char"><returnvalue>char</returnvalue></link>&#160;*
cut_append_diff (<parameter>const <link linkend="char"><type>char</type></link> *message</parameter>,
                 <parameter>const <link linkend="char"><type>char</type></link> *from</parameter>,
                 <parameter>const <link linkend="char"><type>char</type></link> *to</parameter>);</programlisting>
<warning><para><literal>cut_append_diff</literal> has been deprecated since version 1.0.9 and should not be used in newly-written code.</para> <para>Use <link linkend="cut-set-expected"><function>cut_set_expected()</function></link> and
<link linkend="cut-set-actual"><function>cut_set_actual()</function></link> instead.</para>
</warning>
<para>Computes diff between <parameter>from</parameter>
 and <parameter>to</parameter>
 and append the diff
to <parameter>message</parameter>
. Returned string is owned by Cutter.</para>
<refsect3 role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>message</para></entry>
<entry role="parameter_description"><para>the string to be appended diff.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>from</para></entry>
<entry role="parameter_description"><para>the original string.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>to</para></entry>
<entry role="parameter_description"><para>the modified string.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 role="returns">
<title>Returns</title>
<para> <parameter>message</parameter>
with diff between <parameter>from</parameter>
and <parameter>to</parameter>
or same
as <parameter>message</parameter>
if the diff not interested. Don't free it.</para>
<para></para>
</refsect3><para role="since">Since 1.0.3</para></refsect2>
<refsect2 id="cut-set-expected" role="macro" condition="since:1.0.9">
<title>cut_set_expected()</title>
<indexterm zone="cut-set-expected" role="1.0.9"><primary>cut_set_expected</primary></indexterm>
<programlisting language="C">#define             cut_set_expected(expected)</programlisting>
<para>Sets an inspected expected object to be used by the next
assertion.</para>
<para>If both of expected and actual object are set and diff of
them is needed, the diff is generated automatically.</para>
<para>See also <link linkend="cut-set-actual"><function>cut_set_actual()</function></link>.</para>
<refsect3 role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>expected</para></entry>
<entry role="parameter_description"><para>the inspected expected object.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since 1.0.9</para></refsect2>
<refsect2 id="cut-set-actual" role="macro" condition="since:1.0.9">
<title>cut_set_actual()</title>
<indexterm zone="cut-set-actual" role="1.0.9"><primary>cut_set_actual</primary></indexterm>
<programlisting language="C">#define             cut_set_actual(actual)</programlisting>
<para>Sets an inspected actual object to be used by the next
assertion.</para>
<para>If both of expected and actual object are set and diff of
them is needed, the diff is generated automatically.</para>
<para>See also <link linkend="cut-set-expected"><function>cut_set_expected()</function></link>.</para>
<refsect3 role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>actual</para></entry>
<entry role="parameter_description"><para>the inspected actual object.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since 1.0.9</para></refsect2>
<refsect2 id="cut-inspect-string-array" role="function">
<title>cut_inspect_string_array&#160;()</title>
<indexterm zone="cut-inspect-string-array"><primary>cut_inspect_string_array</primary></indexterm>
<programlisting language="C">const <link linkend="char"><returnvalue>char</returnvalue></link>&#160;*
cut_inspect_string_array (<parameter>const <link linkend="char"><type>char</type></link> **strings</parameter>);</programlisting>
<para>Formats <parameter>strings</parameter>
 as human readable string that is owned by Cutter.</para>
<refsect3 role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>strings</para></entry>
<entry role="parameter_description"><para>the array of strings to be inspected.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 role="returns">
<title>Returns</title>
<para> a inspected string owned by Cutter. Don't free it.</para>
<para></para>
</refsect3></refsect2>
<refsect2 id="cut-equal-string" role="function" condition="since:1.0.5">
<title>cut_equal_string&#160;()</title>
<indexterm zone="cut-equal-string" role="1.0.5"><primary>cut_equal_string</primary></indexterm>
<programlisting language="C"><link linkend="cut-boolean"><returnvalue>cut_boolean</returnvalue></link>
cut_equal_string (<parameter>const <link linkend="char"><type>char</type></link> *string1</parameter>,
                  <parameter>const <link linkend="char"><type>char</type></link> *string2</parameter>);</programlisting>
<para>Compare <parameter>string1</parameter>
 to <parameter>string2</parameter>
. <parameter>string1</parameter>
 and/or <parameter>string2</parameter>

maybe <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</para>
<refsect3 role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string1</para></entry>
<entry role="parameter_description"><para>a string.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>string2</para></entry>
<entry role="parameter_description"><para>a string.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 role="returns">
<title>Returns</title>
<para> <link linkend="CUT-TRUE:CAPS"><literal>CUT_TRUE</literal></link> if both <parameter>string1</parameter>
and <parameter>string2</parameter>
are <link linkend="NULL:CAPS"><literal>NULL</literal></link> or
have the same contents; <link linkend="CUT-FALSE:CAPS"><literal>CUT_FALSE</literal></link> otherwise.</para>
<para></para>
</refsect3><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="cut-equal-double" role="function" condition="since:1.0.5">
<title>cut_equal_double&#160;()</title>
<indexterm zone="cut-equal-double" role="1.0.5"><primary>cut_equal_double</primary></indexterm>
<programlisting language="C"><link linkend="cut-boolean"><returnvalue>cut_boolean</returnvalue></link>
cut_equal_double (<parameter><link linkend="double"><type>double</type></link> double1</parameter>,
                  <parameter><link linkend="double"><type>double</type></link> double2</parameter>,
                  <parameter><link linkend="double"><type>double</type></link> error</parameter>);</programlisting>
<para>Compare <parameter>double1</parameter>
 to <parameter>double2</parameter>
 with <parameter>error</parameter>
 range.</para>
<refsect3 role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>double1</para></entry>
<entry role="parameter_description"><para>a double value.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>double2</para></entry>
<entry role="parameter_description"><para>a double value.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>error</para></entry>
<entry role="parameter_description"><para>a double value that specifies error range.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 role="returns">
<title>Returns</title>
<para> <link linkend="CUT-TRUE:CAPS"><literal>CUT_TRUE</literal></link> if |<parameter>double1</parameter>
- <parameter>double2</parameter>
| &lt;= <parameter>error</parameter>
;
<link linkend="CUT-FALSE:CAPS"><literal>CUT_FALSE</literal></link> otherwise.</para>
<para></para>
</refsect3><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="cut-equal-sockaddr" role="macro" condition="since:1.1.1">
<title>cut_equal_sockaddr()</title>
<indexterm zone="cut-equal-sockaddr" role="1.1.1"><primary>cut_equal_sockaddr</primary></indexterm>
<programlisting language="C">#define cut_equal_sockaddr(address1, address2) CUT_FALSE
</programlisting>
<para>Compare <parameter>address1</parameter>
 to <parameter>address2</parameter>
.</para>
<para>This function can be disabled by defining CUT_DISABLE_SOCKET_SUPPORT.</para>
<refsect3 role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>address1</para></entry>
<entry role="parameter_description"><para>a socket address.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>address2</para></entry>
<entry role="parameter_description"><para>a socket address.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 role="returns">
<title>Returns</title>
<para> <link linkend="CUT-TRUE:CAPS"><literal>CUT_TRUE</literal></link> if <parameter>address1</parameter>
== <parameter>address2</parameter>
,
<link linkend="CUT-FALSE:CAPS"><literal>CUT_FALSE</literal></link> otherwise.</para>
<para></para>
</refsect3><para role="since">Since 1.1.1</para></refsect2>
<refsect2 id="cut-inspect-sockaddr" role="macro" condition="since:1.1.1">
<title>cut_inspect_sockaddr()</title>
<indexterm zone="cut-inspect-sockaddr" role="1.1.1"><primary>cut_inspect_sockaddr</primary></indexterm>
<programlisting language="C">#define             cut_inspect_sockaddr(address)</programlisting>
<para>Formats <parameter>address</parameter>
 as human readable string that is owned
by Cutter.</para>
<para>This function can be disabled by defining CUT_DISABLE_SOCKET_SUPPORT.</para>
<refsect3 role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>address</para></entry>
<entry role="parameter_description"><para>the socket address to be inspected.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 role="returns">
<title>Returns</title>
<para> a inspected socket address owned by Cutter. Don't free it.</para>
<para></para>
</refsect3><para role="since">Since 1.1.1</para></refsect2>
<refsect2 id="cut-get-test-directory" role="function" condition="since:1.1.4">
<title>cut_get_test_directory&#160;()</title>
<indexterm zone="cut-get-test-directory" role="1.1.4"><primary>cut_get_test_directory</primary></indexterm>
<programlisting language="C">const <link linkend="char"><returnvalue>char</returnvalue></link>&#160;*
cut_get_test_directory (<parameter><type>void</type></parameter>);</programlisting>
<para>Gets the test directory name which is specified by command line.</para>
<refsect3 role="returns">
<title>Returns</title>
<para> a string owned by Cutter that must not be modified or freed.</para>
<para></para>
</refsect3><para role="since">Since 1.1.4</para></refsect2>
<refsect2 id="cut-get-source-directory" role="function" condition="since:1.1.5">
<title>cut_get_source_directory&#160;()</title>
<indexterm zone="cut-get-source-directory" role="1.1.5"><primary>cut_get_source_directory</primary></indexterm>
<programlisting language="C">const <link linkend="char"><returnvalue>char</returnvalue></link>&#160;*
cut_get_source_directory (<parameter><type>void</type></parameter>);</programlisting>
<para>Gets the source directory name which is specified by command line.</para>
<refsect3 role="returns">
<title>Returns</title>
<para> a string owned by Cutter that must not be modified or freed.</para>
<para></para>
</refsect3><para role="since">Since 1.1.5</para></refsect2>

</refsect1>
<refsect1 id="cutter-Assertion-writing-helper.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="CUT-RELATIVE-PATH:CAPS" role="macro" condition="since:1.0.6">
<title>CUT_RELATIVE_PATH</title>
<indexterm zone="CUT-RELATIVE-PATH:CAPS" role="1.0.6"><primary>CUT_RELATIVE_PATH</primary></indexterm>
<programlisting language="C">#  define CUT_RELATIVE_PATH NULL
</programlisting>
<para>Define this macro in a source code or build option
(e.g. -DCUT_RELATIVE_PATH=\""sub/dir/"\") if the source
code is built as shared library and used it as helper
library of your test. If this path isn't set, you can't
get correct path from <link linkend="cut-trace"><function>cut_trace()</function></link> and
<link linkend="cut-trace-with-info-expression"><function>cut_trace_with_info_expression()</function></link>.</para>
<para>Here is an example structure for explain:</para>
<informalexample><programlisting><![CDATA[
--- core-lib/ --- XXX.c # Your core library
 |             +- ...
 |             +- YYY.c
 +- util-lib/ --- AAA.c # Your utility library
 |             +- ...
 |             +- BBB.c
 |
 +- test/ --- core/ --- test-XXX.c # Tests for your core library
           |         +- ...
           |         +- test-YYY.c
           +- util/ --- test-AAA.c # Tests for your utility library
           |         +- ...
           |         +- test-BBB.c
           +- lib/  --- my-assertions.c # Your library of tests.
                     +- my-assertions.h # This library will be used
                     |                  # as shared library of your
                     |                  # tests (test/core/test-*.so
                     |                  # and test/util/test-*.so)
                     +- ...

  % cutter --source-directory=test test
]]></programlisting></informalexample>
<para></para>
<para>In the above example structure, you need to define
<link linkend="CUT-RELATIVE-PATH:CAPS"><literal>CUT_RELATIVE_PATH</literal></link> as "lib" in test/lib/my-assertions.c
because my-assertions.c is in lib/ directory from source
directory "test" specified by command line option
--source-directory.</para>
<para>Here are example code and build option:</para>
<informalexample><programlisting><![CDATA[
test/lib/my-assertions.c:
  #define CUT_RELATIVE_PATH "lib"
  #include <cutter.h>

build option:
  % gcc -DCUT_RELATIVE_PATH="\"lib\"" ...
]]></programlisting></informalexample>
<para></para>
<para role="since">Since 1.0.6</para></refsect2>

</refsect1>

</refentry>
