15.6 Time

► |  | The Racket Reference

1 | Language Model
2 | Notation for Documentation
3 | Syntactic Forms
4 | Datatypes
5 | Structures
6 | Classes and Objects
7 | Units
8 | Contracts
9 | Pattern Matching
10 | Control Flow
11 | Concurrency and Parallelism
12 | Macros
13 | Input and Output
14 | Reflection and Security
15 | Operating System
16 | Memory Management
17 | Unsafe Operations
18 | Running Racket
| Bibliography
| Index

▼ | 15 | Operating System

15.1 | Paths
15.2 | Filesystem
15.3 | Networking
15.4 | Processes
15.5 | Logging
15.6 | Time
15.7 | Environment Variables
15.8 | Environment and Runtime Information
15.9 | Command-Line Parsing
15.10 | Additional Operating System Functions

► | 15.6 | Time

15.6.1 | Date Utilities

On this page:

current-seconds
current-inexact-milliseconds
seconds->date
date
date*
current-milliseconds
current-process-milliseconds
current-gc-milliseconds
time-apply
time
15.6.1`` Date Utilities
current-date
date->string
date-display-format
date->seconds
date*->seconds
find-seconds
date->julian/ scaliger
julian/ scaliger->string

top ← prev up next →

#### 15.6`` Time

> procedure (current-seconds) → exact-integer?

Returns the current time in seconds since midnight UTC, January 1, 1970.

> procedure (current-inexact-milliseconds) → real?

Returns the current time in milliseconds since midnight UTC, January 1, 1970. The result may contain fractions of a millisecond.

Example:

> > (current-inexact-milliseconds)
> 1289513737015.418

In this example, 1289513737015 is in milliseconds and 418 is in microseconds.

> procedure (seconds->date secs-n [local-time?]) → date*?
> secs-n : real?
> local-time? : any/c = #t

Takes secs-n, a platform-specific time in seconds returned by current-seconds, file-or-directory-modify-seconds, or 1/1000th of current-inexact-milliseconds, and returns an instance of the date* structure type. Note that secs-n can include fractions of a second. If secs-n is too small or large, the exn:fail exception is raised.

The resulting date* reflects the time according to the local time zone if local-time? is #t, otherwise it reflects a date in UTC.

