1 ! Copyright (C) 2008 Doug Coleman.
2 ! See https://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). Weeks start on Monday and end on Sunday. The end of December can sometimes be the first week of the next year and January can be the last week number of the previous year. 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." } ;
498 { "timestamp" timestamp }
501 { "new-timestamp" timestamp } }
502 { $description "Calculates the time of sunrise on the given day at the given location in the given timezone." } ;
506 { "timestamp" timestamp }
509 { "new-timestamp" timestamp } }
510 { $description "Calculates the time of sunset on the given day at the given location in the given timezone." } ;
514 { "timestamp" timestamp }
516 { "new-timestamp" timestamp } }
517 { $description "Calculates solar noon of the given day at the given longitude in the given timezone." } ;
519 ARTICLE: "calendar" "Calendar"
520 "The " { $vocab-link "calendar" } " vocabulary defines two data types and a set of operations on them:"
525 "Durations represent spans of time:"
526 { $subsections "using-durations" }
527 "Arithmetic on timestamps and durations:"
528 { $subsections "timestamp-arithmetic" }
529 "Getting the current timestamp:"
542 "Timestamps relative to each other:"
543 { $subsections "relative-timestamps" }
544 "Operations on units of time:"
550 "Both " { $link timestamp } "s and " { $link duration } "s implement the " { $link "math.order" } "."
552 "Solar position calculations:"
559 "Metadata about the calendar:"
560 { $subsections "calendar-facts" } ;
562 ARTICLE: "timestamp-arithmetic" "Timestamp arithmetic"
563 "Adding timestamps and durations, or durations and durations:"
564 { $subsections time+ }
566 { $subsections time- }
567 "Multiplying durations:"
568 { $subsections duration* } ;
570 ARTICLE: "using-durations" "Using durations"
571 "Creating a duration object:"
585 "Converting a duration to a number:"
593 duration>milliseconds
594 duration>microseconds
598 ARTICLE: "relative-timestamps" "Relative timestamps"
600 { $subsections hence }
604 { $subsections before }
605 "Days of the week relative to " { $link now } ":"
615 "New timestamps relative to calendar events:"
624 ARTICLE: "calendar-facts" "Calendar facts"
638 "Calculating a Julian day number:"
639 { $subsections julian-day-number }
640 "Calculate a timestamp:"
641 { $subsections julian-day-number>date } ;
643 ARTICLE: "years" "Year operations"
644 "Leap year predicate:"
645 { $subsections leap-year? }
646 "Find the number of days in a year:"
647 { $subsections days-in-year } ;