<refentry id="lunar-lunardate">
<refmeta>
<refentrytitle role="top_of_page" id="lunar-lunardate.top_of_page">LunarDate</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>LUNAR Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>LunarDate</refname>
<refpurpose>Translate the date between solar and chinese lunar.</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv id="lunar-lunardate.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;lunar/lunar.h&gt;

typedef             <link linkend="GDateHour">GDateHour</link>;
                    <link linkend="LunarDate">LunarDate</link>;
#define             <link linkend="LUNAR-DATE-ERROR:CAPS">LUNAR_DATE_ERROR</link>
enum                <link linkend="LunarDateError">LunarDateError</link>;
<link linkend="GQuark">GQuark</link>              <link linkend="lunar-date-error-quark">lunar_date_error_quark</link>              (void);
<link linkend="LunarDate">LunarDate</link>*          <link linkend="lunar-date-new">lunar_date_new</link>                      (void);
<link linkend="void">void</link>                <link linkend="lunar-date-set-solar-date">lunar_date_set_solar_date</link>           (<link linkend="LunarDate">LunarDate</link> *date,
                                                         <link linkend="GDateYear">GDateYear</link> year,
                                                         <link linkend="GDateMonth">GDateMonth</link> month,
                                                         <link linkend="GDateDay">GDateDay</link> day,
                                                         <link linkend="GDateHour">GDateHour</link> hour,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="void">void</link>                <link linkend="lunar-date-set-lunar-date">lunar_date_set_lunar_date</link>           (<link linkend="LunarDate">LunarDate</link> *date,
                                                         <link linkend="GDateYear">GDateYear</link> year,
                                                         <link linkend="GDateMonth">GDateMonth</link> month,
                                                         <link linkend="GDateDay">GDateDay</link> day,
                                                         <link linkend="GDateHour">GDateHour</link> hour,
                                                         <link linkend="gboolean">gboolean</link> isleap,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="gchar">gchar</link>*              <link linkend="lunar-date-get-jieri">lunar_date_get_jieri</link>                (<link linkend="LunarDate">LunarDate</link> *date);
<link linkend="gchar">gchar</link>*              <link linkend="lunar-date-strftime">lunar_date_strftime</link>                 (<link linkend="LunarDate">LunarDate</link> *date,
                                                         const <link linkend="char">char</link> *format);
<link linkend="void">void</link>                <link linkend="lunar-date-free">lunar_date_free</link>                     (<link linkend="LunarDate">LunarDate</link> *date);
</synopsis>
</refsynopsisdiv>









<refsect1 id="lunar-lunardate.description" role="desc">
<title role="desc.title">Description</title>
<para>

</para>
</refsect1>

<refsect1 id="lunar-lunardate.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GDateHour" role="typedef">
<title>GDateHour</title>
<indexterm zone="GDateHour"><primary>GDateHour</primary></indexterm><programlisting>typedef guint8  GDateHour;
</programlisting>
<para>

</para></refsect2>
<refsect2 id="LunarDate" role="struct">
<title>LunarDate</title>
<indexterm zone="LunarDate"><primary>LunarDate</primary></indexterm><programlisting>typedef struct _LunarDate LunarDate;</programlisting>
<para>
The LUNARDate struct contains only private fields and should not be used directly.
</para></refsect2>
<refsect2 id="LUNAR-DATE-ERROR:CAPS" role="macro">
<title>LUNAR_DATE_ERROR</title>
<indexterm zone="LUNAR-DATE-ERROR:CAPS"><primary>LUNAR_DATE_ERROR</primary></indexterm><programlisting>#define LUNAR_DATE_ERROR	(lunar_date_error_quark ())
</programlisting>
<para>

</para></refsect2>
<refsect2 id="LunarDateError" role="enum">
<title>enum LunarDateError</title>
<indexterm zone="LunarDateError"><primary>LunarDateError</primary></indexterm><programlisting>typedef enum
{
    LUNAR_DATE_ERROR_INTERNAL,
    LUNAR_DATE_ERROR_DAY,
    LUNAR_DATE_ERROR_YEAR,
    LUNAR_DATE_ERROR_LEAP
} LunarDateError;
</programlisting>
<para>

</para><variablelist role="enum">
<varlistentry id="LUNAR-DATE-ERROR-INTERNAL:CAPS" role="constant">
<term><literal>LUNAR_DATE_ERROR_INTERNAL</literal></term>
<listitem><simpara>a internal error was found.
</simpara></listitem>
</varlistentry>
<varlistentry id="LUNAR-DATE-ERROR-DAY:CAPS" role="constant">
<term><literal>LUNAR_DATE_ERROR_DAY</literal></term>
<listitem><simpara>the day is out of the range.
</simpara></listitem>
</varlistentry>
<varlistentry id="LUNAR-DATE-ERROR-YEAR:CAPS" role="constant">
<term><literal>LUNAR_DATE_ERROR_YEAR</literal></term>
<listitem><simpara>the year is out of the range.
</simpara></listitem>
</varlistentry>
<varlistentry id="LUNAR-DATE-ERROR-LEAP:CAPS" role="constant">
<term><literal>LUNAR_DATE_ERROR_LEAP</literal></term>
<listitem><simpara>the <parameter>isleap</parameter> parameter of <link linkend="lunar-date-set-lunar-date"><function>lunar_date_set_lunar_date()</function></link> is not corret.

</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="lunar-date-error-quark" role="function">
<title>lunar_date_error_quark ()</title>
<indexterm zone="lunar-date-error-quark"><primary>lunar_date_error_quark</primary></indexterm><programlisting><link linkend="GQuark">GQuark</link>              lunar_date_error_quark              (void);</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="lunar-date-new" role="function">
<title>lunar_date_new ()</title>
<indexterm zone="lunar-date-new"><primary>lunar_date_new</primary></indexterm><programlisting><link linkend="LunarDate">LunarDate</link>*          lunar_date_new                      (void);</programlisting>
<para>
Allocates a <link linkend="LunarDate"><type>LunarDate</type></link> and initializes it. Free the return value with <link linkend="lunar-date-free"><function>lunar_date_free()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly-allocated <link linkend="LunarDate"><type>LunarDate</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="lunar-date-set-solar-date" role="function">
<title>lunar_date_set_solar_date ()</title>
<indexterm zone="lunar-date-set-solar-date"><primary>lunar_date_set_solar_date</primary></indexterm><programlisting><link linkend="void">void</link>                lunar_date_set_solar_date           (<link linkend="LunarDate">LunarDate</link> *date,
                                                         <link linkend="GDateYear">GDateYear</link> year,
                                                         <link linkend="GDateMonth">GDateMonth</link> month,
                                                         <link linkend="GDateDay">GDateDay</link> day,
                                                         <link linkend="GDateHour">GDateHour</link> hour,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Sets the solar year, month, day and the hour for a <link linkend="LunarDate"><type>LunarDate</type></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>date</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="LunarDate"><type>LunarDate</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>year</parameter>&nbsp;:</term>
<listitem><simpara> year to set.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>month</parameter>&nbsp;:</term>
<listitem><simpara> month to set.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>day</parameter>&nbsp;:</term>
<listitem><simpara> day to set.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>hour</parameter>&nbsp;:</term>
<listitem><simpara> hour to set.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
<listitem><simpara> location to store the error occuring, or NULL to ignore errors.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="lunar-date-set-lunar-date" role="function">
<title>lunar_date_set_lunar_date ()</title>
<indexterm zone="lunar-date-set-lunar-date"><primary>lunar_date_set_lunar_date</primary></indexterm><programlisting><link linkend="void">void</link>                lunar_date_set_lunar_date           (<link linkend="LunarDate">LunarDate</link> *date,
                                                         <link linkend="GDateYear">GDateYear</link> year,
                                                         <link linkend="GDateMonth">GDateMonth</link> month,
                                                         <link linkend="GDateDay">GDateDay</link> day,
                                                         <link linkend="GDateHour">GDateHour</link> hour,
                                                         <link linkend="gboolean">gboolean</link> isleap,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Sets the lunar year, month, day and the hour for a <link linkend="LunarDate"><type>LunarDate</type></link>. If the month is a leap month, you should set the isleap to TRUE.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>date</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="LunarDate"><type>LunarDate</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>year</parameter>&nbsp;:</term>
<listitem><simpara> year to set.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>month</parameter>&nbsp;:</term>
<listitem><simpara> month to set.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>day</parameter>&nbsp;:</term>
<listitem><simpara> day to set.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>hour</parameter>&nbsp;:</term>
<listitem><simpara> hour to set.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>isleap</parameter>&nbsp;:</term>
<listitem><simpara> indicate whether the month is a leap month.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
<listitem><simpara> location to store the error occuring, or <link linkend="NULL:CAPS"><type>NULL</type></link> to ignore errors.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="lunar-date-get-jieri" role="function">
<title>lunar_date_get_jieri ()</title>
<indexterm zone="lunar-date-get-jieri"><primary>lunar_date_get_jieri</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              lunar_date_get_jieri                (<link linkend="LunarDate">LunarDate</link> *date);</programlisting>
<para>
Returns the holiday of the date. The date must be valid.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>date</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="LunarDate"><type>LunarDate</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>  a newly-allocated holiday string of the date.
This can be changed in $(datadir)/liblunar/holiday.dat file.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="lunar-date-strftime" role="function">
<title>lunar_date_strftime ()</title>
<indexterm zone="lunar-date-strftime"><primary>lunar_date_strftime</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              lunar_date_strftime                 (<link linkend="LunarDate">LunarDate</link> *date,
                                                         const <link linkend="char">char</link> *format);</programlisting>
<para>
使用给定的格式来输出字符串。类似于strftime的用法。可使用的格式及输出如下：
</para>
<para>
%(YEAR)年%(MONTH)月%(DAY)日      公历：大写->二OO八年一月二十一日
</para>
<para>
%(year)年%(month)月%(day)日      公历：小写->2008年1月21日
</para>
<para>
%(NIAN)年%(YUE)月%(RI)日%(SHI)时 阴历：大写->丁亥年腊月十四日
</para>
<para>
%(nian)年%(yue)月%(ri)日%(shi)时 阴历：小写->2007年12月14日
</para>
<para>
%(Y60)年%(M60)月%(D60)日%(H60)时 干支：大写->丁亥年癸丑月庚申日
</para>
<para>
%(y60)年%(m60)月%(d60)日%(h60)时 干支：小写 not use
</para>
<para>
%(Y8)年%(M8)月%(D8)日%(H8)时     八字：大写->丁亥年癸丑月庚申日
</para>
<para>
%(y8)年%(m8)月%(d8)日%(h8)时     八字：小写 not use
</para>
<para>
%(shengxiao)                     生肖：猪
%(jieri)                         节日(节日、纪念日、节气等)：立春
</para>
<para>
使用%(jieri)时，如果此日没有节日或节气，那么将为空。
节日可以自定义，只要按照格式修改$(prefix)/share/liblunar/hodiday.dat即可。</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>date</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="LunarDate"><type>LunarDate</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
<listitem><simpara> specify the output format. this
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly-allocated output string, nul-terminated
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="lunar-date-free" role="function">
<title>lunar_date_free ()</title>
<indexterm zone="lunar-date-free"><primary>lunar_date_free</primary></indexterm><programlisting><link linkend="void">void</link>                lunar_date_free                     (<link linkend="LunarDate">LunarDate</link> *date);</programlisting>
<para>
Frees a <link linkend="LunarDate"><type>LunarDate</type></link> returned from <link linkend="lunar-date-new"><function>lunar_date_new()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>date</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="LunarDate"><type>LunarDate</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
