<?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-Utilities-for-GEnum-and-GFlags">
<refmeta>
<refentrytitle role="top_of_page" id="cutter-Assertion-Utilities-for-GEnum-and-GFlags.top_of_page">Assertion Utilities for GEnum and GFlags</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>
  CUTTER Library
</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Assertion Utilities for GEnum and GFlags</refname>
<refpurpose>Utilities to write assertions related
to <link linkend="GEnum"><type>GEnum</type></link> or <link linkend="GFlags"><type>GFlags</type></link> more easily.</refpurpose>
</refnamediv>

<refsynopsisdiv id="cutter-Assertion-Utilities-for-GEnum-and-GFlags.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>#define             <link linkend="GCUT-ENUM-ERROR:CAPS">GCUT_ENUM_ERROR</link>
<link linkend="GQuark"><returnvalue>GQuark</returnvalue></link>              <link linkend="gcut-enum-error-quark">gcut_enum_error_quark</link>               (<parameter><type>void</type></parameter>);
enum                <link linkend="GCutEnumError">GCutEnumError</link>;
<link linkend="gchar"><returnvalue>gchar</returnvalue></link> *             <link linkend="gcut-enum-inspect">gcut_enum_inspect</link>                   (<parameter><link linkend="GType"><type>GType</type></link> enum_type</parameter>,
                                                         <parameter><link linkend="gint"><type>gint</type></link> enum_value</parameter>);
<link linkend="gint"><returnvalue>gint</returnvalue></link>                <link linkend="gcut-enum-parse">gcut_enum_parse</link>                     (<parameter><link linkend="GType"><type>GType</type></link> enum_type</parameter>,
                                                         <parameter>const <link linkend="gchar"><type>gchar</type></link> *enum_value</parameter>,
                                                         <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);
<link linkend="gchar"><returnvalue>gchar</returnvalue></link> *             <link linkend="gcut-flags-inspect">gcut_flags_inspect</link>                  (<parameter><link linkend="GType"><type>GType</type></link> flags_type</parameter>,
                                                         <parameter><link linkend="guint"><type>guint</type></link> flags_value</parameter>);
<link linkend="guint"><returnvalue>guint</returnvalue></link>               <link linkend="gcut-flags-parse">gcut_flags_parse</link>                    (<parameter><link linkend="GType"><type>GType</type></link> flags_type</parameter>,
                                                         <parameter>const <link linkend="gchar"><type>gchar</type></link> *flags_value</parameter>,
                                                         <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);
<link linkend="guint"><returnvalue>guint</returnvalue></link>               <link linkend="gcut-flags-get-all">gcut_flags_get_all</link>                  (<parameter><link linkend="GType"><type>GType</type></link> flags_type</parameter>,
                                                         <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);
</synopsis>
</refsynopsisdiv>

<refsect1 id="cutter-Assertion-Utilities-for-GEnum-and-GFlags.description" role="desc">
<title role="desc.title">Description</title>
<para>
To write assertions, you need to check equality and show
expected and actual values.
</para>
<para>
The utilities help you to write assertions that are
related to <link linkend="GEnum"><type>GEnum</type></link> or <link linkend="GFlags"><type>GFlags</type></link>.
</para>
</refsect1>
<refsect1 id="cutter-Assertion-Utilities-for-GEnum-and-GFlags.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GCUT-ENUM-ERROR:CAPS" role="macro" condition="since:1.0.6">
<title>GCUT_ENUM_ERROR</title>
<indexterm zone="GCUT-ENUM-ERROR:CAPS" role="1.0.6"><primary>GCUT_ENUM_ERROR</primary></indexterm>
<programlisting>#define GCUT_ENUM_ERROR (gcut_enum_error_quark())
</programlisting>
<para>
Error domain for enum related operations. Errors in this domain
will be from the <link linkend="GCutEnumError"><type>GCutEnumError</type></link> enumeration.
</para><para role="since">Since 1.0.6</para></refsect2>
<refsect2 id="gcut-enum-error-quark" role="function">
<title>gcut_enum_error_quark ()</title>
<indexterm zone="gcut-enum-error-quark"><primary>gcut_enum_error_quark</primary></indexterm>
<programlisting><link linkend="GQuark"><returnvalue>GQuark</returnvalue></link>              gcut_enum_error_quark               (<parameter><type>void</type></parameter>);</programlisting>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GCutEnumError" role="enum" condition="since:1.0.6">
<title>enum GCutEnumError</title>
<indexterm zone="GCutEnumError" role="1.0.6"><primary>GCutEnumError</primary></indexterm>
<programlisting>typedef enum
{
    GCUT_ENUM_ERROR_INVALID_TYPE,
    GCUT_ENUM_ERROR_INVALID_VALUE
} GCutEnumError;
</programlisting>
<para>
Error codes returned by enum related operation.
</para><variablelist role="enum">
<varlistentry id="GCUT-ENUM-ERROR-INVALID-TYPE:CAPS" role="constant">
<term><literal>GCUT_ENUM_ERROR_INVALID_TYPE</literal></term>
<listitem><simpara>Invalid type.
</simpara></listitem>
</varlistentry>
<varlistentry id="GCUT-ENUM-ERROR-INVALID-VALUE:CAPS" role="constant">
<term><literal>GCUT_ENUM_ERROR_INVALID_VALUE</literal></term>
<listitem><simpara>Invalid value.
</simpara></listitem>
</varlistentry>
</variablelist><para role="since">Since 1.0.6</para></refsect2>
<refsect2 id="gcut-enum-inspect" role="function" condition="since:1.0.5">
<title>gcut_enum_inspect ()</title>
<indexterm zone="gcut-enum-inspect" role="1.0.5"><primary>gcut_enum_inspect</primary></indexterm>
<programlisting><link linkend="gchar"><returnvalue>gchar</returnvalue></link> *             gcut_enum_inspect                   (<parameter><link linkend="GType"><type>GType</type></link> enum_type</parameter>,
                                                         <parameter><link linkend="gint"><type>gint</type></link> enum_value</parameter>);</programlisting>
