1 ! Copyright (C) 2008 Doug Coleman.
2 ! See http://factorcode.org/license.txt for BSD license.
3 USING: arrays kernel math strings help.markup help.syntax
8 { $description "A duration is a period of time years, months, days, hours, minutes, and seconds. All duration slots can store " { $link real } " numbers. Compare two durations with the " { $link <=> } " word." } ;
11 { $description "A timestamp is a date and a time with a timezone offset. Timestamp slots must store integers except for " { $snippet "seconds" } ", which stores reals, and " { $snippet "gmt-offset" } ", which stores a " { $link duration } ". Compare two durations with the " { $link <=> } " word." } ;
13 { timestamp duration } related-words
15 HELP: gmt-offset-duration
16 { $values { "duration" duration } }
17 { $description "Returns a " { $link duration } " object with the GMT offset returned by " { $link gmt-offset } "." } ;
20 { $values { "year" integer } { "month" integer } { "day" integer } { "timestamp" timestamp } }
21 { $description "Returns a timestamp object representing the start of the specified day in your current timezone." }
23 { $example "USING: accessors calendar prettyprint ;"
24 "2010 12 25 <date> instant >>gmt-offset ."
25 "T{ timestamp { year 2010 } { month 12 } { day 25 } }"
30 { $values { "value" object } }
31 { $description "Returns an array with the English names of all the months." }
32 { $warning "Do not use this array for looking up a month name directly. Use " { $link month-name } " instead." } ;
35 { $values { "obj" { $or integer timestamp } } { "string" string } }
36 { $description "Looks up the month name and returns it as a string. January has an index of 1 instead of zero." } ;
38 HELP: month-abbreviations
39 { $values { "value" array } }
40 { $description "Returns an array with the English abbreviated names of all the months." }
41 { $warning "Do not use this array for looking up a month name directly. Use " { $link month-abbreviation } " instead." } ;
43 HELP: month-abbreviation
44 { $values { "n" integer } { "string" string } }
45 { $description "Looks up the abbreviated month name and returns it as a string. January has an index of 1 instead of zero." } ;
48 { $values { "value" array } }
49 { $description "Returns an array with the English names of the days of the week." } ;
52 { $values { "obj" { $or integer timestamp } } { "string" string } }
53 { $description "Looks up the day name and returns it as a string." } ;
55 HELP: day-abbreviations2
56 { $values { "value" array } }
57 { $description "Returns an array with the abbreviated English names of the days of the week. This abbreviation is two characters long." } ;
59 HELP: day-abbreviation2
60 { $values { "n" integer } { "string" string } }
61 { $description "Looks up the abbreviated day name and returns it as a string. This abbreviation is two characters long." } ;
63 HELP: day-abbreviations3
64 { $values { "value" array } }
65 { $description "Returns an array with the abbreviated English names of the days of the week. This abbreviation is three characters long." } ;
67 HELP: day-abbreviation3
68 { $values { "n" integer } { "string" string } }
69 { $description "Looks up the abbreviated day name and returns it as a string. This abbreviation is three characters long." } ;
73 day-abbreviation2 day-abbreviations2
74 day-abbreviation3 day-abbreviations3
78 { $values { "value" ratio } }
79 { $description "The length of an average month averaged over 400 years. Used internally for adding an arbitrary real number of months to a timestamp." } ;
82 { $values { "value" integer } }
83 { $description "Returns the number of months in a year." } ;
86 { $values { "value" ratio } }
87 { $description "Returns the number of days in a year averaged over 400 years. Used internally for adding an arbitrary real number of days to a timestamp." } ;
90 { $values { "value" ratio } }
91 { $description "Returns the number of hours in a year averaged over 400 years. Used internally for adding an arbitrary real number of hours to a timestamp." } ;
93 HELP: minutes-per-year
94 { $values { "value" ratio } }
95 { $description "Returns the number of minutes in a year averaged over 400 years. Used internally for adding an arbitrary real number of minutes to a timestamp." } ;
97 HELP: seconds-per-year
98 { $values { "value" integer } }
99 { $description "Returns the number of seconds in a year averaged over 400 years. Used internally for adding an arbitrary real number of seconds to a timestamp." } ;
101 HELP: julian-day-number
102 { $values { "year" integer } { "month" integer } { "day" integer } { "n" integer } }
103 { $description "Calculates the Julian day number from a year, month, and day. The difference between two Julian day numbers is the number of days that have elapsed between the two corresponding dates." }
104 { $warning "Not valid before year -4800 BCE." } ;
106 HELP: julian-day-number>date
107 { $values { "n" integer } { "year" integer } { "month" integer } { "day" integer } }
108 { $description "Converts from a Julian day number back to a year, month, and day." } ;
109 { julian-day-number julian-day-number>date } related-words
112 { $values { "timestamp" timestamp } { "year" integer } { "month" integer } { "day" integer } }
113 { $description "Explodes a " { $snippet "timestamp" } " into its year, month, and day components." }
114 { $examples { $example "USING: arrays calendar prettyprint ;"
115 "2010 8 24 <date> >date< 3array ."
121 { $values { "timestamp" timestamp } { "hour" integer } { "minute" integer } { "second" integer } }
122 { $description "Explodes a " { $snippet "timestamp" } " into its hour, minute, and second components." }
123 { $examples { $example "USING: arrays calendar prettyprint ;"
124 "now noon >time< 3array ."
129 { >date< >time< } related-words
132 { $values { "duration" duration } }
133 { $description "Pushes a " { $snippet "duration" } " of zero seconds." } ;
136 { $values { "x" number } { "duration" duration } }
137 { $description "Creates a duration object with the specified number of years." } ;
140 { $values { "x" number } { "duration" duration } }
141 { $description "Creates a duration object with the specified number of months." } ;
144 { $values { "x" number } { "duration" duration } }
145 { $description "Creates a duration object with the specified number of days." } ;
148 { $values { "x" number } { "duration" duration } }
149 { $description "Creates a duration object with the specified number of weeks." } ;
152 { $values { "x" number } { "duration" duration } }
153 { $description "Creates a duration object with the specified number of hours." } ;
156 { $values { "x" number } { "duration" duration } }
157 { $description "Creates a duration object with the specified number of minutes." } ;
160 { $values { "x" number } { "duration" duration } }
161 { $description "Creates a duration object with the specified number of seconds." } ;
164 { $values { "x" number } { "duration" duration } }
165 { $description "Creates a duration object with the specified number of milliseconds." } ;
168 { $values { "x" number } { "duration" duration } }
169 { $description "Creates a duration object with the specified number of microseconds." } ;
172 { $values { "x" number } { "duration" duration } }
173 { $description "Creates a duration object with the specified number of nanoseconds." } ;
175 { years months days hours minutes seconds milliseconds microseconds nanoseconds } related-words
178 { $values { "obj" object } { "?" boolean } }
179 { $description "Returns " { $link t } " if the object represents a leap year." }
181 { $example "USING: calendar prettyprint ;"
185 { $example "USING: calendar prettyprint ;"
186 "2010 1 1 <date> leap-year? ."
192 { $values { "time1" "timestamp or duration" } { "time2" "timestamp or duration" } { "time3" "timestamp or duration" } }
193 { $description "Adds two durations to produce a duration or adds a timestamp and a duration to produce a timestamp. The calculation takes timezones into account." }
195 { $example "USING: calendar math.order prettyprint ;"
196 "10 months 2 months time+ 1 years <=> ."
199 { $example "USING: accessors calendar math.order prettyprint ;"
200 "2010 1 1 <date> 3 days time+ day>> ."
206 { $values { "duration" duration } { "x" number } }
207 { $description "Calculates the length of a duration in years." }
209 { $example "USING: calendar prettyprint ;"
210 "6 months duration>years ."
215 HELP: duration>months
216 { $values { "duration" duration } { "x" number } }
217 { $description "Calculates the length of a duration in months." }
219 { $example "USING: calendar prettyprint ;"
220 "30 days duration>months ."
226 { $values { "duration" duration } { "x" number } }
227 { $description "Calculates the length of a duration in days." }
229 { $example "USING: calendar prettyprint ;"
230 "6 hours duration>days ."
236 { $values { "duration" duration } { "x" number } }
237 { $description "Calculates the length of a duration in hours." }
239 { $example "USING: calendar prettyprint ;"
240 "3/4 days duration>hours ."
244 HELP: duration>minutes
245 { $values { "duration" duration } { "x" number } }
246 { $description "Calculates the length of a duration in minutes." }
248 { $example "USING: calendar prettyprint ;"
249 "6 hours duration>minutes ."
253 HELP: duration>seconds
254 { $values { "duration" duration } { "x" number } }
255 { $description "Calculates the length of a duration in seconds." }
257 { $example "USING: calendar prettyprint ;"
258 "6 minutes duration>seconds ."
263 HELP: duration>milliseconds
264 { $values { "duration" duration } { "x" number } }
265 { $description "Calculates the length of a duration in milliseconds." }
267 { $example "USING: calendar prettyprint ;"
268 "6 seconds duration>milliseconds ."
273 HELP: duration>microseconds
274 { $values { "duration" duration } { "x" number } }
275 { $description "Calculates the length of a duration in microseconds." }
277 { $example "USING: calendar prettyprint ;"
278 "6 seconds duration>microseconds ."
283 HELP: duration>nanoseconds
284 { $values { "duration" duration } { "x" number } }
285 { $description "Calculates the length of a duration in nanoseconds." }
287 { $example "USING: calendar prettyprint ;"
288 "6 seconds duration>nanoseconds ."
293 { duration>years duration>months duration>days duration>hours duration>minutes duration>seconds duration>milliseconds duration>microseconds duration>nanoseconds } related-words
297 { $values { "time1" "timestamp or duration" } { "time2" "timestamp or duration" } { "time3" "timestamp or duration" } }
298 { $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." }
300 { $example "USING: calendar math.order prettyprint ;"
301 "10 months 2 months time- 8 months <=> ."
304 { $example "USING: accessors calendar math.order prettyprint ;"
305 "2010 1 1 <date> 3 days time- day>> ."
310 HELP: convert-timezone
311 { $values { "timestamp" timestamp } { "duration" duration } { "timestamp'" timestamp } }
312 { $description "Converts the " { $snippet "timestamp" } "'s " { $snippet "gmt-offset" } " to the GMT offset represented by the " { $snippet "duration" } "." }
314 { $example "USING: accessors calendar prettyprint ;"
315 "gmt noon instant -5 >>hour convert-timezone gmt-offset>> hour>> ."
321 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
322 { $description "Converts the " { $snippet "timestamp" } " to the timezone of your computer." }
324 { $example "USING: accessors calendar kernel prettyprint ;"
325 "now gmt >local-time [ gmt-offset>> ] same? ."
331 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
332 { $description "Converts the " { $snippet "timestamp" } " to the GMT timezone." }
334 { $example "USING: accessors calendar kernel prettyprint ;"
335 "now >gmt gmt-offset>> hour>> ."
341 { $values { "obj1" object } { "obj2" object } { "obj3" object } }
342 { $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 } "." } ;
343 { time+ time- time* } related-words
346 { $values { "duration" duration } { "-duration" duration } }
347 { $description "Negates a duration." }
349 { $example "USING: accessors calendar prettyprint ;"
350 "3 hours before now noon time+ hour>> ."
356 { $values { "timestamp" timestamp } }
357 { $description "Returns a zero timestamp that consists of zeros for every slot. Used to see if timestamps are valid." } ;
359 HELP: valid-timestamp?
360 { $values { "timestamp" timestamp } { "?" boolean } }
361 { $description "Tests if a timestamp is valid or not." } ;
364 { $values { "timestamp" timestamp } }
365 { $description "Returns the beginning of UNIX time, or midnight, January 1, 1970." } ;
367 HELP: micros>timestamp
368 { $values { "x" number } { "timestamp" timestamp } }
369 { $description "Converts a number of microseconds into a timestamp value in GMT time." }
371 { $example "USING: accessors calendar prettyprint ;"
372 "1000 micros>timestamp year>> ."
378 { $values { "timestamp" timestamp } }
379 { $description "Returns the time right now, but in the GMT timezone." } ;
381 { gmt now } related-words
384 { $values { "timestamp" timestamp } }
385 { $description "Returns the time right now in your computer's timezone." }
387 { $unchecked-example "USING: calendar prettyprint ;"
389 "T{ timestamp f 2008 9 1 16 38 24+801/1000 T{ duration f 0 0 0 -5 0 0 } }"
394 { $values { "duration" duration } { "timestamp" timestamp } }
395 { $description "Computes a time in the future that is the " { $snippet "duration" } " added to the result of " { $link now } "." }
398 "USING: calendar prettyprint ;"
400 "T{ timestamp f 2008 9 2 2 47 45+943/1000 T{ duration f 0 0 0 -5 0 0 } }"
405 { $values { "duration" duration } { "timestamp" timestamp } }
406 { $description "Computes a time in the past that is the " { $snippet "duration" } " subtracted from the result of " { $link now } "." }
409 "USING: calendar prettyprint ;"
411 "T{ timestamp f 2008 8 11 16 49 52+99/500 T{ duration f 0 0 0 -5 0 0 } }"
415 HELP: zeller-congruence
416 { $values { "year" integer } { "month" integer } { "day" integer } { "n" integer } }
417 { $description "An implementation of an algorithm that computes the day of the week given a date. Days are indexed starting from Sunday, which is index 0." }
418 { $notes "User code should use the " { $link day-of-week } " word, which takes a " { $snippet "timestamp" } " instead of integers." } ;
421 { $values { "obj" "a timestamp or an integer" } { "n" integer } }
422 { $description "Calculates the number of days in a given year." }
424 { $example "USING: calendar prettyprint ;"
425 "2004 days-in-year ."
431 { $values { "timestamp" timestamp } { "n" integer } }
432 { $description "Calculates the number of days in a given month." }
434 { $example "USING: calendar prettyprint ;"
435 "2008 8 24 <date> days-in-month ."
441 { $values { "timestamp" timestamp } { "n" integer } }
442 { $description "Calculates the index of the day of the week. Sunday will result in an index of 0." }
444 { $example "USING: calendar prettyprint ;"
445 "now sunday day-of-week ."
451 { $values { "timestamp" timestamp } { "n" integer } }
452 { $description "Calculates the day of the year, resulting in a number from 1 to 366 (leap years)." }
454 { $example "USING: calendar prettyprint ;"
455 "2008 1 4 <date> day-of-year ."
461 { $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
462 { $description "Returns the Sunday from the current week, which starts on a Sunday." } ;
465 { $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
466 { $description "Returns the Monday from the current week, which starts on a Sunday." } ;
469 { $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
470 { $description "Returns the Tuesday from the current week, which starts on a Sunday." } ;
473 { $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
474 { $description "Returns the Wednesday from the current week, which starts on a Sunday." } ;
477 { $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
478 { $description "Returns the Thursday from the current week, which starts on a Sunday." } ;
481 { $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
482 { $description "Returns the Friday from the current week, which starts on a Sunday." } ;
485 { $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
486 { $description "Returns the Saturday from the current week, which starts on a Sunday." } ;
488 { sunday monday tuesday wednesday thursday friday saturday } related-words
491 { $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
492 { $description "Returns a new timestamp that represents the day at midnight, or the beginning of the day." } ;
495 { $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
496 { $description "Returns a new timestamp that represents the day at noon, or the middle of the day." } ;
499 { $values { "timestamp" timestamp } }
500 { $description "Returns a timestamp that represents today at midnight." } ;
502 HELP: beginning-of-month
503 { $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
504 { $description "Returns a new timestamp with the day set to one." } ;
506 HELP: beginning-of-week
507 { $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
508 { $description "Returns a new timestamp where the day of the week is Sunday." } ;
510 HELP: beginning-of-year
511 { $values { "object" object } { "new-timestamp" timestamp } }
512 { $description "Returns a new timestamp with the month and day set to one, or January 1 of the input timestamp, given a year or a timestamp." } ;
514 HELP: time-since-midnight
515 { $values { "timestamp" timestamp } { "duration" duration } }
516 { $description "Calculates a " { $snippet "duration" } " that represents the elapsed time since midnight of the input " { $snippet "timestamp" } "." } ;
520 { "duration" duration }
521 { "timestamp" timestamp } }
522 { $description "Adds the duration to the beginning of Unix time and returns the result as a timestamp." } ;
524 ARTICLE: "calendar" "Calendar"
525 "The " { $vocab-link "calendar" } " vocabulary defines two data types and a set of operations on them:"
530 "Durations represent spans of time:"
531 { $subsections "using-durations" }
532 "Arithmetic on timestamps and durations:"
533 { $subsections "timestamp-arithmetic" }
534 "Getting the current timestamp:"
545 "Timestamps relative to each other:"
546 { $subsections "relative-timestamps" }
547 "Operations on units of time:"
553 "Both " { $link timestamp } "s and " { $link duration } "s implement the " { $link "math.order" } "."
555 "Meta-data about the calendar:"
556 { $subsections "calendar-facts" } ;
558 ARTICLE: "timestamp-arithmetic" "Timestamp arithmetic"
559 "Adding timestamps and durations, or durations and durations:"
560 { $subsections time+ }
562 { $subsections time- }
563 "Element-wise multiplication:"
564 { $subsections time* } ;
566 ARTICLE: "using-durations" "Using durations"
567 "Creating a duration object:"
581 "Converting a duration to a number:"
589 duration>milliseconds
590 duration>microseconds
594 ARTICLE: "relative-timestamps" "Relative timestamps"
596 { $subsections hence }
600 { $subsections before }
601 "Days of the week relative to " { $link now } ":"
611 "New timestamps relative to calendar events:"
620 ARTICLE: "days" "Day operations"
630 "Calculating a Julian day number:"
631 { $subsections julian-day-number }
632 "Calculate a timestamp:"
633 { $subsections julian-day-number>date } ;
635 ARTICLE: "calendar-facts" "Calendar facts"
649 ARTICLE: "years" "Year operations"
650 "Leap year predicate:"
651 { $subsections leap-year? }
652 "Find the number of days in a year:"
653 { $subsections days-in-year } ;
655 ARTICLE: "months" "Month operations"