calendar: change >gmt, >local-time to clone.

[factor.git] / basis / calendar / calendar-docs.factor

diff --git a/basis/calendar/calendar-docs.factor b/basis/calendar/calendar-docs.factor
index 74a06717f1638657bd5c469b6b8cdcb79998b726..e2fa95d4e76e3a0d4cd9d3e0b0d0caa106835a81 100644 (file)
--- a/basis/calendar/calendar-docs.factor
+++ b/basis/calendar/calendar-docs.factor
@@ -154,6 +154,20 @@ HELP: time+
     }
 } ;
 
+HELP: time-
+{ $values { "time1" { $or timestamp duration } } { "time2" { $or timestamp duration } } { "time3" { $or timestamp duration } } }
+{ $description "Subtracts two durations to produce a duration or subtracts a duration from a timestamp to produce a timestamp. The calculation takes timezones into account." }
+{ $examples
+    { $example "USING: calendar math.order prettyprint ;"
+               "10 months 2 months time- 8 months <=> ."
+               "+eq+"
+    }
+    { $example "USING: accessors calendar math.order prettyprint ;"
+               "2010 1 1 <date> 3 days time- day>> ."
+               "29"
+    }
+} ;
+
 { time+ time- } related-words
 
 HELP: duration>years
@@ -247,43 +261,29 @@ HELP: duration>nanoseconds
 { duration>years duration>months duration>days duration>hours duration>minutes duration>seconds duration>milliseconds duration>microseconds duration>nanoseconds } related-words
 
 
-HELP: time-
-{ $values { "time1" { $or timestamp duration } } { "time2" { $or timestamp duration } } { "time3" { $or timestamp duration } } }
-{ $description "Subtracts two durations to produce a duration or subtracts a duration from a timestamp to produce a timestamp. The calculation takes timezones into account." }
-{ $examples
-    { $example "USING: calendar math.order prettyprint ;"
-               "10 months 2 months time- 8 months <=> ."
-               "+eq+"
-    }
-    { $example "USING: accessors calendar math.order prettyprint ;"
-               "2010 1 1 <date> 3 days time- day>> ."
-               "29"
-    }
-} ;
-
 HELP: convert-timezone
 { $values { "timestamp" timestamp } { "duration" duration } }
 { $description "Converts the " { $snippet "timestamp" } "'s " { $snippet "gmt-offset" } " to the GMT offset represented by the " { $snippet "duration" } "." }
 { $examples
     { $example "USING: accessors calendar prettyprint ;"
-               "now >gmt noon -5 hours convert-timezone gmt-offset>> hour>> ."
+               "now-gmt noon instant -5 >>hour convert-timezone gmt-offset>> hour>> ."
                "-5"
     }
 } ;
 
 HELP: >local-time
-{ $values { "timestamp" timestamp } }
-{ $description "Converts the " { $snippet "timestamp" } " to the timezone of your computer." }
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
+{ $description "Converts the " { $snippet "timestamp" } " to the timezone of your computer, returning a new " { $link timestamp } " instance." }
 { $examples
     { $example "USING: accessors calendar kernel prettyprint ;"
-               "now dup clone >gmt >local-time [ gmt-offset>> ] same? ."
+               "now now-gmt >local-time [ gmt-offset>> ] same? ."
                "t"
     }
 } ;
 
 HELP: >gmt
-{ $values { "timestamp" timestamp } }
-{ $description "Converts the " { $snippet "timestamp" } " to the GMT timezone." }
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
+{ $description "Converts the " { $snippet "timestamp" } " to the GMT timezone, returning a new " { $link timestamp } " instance." }
 { $examples
     { $example "USING: accessors calendar kernel prettyprint ;"
                "now >gmt gmt-offset>> hour>> ."
@@ -301,11 +301,11 @@ HELP: gmt
 { $description "Set the time zone to GMT." }
 { $notes "The time is not converted, if you want that then call " { $link >gmt } "." } ;
 
-{ local-time >local-time gmt >gmt convert-timezone } related-words
+{ local-time >local-time convert-local-time gmt >gmt convert-gmt utc >utc convert-utc convert-timezone } related-words
 
 HELP: duration*
 { $values { "obj1" object } { "obj2" object } { "obj3" object } }
-{ $description "Multiplies each time slot of a duration by a number and make a new duration from the result. Used in the implementation of " { $link before } "." } ;
+{ $description "Multiplies each time slot of a timestamp or duration by a number and make a new duration from the result. Used in the implementation of " { $link before } "." } ;
 
 HELP: before
 { $values { "duration" duration } { "-duration" duration } }
@@ -331,6 +331,12 @@ HELP: micros>timestamp
     }
 } ;
 
+HELP: now-gmt
+{ $values { "timestamp" timestamp } }
+{ $description "Returns the time right now, but in the GMT timezone." } ;
+
+{ now now-gmt } related-words
+
 HELP: now
 { $values { "timestamp" timestamp } }
 { $description "Returns the time right now in your computer's timezone." }
@@ -507,6 +513,7 @@ ARTICLE: "calendar" "Calendar"
 { $subsections
     >local-time
     >gmt
+    >utc
     convert-timezone
 }
 "Timestamps relative to each other:"