<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="libedataserver-e-time-utils">
<refmeta>
<refentrytitle role="top_of_page" id="libedataserver-e-time-utils.top_of_page">Time-Related Utility Functions</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>LIBEDATASERVER Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Time-Related Utility Functions</refname>
<refpurpose>Utility functions for time structure manipulation.</refpurpose>
</refnamediv>

<refsynopsisdiv id="libedataserver-e-time-utils.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>
enum                <link linkend="ETimeParseStatus">ETimeParseStatus</link>;
<link linkend="ETimeParseStatus">ETimeParseStatus</link>    <link linkend="e-time-parse-date-and-time">e_time_parse_date_and_time</link>          (const <link linkend="char">char</link> *value,
                                                         <link linkend="struct-tm">struct tm</link> *result);
<link linkend="ETimeParseStatus">ETimeParseStatus</link>    <link linkend="e-time-parse-date">e_time_parse_date</link>                   (const <link linkend="char">char</link> *value,
                                                         <link linkend="struct-tm">struct tm</link> *result);
<link linkend="ETimeParseStatus">ETimeParseStatus</link>    <link linkend="e-time-parse-date-and-time-ex">e_time_parse_date_and_time_ex</link>       (const <link linkend="char">char</link> *value,
                                                         <link linkend="struct-tm">struct tm</link> *result,
                                                         <link linkend="gboolean">gboolean</link> *two_digit_year);
<link linkend="ETimeParseStatus">ETimeParseStatus</link>    <link linkend="e-time-parse-date-ex">e_time_parse_date_ex</link>                (const <link linkend="char">char</link> *value,
                                                         <link linkend="struct-tm">struct tm</link> *result,
                                                         <link linkend="gboolean">gboolean</link> *two_digit_year);
<link linkend="ETimeParseStatus">ETimeParseStatus</link>    <link linkend="e-time-parse-time">e_time_parse_time</link>                   (const <link linkend="char">char</link> *value,
                                                         <link linkend="struct-tm">struct tm</link> *result);
<link linkend="void">void</link>                <link linkend="e-time-format-date-and-time">e_time_format_date_and_time</link>         (<link linkend="struct-tm">struct tm</link> *date_tm,
                                                         <link linkend="gboolean">gboolean</link> use_24_hour_format,
                                                         <link linkend="gboolean">gboolean</link> show_midnight,
                                                         <link linkend="gboolean">gboolean</link> show_zero_seconds,
                                                         <link linkend="char">char</link> *buffer,
                                                         <link linkend="int">int</link> buffer_size);
<link linkend="void">void</link>                <link linkend="e-time-format-time">e_time_format_time</link>                  (<link linkend="struct-tm">struct tm</link> *date_tm,
                                                         <link linkend="gboolean">gboolean</link> use_24_hour_format,
                                                         <link linkend="gboolean">gboolean</link> show_zero_seconds,
                                                         <link linkend="char">char</link> *buffer,
                                                         <link linkend="int">int</link> buffer_size);
<link linkend="time-t">time_t</link>              <link linkend="e-mktime-utc">e_mktime_utc</link>                        (<link linkend="struct-tm">struct tm</link> *tm);
<link linkend="void">void</link>                <link linkend="e-localtime-with-offset">e_localtime_with_offset</link>             (<link linkend="time-t">time_t</link> tt,
                                                         <link linkend="struct-tm">struct tm</link> *tm,
                                                         <link linkend="int">int</link> *offset);
<link linkend="char">char</link> *              <link linkend="e-time-get-d-fmt-with-4digit-year">e_time_get_d_fmt_with_4digit_year</link>   (void);
</synopsis>
</refsynopsisdiv>









<refsect1 id="libedataserver-e-time-utils.description" role="desc">
<title role="desc.title">Description</title>
<para>
</para>
</refsect1>

<refsect1 id="libedataserver-e-time-utils.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="ETimeParseStatus" role="enum">
<title>enum ETimeParseStatus</title>
<indexterm zone="ETimeParseStatus"><primary sortas="ETimeParseStatus">ETimeParseStatus</primary></indexterm><programlisting>typedef enum {
	E_TIME_PARSE_OK,
	E_TIME_PARSE_NONE,
	E_TIME_PARSE_INVALID
} ETimeParseStatus;
</programlisting>
<para>
</para>
<para>
</para><variablelist role="enum">
<varlistentry id="E-TIME-PARSE-OK--CAPS" role="constant">
<term><literal>E_TIME_PARSE_OK</literal></term>
<listitem><simpara> The time string was parsed successfully.
</simpara></listitem>
</varlistentry>
<varlistentry id="E-TIME-PARSE-NONE--CAPS" role="constant">
<term><literal>E_TIME_PARSE_NONE</literal></term>
<listitem><simpara> The time string was empty.
</simpara></listitem>
</varlistentry>
<varlistentry id="E-TIME-PARSE-INVALID--CAPS" role="constant">
<term><literal>E_TIME_PARSE_INVALID</literal></term>
<listitem><simpara> The time string was not formatted correctly.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="e-time-parse-date-and-time" role="function">
<title>e_time_parse_date_and_time ()</title>
<indexterm zone="e-time-parse-date-and-time"><primary sortas="e_time_parse_date_and_time">e_time_parse_date_and_time</primary></indexterm><programlisting><link linkend="ETimeParseStatus">ETimeParseStatus</link>    e_time_parse_date_and_time          (const <link linkend="char">char</link> *value,
                                                         <link linkend="struct-tm">struct tm</link> *result);</programlisting>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>result</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-time-parse-date" role="function">
