basis/calendar/calendar-docs.factor

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