basis/calendar/calendar-docs.factor

   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 ;
   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). 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"