Document DateTime constructors

Author: moritz

lib/Type/DateTime.pod

@@ -0,0 +1,66 @@
+=begin pod
+
+=TITLE class DateTime
+
+=SUBTITLE A date and time object
+
+    class DateTime does Dateish { ... }
+
+For handling points in civil time, a C<DateTime> object stores year, month,
+day, hour, minute (all L<Int|/type/Int>), second (potentially fractional) and
+a time zone.
+
+It provides methods for calculating with date and time.
+
+C<DateTime> methods are immutable; if you are tempted to modify one, create a
+modified copy instead.
+
+Time zones are handled as L<Integers|/type/Int> in B<seconds> offset from UTC.
+
+=head1 Methods
+
+=head2 method new
+
+    multi method new(Int :$year!, Int :$month, Int :$day,
+                     Int :$hour, Int :$minute, :$second
+                     :$timezone, :&formatter)
+    multi method new(Date :$date!,
+                     Int :$hour, Int :$minute, :$second
+                     :$timezone=0, :&formatter)
+    multi method new(Instant:D $i,  :$timezone=0, :&formatter)
+    multi method new(Int:D $posix,  :$timezone=0, :&formatter)
+    multi method new(Str:D $format, :$timezone=0, :&formatter)
+
+Creates a new C<DateTime> object. One option for creating a new DatTime object
+is from the components (year, month, day, hour, ...) separately. Another is to
+pass a L<Date|/type/Date> object for the date component, and specify the time
+component-wise. Yet another is to obtain the time from an
+L<Intstant|/type/Instant>, and only suplly the time zone and formatter. Or
+instead of an Instant you can supply an L<Int|/type/Int> as a UNIX timestamp,
+or a C<Str|/type/Str> formatted as C<yyyy-mm-ddThh:mm::ssZ> or
+C<yyyy-mm-ddThh:mm:ss+0100> (ISO 8601 timestamp notation).
+
+An invalid input string throws and exception of type
+L<X::Temporal::InvalidFormat>. If you supply a string that includes a time
+zone and supply the C<timezone> named argument, and exception of type
+L<X::DateTime:TimezoneClash> is thrown.
+
+=head2 method now
+
+    method now(:$timezone=*$TZ, &formatter) returns DateTime:D
+
+Creates a new C<DateTime> object from the current system time, optionally with
+a different timezone than the default attached.
+
+=head2 method clone
+
+    method clone(:$year, :$month, :$day, :$hour, :$minute, :$second,
+                 :$timezone, :&formatter)
+
+Creates a new C<DateTime> object based on the invocant, but with the given
+arguments overriding the values from the invocant.
+
+    say DateTime.new('2015-12-24T12:23:00Z').clone(hour => 0);
+        # 2015-12-24T00:23:00Z
+
+=end pod