! 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 "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 } }
+{ $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
}
} ;
-HELP: >local
-{ $values { "timestamp" timestamp } }
-{ $description "Converts the " { $snippet "timestamp" } " to the timezone of your computer." }
+HELP: >local-time
+{ $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 now-gmt >local [ gmt-offset>> ] same? ."
+ "now now-gmt >local-time [ gmt-offset>> ] same? ."
"t"
}
} ;
HELP: >gmt
-{ $values { "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: local
+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 } "." } ;
+{ $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 >local gmt >gmt convert-timezone } related-words
+{ 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 "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: 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" } }
+{ $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 ;"
} ;
HELP: sunday
-{ $values { "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 } }
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
{ $description "Returns the Monday from the current week, which starts on a Sunday." } ;
HELP: tuesday
-{ $values { "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 } }
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
{ $description "Returns the Wednesday from the current week, which starts on a Sunday." } ;
HELP: thursday
-{ $values { "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 } }
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
{ $description "Returns the Friday from the current week, which starts on a Sunday." } ;
HELP: saturday
-{ $values { "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 } }
+{ $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 } }
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
{ $description "Sets the timestamp to represent the day at noon, or the middle of the day." } ;
HELP: today
{ $description "Sets the timestamp to represents today at midnight." } ;
HELP: start-of-month
-{ $values { "timestamp" timestamp } }
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
{ $description "Sets the timestamp with the day set to one." } ;
HELP: start-of-week
-{ $values { "timestamp" timestamp } }
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
{ $description "Sets the timestamp with the day of the week set to Sunday." } ;
HELP: start-of-year
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 " { $vocab-link "calendar" } " vocabulary defines two data types and a set of operations on them:"
{ $subsections
"Getting the current timestamp:"
{ $subsections
now
- gmt
+ now-gmt
+ now-utc
}
"Time zones:"
{ $subsections
- >local
+ >local-time
>gmt
+ >utc
convert-timezone
}
"Timestamps relative to each other:"
}
"Both " { $link timestamp } "s and " { $link duration } "s implement the " { $link "math.order" } "."
$nl
-"Meta-data about the calendar:"
+"Solar position calculations:"
+{ $subsections
+ sunrise
+ sunset
+ solar-noon
+}
+$nl
+"Metadata about the calendar:"
{ $subsections "calendar-facts" } ;
ARTICLE: "timestamp-arithmetic" "Timestamp arithmetic"
projects / factor.git / blobdiff