(***********************************************************************)
(*                                                                     *)
(*                                 GALAX                               *)
(*                              XQuery Engine                          *)
(*                                                                     *)
(*  Copyright 2001-2007.                                               *)
(*  Distributed only by permission.                                    *)
(*                                                                     *)
(***********************************************************************)

(* $Id: dateTime.mli,v 1.24 2007/02/01 22:08:46 simeon Exp $ *)

(* Module DateTime
   Description:
   This modules implement internal support for the XML Schema
   primitive simple types related to date and time.
*)

(* types *)

(** Relative offset of the timezone to UTC *)
type _TZrel

(** Internal Representation of a timezone *)
type _timezone

(** xs:time datatype *)
type xs_time

(** xs:date datatypes *)
type xs_date

(** xs:dateTime datatype consisting of a date value and a time value *)
type xs_dateTime

(** xs:duration datatype consisting of a year,month,day,hour,minute, and second *)
type xs_duration

(** xs:gYearMonth datatype consisting of a year value and a month value *)
type xs_gYearMonth

(** xs:gYear datatype consisting of a year value *)
type xs_gYear

(** xs:gMonthDay datatype consisting of a month value and a day value *)
type xs_gMonthDay

(** xs:gDay datatype consisting of a day value *)
type xs_gDay

(** xs:gMonth datatype consisting of a month value *)
type xs_gMonth

(** xs:yearMonthDuration datatype *)
type xs_yearMonthDuration

(** xs:dayTimeDuration datatype *)
type xs_dayTimeDuration

(** string_of_ functions *)

(** Gives the string value of an xs_date
   @param date The date to be converted to a string 
   @return the string representation of a date *)
val string_of_date : xs_date -> string

val string_of_duration   : xs_duration   -> string
val string_of_gYearMonth : xs_gYearMonth -> string
val string_of_gYear      : xs_gYear      -> string
val string_of_gMonthDay  : xs_gMonthDay  -> string
val string_of_gDay       : xs_gDay       -> string
val string_of_gMonth     : xs_gMonth     -> string

(** Gives the string value of an xs_time 
   @return the string representation of a time *)
val string_of_time : xs_time -> string

(** Gives the string value of an xs_dateTime
   @return the string representation of a dateTime *)
val string_of_dateTime : xs_dateTime -> string

(** Gives the string representation of a yearMonthDuration 
   @return the string representation of a yearMonthDuration *)
val string_of_yearMonthDuration : xs_yearMonthDuration -> string
val canonical_of_yearMonthDuration : xs_yearMonthDuration -> string

(** Gives the string representation of a dayTimeDuration 
   @return the string representation of a dayTimeDuration *)
val string_of_dayTimeDuration : xs_dayTimeDuration -> string
val canonical_of_dayTimeDuration : xs_dayTimeDuration -> string
 
(** Constructors for the date/time datatypes *)

(** Takes a year, month, day, and timezone as a duration and returns an xs_date datatype.
    @return an xs_date *)
val mkdate : (int option * int * int * xs_dayTimeDuration option) -> xs_date

(** Takes an hour, minute, second and timezone as a duration and returns an xs_time datatype.
   @return an xs_time *)
val mktime : (int * int * Decimal._decimal * xs_dayTimeDuration option) -> xs_time
(** Takes an hour, minute, second and timezone as a duration and returns an xs_time datatype.
   @return an xs_time and dayTimeDuration, if time rolls over into a day *)
val mktime_dtd : (int * int * Decimal._decimal * xs_dayTimeDuration option) -> (xs_dayTimeDuration * xs_time)

(** Takes a date, a time, and a timezone as a duration and returns an
    xs_dateTime @return an xs_dateTime *)
val mkdateTime   : (xs_date * xs_time * xs_dayTimeDuration option) -> xs_dateTime
val mkgYearMonth : (int * int * xs_dayTimeDuration option) -> xs_gYearMonth
val mkgYear      : (int * xs_dayTimeDuration option) -> xs_gYear
val mkgMonthDay  : (int * int * xs_dayTimeDuration option) -> xs_gMonthDay
val mkgDay       : (int * xs_dayTimeDuration option) -> xs_gDay
val mkgMonth     : (int * xs_dayTimeDuration option) -> xs_gMonth

