Sign in Join
FPDoc Onlineexperiment

TryISOStrToDateTime function

In unit DateUtils

Attempts to convert an ISO 8601-formatted date/time value to a TDateTime type.

Declaration

pascal
function TryISOStrToDateTime(const aString: string; 
 out outDateTime: TDateTime): Boolean

Arguments

aString

ISO 8601 date/time value examined in the function.

outDateTime

TDateTime type containing the date and time values from the function.

Function result

True if the time value is successfully converted to a TDateTime type.

Description

TryISOStrToDateTime is a Boolean function which attempts to convert an ISO 8601-formatted date/time value to a TDateTime type. aString contains the date/time value examined in the routine, and can use one of the supported ISO 8601 notations. Internally, TryISOStrToDateTime separates the value in aString into date and time parts and calls both TryISOStrToDate and TryISOStrToTime.

outDateTime is a TDateTime output parameter where the date/time value is stored in the function.

The date/time value examined in the routine can use one of the supported ISO 8601 notations. For example: 

[DATE][SEPARATOR][TIME][TIMEZONE]

where [DATE] can be one of the following formats:

  • YYYY (assumes month is 1 and day of month is 1)
  • YYYYMM (assumes day of month is 1)
  • YYYYMMDD (eg 20210827)
  • YYYY-MM (assumes day of month is 1)
  • YYYY-MM-DD (eg 2021-08-27)

[SEPARATOR] can contain the following:

  • T (literal character that marks the start of the time element). The Space character ( #32) is also allowed as the separator at the start of the time value.

[TIME] can use one of the following formats:

  • hhmm
  • hh:mm
  • hhmmss
  • hh:mm:ss
  • hhmmss.zzz (arbitrary number of digits for fractions of a second)
  • hh:mm:ss.zzz (arbitrary number of digits for fractions of a second)

A time value with a fractional number of seconds can use either the '.' (Period) or ',' (Comma) character for the decimal point.

[TIMEZONE] is an optional time zone designation, and uses one of the following notations:

  • Z (Time zone Zulu or UTC)
  • ±hh (Positive or negative offset hours)
  • ±hhmm (Positive or negative offset hours and minutes)
  • ±hh:mm (Positive or negative offset hours and minutes)

In the above, the following formats are used:

YYYY
Four digits for year
MM
Two digits for month (01=January, etc.)
DD
Two digits for day of month (01 through 31)
T
Literal character used as a marker for the time value
hh
Two digits for hour (00 through 23) (am/pm NOT allowed)
mm
Two digits for minute (00 through 59)
ss
Two digits for seconds (00 through 59)
z
One or more digits representing the fractional seconds value (no maximum precision limit)

The return value is True if aString is successfully parsed and converted to a TDateTime type. The return value is False if aString contains a value that cannot be parsed in the function. When the return value is False, outDateTime is set to 0 (representing an empty date/time value).

Use TryISOStrToDate or TryISOStrToTime to convert a string using only a date or a time value (respectively).

Use TryISO8601ToDate to convert a string value which uses more intricate forms of the ISO 8601 time notation.

See also

An experiment, built from development snapshots. Not the official Free Pascal or Lazarus documentation.