<title>e_time_parse_date ()</title>
<indexterm zone="e-time-parse-date"><primary sortas="e_time_parse_date">e_time_parse_date</primary></indexterm><programlisting><link linkend="ETimeParseStatus">ETimeParseStatus</link>    e_time_parse_date                   (const <link linkend="char">char</link> *value,
                                                         <link linkend="struct-tm">struct tm</link> *result);</programlisting>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>result</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-time-parse-date-and-time-ex" role="function">
<title>e_time_parse_date_and_time_ex ()</title>
<indexterm zone="e-time-parse-date-and-time-ex"><primary sortas="e_time_parse_date_and_time_ex">e_time_parse_date_and_time_ex</primary></indexterm><programlisting><link linkend="ETimeParseStatus">ETimeParseStatus</link>    e_time_parse_date_and_time_ex       (const <link linkend="char">char</link> *value,
                                                         <link linkend="struct-tm">struct tm</link> *result,
                                                         <link linkend="gboolean">gboolean</link> *two_digit_year);</programlisting>
<para>
Parses a string <parameter>value</parameter> containing a date and a time and stores the
result in <parameter>result</parameter>. The date in <parameter>value</parameter> is expected to be in a format
like "Wed 3/13/00 14:20:00", though <link linkend="gettext"><function>gettext()</function></link> is used to support the
appropriate local formats. There is also some leniency on the
format of the string, e.g. the weekday can be skipped or 12-hour
formats with am/pm can be used.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara> The string to parse a date and time from.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>result</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="tm"><type>tm</type></link> to store the result in.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>two_digit_year</parameter>&#160;:</term>
<listitem><simpara> set to TRUE, is parsing with two-digit year, else FALSE,
   but only when not NULL.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> E_TIME_PARSE_OK if the string was successfully parsed,
         E_TIME_PARSE_NONE if the string was empty, or
         E_TIME_PARSE_INVALID if the string could not be parsed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-time-parse-date-ex" role="function">
<title>e_time_parse_date_ex ()</title>
<indexterm zone="e-time-parse-date-ex"><primary sortas="e_time_parse_date_ex">e_time_parse_date_ex</primary></indexterm><programlisting><link linkend="ETimeParseStatus">ETimeParseStatus</link>    e_time_parse_date_ex                (const <link linkend="char">char</link> *value,
                                                         <link linkend="struct-tm">struct tm</link> *result,
                                                         <link linkend="gboolean">gboolean</link> *two_digit_year);</programlisting>
<para>
Takes in a date string entered by the user and tries to convert it to
a struct <link linkend="tm"><type>tm</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara> A date string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>result</parameter>&#160;:</term>
<listitem><simpara> Return value for the parsed date.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>two_digit_year</parameter>&#160;:</term>
<listitem><simpara> set to TRUE, is parsing with two-digit year, else FALSE,
   but only when not NULL.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> An <link linkend="ETimeParseStatus"><type>ETimeParseStatus</type></link> result code indicating whether
<parameter>value</parameter> was an empty string, a valid date, or an invalid date.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-time-parse-time" role="function">
<title>e_time_parse_time ()</title>
<indexterm zone="e-time-parse-time"><primary sortas="e_time_parse_time">e_time_parse_time</primary></indexterm><programlisting><link linkend="ETimeParseStatus">ETimeParseStatus</link>    e_time_parse_time                   (const <link linkend="char">char</link> *value,
                                                         <link linkend="struct-tm">struct tm</link> *result);</programlisting>
<para>
Parses <parameter>value</parameter>, a string containing a time. <parameter>value</parameter> is expected to be
in a format like "14:20:00". <link linkend="gettext"><function>gettext()</function></link> is used to
support the appropriate local formats and slightly
different formats, such as 12-hour formats with am/pm,
are accepted as well.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara> The string to parse a time from.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>result</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="tm"><type>tm</type></link> to store the result in.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> An <link linkend="ETimeParseStatus"><type>ETimeParseStatus</type></link> result code indicating whether
<parameter>value</parameter> was an empty string, a valid date, or an invalid date.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-time-format-date-and-time" role="function">
<title>e_time_format_date_and_time ()</title>
<indexterm zone="e-time-format-date-and-time"><primary sortas="e_time_format_date_and_time">e_time_format_date_and_time</primary></indexterm><programlisting><link linkend="void">void</link>                e_time_format_date_and_time         (<link linkend="struct-tm">struct tm</link> *date_tm,
                                                         <link linkend="gboolean">gboolean</link> use_24_hour_format,
                                                         <link linkend="gboolean">gboolean</link> show_midnight,
                                                         <link linkend="gboolean">gboolean</link> show_zero_seconds,
                                                         <link linkend="char">char</link> *buffer,
                                                         <link linkend="int">int</link> buffer_size);</programlisting>