(** Takes a number of years and a number of months and returns a
    yearMonthDuration @return an xs_yearMonthDuration *)
val mkyearMonthDuration : (int * int) -> xs_yearMonthDuration
val zero_yearMonthDuration : xs_yearMonthDuration

(** Takes a number of days, hours, minutes, and seconds and returns a
    dayTimeDuration @return an xs_dayTimeDuration *)
val mkdayTimeDuration : (int * int * int * Decimal._decimal) -> xs_dayTimeDuration
val zero_dayTimeDuration : xs_dayTimeDuration

val mkduration :
    bool -> xs_yearMonthDuration * xs_dayTimeDuration -> xs_duration

(** Operations
    Comparisons and Arithmetic operations *)

(** Compares two dates. The dayTimeDuration option is the timezone
    used if one of the dates does not contain a timezone.  @return -1
    if the first is earlier than the second, 1 if it is later, and 0
    if it is the same *)
val date_compare       : xs_dayTimeDuration option -> xs_date -> xs_date -> int 
val duration_compare   : xs_duration -> xs_duration -> int 
val gYearMonth_compare : xs_dayTimeDuration option -> xs_gYearMonth -> xs_gYearMonth -> int 
val gYear_compare      : xs_dayTimeDuration option -> xs_gYear -> xs_gYear -> int 
val gMonthDay_compare  : xs_dayTimeDuration option -> xs_gMonthDay -> xs_gMonthDay -> int 
val gDay_compare       : xs_dayTimeDuration option -> xs_gDay -> xs_gDay -> int
val gMonth_compare     : xs_dayTimeDuration option -> xs_gMonth -> xs_gMonth -> int 

(** Add a yearMonthDuration to a date yielding the new date
   @return The given duration added to the date *)
val add_yearMonthDuration_to_date :  xs_date -> xs_yearMonthDuration -> xs_date

(** @return The date resulting from adding the given duration to the date given *)
val add_dayTimeDuration_to_date : xs_date -> xs_dayTimeDuration -> xs_date

(** @return The yearMonthDuration representing the difference
   in time between the first date and the second date *)
val subtract_dates : xs_date -> xs_date -> xs_dayTimeDuration

(** @return The date resulting from subtracting the given yearMonthDuration from the given date *)
val subtract_yearMonthDuration_from_date : xs_date -> xs_yearMonthDuration -> xs_date

(** @return The date resulting from subtracting the given dayTimeDuration from the given date *)
val subtract_dayTimeDuration_from_date : xs_date -> xs_dayTimeDuration -> xs_date

(** @return 1 if the first time is later than the second, -1 if it is earlier, and 0 if they are the same
   The dayTimeDuration option is the timezone used if one of the times has a timezone and one
   does not *)
val time_compare : xs_dayTimeDuration option -> xs_time -> xs_time -> int

(** @return The time resulting from adding the given duration to the given time *)
val add_dayTimeDuration_to_time : xs_time -> xs_dayTimeDuration -> xs_time

(** @return The duration of time between the first time and the second time *)
val subtract_dateTimes : xs_dateTime -> xs_dateTime -> xs_dayTimeDuration

(** @return The duration of time between the first time and the second time *)
val subtract_dates : xs_date -> xs_date -> xs_dayTimeDuration

(** @return The duration of time between the first time and the second time *)
val subtract_times : xs_time -> xs_time -> xs_dayTimeDuration

(** @return The time resulting from subtracting the dayTimeDuration from the given time *)
val subtract_dayTimeDuration_from_time : xs_time -> xs_dayTimeDuration -> xs_time

(** @return 1 if the first dateTime occurs after the second, -1 if it occurs before and 0 otherwise.
   The dayTimeDuration option is the timezone used if one of the dateTimes is given
   with a timezone and the other is not *)
val dateTime_compare : xs_dayTimeDuration option -> xs_dateTime -> xs_dateTime -> int

