1 ! Copyright (C) 2008 Doug Coleman.
2 ! See http://factorcode.org/license.txt for BSD license.
3 USING: help.markup help.syntax kernel math math.order ;
7 { $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." } ;
10 { $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." } ;
12 { timestamp duration } related-words
14 HELP: gmt-offset-duration
15 { $values { "duration" duration } }
16 { $description "Returns a " { $link duration } " object with the GMT offset returned by " { $link gmt-offset } "." } ;
19 { $values { "year" integer } { "month" integer } { "day" integer } { "timestamp" timestamp } }
20 { $description "Returns a timestamp object representing the start of the specified day in your current timezone." }
22 { $example "USING: accessors calendar prettyprint ;"
23 "2010 12 25 <date> instant >>gmt-offset ."
24 "T{ timestamp { year 2010 } { month 12 } { day 25 } }"
29 { $values { "value" ratio } }
30 { $description "The length of an average month averaged over 400 years. Used internally for adding an arbitrary real number of months to a timestamp." } ;
33 { $values { "value" integer } }
34 { $description "Returns the number of months in a year." } ;
37 { $values { "value" ratio } }
38 { $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." } ;
41 { $values { "value" ratio } }
42 { $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." } ;
44 HELP: minutes-per-year
45 { $values { "value" ratio } }
46 { $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." } ;
48 HELP: seconds-per-year
49 { $values { "value" integer } }
50 { $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." } ;
52 HELP: julian-day-number
53 { $values { "$year" integer } { "$month" integer } { "$day" integer } { "n" integer } }
54 { $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." }
55 { $warning "Not valid before year -4800 BCE." } ;
57 HELP: julian-day-number>date
58 { $values { "$n" integer } { "year" integer } { "month" integer } { "day" integer } }
59 { $description "Converts from a Julian day number back to a year, month, and day." } ;
60 { julian-day-number julian-day-number>date } related-words
63 { $values { "timestamp" timestamp } { "year" integer } { "month" integer } { "day" integer } }
64 { $description "Explodes a " { $snippet "timestamp" } " into its year, month, and day components." }
65 { $examples { $example "USING: arrays calendar prettyprint ;"
66 "2010 8 24 <date> >date< 3array ."
72 { $values { "timestamp" timestamp } { "hour" integer } { "minute" integer } { "second" integer } }
73 { $description "Explodes a " { $snippet "timestamp" } " into its hour, minute, and second components." }
74 { $examples { $example "USING: arrays calendar prettyprint ;"
75 "now noon >time< 3array ."
80 { >date< >time< } related-words
83 { $values { "duration" duration } }
84 { $description "Pushes a " { $snippet "duration" } " of zero seconds." } ;
87 { $values { "x" number } { "duration" duration } }
88 { $description "Creates a duration object with the specified number of years." } ;
91 { $values { "x" number } { "duration" duration } }
92 { $description "Creates a duration object with the specified number of months." } ;
95 { $values { "x" number } { "duration" duration } }
96 { $description "Creates a duration object with the specified number of days." } ;
99 { $values { "x" number } { "duration" duration } }
100 { $description "Creates a duration object with the specified number of weeks." } ;
103 { $values { "x" number } { "duration" duration } }
104 { $description "Creates a duration object with the specified number of hours." } ;
107 { $values { "x" number } { "duration" duration } }
108 { $description "Creates a duration object with the specified number of minutes." } ;
111 { $values { "x" number } { "duration" duration } }
112 { $description "Creates a duration object with the specified number of seconds." } ;
115 { $values { "x" number } { "duration" duration } }
116 { $description "Creates a duration object with the specified number of milliseconds." } ;
119 { $values { "x" number } { "duration" duration } }
120 { $description "Creates a duration object with the specified number of microseconds." } ;
123 { $values { "x" number } { "duration" duration } }
124 { $description "Creates a duration object with the specified number of nanoseconds." } ;
126 { years months days hours minutes seconds milliseconds microseconds nanoseconds } related-words
129 { $values { "obj" object } { "?" boolean } }
130 { $description "Returns " { $link t } " if the object represents a leap year." }
132 { $example "USING: calendar prettyprint ;"
136 { $example "USING: calendar prettyprint ;"
137 "2010 1 1 <date> leap-year? ."
143 { $values { "time1" { $or timestamp duration } } { "time2" { $or timestamp duration } } { "time3" { $or timestamp duration } } }
144 { $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." }
146 { $example "USING: calendar math.order prettyprint ;"
147 "10 months 2 months time+ 1 years <=> ."
150 { $example "USING: accessors calendar math.order prettyprint ;"
151 "2010 1 1 <date> 3 days time+ day>> ."
157 { $values { "time1" { $or timestamp duration } } { "time2" { $or timestamp duration } } { "time3" { $or timestamp duration } } }
158 { $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." }
160 { $example "USING: calendar math.order prettyprint ;"
161 "10 months 2 months time- 8 months <=> ."
164 { $example "USING: accessors calendar math.order prettyprint ;"
165 "2010 1 1 <date> 3 days time- day>> ."
170 { time+ time- } related-words
173 { $values { "duration" duration } { "x" number } }
174 { $description "Calculates the length of a duration in years." }
176 { $example "USING: calendar prettyprint ;"
177 "6 months duration>years ."
182 HELP: duration>months
183 { $values { "duration" duration } { "x" number } }
184 { $description "Calculates the length of a duration in months." }
186 { $example "USING: calendar prettyprint ;"
187 "30 days duration>months ."
193 { $values { "duration" duration } { "x" number } }
194 { $description "Calculates the length of a duration in days." }
196 { $example "USING: calendar prettyprint ;"
197 "6 hours duration>days ."
203 { $values { "duration" duration } { "x" number } }
204 { $description "Calculates the length of a duration in hours." }
206 { $example "USING: calendar prettyprint ;"
207 "3/4 days duration>hours ."
211 HELP: duration>minutes
212 { $values { "duration" duration } { "x" number } }
213 { $description "Calculates the length of a duration in minutes." }
215 { $example "USING: calendar prettyprint ;"
216 "6 hours duration>minutes ."
220 HELP: duration>seconds
221 { $values { "duration" duration } { "x" number } }
222 { $description "Calculates the length of a duration in seconds." }
224 { $example "USING: calendar prettyprint ;"
225 "6 minutes duration>seconds ."
230 HELP: duration>milliseconds
231 { $values { "duration" duration } { "x" number } }
232 { $description "Calculates the length of a duration in milliseconds." }
234 { $example "USING: calendar prettyprint ;"
235 "6 seconds duration>milliseconds ."
240 HELP: duration>microseconds
241 { $values { "duration" duration } { "x" number } }
242 { $description "Calculates the length of a duration in microseconds." }
244 { $example "USING: calendar prettyprint ;"
245 "6 seconds duration>microseconds ."
250 HELP: duration>nanoseconds
251 { $values { "duration" duration } { "x" number } }
252 { $description "Calculates the length of a duration in nanoseconds." }
254 { $example "USING: calendar prettyprint ;"
255 "6 seconds duration>nanoseconds ."
260 { duration>years duration>months duration>days duration>hours duration>minutes duration>seconds duration>milliseconds duration>microseconds duration>nanoseconds } related-words
263 HELP: convert-timezone
264 { $values { "timestamp" timestamp } { "duration" duration } }
265 { $description "Converts the " { $snippet "timestamp" } "'s " { $snippet "gmt-offset" } " to the GMT offset represented by the " { $snippet "duration" } "." }
267 { $example "USING: accessors calendar prettyprint ;"
268 "now-gmt noon instant -5 >>hour convert-timezone gmt-offset>> hour>> ."
274 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
275 { $description "Converts the " { $snippet "timestamp" } " to the timezone of your computer, returning a new " { $link timestamp } " instance." }
277 { $example "USING: accessors calendar kernel prettyprint ;"
278 "now now-gmt >local-time [ gmt-offset>> ] same? ."
284 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
285 { $description "Converts the " { $snippet "timestamp" } " to the GMT timezone, returning a new " { $link timestamp } " instance." }
287 { $example "USING: accessors calendar kernel prettyprint ;"
288 "now >gmt gmt-offset>> hour>> ."
294 { $values { "timestamp" timestamp } }
295 { $description "Set the time zone to the computer's local timezone." }
296 { $notes "The time is not converted, if you want that then call " { $link >local-time } "." } ;
299 { $values { "timestamp" timestamp } }
300 { $description "Set the time zone to GMT." }
301 { $notes "The time is not converted, if you want that then call " { $link >gmt } "." } ;
303 { local-time >local-time convert-local-time gmt >gmt convert-gmt utc >utc convert-utc convert-timezone } related-words
306 { $values { "obj1" object } { "obj2" object } { "obj3" object } }
307 { $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 } "." } ;
310 { $values { "duration" duration } { "-duration" duration } }
311 { $description "Negates a duration." }
313 { $example "USING: accessors calendar prettyprint ;"
314 "3 hours before now noon time+ hour>> ."
320 { $values { "timestamp" timestamp } }
321 { $description "Returns the beginning of UNIX time, or midnight, January 1, 1970." } ;
323 HELP: micros>timestamp
324 { $values { "x" number } { "timestamp" timestamp } }
325 { $description "Converts a number of microseconds into a timestamp value in GMT time." }
327 { $example "USING: accessors calendar prettyprint ;"
328 "1000 micros>timestamp year>> ."
334 { $values { "timestamp" timestamp } }
335 { $description "Returns the time right now, but in the GMT timezone." } ;
337 { now now-gmt } related-words
340 { $values { "timestamp" timestamp } }
341 { $description "Returns the time right now in your computer's timezone." }
343 { $unchecked-example "USING: calendar prettyprint ;"
345 "T{ timestamp f 2008 9 1 16 38 24+801/1000 T{ duration f 0 0 0 -5 0 0 } }"
350 { $values { "duration" duration } { "timestamp" timestamp } }
351 { $description "Computes a time in the future that is the " { $snippet "duration" } " added to the result of " { $link now } "." }
354 "USING: calendar prettyprint ;"
356 "T{ timestamp f 2008 9 2 2 47 45+943/1000 T{ duration f 0 0 0 -5 0 0 } }"
361 { $values { "duration" duration } { "timestamp" timestamp } }
362 { $description "Computes a time in the past that is the " { $snippet "duration" } " subtracted from the result of " { $link now } "." }
365 "USING: calendar prettyprint ;"
367 "T{ timestamp f 2008 8 11 16 49 52+99/500 T{ duration f 0 0 0 -5 0 0 } }"
372 { $values { "year" integer } { "month" integer } { "day" integer } { "n" integer } }
373 { $description "An implementation of the Zeller's congruence algorithm that computes the day of the week given a date. Days are indexed starting from Sunday, which is index 0." }
374 { $notes "User code should use the " { $link day-of-week } " word, which takes a " { $snippet "timestamp" } " instead of integers." } ;
377 { $values { "obj" { $or timestamp integer } } { "n" integer } }
378 { $description "Calculates the number of days in a given year." }
380 { $example "USING: calendar prettyprint ;"
381 "2004 days-in-year ."
387 { $values { "timestamp" timestamp } { "n" integer } }
388 { $description "Calculates the number of days in a given month." }
390 { $example "USING: calendar prettyprint ;"
391 "2008 8 24 <date> days-in-month ."
397 { $values { "timestamp" timestamp } { "n" integer } }
398 { $description "Calculates the index of the day of the week. Sunday will result in an index of 0." }
400 { $example "USING: calendar prettyprint ;"
401 "now sunday day-of-week ."
407 { $values { "timestamp" timestamp } { "n" integer } }
408 { $description "Calculates the day of the year, resulting in a number from 1 to 366 (leap years)." }
410 { $example "USING: calendar prettyprint ;"
411 "2008 1 4 <date> day-of-year ."
417 { $values { "timestamp" timestamp } { "[1,53]" integer } }
418 { $description "Calculates the ISO 8601 week number from 1 to 53 (leap years). See " { $snippet "https://en.wikipedia.org/wiki/ISO_week_date" } }
420 "Last day of 2018 is already in the first week of 2019."
421 { $example "USING: calendar prettyprint ;"
422 "2018 12 31 <date> week-number ."
425 "2020 is a leap year with 53 weeks, and January 1st, 2021 is still in week 53 of 2020."
426 { $example "USING: calendar prettyprint ;"
427 "2021 1 1 <date> week-number ."
433 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
434 { $description "Returns the Sunday from the current week, which starts on a Sunday." } ;
437 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
438 { $description "Returns the Monday from the current week, which starts on a Sunday." } ;
441 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
442 { $description "Returns the Tuesday from the current week, which starts on a Sunday." } ;
445 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
446 { $description "Returns the Wednesday from the current week, which starts on a Sunday." } ;
449 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
450 { $description "Returns the Thursday from the current week, which starts on a Sunday." } ;
453 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
454 { $description "Returns the Friday from the current week, which starts on a Sunday." } ;
457 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
458 { $description "Returns the Saturday from the current week, which starts on a Sunday." } ;
460 { sunday monday tuesday wednesday thursday friday saturday } related-words
463 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
464 { $description "Sets the timestamp to represent the day at midnight, or the beginning of the day." } ;
467 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
468 { $description "Sets the timestamp to represent the day at noon, or the middle of the day." } ;
471 { $values { "timestamp" timestamp } }
472 { $description "Sets the timestamp to represents today at midnight." } ;
475 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
476 { $description "Sets the timestamp with the day set to one." } ;
479 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
480 { $description "Sets the timestamp with the day of the week set to Sunday." } ;
483 { $values { "object" object } { "timestamp" timestamp } }
484 { $description "Sets the timestamp with the month and day set to one, or January 1 of the input timestamp, given a year or a timestamp." } ;
486 HELP: time-since-midnight
487 { $values { "timestamp" timestamp } { "duration" duration } }
488 { $description "Calculates a " { $snippet "duration" } " that represents the elapsed time since midnight of the input " { $snippet "timestamp" } "." } ;
492 { "duration" duration }
493 { "timestamp" timestamp } }
494 { $description "Adds the duration to the beginning of Unix time and returns the result as a timestamp." } ;
496 ARTICLE: "calendar" "Calendar"
497 "The " { $vocab-link "calendar" } " vocabulary defines two data types and a set of operations on them:"
502 "Durations represent spans of time:"
503 { $subsections "using-durations" }
504 "Arithmetic on timestamps and durations:"
505 { $subsections "timestamp-arithmetic" }
506 "Getting the current timestamp:"
518 "Timestamps relative to each other:"
519 { $subsections "relative-timestamps" }
520 "Operations on units of time:"
526 "Both " { $link timestamp } "s and " { $link duration } "s implement the " { $link "math.order" } "."
528 "Metadata about the calendar:"
529 { $subsections "calendar-facts" } ;
531 ARTICLE: "timestamp-arithmetic" "Timestamp arithmetic"
532 "Adding timestamps and durations, or durations and durations:"
533 { $subsections time+ }
535 { $subsections time- }
536 "Multiplying durations:"
537 { $subsections duration* } ;
539 ARTICLE: "using-durations" "Using durations"
540 "Creating a duration object:"
554 "Converting a duration to a number:"
562 duration>milliseconds
563 duration>microseconds
567 ARTICLE: "relative-timestamps" "Relative timestamps"
569 { $subsections hence }
573 { $subsections before }
574 "Days of the week relative to " { $link now } ":"
584 "New timestamps relative to calendar events:"
593 ARTICLE: "calendar-facts" "Calendar facts"
607 "Calculating a Julian day number:"
608 { $subsections julian-day-number }
609 "Calculate a timestamp:"
610 { $subsections julian-day-number>date } ;
612 ARTICLE: "years" "Year operations"
613 "Leap year predicate:"
614 { $subsections leap-year? }
615 "Find the number of days in a year:"
616 { $subsections days-in-year } ;