<refentry id="libtracker-extract-tracker-utils">
<refmeta>
<refentrytitle role="top_of_page" id="libtracker-extract-tracker-utils.top_of_page">Data utilities</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>LIBTRACKER-EXTRACT Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Data utilities</refname>
<refpurpose>Functions for coalescing, merging, date
handling and normalizing</refpurpose>
</refnamediv>
<refsect1 id="libtracker-extract-tracker-utils.stability-level">
<title>Stability Level</title>
Stable, unless otherwise indicated
</refsect1>

<refsynopsisdiv id="libtracker-extract-tracker-utils.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;libtracker-extract/tracker-extract.h&gt;

<link linkend="gchar">gchar</link>*              <link linkend="tracker-coalesce">tracker_coalesce</link>                    (<link linkend="gint">gint</link> n_values,
                                                         ...);
const <link linkend="gchar">gchar</link>*        <link linkend="tracker-coalesce-strip">tracker_coalesce_strip</link>              (<link linkend="gint">gint</link> n_values,
                                                         ...);
<link linkend="gchar">gchar</link>*              <link linkend="tracker-merge">tracker_merge</link>                       (const <link linkend="gchar">gchar</link> *delimiter,
                                                         <link linkend="gint">gint</link> n_values,
                                                         ...);
<link linkend="gchar">gchar</link>*              <link linkend="tracker-merge-const">tracker_merge_const</link>                 (const <link linkend="gchar">gchar</link> *delimiter,
                                                         <link linkend="gint">gint</link> n_values,
                                                         ...);
<link linkend="gchar">gchar</link>*              <link linkend="tracker-text-normalize">tracker_text_normalize</link>              (const <link linkend="gchar">gchar</link> *text,
                                                         <link linkend="guint">guint</link> max_words,
                                                         <link linkend="guint">guint</link> *n_words);
<link linkend="gchar">gchar</link>*              <link linkend="tracker-date-format-to-iso8601">tracker_date_format_to_iso8601</link>      (const <link linkend="gchar">gchar</link> *date_string,
                                                         const <link linkend="gchar">gchar</link> *format);
<link linkend="gchar">gchar</link>*              <link linkend="tracker-date-guess">tracker_date_guess</link>                  (const <link linkend="gchar">gchar</link> *date_string);
</synopsis>
</refsynopsisdiv>









<refsect1 id="libtracker-extract-tracker-utils.description" role="desc">
<title role="desc.title">Description</title>
<para>
This API is provided to facilitate common more general functions
which extractors may find useful. These functions are also used by
the in-house extractors quite frequently.</para>
<para>
</para>
</refsect1>

<refsect1 id="libtracker-extract-tracker-utils.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="tracker-coalesce" role="function" condition="deprecated:1.0: Use tracker_coalesce_strip() instead.|since:0.8">
<title>tracker_coalesce ()</title>
<indexterm zone="tracker-coalesce" role="deprecated"><primary sortas="tracker_coalesce">tracker_coalesce</primary></indexterm><indexterm zone="tracker-coalesce" role="0.8"><primary sortas="tracker_coalesce">tracker_coalesce</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              tracker_coalesce                    (<link linkend="gint">gint</link> n_values,
                                                         ...);</programlisting>
<warning><para><literal>tracker_coalesce</literal> has been deprecated since version 1.0 and should not be used in newly-written code. Use <link linkend="tracker-coalesce-strip"><function>tracker_coalesce_strip()</function></link> instead.</para></warning>
<para>
This function iterates through a series of string pointers passed
using <parameter>Varargs</parameter> and returns the first which is not <link linkend="NULL--CAPS"><literal>NULL</literal></link>, not empty
(i.e. "") and not comprised of one or more spaces (i.e. " ").
</para>
<para>
The returned value is stripped using <link linkend="g-strstrip"><function>g_strstrip()</function></link>. All other values
supplied are freed. It is MOST important NOT to pass constant
string pointers to this function!</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>n_values</parameter>&#160;:</term>
<listitem><simpara> the number of <parameter>Varargs</parameter> supplied
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara> the string pointers to coalesce
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the first string pointer from those provided which
matches, otherwise <link linkend="NULL--CAPS"><literal>NULL</literal></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.8</para></refsect2>
<refsect2 id="tracker-coalesce-strip" role="function" condition="since:0.9">
<title>tracker_coalesce_strip ()</title>
<indexterm zone="tracker-coalesce-strip" role="0.9"><primary sortas="tracker_coalesce_strip">tracker_coalesce_strip</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        tracker_coalesce_strip              (<link linkend="gint">gint</link> n_values,
                                                         ...);</programlisting>
