! Copyright (C) 2008 Doug Coleman.
-! See http://factorcode.org/license.txt for BSD license.
-USING: arrays kernel math strings help.markup help.syntax
-math.order ;
+! See https://factorcode.org/license.txt for BSD license.
+USING: help.markup help.syntax kernel math math.order ;
IN: calendar
HELP: duration
-{ $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." } ;
+{ $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." } ;
HELP: timestamp
-{ $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 duarionts with the " { $link <=> } " word." } ;
+{ $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." } ;
{ timestamp duration } related-words
}
} ;
-HELP: month-names
-{ $values { "value" object } }
-{ $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 { "value" 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 { "value" 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 { "value" 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 } }
+{ $values { "value" 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 } }
+{ $values { "value" integer } }
{ $description "Returns the number of months in a year." } ;
HELP: days-per-year
-{ $values { "ratio" ratio } }
+{ $values { "value" 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 } }
+{ $values { "value" 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 } }
+{ $values { "value" 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 } }
+{ $values { "value" 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." }
+{ $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 } }
+{ $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
{ years months days hours minutes seconds milliseconds microseconds nanoseconds } related-words
HELP: leap-year?
-{ $values { "obj" object } { "?" "a boolean" } }
+{ $values { "obj" object } { "?" boolean } }
{ $description "Returns " { $link t } " if the object represents a leap year." }
{ $examples
{ $example "USING: calendar prettyprint ;"
} ;
HELP: time+
-{ $values { "time1" "timestamp or duration" } { "time2" "timestamp or duration" } { "time3" "timestamp or duration" } }
+{ $values { "time1" { $or timestamp duration } } { "time2" { $or timestamp duration } } { "time3" { $or timestamp duration } } }
{ $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." }
{ $examples
{ $example "USING: calendar math.order prettyprint ;"
}
} ;
+HELP: time-
+{ $values { "time1" { $or timestamp duration } } { "time2" { $or timestamp duration } } { "time3" { $or timestamp duration } } }
+{ $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." }
+{ $examples
+ { $example "USING: calendar math.order prettyprint ;"
+ "10 months 2 months time- 8 months <=> ."
+ "+eq+"
+ }
+ { $example "USING: accessors calendar math.order prettyprint ;"
+ "2010 1 1 <date> 3 days time- day>> ."
+ "29"
+ }
+} ;
+
+{ time+ time- } related-words
+
HELP: duration>years
{ $values { "duration" duration } { "x" number } }
{ $description "Calculates the length of a duration in years." }
{ duration>years duration>months duration>days duration>hours duration>minutes duration>seconds duration>milliseconds duration>microseconds duration>nanoseconds } related-words
-HELP: time-
-{ $values { "time1" "timestamp or duration" } { "time2" "timestamp or duration" } { "time3" "timestamp or duration" } }
-{ $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." }
-{ $examples
- { $example "USING: calendar math.order prettyprint ;"
- "10 months 2 months time- 8 months <=> ."
- "+eq+"
- }
- { $example "USING: accessors calendar math.order prettyprint ;"
- "2010 1 1 <date> 3 days time- day>> ."
- "29"
- }
-} ;
-
HELP: convert-timezone
-{ $values { "timestamp" timestamp } { "duration" duration } { "timestamp" timestamp } }
+{ $values { "timestamp" timestamp } { "duration" duration } }
{ $description "Converts the " { $snippet "timestamp" } "'s " { $snippet "gmt-offset" } " to the GMT offset represented by the " { $snippet "duration" } "." }
{ $examples
{ $example "USING: accessors calendar prettyprint ;"
- "gmt noon instant -5 >>hour convert-timezone gmt-offset>> hour>> ."
+ "now-gmt noon instant -5 >>hour convert-timezone gmt-offset>> hour>> ."
"-5"
}
} ;
HELP: >local-time
-{ $values { "timestamp" timestamp } { "timestamp" timestamp } }
-{ $description "Converts the " { $snippet "timestamp" } " to the timezone of your computer." }
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
+{ $description "Converts the " { $snippet "timestamp" } " to the timezone of your computer, returning a new " { $link timestamp } " instance." }
{ $examples
{ $example "USING: accessors calendar kernel prettyprint ;"
- "now gmt >local-time [ gmt-offset>> ] bi@ = ."
+ "now now-gmt >local-time [ gmt-offset>> ] same? ."
"t"
}
} ;
HELP: >gmt
-{ $values { "timestamp" timestamp } { "timestamp" timestamp } }
-{ $description "Converts the " { $snippet "timestamp" } " to the GMT timezone." }
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
+{ $description "Converts the " { $snippet "timestamp" } " to the GMT timezone, returning a new " { $link timestamp } " instance." }
{ $examples
{ $example "USING: accessors calendar kernel prettyprint ;"
"now >gmt gmt-offset>> hour>> ."
}
} ;
-HELP: time*
+HELP: local-time
+{ $values { "timestamp" timestamp } }
+{ $description "Set the time zone to the computer's local timezone." }
+{ $notes "The time is not converted, if you want that then call " { $link >local-time } "." } ;
+
+HELP: gmt
+{ $values { "timestamp" timestamp } }
+{ $description "Set the time zone to GMT." }
+{ $notes "The time is not converted, if you want that then call " { $link >gmt } "." } ;
+
+{ local-time >local-time convert-local-time gmt >gmt convert-gmt utc >utc convert-utc convert-timezone } related-words
+
+HELP: duration*
{ $values { "obj1" object } { "obj2" object } { "obj3" object } }
-{ $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 } "." } ;
-{ time+ time- time* } related-words
+{ $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 } "." } ;
HELP: before
{ $values { "duration" duration } { "-duration" duration } }
}
} ;
-HELP: <zero>
-{ $values { "timestamp" timestamp } }
-{ $description "Outputs a zero timestamp that consists of zeros for every slot. Used to see if timestamps are valid." } ;
-
-HELP: valid-timestamp?
-{ $values { "timestamp" timestamp } { "?" "a boolean" } }
-{ $description "Tests if a timestamp is valid or not." } ;
-
HELP: unix-1970
{ $values { "timestamp" timestamp } }
-{ $description "Outputs the beginning of UNIX time, or midnight, January 1, 1970." } ;
+{ $description "Returns the beginning of UNIX time, or midnight, January 1, 1970." } ;
HELP: micros>timestamp
{ $values { "x" number } { "timestamp" timestamp } }
}
} ;
-HELP: gmt
+HELP: now-gmt
{ $values { "timestamp" timestamp } }
-{ $description "Outputs the time right now, but in the GMT timezone." } ;
+{ $description "Returns the time right now, but in the GMT timezone." } ;
-{ gmt now } related-words
+{ now now-gmt } related-words
HELP: now
{ $values { "timestamp" timestamp } }
-{ $description "Outputs the time right now in your computer's timezone." }
+{ $description "Returns the time right now in your computer's timezone." }
{ $examples
{ $unchecked-example "USING: calendar prettyprint ;"
"now ."
{ $description "Computes a time in the future that is the " { $snippet "duration" } " added to the result of " { $link now } "." }
{ $examples
{ $unchecked-example
- "USING: calendar prettyprint ;"
- "10 hours hence ."
- "T{ timestamp f 2008 9 2 2 47 45+943/1000 T{ duration f 0 0 0 -5 0 0 } }"
+ "USING: calendar prettyprint ;"
+ "10 hours hence ."
+ "T{ timestamp f 2008 9 2 2 47 45+943/1000 T{ duration f 0 0 0 -5 0 0 } }"
}
} ;
{ $description "Computes a time in the past that is the " { $snippet "duration" } " subtracted from the result of " { $link now } "." }
{ $examples
{ $unchecked-example
- "USING: calendar prettyprint ;"
- "3 weeks ago ."
- "T{ timestamp f 2008 8 11 16 49 52+99/500 T{ duration f 0 0 0 -5 0 0 } }"
+ "USING: calendar prettyprint ;"
+ "3 weeks ago ."
+ "T{ timestamp f 2008 8 11 16 49 52+99/500 T{ duration f 0 0 0 -5 0 0 } }"
}
} ;
-HELP: zeller-congruence
+HELP: (day-of-week)
{ $values { "year" integer } { "month" integer } { "day" integer } { "n" integer } }
-{ $description "An implementation of an algorithm that computes the day of the week given a date. Days are indexed starting from Sunday, which is index 0." }
+{ $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." }
{ $notes "User code should use the " { $link day-of-week } " word, which takes a " { $snippet "timestamp" } " instead of integers." } ;
HELP: days-in-year
-{ $values { "obj" "a timestamp or an integer" } { "n" integer } }
+{ $values { "obj" { $or timestamp integer } } { "n" integer } }
{ $description "Calculates the number of days in a given year." }
{ $examples
{ $example "USING: calendar prettyprint ;"
}
} ;
+HELP: week-number
+{ $values { "timestamp" timestamp } { "[1,53]" integer } }
+{ $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" } }
+{ $examples
+ "Last day of 2018 is already in the first week of 2019."
+ { $example "USING: calendar prettyprint ;"
+ "2018 12 31 <date> week-number ."
+ "1"
+ }
+ "2020 is a leap year with 53 weeks, and January 1st, 2021 is still in week 53 of 2020."
+ { $example "USING: calendar prettyprint ;"
+ "2021 1 1 <date> week-number ."
+ "53"
+ }
+} ;
+
HELP: sunday
-{ $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
{ $description "Returns the Sunday from the current week, which starts on a Sunday." } ;
HELP: monday
-{ $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
{ $description "Returns the Monday from the current week, which starts on a Sunday." } ;
HELP: tuesday
-{ $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
{ $description "Returns the Tuesday from the current week, which starts on a Sunday." } ;
HELP: wednesday
-{ $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
{ $description "Returns the Wednesday from the current week, which starts on a Sunday." } ;
HELP: thursday
-{ $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
{ $description "Returns the Thursday from the current week, which starts on a Sunday." } ;
HELP: friday
-{ $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
{ $description "Returns the Friday from the current week, which starts on a Sunday." } ;
HELP: saturday
-{ $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
{ $description "Returns the Saturday from the current week, which starts on a Sunday." } ;
{ sunday monday tuesday wednesday thursday friday saturday } related-words
HELP: midnight
-{ $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
-{ $description "Returns a timestamp that represents today at midnight, or the beginning of the day." } ;
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
+{ $description "Sets the timestamp to represent the day at midnight, or the beginning of the day." } ;
HELP: noon
-{ $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
-{ $description "Returns a timestamp that represents today at noon, or the middle of the day." } ;
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
+{ $description "Sets the timestamp to represent the day at noon, or the middle of the day." } ;
-HELP: beginning-of-month
-{ $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
-{ $description "Outputs a timestamp with the day set to one." } ;
+HELP: today
+{ $values { "timestamp" timestamp } }
+{ $description "Sets the timestamp to represents today at midnight." } ;
+
+HELP: start-of-month
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
+{ $description "Sets the timestamp with the day set to one." } ;
-HELP: beginning-of-week
-{ $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
-{ $description "Outputs a timestamp where the day of the week is Sunday." } ;
+HELP: start-of-week
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
+{ $description "Sets the timestamp with the day of the week set to Sunday." } ;
-HELP: beginning-of-year
-{ $values { "timestamp" timestamp } { "new-timestamp" timestamp } }
-{ $description "Outputs a timestamp with the month and day set to one, or January 1 of the input timestamp." } ;
+HELP: start-of-year
+{ $values { "object" object } { "timestamp" timestamp } }
+{ $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." } ;
HELP: time-since-midnight
{ $values { "timestamp" timestamp } { "duration" duration } }
HELP: since-1970
{ $values
- { "duration" duration }
- { "timestamp" timestamp } }
+ { "duration" duration }
+ { "timestamp" timestamp } }
{ $description "Adds the duration to the beginning of Unix time and returns the result as a timestamp." } ;
+HELP: sunrise
+{ $values
+ { "timestamp" timestamp }
+ { "latitude" real }
+ { "longitude" real }
+ { "new-timestamp" timestamp } }
+{ $description "Calculates the time of sunrise on the given day at the given location in the given timezone." } ;
+
+HELP: sunset
+{ $values
+ { "timestamp" timestamp }
+ { "latitude" real }
+ { "longitude" real }
+ { "new-timestamp" timestamp } }
+{ $description "Calculates the time of sunset on the given day at the given location in the given timezone." } ;
+
+HELP: solar-noon
+{ $values
+ { "timestamp" timestamp }
+ { "longitude" real }
+ { "new-timestamp" timestamp } }
+{ $description "Calculates solar noon of the given day at the given longitude in the given timezone." } ;
+
ARTICLE: "calendar" "Calendar"
-"The two data types used throughout the calendar library:"
+"The " { $vocab-link "calendar" } " vocabulary defines two data types and a set of operations on them:"
{ $subsections
timestamp
duration
"Getting the current timestamp:"
{ $subsections
now
- gmt
+ now-gmt
+ now-utc
}
-"Converting between timestamps:"
+"Time zones:"
{ $subsections
>local-time
>gmt
+ >utc
+ convert-timezone
}
-"Converting between timezones:"
-{ $subsections convert-timezone }
"Timestamps relative to each other:"
{ $subsections "relative-timestamps" }
"Operations on units of time:"
"months"
"days"
}
-"Meta-data about the calendar:"
-{ $subsections "calendar-facts" }
-;
+"Both " { $link timestamp } "s and " { $link duration } "s implement the " { $link "math.order" } "."
+$nl
+"Solar position calculations:"
+{ $subsections
+ sunrise
+ sunset
+ solar-noon
+}
+$nl
+"Metadata about the calendar:"
+{ $subsections "calendar-facts" } ;
ARTICLE: "timestamp-arithmetic" "Timestamp arithmetic"
"Adding timestamps and durations, or durations and durations:"
{ $subsections time+ }
"Subtracting:"
{ $subsections time- }
-"Element-wise multiplication:"
-{ $subsections time* } ;
+"Multiplying durations:"
+{ $subsections duration* } ;
ARTICLE: "using-durations" "Using durations"
"Creating a duration object:"
}
"New timestamps relative to calendar events:"
{ $subsections
- beginning-of-year
- beginning-of-month
- beginning-of-week
+ start-of-year
+ start-of-month
+ start-of-week
midnight
noon
} ;
-ARTICLE: "days" "Day operations"
-"Naming days:"
-{ $subsections
- day-abbreviation2
- day-abbreviations2
- day-abbreviation3
- day-abbreviations3
- day-name
- day-names
-}
-"Calculating a Julian day number:"
-{ $subsections julian-day-number }
-"Calculate a timestamp:"
-{ $subsections julian-day-number>date } ;
-
ARTICLE: "calendar-facts" "Calendar facts"
"Calendar facts:"
{ $subsections
days-in-month
day-of-year
day-of-week
-} ;
+ week-number
+}
+"Calculating a Julian day number:"
+{ $subsections julian-day-number }
+"Calculate a timestamp:"
+{ $subsections julian-day-number>date } ;
ARTICLE: "years" "Year operations"
"Leap year predicate:"
"Find the number of days in a year:"
{ $subsections days-in-year } ;
-ARTICLE: "months" "Month operations"
-"Naming months:"
-{ $subsections
- month-name
- month-names
- month-abbreviation
- month-abbreviations
-} ;
-
ABOUT: "calendar"
projects / factor.git / blobdiff