GBBopen 1.5 Reference -- encode-date-and-time

encode-date-and-time

encode-date-and-time string &key start end junk-allowed date-separators time-separators month-precedes-date year-first default-to-current-year time-first time-zone => universal-time, pos [Function]

Purpose
Parse and then encode a date-and-time specification string to a Universal Time.

Package :gbbopen-tools

Module :gbbopen-tools

Arguments and values

string		A string
start		Starting index into `string` (default is `0`)
end		Ending index into `string` (default is `nil`, meaning end of `string`)
junk-allowed		A generalized boolean (default is `nil`)
date-separators		A sequence of characters that are skipped and separate the date, month, and year fields in `string`, if needed (default is `"-/ ,"`)
time-separators		A sequence of characters that are skipped and separate the hour, minute, and second fields in `string`, if needed (default is `" :"`)
month-precedes-date		A generalized boolean (default is *month-precedes-date*)
year-first		A generalized boolean (default is *year-first*)
default-to-current-year		A generalized boolean (default is `nil`)
time-first		A generalized boolean (default is *time-first*)
time-zone		A time zone (default is `nil`, which is equivalent to the current time zone adjusted for daylight saving time)
universal-time		A Universal Time
position		A index in `string`

Returns
Two values: universal-time and position

Errors
If junk-allowed is false, an error is signaled if a numeric field in string does not consist entirely of the representation of a integer, possibly surrounded on either side by characters in separators.

Description
Both the month and date must be specified in string, optionally followed by the year and the time of day. The month can be a numeric value (1–12), a three-letter abbreviation, or the full month name. If the month is specified numerically, then the value of month-precedes-date is used to determine the month and date ordering. If no year is specified in string and default-to-current-year is nil, the current calendar year is assumed, unless the specified month and date have passed, in which case the next year is assumed. If no year is specified in string and default-to-current-year is true, the current calendar year is always assumed. If no hour, minute, or second values are specified, they default to zero.

If month-precedes-date is true, the month is expected before the date; otherwise the date is expected to follow the month.

If year-first is supplied and is non-nil, the year must be provided and it is expected before the month and date; otherwise the year (if provided) is expected to follow the month and date.

If a time-zone is specified in string, it is used when encoding the universal-time value. Otherwise, if a non-nil time-zone argument was supplied, it used for the encoding. Otherwise, the current time zone adjusted for daylight saving time is used.

If time-first is true, the time-of-day is expected before the date; otherwise the time-of-day is expected to follow the date.

The returned position is the index within string where the parse ended.

Examples

  > (encode-date-and-time "1 Apr 2010")
  3479083200
  10
  > (encode-date-and-time "April 1, 2010 10:30")
  3479121000
  19
  > (encode-date-and-time "Thu 1 Apr 2010")
  3479083200
  14
  > (encode-date-and-time "Thursday, April 1, 2010 10:30")
  3479121000
  29
  > (encode-date-and-time "4/1/10 10:30pm")
  3479164200
  14
  > (encode-date-and-time "10:30pm 4/1/10" :time-first 't)
  3479164200
  14
  > (encode-date-and-time "Apr 1 2010 10:30 EDT")
  3479121000
  20
  > (encode-date-and-time "Apr 1 2010 10:30PM EDT")
  3479164200
  22
  > (encode-date-and-time "1 Apr 2010 10:30 IST")
  3479086800
  20
  > (encode-date-and-time "1 Apr 2010 10:30" :time-zone -11/2)
  3479121000
  20
  > (encode-date-and-time "1 Apr 2010 10:30 EDT" :time-zone -11/2)
  3479086800
  16
  > (encode-date-and-time "April 1, 2010 10:30 UTC-4")
  3479121000
  25
  >

REPL Note
The equivalent of:

  (print (encode-date-and-time string))

can be invoked using the REPL command :ut string.

The GBBopen Project

encode-date-and-time