<para>
This function iterates through a series of string pointers passed
using <parameter>Varargs</parameter> and returns the first which is not <link linkend="NULL--CAPS"><literal>NULL</literal></link>, not empty
(i.e. "") and not comprised of one or more spaces (i.e. " ").
</para>
<para>
The returned value is stripped using <link linkend="g-strstrip"><function>g_strstrip()</function></link>. It is MOST
important NOT to pass constant string pointers to this function!</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>n_values</parameter>&#160;:</term>
<listitem><simpara> the number of <parameter>Varargs</parameter> supplied
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara> the string pointers to coalesce
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the first string pointer from those provided which
matches, otherwise <link linkend="NULL--CAPS"><literal>NULL</literal></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.9</para></refsect2>
<refsect2 id="tracker-merge" role="function" condition="deprecated:1.0: Use tracker_merge_const() instead.|since:0.8">
<title>tracker_merge ()</title>
<indexterm zone="tracker-merge" role="deprecated"><primary sortas="tracker_merge">tracker_merge</primary></indexterm><indexterm zone="tracker-merge" role="0.8"><primary sortas="tracker_merge">tracker_merge</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              tracker_merge                       (const <link linkend="gchar">gchar</link> *delimiter,
                                                         <link linkend="gint">gint</link> n_values,
                                                         ...);</programlisting>
