basis/calendar/calendar-docs.factor

   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 ;
   4 IN: calendar
   5
   6 HELP: duration
   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." } ;
   8
   9 HELP: timestamp
  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." } ;
  11
  12 { timestamp duration } related-words
  13
  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 } "." } ;
  17
  18 HELP: <date>
  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." }
  21 { $examples
  22     { $example "USING: accessors calendar prettyprint ;"
  23                "2010 12 25 <date> instant >>gmt-offset ."
  24                "T{ timestamp { year 2010 } { month 12 } { day 25 } }"
  25     }
  26 } ;
  27
  28 HELP: average-month
  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." } ;
  31
  32 HELP: months-per-year
  33 { $values { "value" integer } }
  34 { $description "Returns the number of months in a year." } ;
  35
  36 HELP: days-per-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." } ;
  39
  40 HELP: hours-per-year
  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." } ;
  43
  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." } ;
  47
  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." } ;
  51
  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." } ;
  56
  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
  61
  62 HELP: >date<
  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 ."
  67                        "{ 2010 8 24 }"
  68                        }
  69 } ;
  70
  71 HELP: >time<
  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 ."
  76                        "{ 12 0 0 }"
  77                        }
  78 } ;
  79
  80 { >date< >time< } related-words
  81
  82 HELP: instant
  83 { $values { "duration" duration } }
  84 { $description "Pushes a " { $snippet "duration" } " of zero seconds." } ;
  85
  86 HELP: years
  87 { $values { "x" number } { "duration" duration } }
  88 { $description "Creates a duration object with the specified number of years." } ;
  89
  90 HELP: months
  91 { $values { "x" number } { "duration" duration } }
  92 { $description "Creates a duration object with the specified number of months." } ;
  93
  94 HELP: days
  95 { $values { "x" number } { "duration" duration } }
  96 { $description "Creates a duration object with the specified number of days." } ;
  97
  98 HELP: weeks
  99 { $values { "x" number } { "duration" duration } }
 100 { $description "Creates a duration object with the specified number of weeks." } ;
 101
 102 HELP: hours
 103 { $values { "x" number } { "duration" duration } }
 104 { $description "Creates a duration object with the specified number of hours." } ;
 105
 106 HELP: minutes
 107 { $values { "x" number } { "duration" duration } }
 108 { $description "Creates a duration object with the specified number of minutes." } ;
 109
 110 HELP: seconds
 111 { $values { "x" number } { "duration" duration } }
 112 { $description "Creates a duration object with the specified number of seconds." } ;
 113
 114 HELP: milliseconds
 115 { $values { "x" number } { "duration" duration } }
 116 { $description "Creates a duration object with the specified number of milliseconds." } ;
 117
 118 HELP: microseconds
 119 { $values { "x" number } { "duration" duration } }
 120 { $description "Creates a duration object with the specified number of microseconds." } ;
 121
 122 HELP: nanoseconds
 123 { $values { "x" number } { "duration" duration } }
 124 { $description "Creates a duration object with the specified number of nanoseconds." } ;
 125
 126 { years months days hours minutes seconds milliseconds microseconds nanoseconds } related-words
 127
 128 HELP: leap-year?
 129 { $values { "obj" object } { "?" boolean } }
 130 { $description "Returns " { $link t } " if the object represents a leap year." }
 131 { $examples
 132     { $example "USING: calendar prettyprint ;"
 133                "2008 leap-year? ."
 134                "t"
 135     }
 136     { $example "USING: calendar prettyprint ;"
 137                "2010 1 1 <date> leap-year? ."
 138                "f"
 139     }
 140 } ;
 141
 142 HELP: time+
 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." }
 145 { $examples
 146     { $example "USING: calendar math.order prettyprint ;"
 147                "10 months 2 months time+ 1 years <=> ."
 148                "+eq+"
 149     }
 150     { $example "USING: accessors calendar math.order prettyprint ;"
 151                "2010 1 1 <date> 3 days time+ day>> ."
 152                "4"
 153     }
 154 } ;
 155
 156 HELP: time-
 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." }
 159 { $examples
 160     { $example "USING: calendar math.order prettyprint ;"
 161                "10 months 2 months time- 8 months <=> ."
 162                "+eq+"
 163     }
 164     { $example "USING: accessors calendar math.order prettyprint ;"
 165                "2010 1 1 <date> 3 days time- day>> ."
 166                "29"
 167     }
 168 } ;
 169
 170 { time+ time- } related-words
 171
 172 HELP: duration>years
 173 { $values { "duration" duration } { "x" number } }
 174 { $description "Calculates the length of a duration in years." }
 175 { $examples
 176     { $example "USING: calendar prettyprint ;"
 177                "6 months duration>years ."
 178                "1/2"
 179     }
 180 } ;
 181
 182 HELP: duration>months
 183 { $values { "duration" duration } { "x" number } }
 184 { $description "Calculates the length of a duration in months." }
 185 { $examples
 186     { $example "USING: calendar prettyprint ;"
 187                "30 days duration>months ."
 188                "16000/16233"
 189     }
 190 } ;
 191
 192 HELP: duration>days
 193 { $values { "duration" duration } { "x" number } }
 194 { $description "Calculates the length of a duration in days." }
 195 { $examples
 196     { $example "USING: calendar prettyprint ;"
 197                "6 hours duration>days ."
 198                "1/4"
 199     }
 200 } ;
 201
 202 HELP: duration>hours
 203 { $values { "duration" duration } { "x" number } }
 204 { $description "Calculates the length of a duration in hours." }
 205 { $examples
 206     { $example "USING: calendar prettyprint ;"
 207                "3/4 days duration>hours ."
 208                "18"
 209     }
 210 } ;
 211 HELP: duration>minutes
 212 { $values { "duration" duration } { "x" number } }
 213 { $description "Calculates the length of a duration in minutes." }
 214 { $examples
 215     { $example "USING: calendar prettyprint ;"
 216                "6 hours duration>minutes ."
 217                "360"
 218     }
 219 } ;
 220 HELP: duration>seconds
 221 { $values { "duration" duration } { "x" number } }
 222 { $description "Calculates the length of a duration in seconds." }
 223 { $examples
 224     { $example "USING: calendar prettyprint ;"
 225                "6 minutes duration>seconds ."
 226                "360"
 227     }
 228 } ;
 229
 230 HELP: duration>milliseconds
 231 { $values { "duration" duration } { "x" number } }
 232 { $description "Calculates the length of a duration in milliseconds." }
 233 { $examples
 234     { $example "USING: calendar prettyprint ;"
 235                "6 seconds duration>milliseconds ."
 236                "6000"
 237     }
 238 } ;
 239
 240 HELP: duration>microseconds
 241 { $values { "duration" duration } { "x" number } }
 242 { $description "Calculates the length of a duration in microseconds." }
 243 { $examples
 244     { $example "USING: calendar prettyprint ;"
 245                "6 seconds duration>microseconds ."
 246                "6000000"
 247     }
 248 } ;
 249
 250 HELP: duration>nanoseconds
 251 { $values { "duration" duration } { "x" number } }
 252 { $description "Calculates the length of a duration in nanoseconds." }
 253 { $examples
 254     { $example "USING: calendar prettyprint ;"
 255                "6 seconds duration>nanoseconds ."
 256                "6000000000"
 257     }
 258 } ;
 259
 260 { duration>years duration>months duration>days duration>hours duration>minutes duration>seconds duration>milliseconds duration>microseconds duration>nanoseconds } related-words
 261
 262
 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" } "." }
 266 { $examples
 267     { $example "USING: accessors calendar prettyprint ;"
 268                "now-gmt noon instant -5 >>hour convert-timezone gmt-offset>> hour>> ."
 269                "-5"
 270     }
 271 } ;
 272
 273 HELP: >local-time
 274 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
 275 { $description "Converts the " { $snippet "timestamp" } " to the timezone of your computer, returning a new " { $link timestamp } " instance." }
 276 { $examples
 277     { $example "USING: accessors calendar kernel prettyprint ;"
 278                "now now-gmt >local-time [ gmt-offset>> ] same? ."
 279                "t"
 280     }
 281 } ;
 282
 283 HELP: >gmt
 284 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
 285 { $description "Converts the " { $snippet "timestamp" } " to the GMT timezone, returning a new " { $link timestamp } " instance." }
 286 { $examples
 287     { $example "USING: accessors calendar kernel prettyprint ;"
 288                "now >gmt gmt-offset>> hour>> ."
 289                "0"
 290     }
 291 } ;
 292
 293 HELP: local-time
 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 } "." } ;
 297
 298 HELP: gmt
 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 } "." } ;
 302
 303 { local-time >local-time convert-local-time gmt >gmt convert-gmt utc >utc convert-utc convert-timezone } related-words
 304
 305 HELP: duration*
 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 } "." } ;
 308
 309 HELP: before
 310 { $values { "duration" duration } { "-duration" duration } }
 311 { $description "Negates a duration." }
 312 { $examples
 313     { $example "USING: accessors calendar prettyprint ;"
 314                "3 hours before now noon time+ hour>> ."
 315                "9"
 316     }
 317 } ;
 318
 319 HELP: unix-1970
 320 { $values { "timestamp" timestamp } }
 321 { $description "Returns the beginning of UNIX time, or midnight, January 1, 1970." } ;
 322
 323 HELP: micros>timestamp
 324 { $values { "x" number } { "timestamp" timestamp } }
 325 { $description "Converts a number of microseconds into a timestamp value in GMT time." }
 326 { $examples
 327     { $example "USING: accessors calendar prettyprint ;"
 328                "1000 micros>timestamp year>> ."
 329                "1970"
 330     }
 331 } ;
 332
 333 HELP: now-gmt
 334 { $values { "timestamp" timestamp } }
 335 { $description "Returns the time right now, but in the GMT timezone." } ;
 336
 337 { now now-gmt } related-words
 338
 339 HELP: now
 340 { $values { "timestamp" timestamp } }
 341 { $description "Returns the time right now in your computer's timezone." }
 342 { $examples
 343     { $unchecked-example "USING: calendar prettyprint ;"
 344         "now ."
 345          "T{ timestamp f 2008 9 1 16 38 24+801/1000 T{ duration f 0 0 0 -5 0 0 } }"
 346     }
 347 } ;
 348
 349 HELP: hence
 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 } "." }
 352 { $examples
 353     { $unchecked-example
 354         "USING: calendar prettyprint ;"
 355         "10 hours hence ."
 356         "T{ timestamp f 2008 9 2 2 47 45+943/1000 T{ duration f 0 0 0 -5 0 0 } }"
 357     }
 358 } ;
 359
 360 HELP: ago
 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 } "." }
 363 { $examples
 364     { $unchecked-example
 365         "USING: calendar prettyprint ;"
 366         "3 weeks ago ."
 367         "T{ timestamp f 2008 8 11 16 49 52+99/500 T{ duration f 0 0 0 -5 0 0 } }"
 368     }
 369 } ;
 370
 371 HELP: (day-of-week)
 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." } ;
 375
 376 HELP: days-in-year
 377 { $values { "obj" { $or timestamp integer } } { "n" integer } }
 378 { $description "Calculates the number of days in a given year." }
 379 { $examples
 380     { $example "USING: calendar prettyprint ;"
 381                "2004 days-in-year ."
 382                "366"
 383     }
 384 } ;
 385
 386 HELP: days-in-month
 387 { $values { "timestamp" timestamp } { "n" integer } }
 388 { $description "Calculates the number of days in a given month." }
 389 { $examples
 390     { $example "USING: calendar prettyprint ;"
 391                "2008 8 24 <date> days-in-month ."
 392                "31"
 393     }
 394 } ;
 395
 396 HELP: day-of-week
 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." }
 399 { $examples
 400     { $example "USING: calendar prettyprint ;"
 401                "now sunday day-of-week ."
 402                "0"
 403     }
 404 } ;
 405
 406 HELP: day-of-year
 407 { $values { "timestamp" timestamp } { "n" integer } }
 408 { $description "Calculates the day of the year, resulting in a number from 1 to 366 (leap years)." }
 409 { $examples
 410     { $example "USING: calendar prettyprint ;"
 411                "2008 1 4 <date> day-of-year ."
 412                "4"
 413     }
 414 } ;
 415
 416 HELP: week-number
 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" } }
 419 { $examples
 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 ."
 423                "1"
 424     }
 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 ."
 428                "53"
 429     }
 430 } ;
 431
 432 HELP: sunday
 433 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
 434 { $description "Returns the Sunday from the current week, which starts on a Sunday." } ;
 435
 436 HELP: monday
 437 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
 438 { $description "Returns the Monday from the current week, which starts on a Sunday." } ;
 439
 440 HELP: tuesday
 441 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
 442 { $description "Returns the Tuesday from the current week, which starts on a Sunday." } ;
 443
 444 HELP: wednesday
 445 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
 446 { $description "Returns the Wednesday from the current week, which starts on a Sunday." } ;
 447
 448 HELP: thursday
 449 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
 450 { $description "Returns the Thursday from the current week, which starts on a Sunday." } ;
 451
 452 HELP: friday
 453 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
 454 { $description "Returns the Friday from the current week, which starts on a Sunday." } ;
 455
 456 HELP: saturday
 457 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
 458 { $description "Returns the Saturday from the current week, which starts on a Sunday." } ;
 459
 460 { sunday monday tuesday wednesday thursday friday saturday } related-words
 461
 462 HELP: midnight
 463 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
 464 { $description "Sets the timestamp to represent the day at midnight, or the beginning of the day." } ;
 465
 466 HELP: noon
 467 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
 468 { $description "Sets the timestamp to represent the day at noon, or the middle of the day." } ;
 469
 470 HELP: today
 471 { $values { "timestamp" timestamp } }
 472 { $description "Sets the timestamp to represents today at midnight." } ;
 473
 474 HELP: start-of-month
 475 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
 476 { $description "Sets the timestamp with the day set to one." } ;
 477
 478 HELP: start-of-week
 479 { $values { "timestamp" timestamp } { "timestamp'" timestamp } }
 480 { $description "Sets the timestamp with the day of the week set to Sunday." } ;
 481
 482 HELP: start-of-year
 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." } ;
 485
 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" } "." } ;
 489
 490 HELP: since-1970
 491 { $values
 492     { "duration" duration }
 493     { "timestamp" timestamp } }
 494 { $description "Adds the duration to the beginning of Unix time and returns the result as a timestamp." } ;
 495
 496 ARTICLE: "calendar" "Calendar"
 497 "The " { $vocab-link "calendar" } " vocabulary defines two data types and a set of operations on them:"
 498 { $subsections
 499     timestamp
 500     duration
 501 }
 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:"
 507 { $subsections
 508     now
 509     gmt
 510 }
 511 "Time zones:"
 512 { $subsections
 513     >local-time
 514     >gmt
 515     >utc
 516     convert-timezone
 517 }
 518 "Timestamps relative to each other:"
 519 { $subsections "relative-timestamps" }
 520 "Operations on units of time:"
 521 { $subsections
 522     "years"
 523     "months"
 524     "days"
 525 }
 526 "Both " { $link timestamp } "s and " { $link duration } "s implement the " { $link "math.order" } "."
 527 $nl
 528 "Metadata about the calendar:"
 529 { $subsections "calendar-facts" } ;
 530
 531 ARTICLE: "timestamp-arithmetic" "Timestamp arithmetic"
 532 "Adding timestamps and durations, or durations and durations:"
 533 { $subsections time+ }
 534 "Subtracting:"
 535 { $subsections time- }
 536 "Multiplying durations:"
 537 { $subsections duration* } ;
 538
 539 ARTICLE: "using-durations" "Using durations"
 540 "Creating a duration object:"
 541 { $subsections
 542     years
 543     months
 544     weeks
 545     days
 546     hours
 547     minutes
 548     seconds
 549     milliseconds
 550     microseconds
 551     nanoseconds
 552     instant
 553 }
 554 "Converting a duration to a number:"
 555 { $subsections
 556     duration>years
 557     duration>months
 558     duration>days
 559     duration>hours
 560     duration>minutes
 561     duration>seconds
 562     duration>milliseconds
 563     duration>microseconds
 564     duration>nanoseconds
 565 } ;
 566
 567 ARTICLE: "relative-timestamps" "Relative timestamps"
 568 "In the future:"
 569 { $subsections hence }
 570 "In the past:"
 571 { $subsections ago }
 572 "Invert a duration:"
 573 { $subsections before }
 574 "Days of the week relative to " { $link now } ":"
 575 { $subsections
 576     sunday
 577     monday
 578     tuesday
 579     wednesday
 580     thursday
 581     friday
 582     saturday
 583 }
 584 "New timestamps relative to calendar events:"
 585 { $subsections
 586     start-of-year
 587     start-of-month
 588     start-of-week
 589     midnight
 590     noon
 591 } ;
 592
 593 ARTICLE: "calendar-facts" "Calendar facts"
 594 "Calendar facts:"
 595 { $subsections
 596     average-month
 597     months-per-year
 598     days-per-year
 599     hours-per-year
 600     minutes-per-year
 601     seconds-per-year
 602     days-in-month
 603     day-of-year
 604     day-of-week
 605     week-number
 606 }
 607 "Calculating a Julian day number:"
 608 { $subsections julian-day-number }
 609 "Calculate a timestamp:"
 610 { $subsections julian-day-number>date } ;
 611
 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 } ;
 617
 618 ABOUT: "calendar"