diff --git a/CHANGES.md b/CHANGES.md index 8e144c8..e74e7b9 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,3 +1,8 @@ +### unreleased + +- Add an optional timezone `tz` argument to the `Zoned_datetime.from_utc` + function and refine doc comments. ([voodoos](https://github.com/voodoos)) + ### v1.1.0 - Add `Duration.to_(seconds|minutes|hours)` ([gr-im](https://github.com/gr-im)) diff --git a/lib/zoned_datetime.ml b/lib/zoned_datetime.ml index ce9a89c..a8ba5ce 100644 --- a/lib/zoned_datetime.ml +++ b/lib/zoned_datetime.ml @@ -20,7 +20,7 @@ let from_local_datetime ?(tz = Timezone.utc) local = { tz; utc } ;; -let from_utc utc = { tz = Timezone.utc; utc } +let from_utc ?(tz = Timezone.utc) utc = { tz; utc } let from ?tz date time = time |> Datetime.from date |> from_local_datetime ?tz let from_date ?tz date = date |> Datetime.from_date |> from_local_datetime ?tz let epoch ?tz () = from_local_datetime ?tz Datetime.epoch diff --git a/lib/zoned_datetime.mli b/lib/zoned_datetime.mli index 617ee18..d0c47ce 100644 --- a/lib/zoned_datetime.mli +++ b/lib/zoned_datetime.mli @@ -27,17 +27,17 @@ type error = | Invalid_datetime of Datetime.error | Invalid_timezone of Timezone.error -(** An exception used for unsafe function. *) +(** An exception used by unsafe functions. *) exception Invalid_zoned_datetime of error (** {1 Building zoned datetime} *) -(** [from_local_datetime ?tz dt] attach a timezone to a regular +(** [from_local_datetime ?tz dt] attaches a timezone to a local {!type:Datetime.t}. The default Timezone [tz] is {!val:Timezone.utc}. *) val from_local_datetime : ?tz:Timezone.t -> Datetime.t -> t -(** [make ?tz ?at ~year ~month ~day ()] create and validate a zoned +(** [make ?tz ?at ~year ~month ~day ()] creates and validates a zoned datetime. The default Timezone [tz] is {!val:Timezone.utc}. See {!val:Datetime.make} *) @@ -50,8 +50,8 @@ val make -> unit -> (t, Datetime.error) result -(** [make' ?at ~year ~month ~day ()] create and validate a zoned - datetime. see {!val:make}. Take an integer rather than a +(** [make' ?at ~year ~month ~day ()] creates and validates a zoned + datetime. see {!val:make}. Takes an integer rather than a {!type:Month.t}. The default Timezone [tz] is {!val:Timezone.utc}. See {!val:Datetime.make'} *) @@ -64,9 +64,9 @@ val make' -> unit -> (t, Datetime.error) result -(** [make_exn ?at ~year ~month ~day ()] create and validate a datetime - like {!val:make} but raise [Invalid_datetime] if the validation - doesn't succeed. The default Timezone [tz] is {!val:Timezone.utc}. +(** [make_exn ?at ~year ~month ~day ()] creates and validates a datetime + like {!val:make} but raises [Invalid_datetime] if the validation + does not succeed. The default Timezone [tz] is {!val:Timezone.utc}. See {!val:Datetime.make_exn} *) val make_exn @@ -78,8 +78,8 @@ val make_exn -> unit -> t -(** [make_exn' ?at ~year ~month ~day ()] create and validate a zoned datetime, - like {!val:make'} but raise [Invalid_datetime] if the validation doesn't +(** [make_exn' ?at ~year ~month ~day ()] creates and validates a zoned datetime, + like {!val:make'} but raise [Invalid_datetime] if the validation does not succeed. The default Timezone [tz] is {!val:Timezone.utc}. See {!val:Datetime.make_exn'} *) @@ -92,39 +92,39 @@ val make_exn' -> unit -> t -(** [from_string s] try to read a date from a string (using the format +(** [from_string s] tries to read a date from a string (using the format [year-mon-dayThh:mm:ssTZ], according to RFC3339). *) val from_string : string -> (t, error) result -(** [from_string_exn s] try to read a date from a string (using the format +(** [from_string_exn s] tries to read a date from a string (using the format [year-mon-dayThh:mm:ssTZ], according to RFC3339) and raise and exception if it fails. *) val from_string_exn : string -> t -(** [from d t] creates a zoned datetime object for the given date, [d] and a - given time [t]. The default Timezone [tz] is {!val:Timezone.utc}. +(** [from d t] creates a zoned datetime object for the local date [d] and + time [t]. The default Timezone [tz] is {!val:Timezone.utc}. See {!val:Datetime.from} *) val from : ?tz:Timezone.t -> Date.t -> Time.t -> t -(** [from_date d] creates a zoned datetime object for the given date, [d], at +(** [from_date d] creates a zoned datetime object for the local date [d], at midnight. The default Timezone [tz] is {!val:Timezone.utc}. See {!val:Datetime.from_date} *) val from_date : ?tz:Timezone.t -> Date.t -> t -(** [from_duration d] converts a duration to a date. [0] is the - 1970-01-01 at 00:00:00. The default Timezone [tz] is +(** [from_duration d] converts a (local) duration to a date. [0] is the + date 1970-01-01 at 00:00:00. The default Timezone [tz] is {!val:Timezone.utc}. See {!val:Datetime.from_duration} *) val from_duration : ?tz:Timezone.t -> Duration.t -> t -(** [from_utc dt] creates a zoned datetime from an UTC datetime (does - not any conversion). *) -val from_utc : Datetime.t -> t +(** [from_utc ?tz dt] creates a zoned datetime from a UTC datetime. No + conversion is done. The default Timezone [tz] is {!val:Timezone.utc}. *) +val from_utc : ?tz:Timezone.t -> Datetime.t -> t -(** Returns the 1st January 1970 at midnight. The default Timezone [tz] is +(** Returns the 1st January 1970 at midnight in local time. The default Timezone [tz] is {!val:Timezone.utc}. See {!val:Datetime.epoch} *) @@ -135,10 +135,10 @@ val epoch : ?tz:Timezone.t -> unit -> t (** [timezone zdt] returns the attached timezone to the given [zdt]. *) val timezone : t -> Timezone.t -(** [on_utc f zdt] apply [f] on the datetime (in UTC) of [zdt]. *) +(** [on_utc f zdt] applies [f] on the datetime (in UTC) of [zdt]. *) val on_utc : (Datetime.t -> 'a) -> t -> 'a -(** [on_local f zdt] apply [f] on the local datetime of [zdt]. *) +(** [on_local f zdt] applies [f] on the local datetime of [zdt]. *) val on_local : (Datetime.t -> 'a) -> t -> 'a (** [map_utc f zdt] applies [f] to the underlying UTC datetime. @@ -177,75 +177,75 @@ val change_timezone : tz:Timezone.t -> t -> t (** {1 Operation on zoned datetimes} *) -(** [add duration zdt] compute a new date adding [duration] to the given +(** [add duration zdt] computes a new date adding [duration] to the given [zdt]. *) val add : Duration.t -> t -> t -(** [sub duration zdt] compute a new date substracting [duration] to the given +(** [sub duration zdt] computes a new date substracting [duration] to the given [zdt]. *) val sub : Duration.t -> t -> t -(** [add_seconds number_of_seconds zoned_datetime] add [number_of_seconds] to the +(** [add_seconds number_of_seconds zoned_datetime] adds [number_of_seconds] to the given [zoned_datetime]. *) val add_seconds : int -> t -> t -(** [sub_seconds number_of_seconds zoned_datetime] remove [number_of_seconds] to the +(** [sub_seconds number_of_seconds zoned_datetime] removes [number_of_seconds] to the given [zoned_datetime]. *) val sub_seconds : int -> t -> t -(** [add_minutes number_of_minutes zoned_datetime] add [number_of_minutes] to the +(** [add_minutes number_of_minutes zoned_datetime] adds [number_of_minutes] to the given [zoned_datetime]. *) val add_minutes : int -> t -> t -(** [sub_minutes number_of_minutes zoned_datetime] remove [number_of_minutes] to the +(** [sub_minutes number_of_minutes zoned_datetime] removes [number_of_minutes] to the given [zoned_datetime]. *) val sub_minutes : int -> t -> t -(** [add_hours number_of_hours zoned_datetime] add [number_of_hours] to the +(** [add_hours number_of_hours zoned_datetime] adds [number_of_hours] to the given [zoned_datetime]. *) val add_hours : int -> t -> t -(** [sub_hours number_of_hours zoned_datetime] remove [number_of_hours] to the +(** [sub_hours number_of_hours zoned_datetime] removes [number_of_hours] to the given [datime]. *) val sub_hours : int -> t -> t -(** [add_days number_of_days zoned_datetime] add [number_of_days] to the given +(** [add_days number_of_days zoned_datetime] adds [number_of_days] to the given [zoned_datetime]. *) val add_days : int -> t -> t -(** [sub_days number_of_days zoned_datetime] remove [number_of_days] to the +(** [sub_days number_of_days zoned_datetime] removes [number_of_days] to the given [zoned_datetime]. *) val sub_days : int -> t -> t -(** [add_weeks number_of_weeks zoned_datetime] add [number_of_weeks] to the +(** [add_weeks number_of_weeks zoned_datetime] adds [number_of_weeks] to the given [zoned_datetime] (a week is [7] days). *) val add_weeks : int -> t -> t -(** [sub_weeks number_of_weeks zoned_datetime] remove [number_of_weeks] to the +(** [sub_weeks number_of_weeks zoned_datetime] removes [number_of_weeks] to the given [zoned_datetime] (a week is [7] days). *) val sub_weeks : int -> t -> t -(** [add_months number_of_months zoned_datetime] add [number_of_months] to the +(** [add_months number_of_months zoned_datetime] adds [number_of_months] to the given [zoned_datetime]. *) val add_months : int -> t -> t -(** [add_months number_of_months zoned_datetime] remove [number_of_months] to +(** [add_months number_of_months zoned_datetime] removes [number_of_months] to the given [zoned_datetime]. *) val sub_months : int -> t -> t -(** [add_quarters number_of_quarters zoned_datetime] add [number_of_quarters] to the +(** [add_quarters number_of_quarters zoned_datetime] adds [number_of_quarters] to the given [zoned_datetime]. *) val add_quarters : int -> t -> t -(** [add_quarters number_of_quarters zoned_datetime] remove [number_of_quarters] to +(** [add_quarters number_of_quarters zoned_datetime] removes [number_of_quarters] to the given [zoned_datetime]. *) val sub_quarters : int -> t -> t -(** [add_years number_of_years zoned_datetime] add [number_of_years] to the +(** [add_years number_of_years zoned_datetime] adds [number_of_years] to the given [zoned_datetime]. *) val add_years : int -> t -> t -(** [sub_years number_of_years zoned_datetime] remove [number_of_years] to the +(** [sub_years number_of_years zoned_datetime] removes [number_of_years] to the given [zoned_datetime]. *) val sub_years : int -> t -> t @@ -350,18 +350,18 @@ val pred_year : t -> t datetime has the given time. *) val with_local_time : Time.t -> t -> t -(** [with_local_date date zoned_datetime] replace the [date] of the given +(** [with_local_date date zoned_datetime] replaces the [date] of the given [zoned_datetime]. This changes the underlying instant so that the resulting local datetime has the given time. *) val with_local_date : Date.t -> t -> t -(** [tomorrow zdt] get the next day of the given [zdt]. See +(** [tomorrow zdt] gets the next day of the given [zdt]. See {!val:succ_day}. *) val tomorrow : t -> t -(** [yesterday zdt] get the previous day of the given [zdt]. See +(** [yesterday zdt] gets the previous day of the given [zdt]. See {!val:pred_day}. *) val yesterday : t -> t