From 1cc5f7eb41bd7929e10c6ccc0c40170d249c0426 Mon Sep 17 00:00:00 2001 From: Doug Coleman Date: Sun, 31 Aug 2008 12:59:27 -0500 Subject: [PATCH] beginning-of-day -> midnight, add noon word, docs --- basis/calendar/calendar-docs.factor | 101 +++++++++++++++++++++++++++- basis/calendar/calendar.factor | 19 +++--- 2 files changed, 110 insertions(+), 10 deletions(-) diff --git a/basis/calendar/calendar-docs.factor b/basis/calendar/calendar-docs.factor index 19427b7c79..734c19f045 100644 --- a/basis/calendar/calendar-docs.factor +++ b/basis/calendar/calendar-docs.factor @@ -28,4 +28,103 @@ HELP: HELP: month-names { $values { "array" array } } -{ $description "Returns an array with the English names of all the months. January has a index of 1 instead of 0." } ; +{ $description "Returns an array with the English names of all the months." } +{ $warning "Do not use this array for looking up a month name directly. Use month-name instead." } ; + +HELP: month-name +{ $values { "n" integer } { "string" string } } +{ $description "Looks up the month name and returns it as a string. January has an index of 1 instead of zero." } ; + +HELP: month-abbreviations +{ $values { "array" array } } +{ $description "Returns an array with the English abbreviated names of all the months." } +{ $warning "Do not use this array for looking up a month name directly. Use month-abbreviation instead." } ; + +HELP: month-abbreviation +{ $values { "n" integer } { "string" string } } +{ $description "Looks up the abbreviated month name and returns it as a string. January has an index of 1 instead of zero." } ; + + +HELP: day-names +{ $values { "array" array } } +{ $description "Returns an array with the English names of the days of the week." } ; + +HELP: day-name +{ $values { "n" integer } { "string" string } } +{ $description "Looks up the day name and returns it as a string." } ; + +HELP: day-abbreviations2 +{ $values { "array" array } } +{ $description "Returns an array with the abbreviated English names of the days of the week. This abbreviation is two characters long." } ; + +HELP: day-abbreviation2 +{ $values { "n" integer } { "string" string } } +{ $description "Looks up the abbreviated day name and returns it as a string. This abbreviation is two characters long." } ; + +HELP: day-abbreviations3 +{ $values { "array" array } } +{ $description "Returns an array with the abbreviated English names of the days of the week. This abbreviation is three characters long." } ; + +HELP: day-abbreviation3 +{ $values { "n" integer } { "string" string } } +{ $description "Looks up the abbreviated day name and returns it as a string. This abbreviation is three characters long." } ; + +{ + day-name day-names + day-abbreviation2 day-abbreviations2 + day-abbreviation3 day-abbreviations3 +} related-words + +HELP: average-month +{ $values { "ratio" ratio } } +{ $description "The length of an average month averaged over 400 years. Used internally for adding an arbitrary real number of months to a timestamp." } ; + +HELP: months-per-year +{ $values { "integer" integer } } +{ $description "Returns the number of months in a year." } ; + +HELP: days-per-year +{ $values { "ratio" ratio } } +{ $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." } ; + +HELP: hours-per-year +{ $values { "ratio" ratio } } +{ $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." } ; + +HELP: minutes-per-year +{ $values { "ratio" ratio } } +{ $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." } ; + +HELP: seconds-per-year +{ $values { "integer" integer } } +{ $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." } ; + +HELP: julian-day-number +{ $values { "year" integer } { "month" integer } { "day" integer } { "n" integer } } +{ $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." } +{ $warning "Not valid before year -4800 BCE." } ; + +HELP: julian-day-number>date +{ $values { "n" integer } { "year" integer } { "month" integer } { "day" integer } } +{ $description "Converts from a Julian day number back to a year, month, and day." } ; +{ julian-day-number julian-day-number>date } related-words + +HELP: >date< +{ $values { "timestamp" timestamp } { "year" integer } { "month" integer } { "day" integer } } +{ $description "Explodes a " { $snippet "timestamp" } " into its year, month, and day components." } +{ $examples { $example "USING: arrays calendar prettyprint ;" + "2010 8 24 >date< 3array ." + "{ 2010 8 24 }" + } +} ; + +HELP: >time< +{ $values { "timestamp" timestamp } { "hour" integer } { "minute" integer } { "second" integer } } +{ $description "Explodes a " { $snippet "timestamp" } " into its hour, minute, and second components." } +{ $examples { $example "USING: arrays calendar prettyprint ;" + "now noon >time< 3array ." + "{ 12 0 0 }" + } +} ; + +{ >date< >time< } related-words diff --git a/basis/calendar/calendar.factor b/basis/calendar/calendar.factor index 402542de3b..af0ced7ed2 100755 --- a/basis/calendar/calendar.factor +++ b/basis/calendar/calendar.factor @@ -57,7 +57,7 @@ PRIVATE> "Jul" "Aug" "Sep" "Oct" "Nov" "Dec" } ; -: month-abbreviation ( n -- array ) +: month-abbreviation ( n -- string ) check-month 1- month-abbreviations nth ; : day-names ( -- array ) @@ -377,23 +377,24 @@ M: timestamp days-in-year ( timestamp -- n ) year>> days-in-year ; : friday ( timestamp -- timestamp ) 5 day-this-week ; : saturday ( timestamp -- timestamp ) 6 day-this-week ; -: beginning-of-day ( timestamp -- new-timestamp ) - clone - 0 >>hour - 0 >>minute - 0 >>second ; inline +: midnight ( timestamp -- new-timestamp ) + clone 0 >>hour 0 >>minute 0 >>second ; inline + +: noon ( timestamp -- new-timestamp ) + midnight 12 >>hour ; inline : beginning-of-month ( timestamp -- new-timestamp ) - beginning-of-day 1 >>day ; + midnight 1 >>day ; : beginning-of-week ( timestamp -- new-timestamp ) - beginning-of-day sunday ; + midnight sunday ; : beginning-of-year ( timestamp -- new-timestamp ) beginning-of-month 1 >>month ; : time-since-midnight ( timestamp -- duration ) - dup beginning-of-day time- ; + dup midnight time- ; + M: timestamp sleep-until timestamp>millis sleep-until ;