#lang scribble/doc @(require (file "base.ss")) @title[#:tag "time"]{SRFI19 time utilities} @(define-eval time-eval srfi/19 (planet untyped/unlib/time)) @defmodule[(planet untyped/unlib/time)]{ Utility procedures for use with SRFI 19 times and dates. @defproc[(copy-date [date srfi:date?] [#:nanosecond nanosecond (U integer #f) #f] [#:second second (U integer #f) #f] [#:minute minute (U integer #f) #f] [#:hour hour (U integer #f) #f] [#:day day (U integer #f) #f] [#:month month (U integer #f) #f] [#:year year (U integer #f) #f] [#:zone-offset zone-offset (U integer #f) #f]) srfi:date?]{ Creates a copy of @scheme[date], substituting non-@scheme[#f] arguments for the values of the relevant fields.} @defproc[(time->date [time (U time-tai? time-utc?)]) srfi:date?]{ Converts @scheme[time] to a date.} @defproc[(time-utc? [item any]) boolean?]{ Predicate that recognises SRFI-19 @scheme[time]@schemeidfont{s} of the @scheme[time-utc] type.} @defproc[(time-tai? [item any]) boolean?]{ Predicate that recognises SRFI-19 @scheme[time]@schemeidfont{s} of the @scheme[time-tai] type.} @defproc[(time-duration? [item any]) boolean?]{ Predicate that recognises SRFI-19 @scheme[time]@schemeidfont{s} of the @scheme[time-duration] type.} @defproc[(leap-year? [year integer?]) boolean?]{ Returns @scheme[#t] if @scheme[year] is a leap year.} @defproc[(days-in-month [month integer?] [year integer? 2001]) integer?]{ Returns the number of days in @scheme[month] in @scheme[year]. @scheme[month] is numbered from 1 to 12. @scheme[year] defaults to a non-leap year if omitted. @examples[ #:eval time-eval (days-in-month 2) (days-in-month 2 2000)]} @defproc[(date-valid? [date srfi:date?]) boolean?]{ Returns @scheme[#t] if @scheme[date] is a valid date (its hour, day, month and so on are all in the correct ranges).} @defproc[(date-day-of-the-week [date date?]) (U 'mon 'tue 'wed 'thu 'fri 'sat 'sun)]{ Returns a symbol representing the day of the week on @scheme[date].} @defproc[(date-week-day? [date date?]) boolean?]{ Returns @scheme[#t] if @scheme[date] is a Monday, Tuesday, Wednesday or Friday.} @defproc[(time->ago-string [then (U time-tai time-utc)] [now (U time-tai time-utc) (current-time (time-type then))] [#:format format-string string? "~a ~a ago"] [#:short? boolean? #f]) string?]{ Given the time of an event the past (and, optionally, another argument representing the current time), returns a textual description of the time passed since the event. Raises exn:fail:unlib if @scheme[now] is before @scheme[then]. See @scheme[seconds->ago-string] for examples. The optional @scheme[format-string] argument should have two wildcards in it: one for the number (1, 2, 59) and one for the unit (seconds, minutes, days). The format string is ignored if the result is @scheme["yesterday"]. The optional @scheme[short?] argument can be set to @scheme[#t] to use abbreviated time units (such as @scheme["min"] rather than @scheme["minute"]).} @defproc[(seconds->ago-string [secs integer?] [now integer? (current-seconds)] [#:format format-string string? "~a ~a ago"] [#:short? boolean? #f]) string?]{ Like @scheme[time->ago-string] but @scheme[then] and @scheme[now] are integer values like those output by @scheme[current-seconds]. @examples[ #:eval time-eval (seconds->ago-string (- (current-seconds) 45)) (seconds->ago-string (- (current-seconds) (* 30 60))) (seconds->ago-string (- (current-seconds) (* 20 60 60))) (seconds->ago-string (- (current-seconds) (* 25 60 60))) (seconds->ago-string (- (current-seconds) (* 50 60 60)))]} @defproc[(current-year) integer?]{ Returns the current four digit year.} @defproc[(current-time-zone-offset) integer?]{ Returns the current local time-zone offset in seconds (taking into account DST when and where appropriate).} } @;{end defmodule}