<para>
Inspects <parameter>enum_type</parameter> value, <parameter>enum_value</parameter>. The returned
string should be freed when no longer needed.
</para><variablelist role="params">
<varlistentry><term><parameter>enum_type</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GEnum"><type>GEnum</type></link> type.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>enum_value</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GEnum"><type>GEnum</type></link> value to be inspected.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> inspected <parameter>enum_value</parameter> as a string.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="gcut-enum-parse" role="function" condition="since:1.0.6">
<title>gcut_enum_parse ()</title>
<indexterm zone="gcut-enum-parse" role="1.0.6"><primary>gcut_enum_parse</primary></indexterm>
<programlisting><link linkend="gint"><returnvalue>gint</returnvalue></link>                gcut_enum_parse                     (<parameter><link linkend="GType"><type>GType</type></link> enum_type</parameter>,
                                                         <parameter>const <link linkend="gchar"><type>gchar</type></link> *enum_value</parameter>,
                                                         <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
<para>
Parses <parameter>enum_value</parameter> and returns a enum value of
<parameter>enum_type</parameter>. <parameter>enum_value</parameter> should be enum name or nick
name. If <parameter>enum_value</parameter> isn't match then <parameter>error</parameter> is set to a
<link linkend="GCutEnumError"><type>GCutEnumError</type></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>enum_type</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GEnum"><type>GEnum</type></link> type.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>enum_value</parameter>&#160;:</term>
<listitem><simpara>a string to be parsed.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara>return location for an error, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> enum value of <parameter>enum_type</parameter> corresponded to <parameter>enum_value</parameter>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.6</para></refsect2>
<refsect2 id="gcut-flags-inspect" role="function" condition="since:1.0.5">
<title>gcut_flags_inspect ()</title>
<indexterm zone="gcut-flags-inspect" role="1.0.5"><primary>gcut_flags_inspect</primary></indexterm>
<programlisting><link linkend="gchar"><returnvalue>gchar</returnvalue></link> *             gcut_flags_inspect                  (<parameter><link linkend="GType"><type>GType</type></link> flags_type</parameter>,
                                                         <parameter><link linkend="guint"><type>guint</type></link> flags_value</parameter>);</programlisting>
<para>
Inspects <parameter>flags_type</parameter> value, <parameter>flags_value</parameter>. The returned
string should be freed when no longer needed.
</para><variablelist role="params">
<varlistentry><term><parameter>flags_type</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GFlags"><type>GFlags</type></link> type.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flags_value</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GFlags"><type>GFlags</type></link> value to be inspected.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> inspected <parameter>flags_value</parameter> as a string.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="gcut-flags-parse" role="function" condition="since:1.0.6">
<title>gcut_flags_parse ()</title>
<indexterm zone="gcut-flags-parse" role="1.0.6"><primary>gcut_flags_parse</primary></indexterm>
<programlisting><link linkend="guint"><returnvalue>guint</returnvalue></link>               gcut_flags_parse                    (<parameter><link linkend="GType"><type>GType</type></link> flags_type</parameter>,
                                                         <parameter>const <link linkend="gchar"><type>gchar</type></link> *flags_value</parameter>,
                                                         <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
<para>
Parses <parameter>flags_value</parameter> and returns a flags value of
<parameter>flags_type</parameter>. <parameter>flags_value</parameter> should be formated as
"nick-or-name1|nick-or-name2|...|nick-or-nameN". If
<parameter>flags_value</parameter> includes unknown flag then <parameter>error</parameter> is set to
a <link linkend="GCutEnumError"><type>GCutEnumError</type></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>flags_type</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GFlags"><type>GFlags</type></link> type.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flags_value</parameter>&#160;:</term>
<listitem><simpara>a string to be parsed.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara>return location for an error, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> flags value of <parameter>flags_type</parameter> corresponded to <parameter>flags_value</parameter>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.6</para></refsect2>
<refsect2 id="gcut-flags-get-all" role="function" condition="since:1.0.6">
<title>gcut_flags_get_all ()</title>
<indexterm zone="gcut-flags-get-all" role="1.0.6"><primary>gcut_flags_get_all</primary></indexterm>
<programlisting><link linkend="guint"><returnvalue>guint</returnvalue></link>               gcut_flags_get_all                  (<parameter><link linkend="GType"><type>GType</type></link> flags_type</parameter>,
                                                         <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
<para>
Gets a flags value that includes all available flag
values.
</para><variablelist role="params">
<varlistentry><term><parameter>flags_type</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GFlags"><type>GFlags</type></link> type.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara>return location for an error, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a flags value that includes all available flag
values.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.6</para></refsect2>

</refsect1>

</refentry>
