# HG changeset patch
# User Rob Hoes <rob.hoes@xxxxxxxxxx>
Add function to Date module to assert ISO 8601 datetime values are UTC

Adds ocamldoc for the whole Date module as well.

Signed-off-by: Rob Hoes <rob.hoes@xxxxxxxxxx>

diff -r 81dbe94e62c3 stdext/META.in
--- a/stdext/META.in
+++ b/stdext/META.in
@@ -1,5 +1,5 @@
 version = "@VERSION@"
 description = "Stdext - Common stdlib extensions"
-requires = "unix,uuid,bigarray,rpc-light.json"
+requires = "unix,str,uuid,bigarray,rpc-light.json"
 archive(byte) = "stdext.cma"
 archive(native) = "stdext.cmxa"
diff -r 81dbe94e62c3 stdext/date.ml
--- a/stdext/date.ml
+++ b/stdext/date.ml
@@ -15,7 +15,6 @@
 type iso8601 = string
 type rfc822 = string
 
-(* Convert calendar time, x, to tm in UTC *)
 let of_float x = 
   let time = Unix.gmtime x in
   Printf.sprintf "%04d%02d%02dT%02d:%02d:%02dZ"
@@ -65,4 +64,9 @@
 let to_string x = x
 let of_string x = x
 
+let assert_utc x =
+	let r = Str.regexp "^[0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]T[0-9][0-9]:[0-9][0-9]:[0-9][0-9]Z$" in
+	if not (Str.string_match r x 0) then
+		invalid_arg x
+
 let never = of_float 0.0
diff -r 81dbe94e62c3 stdext/date.mli
--- a/stdext/date.mli
+++ b/stdext/date.mli
@@ -11,13 +11,39 @@
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU Lesser General Public License for more details.
  *)
+(** Additional types and functions for dates *)
+
+(** {2 ISO 8601 Dates} *)
+
+(** An ISO-8601 date/time type. *)
 type iso8601
+
+(** Convert calendar time [x] (as returned by e.g. Unix.time), to time in UTC. *)
 val of_float : float -> iso8601
+
+(** Convert date/time to a float value: the number of seconds since 00:00:00 UTC, 1 Jan 1970. *)
 val to_float : iso8601 -> float
+
+(** Convert date/time to an ISO 8601 formatted string. *)
 val to_string : iso8601 -> string
+
+(** Convert ISO 8601 formatted string to a date/time value. *)
 val of_string : string -> iso8601
+
+(** Raises an Invalid_argument exception if the given date is not a UTC date.
+ *  A UTC date is an ISO 8601 strings that ends with the character 'Z'. *)
+val assert_utc : iso8601 -> unit
+
+(** Representation of the concept "never" (actually 00:00:00 UTC, 1 Jan 1970). *)
 val never: iso8601
 
+(** {2 RFC 822 Dates} *)
+
+(** An RFC 822 date/time type. *)
 type rfc822
+
+(** Convert calendar time [x] (as returned by e.g. Unix.time), to RFC 822. *)
 val rfc822_of_float : float -> rfc822
+
+(** Convert RFC 822 date/time to a formatted string. *)
 val rfc822_to_string : rfc822 -> string