From 38b868616149e8c94d4a40f0c176f0c9e54cf07f Mon Sep 17 00:00:00 2001 From: Doug Coleman Date: Mon, 1 Sep 2008 20:10:10 -0500 Subject: [PATCH] dt -> duration, lots of docs --- basis/calendar/calendar-docs.factor | 108 +++++++++++++++++----- basis/calendar/calendar.factor | 16 ++-- basis/calendar/format/format-tests.factor | 10 +- 3 files changed, 96 insertions(+), 38 deletions(-) diff --git a/basis/calendar/calendar-docs.factor b/basis/calendar/calendar-docs.factor index cf60d40bf6..81e9bdff28 100644 --- a/basis/calendar/calendar-docs.factor +++ b/basis/calendar/calendar-docs.factor @@ -5,10 +5,10 @@ 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 timestamps 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 timestamps 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 duarionts with the " { $link <=> } " word." } ; { timestamp duration } related-words @@ -135,35 +135,37 @@ HELP: instant HELP: years { $values { "x" number } { "duration" duration } } -{ $description } ; +{ $description "Creates a duration object with the specified number of years." } ; HELP: months { $values { "x" number } { "duration" duration } } -{ $description } ; +{ $description "Creates a duration object with the specified number of months." } ; HELP: days { $values { "x" number } { "duration" duration } } -{ $description } ; +{ $description "Creates a duration object with the specified number of days." } ; HELP: weeks { $values { "x" number } { "duration" duration } } -{ $description } ; +{ $description "Creates a duration object with the specified number of weeks." } ; HELP: hours { $values { "x" number } { "duration" duration } } -{ $description } ; +{ $description "Creates a duration object with the specified number of hours." } ; HELP: minutes { $values { "x" number } { "duration" duration } } -{ $description } ; +{ $description "Creates a duration object with the specified number of minutes." } ; HELP: seconds { $values { "x" number } { "duration" duration } } -{ $description } ; +{ $description "Creates a duration object with the specified number of seconds." } ; HELP: milliseconds { $values { "x" number } { "duration" duration } } -{ $description } ; +{ $description "Creates a duration object with the specified number of milliseconds." } ; + +{ years months days hours minutes seconds milliseconds } related-words HELP: leap-year? { $values { "obj" object } { "?" "a boolean" } } @@ -193,75 +195,75 @@ HELP: time+ } } ; -HELP: dt>years +HELP: duration>years { $values { "duration" duration } { "x" number } } { $description "Calculates the length of a duration in years." } { $examples { $example "USING: calendar prettyprint ;" - "6 months dt>years ." + "6 months duration>years ." "1/2" } } ; -HELP: dt>months +HELP: duration>months { $values { "duration" duration } { "x" number } } { $description "Calculates the length of a duration in months." } { $examples { $example "USING: calendar prettyprint ;" - "30 days dt>months ." + "30 days duration>months ." "16000/16233" } } ; -HELP: dt>days +HELP: duration>days { $values { "duration" duration } { "x" number } } { $description "Calculates the length of a duration in days." } { $examples { $example "USING: calendar prettyprint ;" - "6 hours dt>days ." + "6 hours duration>days ." "1/4" } } ; -HELP: dt>hours +HELP: duration>hours { $values { "duration" duration } { "x" number } } { $description "Calculates the length of a duration in hours." } { $examples { $example "USING: calendar prettyprint ;" - "3/4 days dt>hours ." + "3/4 days duration>hours ." "18" } } ; -HELP: dt>minutes +HELP: duration>minutes { $values { "duration" duration } { "x" number } } { $description "Calculates the length of a duration in minutes." } { $examples { $example "USING: calendar prettyprint ;" - "6 hours dt>minutes ." + "6 hours duration>minutes ." "360" } } ; -HELP: dt>seconds +HELP: duration>seconds { $values { "duration" duration } { "x" number } } { $description "Calculates the length of a duration in seconds." } { $examples { $example "USING: calendar prettyprint ;" - "6 minutes dt>seconds ." + "6 minutes duration>seconds ." "360" } } ; -HELP: dt>milliseconds +HELP: duration>milliseconds { $values { "duration" duration } { "x" number } } { $description "Calculates the length of a duration in milliseconds." } { $examples { $example "USING: calendar prettyprint ;" - "6 seconds dt>milliseconds ." + "6 seconds duration>milliseconds ." "6000" } } ; -{ dt>years dt>months dt>days dt>hours dt>minutes dt>seconds dt>milliseconds } related-words +{ duration>years duration>months duration>days duration>hours duration>minutes duration>seconds duration>milliseconds } related-words HELP: time- @@ -491,3 +493,59 @@ HELP: beginning-of-year HELP: time-since-midnight { $values { "timestamp" timestamp } { "duration" duration } } { $description "Calculates a " { $snippet "duration" } " that represents the elapsed time since midnight of the input " { $snippet "timestamp" } "." } ; + +ARTICLE: "calendar" "Calendar" +"The two data types used throughout the calendar library:" +{ $subsection timestamp } +{ $subsection duration } +"Durations represent spans of time:" +{ $subsection "using-durations" } +"Arithmetic on timestamps and durations:" +{ $subsection time+ } +{ $subsection time- } +{ $subsection time* } +"Getting the current timestamp:" +{ $subsection now } +{ $subsection gmt } +"Converting between timestamps:" +{ $subsection >local-time } +{ $subsection >gmt } +"Timestamps relative to each other:" +{ $subsection "relative-timestamps" } +; + +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 } +"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 } ; + +ARTICLE: "relative-timestamps" "Relative timestamps" +"Getting a relative timestamp:" +{ $subsection hence } +{ $subsection ago } +{ $subsection before } +"Days of the week relative to " { $link now } ":" +{ $subsection sunday } +{ $subsection monday } +{ $subsection tuesday } +{ $subsection wednesday } +{ $subsection thursday } +{ $subsection friday } +{ $subsection saturday } +; + +ABOUT: "calendar" diff --git a/basis/calendar/calendar.factor b/basis/calendar/calendar.factor index 096546349d..57f57f04a9 100755 --- a/basis/calendar/calendar.factor +++ b/basis/calendar/calendar.factor @@ -240,7 +240,7 @@ M: duration time+ 2drop ] if ; -: dt>years ( duration -- x ) +: duration>years ( duration -- x ) #! Uses average month/year length since duration loses calendar #! data 0 swap @@ -253,14 +253,14 @@ M: duration time+ [ second>> seconds-per-year / + ] } cleave ; -M: duration <=> [ dt>years ] compare ; +M: duration <=> [ duration>years ] compare ; -: dt>months ( duration -- x ) dt>years months-per-year * ; -: dt>days ( duration -- x ) dt>years days-per-year * ; -: dt>hours ( duration -- x ) dt>years hours-per-year * ; -: dt>minutes ( duration -- x ) dt>years minutes-per-year * ; -: dt>seconds ( duration -- x ) dt>years seconds-per-year * ; -: dt>milliseconds ( duration -- x ) dt>seconds 1000 * ; +: duration>months ( duration -- x ) duration>years months-per-year * ; +: duration>days ( duration -- x ) duration>years days-per-year * ; +: duration>hours ( duration -- x ) duration>years hours-per-year * ; +: duration>minutes ( duration -- x ) duration>years minutes-per-year * ; +: duration>seconds ( duration -- x ) duration>years seconds-per-year * ; +: duration>milliseconds ( duration -- x ) duration>seconds 1000 * ; GENERIC: time- ( time1 time2 -- time3 ) diff --git a/basis/calendar/format/format-tests.factor b/basis/calendar/format/format-tests.factor index 3efe33e265..978a4dca7f 100755 --- a/basis/calendar/format/format-tests.factor +++ b/basis/calendar/format/format-tests.factor @@ -3,23 +3,23 @@ io.streams.string accessors io math.order ; IN: calendar.format.tests [ 0 ] [ - "Z" [ read1 read-rfc3339-gmt-offset ] with-string-reader dt>hours + "Z" [ read1 read-rfc3339-gmt-offset ] with-string-reader duration>hours ] unit-test [ 1 ] [ - "+01" [ read1 read-rfc3339-gmt-offset ] with-string-reader dt>hours + "+01" [ read1 read-rfc3339-gmt-offset ] with-string-reader duration>hours ] unit-test [ -1 ] [ - "-01" [ read1 read-rfc3339-gmt-offset ] with-string-reader dt>hours + "-01" [ read1 read-rfc3339-gmt-offset ] with-string-reader duration>hours ] unit-test [ -1-1/2 ] [ - "-01:30" [ read1 read-rfc3339-gmt-offset ] with-string-reader dt>hours + "-01:30" [ read1 read-rfc3339-gmt-offset ] with-string-reader duration>hours ] unit-test [ 1+1/2 ] [ - "+01:30" [ read1 read-rfc3339-gmt-offset ] with-string-reader dt>hours + "+01:30" [ read1 read-rfc3339-gmt-offset ] with-string-reader duration>hours ] unit-test [ ] [ now timestamp>rfc3339 drop ] unit-test