! 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 ;
+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
{ $values { "year" integer } { "month" integer } { "day" integer } { "timestamp" timestamp } }
{ $description "Returns a timestamp object representing the start of the specified day in your current timezone." }
{ $examples
- { $example "USING: calendar prettyprint ;"
- "2010 12 25 <date> >gmt midnight ."
+ { $example "USING: accessors calendar prettyprint ;"
+ "2010 12 25 <date> instant >>gmt-offset ."
"T{ timestamp { year 2010 } { month 12 } { day 25 } }"
}
} ;
-HELP: month-names
-{ $values { "array" array } }
-{ $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 ."
}
} ;
-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). 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 } }
{ $description "Adds the duration to the beginning of Unix time and returns the result as a timestamp." } ;
ARTICLE: "calendar" "Calendar"
-"The two data types used throughout the calendar library:"
-{ $subsection timestamp }
-{ $subsection duration }
+"The " { $vocab-link "calendar" } " vocabulary defines two data types and a set of operations on them:"
+{ $subsections
+ timestamp
+ duration
+}
"Durations represent spans of time:"
-{ $subsection "using-durations" }
+{ $subsections "using-durations" }
"Arithmetic on timestamps and durations:"
-{ $subsection "timestamp-arithmetic" }
+{ $subsections "timestamp-arithmetic" }
"Getting the current timestamp:"
-{ $subsection now }
-{ $subsection gmt }
-"Converting between timestamps:"
-{ $subsection >local-time }
-{ $subsection >gmt }
-"Converting between timezones:"
-{ $subsection convert-timezone }
+{ $subsections
+ now
+ gmt
+}
+"Time zones:"
+{ $subsections
+ >local-time
+ >gmt
+ >utc
+ convert-timezone
+}
"Timestamps relative to each other:"
-{ $subsection "relative-timestamps" }
+{ $subsections "relative-timestamps" }
"Operations on units of time:"
-{ $subsection "years" }
-{ $subsection "months" }
-{ $subsection "days" }
-"Meta-data about the calendar:"
-{ $subsection "calendar-facts" }
-;
+{ $subsections
+ "years"
+ "months"
+ "days"
+}
+"Both " { $link timestamp } "s and " { $link duration } "s implement the " { $link "math.order" } "."
+$nl
+"Metadata about the calendar:"
+{ $subsections "calendar-facts" } ;
ARTICLE: "timestamp-arithmetic" "Timestamp arithmetic"
"Adding timestamps and durations, or durations and durations:"
-{ $subsection time+ }
+{ $subsections time+ }
"Subtracting:"
-{ $subsection time- }
-"Element-wise multiplication:"
-{ $subsection time* } ;
+{ $subsections time- }
+"Multiplying durations:"
+{ $subsections duration* } ;
ARTICLE: "using-durations" "Using durations"
"Creating a duration object:"
-{ $subsection years }
-{ $subsection months }
-{ $subsection weeks }
-{ $subsection days }
-{ $subsection hours }
-{ $subsection minutes }
-{ $subsection seconds }
-{ $subsection milliseconds }
-{ $subsection microseconds }
-{ $subsection nanoseconds }
-{ $subsection instant }
+{ $subsections
+ years
+ months
+ weeks
+ days
+ hours
+ minutes
+ seconds
+ milliseconds
+ microseconds
+ nanoseconds
+ instant
+}
"Converting a duration to a number:"
-{ $subsection duration>years }
-{ $subsection duration>months }
-{ $subsection duration>days }
-{ $subsection duration>hours }
-{ $subsection duration>minutes }
-{ $subsection duration>seconds }
-{ $subsection duration>milliseconds }
-{ $subsection duration>microseconds }
-{ $subsection duration>nanoseconds } ;
+{ $subsections
+ duration>years
+ duration>months
+ duration>days
+ duration>hours
+ duration>minutes
+ duration>seconds
+ duration>milliseconds
+ duration>microseconds
+ duration>nanoseconds
+} ;
ARTICLE: "relative-timestamps" "Relative timestamps"
"In the future:"
-{ $subsection hence }
+{ $subsections hence }
"In the past:"
-{ $subsection ago }
+{ $subsections ago }
"Invert a duration:"
-{ $subsection before }
+{ $subsections before }
"Days of the week relative to " { $link now } ":"
-{ $subsection sunday }
-{ $subsection monday }
-{ $subsection tuesday }
-{ $subsection wednesday }
-{ $subsection thursday }
-{ $subsection friday }
-{ $subsection saturday }
+{ $subsections
+ sunday
+ monday
+ tuesday
+ wednesday
+ thursday
+ friday
+ saturday
+}
"New timestamps relative to calendar events:"
-{ $subsection beginning-of-year }
-{ $subsection beginning-of-month }
-{ $subsection beginning-of-week }
-{ $subsection midnight }
-{ $subsection noon }
-;
-
-ARTICLE: "days" "Day operations"
-"Naming days:"
-{ $subsection day-abbreviation2 }
-{ $subsection day-abbreviations2 }
-{ $subsection day-abbreviation3 }
-{ $subsection day-abbreviations3 }
-{ $subsection day-name }
-{ $subsection day-names }
-"Calculating a Julian day number:"
-{ $subsection julian-day-number }
-"Calculate a timestamp:"
-{ $subsection julian-day-number>date }
-;
+{ $subsections
+ start-of-year
+ start-of-month
+ start-of-week
+ midnight
+ noon
+} ;
ARTICLE: "calendar-facts" "Calendar facts"
"Calendar facts:"
-{ $subsection average-month }
-{ $subsection months-per-year }
-{ $subsection days-per-year }
-{ $subsection hours-per-year }
-{ $subsection minutes-per-year }
-{ $subsection seconds-per-year }
-{ $subsection days-in-month }
-{ $subsection day-of-year }
-{ $subsection day-of-week }
-;
+{ $subsections
+ average-month
+ months-per-year
+ days-per-year
+ hours-per-year
+ minutes-per-year
+ seconds-per-year
+ 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:"
-{ $subsection leap-year? }
+{ $subsections leap-year? }
"Find the number of days in a year:"
-{ $subsection days-in-year }
-;
-
-ARTICLE: "months" "Month operations"
-"Naming months:"
-{ $subsection month-name }
-{ $subsection month-names }
-{ $subsection month-abbreviation }
-{ $subsection month-abbreviations }
-;
+{ $subsections days-in-year } ;
ABOUT: "calendar"
projects / factor.git / blobdiff