beginning-of-day -> midnight, add noon word, docs

basis/calendar/calendar-docs.factor

@@ -28,4 +28,103 @@ HELP: <date>
 
 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> >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

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 ;