GBBopen 1.5 Reference -- full-date-and-time

full-date-and-time

full-date-and-time &optional universal-time &key time-zone daylight-savings-p all-numeric separator full-names month-precedes-date year-first include-day include-seconds include-time-zone utc-offset-only 12-hour destination => result [Function]

Purpose
Generate a date-and-time description.

Package :gbbopen-tools

Module :gbbopen-tools

Arguments and values

universal-time		A Universal Time (default is `nil`, which is equivalent to the value returned by `(get-universal-time)`)
time-zone		A time zone (default is `nil`, which is equivalent to the current time zone adjusted for daylight saving time)
daylight-savings-p		A generalized boolean (default is `nil`)
all-numeric		A generalized boolean (default is `nil`)
separator		A character (default is `#\/`)
full-names		A generalized boolean (default is `nil`)
month-precedes-date		A generalized boolean (default is *month-precedes-date*)
year-first		A generalized boolean (default is *year-first*)
include-day		A generalized boolean (default is `nil`)
include-time-zone		A generalized boolean (default is `nil`)
utc-offset-only		A generalized boolean (default is `nil`)
12-hour		A generalized boolean (default is `nil`)
destination		Either `nil`, `t`, a stream, or a string with a fill pointer (default is `nil`)
result		A string or `nil`

Returns
If destination is non-nil, then nil; otherwise, a string.

Description
A 17-character description (longer if full-names, include-day, include-seconds, include-time-zone, or utc-offset-only are non-nil) is generated.

If universal-time is not supplied or is nil, the current time (as returned by get-universal-time is used.

If time-zone is not supplied or is nil, it defaults to the current time zone adjusted for daylight saving time. If a time-zone is supplied, it is assumed to include any adjustment for daylight saving time unless daylight-savings-p is specified and is non-nil.

If all-numeric is supplied and is non-nil, the month is indicated by its numeric value, and the date, month, and year are separated by the separator character.

If full-names is supplied and is non-nil, the full name is generated rather than the abbreviated name for the month (if include-day is nil) and for the day of the week, (if include-day is non-nil).

If month-precedes-date is true, the month is presented in front of the date; otherwise the date precedes the month.

If year-first is supplied and is non-nil, the year is presented in front of the month and date; otherwise the year follows the month and date.

If include-day is supplied and is non-nil, the day of the week is included in front of the date and time.

If include-seconds is supplied and is non-nil, seconds are included in the presented time.

If either include-time-zone or utc-offset-only is true, a time-zone specification is appended to the date-and-time presentation. If utc-offset-only is true, the time zone is presented as a UTC offset—even if a time-zone abbreviation supported by GBBopen Tools is available for the time zone. If a time-zone is supplied, the value of daylight-savings-p is used when generating a non-UTC time zone abbreviation; otherwise, the local daylight-savings setting for the universal-time value (as determined by decode-universal-time) is used, and the daylight-savings-p argument is ignored.

If 12-hour is supplied and is non-nil, the time-of-day is presented in AM/PM format.

Examples
Display the current date and time:

  > (full-date-and-time)
  "Feb 16 2009 13:11"
  >

Display the current date and time (with seconds):

  > (full-date-and-time nil :include-seconds 't)
  "Feb 16 2009 13:11:38"
  >

Display the current date and time (with the day of the week):

  > (full-date-and-time nil :include-day 't)
  "Mon Feb 16 2009 13:11"
  >

Display the current date and time (with no abbreviations and with the day of the week):

  > (full-date-and-time nil :full-names 't :include-day 't)
  "Monday, February 16, 2009 13:11"
  >

Display the current date and time (with no abbreviations, with the month following the date, and with the day of the week):

  > (full-date-and-time nil :full-names 't :include-day 't
                            :month-precedes-date nil)
  "Monday, 16 February, 2009 13:11"
  >

Display the current date and time (with no abbreviations, with the year first and the month following the date, and with the day of the week):

  > (full-date-and-time nil :full-names 't :include-day 't
                            :year-first 't :month-precedes-date nil)
  "2009, 16 February, Monday 13:11"
  >

Display the current date and time (all numeric, with the abbreviated day of the week):

  > (full-date-and-time nil :all-numeric 't :include-day 't)
  "Mon 02/16/2009 13:11"
  >

Display the current date and time (all numeric, with hyphen (minus-sign) separators):

  > (full-date-and-time nil :all-numeric 't :separator #)
  "02-16-2009 13:11"
  >

Display the current date and time (all numeric, with the year first and the abbreviated day of the week):

  > (full-date-and-time nil :all-numeric 't :year-first 't :include-day 't)
  "2009/02/16 Mon 13:11"
  >

Display the current date and time (all numeric, with the month following the date, and with the full day of the week):

  > (full-date-and-time nil :all-numeric 't :include-day 't 
                            :full-names 't :month-precedes-date nil)
  "Monday, 16/02/2009 13:11"
  >

Display the current date and time (with time zone):

  > (full-date-and-time nil :include-time-zone 't)
  "Feb 16 2009 13:11 EST"
  >

Display the current date and time (in 12-hour format with time zone):

  > (full-date-and-time nil :12-hour 't :include-time-zone 't)
  "Feb 16 2009 1:11PM EST"
  >

Display the current date and time (with UTC-offset time zone):

  > (full-date-and-time nil :utc-offset-only 't)
  "Feb 16 2009 13:11 UTC-5"
  >

Display the current date and time (with seconds and time zone):

  > (full-date-and-time nil
      :include-seconds 't 
      :include-time-zone 't)
  "Feb 16 2009 13:11:38 EST"
  >

Display the current date and time as GMT:

  > (full-date-and-time nil :time-zone 0)
  "Feb 16 2009 18:11"
  >

Display the current date and time as GMT (with time zone):

  > (full-date-and-time nil 
      :time-zone 0 
      :include-time-zone 't)
  "Feb 16 2009 18:11 GMT"
  >

The date and time 10 days ago:

  > (full-date-and-time (- (get-universal-time) (parse-duration "10 days")))
  "Feb  6 2009 13:11"
  >

The date and time 125 days ago:

  > (full-date-and-time (- (get-universal-time) (parse-duration "125 days")))
  "Oct 12 2008 13:11"
  >

The date and time 125 days ago (with seconds):

  > (full-date-and-time (- (get-universal-time) (parse-duration "125d"))
      :include-seconds 't)
  "Oct 12 2008 13:11:38"
  >

REPL Note
The equivalent of:

  (print (full-date-and-time universal-time 
            :include-seconds 't))

can be invoked using the REPL command :ut universal-time.

The GBBopen Project

full-date-and-time