(** @return The dateTime resulting from adding the given duration to the given dateTime *)
val add_yearMonthDuration_to_dateTime : xs_dateTime -> xs_yearMonthDuration -> xs_dateTime
val add_yearMonthDuration_to_dateTime2 : xs_yearMonthDuration -> xs_dateTime -> xs_dateTime

(** @return The dateTime resulting from adding the given duration to the given dateTime *)
val add_dayTimeDuration_to_dateTime : xs_dateTime -> xs_dayTimeDuration -> xs_dateTime

(** @return The duration of time in days, hours, minutes... between the first dateTime and the second dateTime *)
val subtract_dateTimes : xs_dateTime -> xs_dateTime -> xs_dayTimeDuration

(** @return The dateTime resulting from subtracting the given duration from the given dateTime *)
val subtract_yearMonthDuration_from_dateTime : xs_dateTime -> xs_yearMonthDuration -> xs_dateTime

(** @return The dateTime resulting from subtracting the given duration from the given dateTime *)
val subtract_dayTimeDuration_from_dateTime : xs_dateTime -> xs_dayTimeDuration -> xs_dateTime

val dateTime_from_date_and_time : xs_date -> xs_time -> xs_dateTime

(** @return 1 if the first duration is longer than the second, -1 if it is less, 0 if they are the same *)
val yearMonthDuration_compare : xs_yearMonthDuration -> xs_yearMonthDuration -> int

(** @return The duration of time resultant from adding the first duration to the second *)
val add_yearMonthDurations : xs_yearMonthDuration -> xs_yearMonthDuration -> xs_yearMonthDuration

(** @return The duration of time resultant from subtracting the second duration from the first *)
val subtract_yearMonthDurations : xs_yearMonthDuration -> xs_yearMonthDuration -> xs_yearMonthDuration

(** @return The resultant duration from multiplying the given duration by the given floating point number *)
val multiply_yearMonthDuration : xs_yearMonthDuration -> float -> xs_yearMonthDuration
val multiply_yearMonthDuration2 : float -> xs_yearMonthDuration -> xs_yearMonthDuration

(** @return The resultant duration from dividing the given duration by the given floating point number *)
val divide_yearMonthDuration : xs_yearMonthDuration -> float -> xs_yearMonthDuration

(** @return The decimal representing the results of dividing one yearMonthDuration by a second
   yearMonthDuration *)
val divide_yearMonthDuration_by_yearMonthDuration : xs_yearMonthDuration -> xs_yearMonthDuration -> Decimal._decimal

(** @return 1 if the first duration is longer than the second, -1 if it is less, and 0 if they are the same *)
val dayTimeDuration_compare : xs_dayTimeDuration -> xs_dayTimeDuration -> int

(** @return The duration of time resultant from adding the first duration to the second *)
val add_dayTimeDurations : xs_dayTimeDuration -> xs_dayTimeDuration -> xs_dayTimeDuration

(** @return The duration of time resultant from subtracting the second duration from the first *)
val subtract_dayTimeDurations : xs_dayTimeDuration -> xs_dayTimeDuration -> xs_dayTimeDuration

(** @return The duration of time resultant from multiplying the given duration by the given floating point number *)
val multiply_dayTimeDuration : xs_dayTimeDuration -> float -> xs_dayTimeDuration
val multiply_dayTimeDuration2 : float -> xs_dayTimeDuration -> xs_dayTimeDuration

(** @return The duration of time resultant from dividing the given duration by the given floating point number *)
val divide_dayTimeDuration : xs_dayTimeDuration -> float -> xs_dayTimeDuration

(** @return The decimal resulting from the division of two dayTimeDurations *)
val divide_dayTimeDuration_by_dayTimeDuration : xs_dayTimeDuration -> xs_dayTimeDuration -> Decimal._decimal

(** Extraction functions on dates, times, and durations *)

(** @return The years in the duration *)
val years_from_duration : xs_yearMonthDuration -> int

(** @return The months in the duration *)
val months_from_duration : xs_yearMonthDuration -> int

(** @return The days in the duration *)
val days_from_duration : xs_dayTimeDuration -> int

(** @return The hours in the