> > struct
> > (struct |  | date | ( | second
> > |  |  |  | minute
> > |  |  |  | hour
> > |  |  |  | day
> > |  |  |  | month
> > |  |  |  | year
> > |  |  |  | week-day
> > |  |  |  | year-day
> > |  |  |  | dst?
> > |  |  |  | time-zone-offset)
> #:extra-constructor-name make-date
> #:transparent)
> second : (integer-in 0 60)
> minute : (integer-in 0 59)
> hour : (integer-in 0 23)
> day : (integer-in 1 31)
> month : (integer-in 1 12)
> year : exact-integer?
> week-day : (integer-in 0 6)
> year-day : (integer-in 0 365)
> dst? : boolean?
> time-zone-offset : exact-integer?

Represents a date. The second field reaches 60 only for leap seconds. The week-day field is 0 for Sunday, 1 for Monday, etc. The year-day field is 0 for January 1, 1 for January 2, etc.; the year-day field reaches 365 only in leap years.

The dst? field is #t if the date reflects a daylight-saving adjustment. The time-zone-offset field reports the number of seconds east of UTC (GMT) for the current time zone (e.g., Pacific Standard Time is -28800), including any daylight-saving adjustment (e.g., Pacific Daylight Time is -25200). When a date record is generated by seconds->date with #f as the second argument, then the dst? and time-zone-offset fields are #f and 0, respectively.

The date constructor accepts any value for dst? and converts any non-#f value to #t.

The value produced for the time-zone-offset field tends to be sensitive to the value of the TZ environment variable, especially on Unix platforms; consult the system documentation (usually under tzset) for details.

See also the racket/date library.

> > struct
> > (struct |  | date* date (nanosecond time-zone-name)
> #:extra-constructor-name make-date*)
> nanosecond : (integer-in 0 999999999)
> time-zone-name : (and/c string? immutable?)

Extends date with nanoseconds and a time zone name, such as "MDT", "Mountain Daylight Time", or "UTC".

When a date* record is generated by seconds->date with #f as the second argument, then the time-zone-name field is "UTC".

The date* constructor accepts a mutable string for time-zone-name and converts it to an immutable one.

> procedure (current-milliseconds) → exact-integer?

Like current-inexact-milliseconds, but coerced to a fixnum (possibly negative). Since the result is a fixnum, the value increases only over a limited (though reasonably long) time on a 32-bit platform.

> procedure (current-process-milliseconds [scope]) → exact-integer?
> scope : (or/c #f thread? 'subprocesses) = #f

Returns an amount of processor time in fixnum milliseconds that has been consumed by on the underlying operating system, including both user and system time.

- If scope is #f, the reported time is for all Racket threads and places.

- If scope is a thread, the result is specific to the time while the thread ran, but it may include time for other places.

- If scope is 'subprocesses, the result is the sum of process times for known-completed subprocesses (see Processes)—and known-completed children of the subprocesses, etc., on Unix and Mac OS—across all places.

The precision of the result is platform-specific, and since the result is a fixnum, the value increases only over a limited (though reasonably long) time on a 32-bit platform.

Changed in version 6.1.1.4 of package base: Added 'subprocesses mode.

> procedure (current-gc-milliseconds) → exact-integer?

Returns the amount of processor time in fixnum milliseconds that has been consumed by Racket’s garbage collection so far. This time is a portion of the time reported by (current-process-milliseconds), and is similarly limited.

> > procedure
> > (time-apply proc lst) |  | → |  |
> > list?
> > exact-integer?
> > exact-integer?
> > exact-integer?
> proc : procedure?
> lst : list?

Collects timing information for a procedure application.

Four values are returned: a list containing the result(s) of applying proc to the arguments in lst, the number of milliseconds of CPU time required to obtain this result, the number of “real” milliseconds required for the result, and the number of milliseconds of CPU time (included in the first result) spent on garbage collection.

The reliability of the timing numbers depends on the platform. If multiple Racket threads are running, then the reported time may include work performed by other threads.

> syntax (time body ...+)

Reports time-apply-style timing information for the evaluation of expr directly to the current output port. The result is the result of the last body.

##### 15.6.1`` Date Utilities

> > > For more date & time operations, see the Gregor: Date and Time documentation or srfi/19

(require racket/date) | package: base

The bindings documented in this section are provided by the racket/date library, not racket/base or racket.

> procedure (current-date) → date*?

An abbreviation for (seconds->date (* 0.001 (current-inexact-milliseconds))).

> procedure (date->string date [time?]) → string?
> date : date?
> time? : any/c = #f

Converts a date to a string. The returned string contains the time of day only if time?. See also date-display-format.

> > parameter
> > (date-display-format) |  | → |  |
> > (or/c 'american
> > 'chinese
> > 'german
> > 'indian
> > 'irish
> > 'iso-8601
> > 'rfc2822
> > 'julian)
> (date-display-format format) → void?
> | format |  | : |  |
> (or/c 'american
> 'chinese
> 'german
> 'indian
> 'irish
> 'iso-8601
> 'rfc2822
> 'julian)

Parameter that determines the date string format. The initial format is 'american.

> procedure (date->seconds date [local-time?]) → exact-integer?
> date : date?
> local-time? : any/c = #t

Finds the representation of a date in platform-specific seconds. If the platform cannot represent the specified date, exn:fail exception is raised.

The week-day, year-day fields of date are ignored. The dst? and time-zone-offset fields of date are also ignored; the date is assumed to be in local time by default or in UTC if local-time? is #f.

> procedure (date*->seconds date [local-time?]) → real?
> date : date?
> local-time? : any/c = #t

Like date->seconds, but returns an exact number that can include a fraction of a second based on (date*-nanosecond date) if date is a date* instance.

> > procedure
> > (find-seconds |  | second |  |  |  |
> > |  | minute |  |  |  |
> > |  | hour |  |  |  |
> > |  | day |  |  |  |
> > |  | month |  |  |  |
> > |  | year |  |  |  |
> > | [ | local-time?]) |  | → |  | exact-integer?
> second : (integer-in 0 61)
> minute : (integer-in 0 59)
> hour : (integer-in 0 23)
> day : (integer-in 1 31)
> month : (integer-in 1 12)
> year : exact-nonnegative-integer?
> local-time? : any/c = #t

Finds the representation of a date in platform-specific seconds. The arguments correspond to the fields of the date structure—in local time by default or UTC if local-time? is #f. If the platform cannot represent the specified date, an error is signaled, otherwise an integer is returned.

> procedure (date->julian/scaliger date) → exact-integer?
> date : date?

Converts a date structure (up to 2099 BCE Gregorian) into a Julian date number. The returned value is not a strict Julian number, but rather Scaliger’s version, which is off by one for easier calculations.

> procedure (julian/scaliger->string date-number) → string?
> date-number : exact-integer?

Converts a Julian number (Scaliger’s off-by-one version) into a string.
top ← prev up next →