<warning><para><literal>tracker_merge</literal> has been deprecated since version 1.0 and should not be used in newly-written code. Use <link linkend="tracker-merge-const"><function>tracker_merge_const()</function></link> instead.</para></warning>
<para>
This function iterates through a series of string pointers passed
using <parameter>Varargs</parameter> and returns a newly allocated string of the merged
strings. All passed strings are freed (don't pass const values)/
</para>
<para>
The <parameter>delimiter</parameter> can be <link linkend="NULL--CAPS"><literal>NULL</literal></link>. If specified, it will be used in
between each merged string in the result.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>delimiter</parameter>&#160;:</term>
<listitem><simpara> the delimiter to use when merging
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_values</parameter>&#160;:</term>
<listitem><simpara> the number of <parameter>Varargs</parameter> supplied
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara> the string pointers to merge
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string holding the result which should
be freed with <link linkend="g-free"><function>g_free()</function></link> when finished with, otherwise <link linkend="NULL--CAPS"><literal>NULL</literal></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.8</para></refsect2>
<refsect2 id="tracker-merge-const" role="function" condition="since:0.9">
<title>tracker_merge_const ()</title>
<indexterm zone="tracker-merge-const" role="0.9"><primary sortas="tracker_merge_const">tracker_merge_const</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              tracker_merge_const                 (const <link linkend="gchar">gchar</link> *delimiter,
                                                         <link linkend="gint">gint</link> n_values,
                                                         ...);</programlisting>
<para>
This function iterates through a series of string pointers passed
using <parameter>Varargs</parameter> and returns a newly allocated string of the merged
strings.
</para>
<para>
The <parameter>delimiter</parameter> can be <link linkend="NULL--CAPS"><literal>NULL</literal></link>. If specified, it will be used in
between each merged string in the result.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>delimiter</parameter>&#160;:</term>
<listitem><simpara> the delimiter to use when merging
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_values</parameter>&#160;:</term>
<listitem><simpara> the number of <parameter>Varargs</parameter> supplied
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara> the string pointers to merge
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string holding the result which should
be freed with <link linkend="g-free"><function>g_free()</function></link> when finished with, otherwise <link linkend="NULL--CAPS"><literal>NULL</literal></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.9</para></refsect2>
<refsect2 id="tracker-text-normalize" role="function" condition="since:0.8">
<title>tracker_text_normalize ()</title>
<indexterm zone="tracker-text-normalize" role="0.8"><primary sortas="tracker_text_normalize">tracker_text_normalize</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              tracker_text_normalize              (const <link linkend="gchar">gchar</link> *text,
                                                         <link linkend="guint">guint</link> max_words,
                                                         <link linkend="guint">guint</link> *n_words);</programlisting>
<para>
This function iterates through <parameter>text</parameter> checking for UTF-8 validity
using <link linkend="g-utf8-get-char-validated"><function>g_utf8_get_char_validated()</function></link>. For each character found, the
<link linkend="GUnicodeType"><literal>GUnicodeType</literal></link> is checked to make sure it is one fo the following
values:
<itemizedlist>
 <listitem><para><link linkend="G-UNICODE-LOWERCASE-LETTER--CAPS"><literal>G_UNICODE_LOWERCASE_LETTER</literal></link></para></listitem>
 <listitem><para><link linkend="G-UNICODE-MODIFIER-LETTER--CAPS"><literal>G_UNICODE_MODIFIER_LETTER</literal></link></para></listitem>
 <listitem><para><link linkend="G-UNICODE-OTHER-LETTER--CAPS"><literal>G_UNICODE_OTHER_LETTER</literal></link></para></listitem>
 <listitem><para><link linkend="G-UNICODE-TITLECASE-LETTER--CAPS"><literal>G_UNICODE_TITLECASE_LETTER</literal></link></para></listitem>
 <listitem><para><link linkend="G-UNICODE-UPPERCASE-LETTER--CAPS"><literal>G_UNICODE_UPPERCASE_LETTER</literal></link></para></listitem>
</itemizedlist>
</para>
<para>
All other symbols, punctuation, marks, numbers and separators are
stripped. A regular space (i.e. " ") is used to separate the words
in the returned string.
</para>
<para>
The <parameter>n_words</parameter> can be <link linkend="NULL--CAPS"><literal>NULL</literal></link>. If specified, it will be populated with
the number of words that were normalized in the result.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>text</parameter>&#160;:</term>
<listitem><simpara> the text to normalize
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>max_words</parameter>&#160;:</term>
<listitem><simpara> the maximum words of <parameter>text</parameter> to normalize
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_words</parameter>&#160;:</term>
<listitem><simpara> the number of words actually normalized
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string holding the result which should
be freed with <link linkend="g-free"><function>g_free()</function></link> when finished with, otherwise <link linkend="NULL--CAPS"><literal>NULL</literal></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.8</para></refsect2>
<refsect2 id="tracker-date-format-to-iso8601" role="function" condition="since:0.8">
<title>tracker_date_format_to_iso8601 ()</title>
<indexterm zone="tracker-date-format-to-iso8601" role="0.8"><primary sortas="tracker_date_format_to_iso8601">tracker_date_format_to_iso8601</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              tracker_date_format_to_iso8601      (const <link linkend="gchar">gchar</link> *date_string,
                                                         const <link linkend="gchar">gchar</link> *format);</programlisting>
<para>
This function uses <link linkend="strptime"><function>strptime()</function></link> to create a time tm structure using
<parameter>date_string</parameter> and <parameter>format</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>date_string</parameter>&#160;:</term>
<listitem><simpara> the date in a string pointer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</term>
<listitem><simpara> the format of the <parameter>date_string</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string with the time represented in
ISO8601 date format which should be freed with <link linkend="g-free"><function>g_free()</function></link> when
finished with, otherwise <link linkend="NULL--CAPS"><literal>NULL</literal></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.8</para></refsect2>
<refsect2 id="tracker-date-guess" role="function" condition="since:0.8">
<title>tracker_date_guess ()</title>
<indexterm zone="tracker-date-guess" role="0.8"><primary sortas="tracker_date_guess">tracker_date_guess</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              tracker_date_guess                  (const <link linkend="gchar">gchar</link> *date_string);</programlisting>
<para>
This function uses a number of methods to try and guess the date
held in <parameter>date_string</parameter>. The <parameter>date_string</parameter> must be at least 5
characters in length or longer for any guessing to be attempted.
Some of the string formats guessed include:
</para>
<para>
<itemizedlist>
 <listitem><para>"YYYY-MM-DD" (Simple format)</para></listitem>
 <listitem><para>"20050315113224-08'00'" (PDF format)</para></listitem>
 <listitem><para>"20050216111533Z" (PDF format)</para></listitem>
 <listitem><para>"Mon Feb  9 10:10:00 2004" (Microsoft Office format)</para></listitem>
 <listitem><para>"2005:04:29 14:56:54" (Exif format)</para></listitem>
 <listitem><para>"YYYY-MM-DDThh:mm:ss.ff+zz:zz</para></listitem>
</itemizedlist></para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>date_string</parameter>&#160;:</term>
<listitem><simpara> the date in a string pointer
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string with the time represented in
ISO8601 date format which should be freed with <link linkend="g-free"><function>g_free()</function></link> when
finished with, otherwise <link linkend="NULL--CAPS"><literal>NULL</literal></link>.

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

</refsect1>




</refentry>
