Initial Header for Islamic Date functions

[Ali Abdin <aliabdin aucegypt edu>]

Here is an initial header file for the Islamic Date functions.

I would appreciate it if people read it and provide feedback (especially for
the FIXME's!)

I've noticed something that doesn't make sense though. It doesn't make sense
to map any days (Sun/Mon/Tue/Wed/etc.) to Islamic calendar. They are just
identical to the Gregorian days. My option would be to take out the "days" from
Islamic calendar support (i.e. you can just get a GDate from GIslamicDate and
then do day manipulation functions based on the that). Or I can just handle it
myself (so as to remain consistent with the Gregorian implementation).

Regards,
Ali

/* GLIB - Library of useful routines for C programming
 *
 * Copyright (C) 2000 Ali Abdin <aliabdin aucegypt edu>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
 */

#ifndef __G_ISLAMIC_DATE_H
#define __G_ISLAMIC_DATE_H

G_BEGIN_DECLS

/* GIslamicDate
 *
 * This is basically an implmentation for the Islamic lunar calendar. It
 * is a deterministic calendar which means it can not ever be 100%
 * accurate. This implementation is based on the GNU Emacs lisp implementation
 * of the Islamic lunar calendar. It is discussed in a paper found at this
 * website: http://emr.cs.uiuc.edu/~reingold/calendars.shtml
 */

typedef guint16 GIslamicDateYear;
typedef guint8  GIslamicDateDay;
typedef struct _GIslamicDate GIslamicDate;
/* To recognize struct tm withotu including time.h */
struct tm;

typedef enum
{
  G_ISLAMIC_DATE_BAD_WEEKDAY = 0,
  G_ISLAMIC_DATE_AHD 	     = 1,
  G_ISLAMIC_DATE_ETHNEEN     = 2,
  G_ISLAMIC_DATE_THALATH     = 3,
  G_ISLAMIC_DATE_ARBAA 	     = 4,
  G_ISLAMIC_DATE_KHAMIS      = 5,
  G_ISLAMIC_DATE_GOMAA       = 6,
  G_ISLAMIC_DATE_SABT        = 7
} GIslamicDateWeekday;
typedef enum
{
  G_ISLAMIC_DATE_BAD_MONTH    = 0,
  G_ISLAMIC_DATE_MUHARRAM     = 1,
  G_ISLAMIC_DATE_SAFAR	      = 2,
  G_ISLAMIC_DATE_RABI1	      = 3,
  G_ISLAMIC_DATE_RABI2	      = 4,
  G_ISLAMIC_DATE_JUMADA1      = 5,
  G_ISLAMIC_DATE_JUMADA2      = 6,
  G_ISLAMIC_DATE_RAJAB	      = 7,
  G_ISLAMIC_DATE_SHAABAN      = 8,
  G_ISLAMIC_DATE_RAMADAN      = 9,
  G_ISLAMIC_DATE_SHAWAL	      = 10,
  G_ISLAMIC_DATE_DHU-AL-QHADA = 11,
  G_ISLAMIC_DATE_DHU-AL-Hijja = 12
} GIslamicDateMonth;
typedef enum
{
  G_ISLAMIC_RAMADAN_EARLY     = 0, /* Ramadan was one day early */
  G_ISLAMIC_RAMADAN_NORMAL    = 1, /* Default: Ramadan is on schedule */
  G_ISLAMIC_RAMADAN_LATE      = 2  /* Ramadan is one day late	*/
} GIslamicRamadanSchedule;

#define G_ISLAMIC_DATE_BAD_DAY 0U
#define G_ISLAMIC_DATE_BAD_YEAR 0U

/* Don't access the struct directly */
struct _GIslamicDate
{
  GIslamicRamadanSchedule ramadan_sched;
  
  guint day    	: 6;
  guint month	: 4;
  guint year   	: 16;
};

GIslamicDate*		g_islamic_date_new		(void);
/* dmy is in Islamic month/day/year (not gregorian!) */
GIslamicDate*		g_islamic_date_new_dmy		(GIslamicDateDay     day,
							 GIslamicDateMonth   month,
							 GIslamicDateYear    year);
/* New GIslamicDate from an existing GDate */
GIslamicDate*		g_islamic_date_new_gdate	(GDate 		     *date);
/* FIXME: Should we have a g_islamic_date_new_julian ? */
void 			g_islamic_date_free		(GIslamicDate 	     *date);

/* Always check for an operation that could fail */
gboolean		g_islamic_date_valid		(GIslamicDate 	     *date);
gboolean		g_islamic_date_valid_day	(GIslamicDateDay     day) G_GNUC_CONST;
gboolean		g_islamic_date_valid_month	(GIslamicDateMonth   month) G_GNUC_CONST;
gboolean		g_islamic_date_valid_year	(GIslamicDateYear    year) G_GNUC_CONST;
gboolean		g_islamic_date_valid_weekday	(GIslamicDateWeekday wekday) G_GNUC_CONST;
/* Islamic dmy - not gregorian */
gboolean		g_islamic_date_valid_dmy	(GIslamicDateDay     day,
							 GIslamicDateMonth   month,
							 GIslamicDateYear    year) G_GNUC_CONST;

GIslamicDateWeekday 	g_islamic_date_weekday		(GIslamicDate	     *date);
GIslamicDateMonth	g_islamic_date_month		(GIslamicDate	     *date);
GIslamicDateYear	g_islamic_date_year		(GIslamicDate	     *date);
GIslamicDateDay		g_islamic_date_day		(GIslamicDate 	     *date);
/* FIXME: do we need a day of year function? */

/* If you create a static date struct you need to clear it to get it
 * in a sane state before use. You can clear a whole array at
 * once with the ndates argument.
 */
void			g_islamic_date_clear		(GIslamicDate	     *date,
                                           		 guint        	     n_dates);

/* FIXME: Parse function from string to date - (should we handle arabic
 * chars? what about english words (as demonstrated above)?)
 */

void			g_islamic_date_set_month	(GIslamicDate	     *date,
							 GIslamicDateMonth   month);
void			g_islamic_date_set_day		(GIslamicDate	     *date,
							 GIslamicDateDay     day);
void			g_islamic_date_set_year		(GIslamicDate	     *date,
							 GIslamicDateYear    year);
void			g_islamic_date_dmy		(GIslamicDate	     *date,
							 GIslamicDateDay     day,
							 GIslamicDateMonnth  month,
							 GIslamicDateYear    year);
							 		
/* FIXME: Possibly add first_of_month/last_of_month functions */
void			g_islamic_date_add_days		(GIslamicDate	     *date,
							 guint		     n_days);
void			g_islamic_date_subtract_days	(GIslamicDate	     *date,
							 guint		     n_days);

/* If you add/sub months while day > 29, the day might change */
void			g_islamic_date_add_months	(GIslamicDate	     *date,
							 guint		     n_months);
void			g_islamic_date_subtract_months	(GIslamicDate	     *date,
							 guint		     n_months);

/* Moving years will reset the ramadan setting to NORMAL and it
 * Dhu al-Hijja may be either 29 or 30 days (leap year calculation)
 */
void			g_islamic_date_add_years	(GIslamicDate	     *date,
							 guint		     n_years);
void			g_islamic_date_subtract_years	(GIslamicDate	     *date,
							 guint		     n_years);
gboolean		g_islamic_date_is_leap_year	(GIslamicDateYear    year) G_GNUC_CONST;
/* If the year == current year then take ramadan setting into account */
guint8			g_islamic_date_days_in_month	(GIslamicDateMonth   month,
							 GIslamicDateYear    year) G_GNUC_CONST;
/* q-sort friendly with a cast? */
gint			g_islamic_date_compare		(GIslamicDate 	     *lhs,
							 GIslamicDate	     *rhs);

void			g_islamic_date_to_struct_tm	(GIslamicDate 	     *date,
							 struct tm	     *tm);
/* FIXME: Should this be g_date_new_islamic (like g_date_new_julians and
 * g_islamic_date_new_gdate)?
 */
void			g_islamic_date_to_gdate		(GIslamicDate	     *date,
							 GDate		     *norm_gdate);
/* FIXME: Should we add conversion functions to/from time_t ? */

/* FIXME: Should we add a function that returns an i18n'd dup'd string based on
 * the GIslamicDateMonth
 */

G_END_DECLS

#endif /* __G_ISLAMIC_DATE_H__ */