<para>
Creates a string representation of the time value <parameter>date_tm</parameter> and
stores it in <parameter>buffer</parameter>.  <parameter>buffer_size</parameter> should be at least 64 to be
safe. If <parameter>show_midnight</parameter> is <link linkend="FALSE--CAPS"><type>FALSE</type></link>, and the time is midnight, then
only the date is stored in <parameter>buffer</parameter>. If <parameter>show_zero_seconds</parameter> is
<link linkend="FALSE--CAPS"><type>FALSE</type></link>, then if the time has zero seconds only the hour and minute
of the time are stored in <parameter>buffer</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>date_tm</parameter>&#160;:</term>
<listitem><simpara> The <link linkend="tm"><type>tm</type></link> to convert to a string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>use_24_hour_format</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="gboolean"><type>gboolean</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>show_midnight</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="gboolean"><type>gboolean</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>show_zero_seconds</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="gboolean"><type>gboolean</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buffer</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="char"><type>char</type></link> buffer to store the time string in.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buffer_size</parameter>&#160;:</term>
<listitem><simpara> The length of <parameter>buffer</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-time-format-time" role="function">
<title>e_time_format_time ()</title>
<indexterm zone="e-time-format-time"><primary sortas="e_time_format_time">e_time_format_time</primary></indexterm><programlisting><link linkend="void">void</link>                e_time_format_time                  (<link linkend="struct-tm">struct tm</link> *date_tm,
                                                         <link linkend="gboolean">gboolean</link> use_24_hour_format,
                                                         <link linkend="gboolean">gboolean</link> show_zero_seconds,
                                                         <link linkend="char">char</link> *buffer,
                                                         <link linkend="int">int</link> buffer_size);</programlisting>
<para>
Creates a string representation of a time value in <parameter>date_tm</parameter> and
stores it in <parameter>buffer</parameter>. <parameter>buffer_size</parameter> should be at least 64.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>date_tm</parameter>&#160;:</term>
<listitem><simpara> The <link linkend="tm"><type>tm</type></link> to convert to a string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>use_24_hour_format</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="gboolean"><type>gboolean</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>show_zero_seconds</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="gboolean"><type>gboolean</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buffer</parameter>&#160;:</term>
<listitem><simpara> The <link linkend="char"><type>char</type></link> buffer to store the result in.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buffer_size</parameter>&#160;:</term>
<listitem><simpara> The length of <parameter>buffer</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-mktime-utc" role="function">
<title>e_mktime_utc ()</title>
<indexterm zone="e-mktime-utc"><primary sortas="e_mktime_utc">e_mktime_utc</primary></indexterm><programlisting><link linkend="time-t">time_t</link>              e_mktime_utc                        (<link linkend="struct-tm">struct tm</link> *tm);</programlisting>
<para>
Like mktime(3), but assumes UTC instead of local timezone.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tm</parameter>&#160;:</term>
<listitem><simpara> The <link linkend="tm"><type>tm</type></link> to convert to a calendar time representation.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The calendar time representation of <parameter>tm</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-localtime-with-offset" role="function">
<title>e_localtime_with_offset ()</title>
<indexterm zone="e-localtime-with-offset"><primary sortas="e_localtime_with_offset">e_localtime_with_offset</primary></indexterm><programlisting><link linkend="void">void</link>                e_localtime_with_offset             (<link linkend="time-t">time_t</link> tt,
                                                         <link linkend="struct-tm">struct tm</link> *tm,
                                                         <link linkend="int">int</link> *offset);</programlisting>
<para>
Converts the calendar time time representation <parameter>tt</parameter> to a broken-down
time representation, store in <parameter>tm</parameter>, and provides the offset in
seconds from UTC time, stored in <parameter>offset</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tt</parameter>&#160;:</term>
<listitem><simpara> The <link linkend="time-t"><type>time_t</type></link> to convert.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>tm</parameter>&#160;:</term>
<listitem><simpara> The <link linkend="tm"><type>tm</type></link> to store the result in.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>offset</parameter>&#160;:</term>
<listitem><simpara> The <link linkend="int"><type>int</type></link> to store the offset in.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-time-get-d-fmt-with-4digit-year" role="function">
<title>e_time_get_d_fmt_with_4digit_year ()</title>
<indexterm zone="e-time-get-d-fmt-with-4digit-year"><primary sortas="e_time_get_d_fmt_with_4digit_year">e_time_get_d_fmt_with_4digit_year</primary></indexterm><programlisting><link linkend="char">char</link> *              e_time_get_d_fmt_with_4digit_year   (void);</programlisting>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
