# xs:dateTime

Converts $string-var (a string in the dateTime format) to the dateTime data type.

If the value of $string-var is the empty sequence, the empty sequence is returned. The empty sequence is a sequence containing zero items (), which is similar to null in SQL.

If the value of $string-var is not valid to the dateTime format the following error is reported:

Could not cast "invalid_dateTime_string" to type [date@htttp://www.w3.org/2001/XMLSchema] is displayed.

Where invalid_dateTime_string is the string not valid to the date format, for example: "2003-08-16T21:10".

### Signatures

xs:dateTime(xs:string $string-var) —> xs:dateTime

### Arguments

Data Type | Argument | Description
--- | --- | ---
xs:string | $string-var | Represents a string with the date and time specified with one of the following formats: YYYY-MM-DDThh:mm:ss.sssssss YYYY-MM-DDThh:mm:ss.sssssssZ YYYY-MM-DDThh:mm:ss.sssssss+hh:mm YYYY-MM-DDThh:mm:ss.sssssss-hh:mm
| YYYY | Year.
MM | Month (as a number).
DD | Day.
T | Date and Time separator.
hh | Number of hours.
mm | Number of minutes.
ss.sssssss | Number of seconds. Seconds can be specified up to 7 digits after the decimal place. (Format xx.xxxxxxx)
: | Separator between hours, minutes, or seconds.
+ | Positive time zone offset. This option is optional. If a plus or minus is not specified, + is assumed.
- | Negative time zone offset. (Optional)
hh | Number of hours that the time zone differs from UTC.
mm | Number of minutes that the time zone differs from UTC.
Z | Indicates that the time corresponds to the UTC time zone.

### Returns

Returns the specified date and time in the dateTime data type.

### Examples

#### Simple

Invoking dateTime("2003-08-16T21:10:50") returns a dateTime value corresponding to August 16th, 2003 at 9:10PM (21:10 in twenty four hour time) and 50 seconds in the current time zone, as shown in the following example query:

    let $mydate := xs:dateTime("2003-08-16T21:10:50")
    return
    <components>
    	<year>{xf:get-year-from-dateTime($mydate)}</year>
    	<month>{xf:get-month-from-dateTime($mydate)}</month>
    	<day>{xf:get-day-from-dateTime($mydate)}</day>
    	<hour>{xf:get-hours-from-dateTime($mydate)}</hour>
    	<minute>{xf:get-minutes-from-dateTime($mydate)}</minute>
    	<second>{xf:get-seconds-from-dateTime($mydate)}</second>
    </components>

The preceding query, generates the following XML result:

    <components>
    	<year>2003</year>
    	<month>8</month>
    	<day>16</day>
    	<hour>21</hour>
    	<minute>10</minute>
    	<second>50</second>
    </components>

#### Seconds with Decimal

Invoking dateTime("2003-08-16T21:10:50.577") returns a dateTime value corresponding to August 16th, 2003 at 9:10 PM (21:10 in twenty four hour time) and 50.577 seconds in the current time zone, as shown in the following example query:

    let $mydate := xs:dateTime("2003-08-16T21:10:50.557")
    return
    <components>
    	<year>{xf:get-year-from-dateTime($mydate)}</year>
    	<month>{xf:get-month-from-dateTime($mydate)}</month>
    	<day>{xf:get-day-from-dateTime($mydate)}</day>
    	<hour>{xf:get-hours-from-dateTime($mydate)}</hour>
    	<minute>{xf:get-minutes-from-dateTime($mydate)}</minute>
    	<second>{xf:get-seconds-from-dateTime($mydate)}</second>
    </components>

The preceding query, generates the following XML result:

    <components>
    	<year>2003</year>
    	<month>8</month>
    	<day>16</day>
    	<hour>21</hour>
    	<minute>10</minute>
    	<second>50.5570000</second>
    </components>

#### UTC Time Zone

Invoking dateTime("2003-08-16T21:10:50Z") returns a dateTime value corresponding to August 16th, 2003 at 9:10 PM (21:10 in twenty four hour time) and 50 seconds, in the UTC time zone, as shown in the following example query:

    let $mydate := xs:dateTime("2003-08-16T21:10:50Z")
    return
    <components>
    	<year>{xf:get-year-from-dateTime($mydate)}</year>
    	<month>{xf:get-month-from-dateTime($mydate)}</month>
    	<day>{xf:get-day-from-dateTime($mydate)}</day>
    	<hour>{xf:get-hours-from-dateTime($mydate)}</hour>
    	<minute>{xf:get-minutes-from-dateTime($mydate)}</minute>
    	<second>{xf:get-seconds-from-dateTime($mydate)}</second>
    </components>

The preceding query, generates the following XML result:

    <components>
    	<year>2003</year>
    	<month>8</month>
    	<day>16</day>
    	<hour>21</hour>
    	<minute>10</minute>
    	<second>50</second>
    </components>

#### Offset Time Zone

Invoking dateTime("2003-08-16T13:10:50-07:00") returns a dateTime value corresponding to August 16th, 2003 at 1:10 PM (13:10 in twenty four hour time) and 50 seconds, in the Pacific Daylight Savings (PDT) time zone that is offset by -7 hours from UTC (Universal Time, Coordinated), as shown in the following example query:

    let $mydate := xs:dateTime("2003-08-16T13:10:50-07:00")
    return
    <components>
    	<year>{xf:get-year-from-dateTime($mydate)}</year>
    	<month>{xf:get-month-from-dateTime($mydate)}</month>
    	<day>{xf:get-day-from-dateTime($mydate)}</day>
    	<hour>{xf:get-hours-from-dateTime($mydate)}</hour>
    	<minute>{xf:get-minutes-from-dateTime($mydate)}</minute>
    	<second>{xf:get-seconds-from-dateTime($mydate)}</second>
    </components>

The preceding query, generates the following XML result:

    <components>
    	<year>2003</year>
    	<month>8</month>
    	<day>16</day>
    	<hour>20</hour>
    	<minute>10</minute>
    	<second>50</second>
    </components>

The conversion of the date and time is shown in the following figure.

#### Error—No Seconds

Invoking dateTime("2003-08-16T21:10") outputs an error because seconds are not specified.

For example, the following example query:

    <result>{xs:dateTime("2003-08-16T21:10")}</result>

Produces the following error:

    Error occurred while executing XQuery: Could not cast "2003-08-16T21:10" to type [dateTime@http://www.w3.org/2001/XMLSchema]

#### Error—Incorrect Format

Invoking dateTime("2003-8-16T21:10:50") outputs an error because the month is not specified using two digits.

For example, the following example query:

    <result>{xs:dateTime("2003-8-16T21:10:50")}</result>

Produces the following error:

    Error occurred while executing XQuery: Could not cast "2003-8-16T21:10:50" to type [dateTime@http://www.w3.org/2001/XMLSchema]

Related Topics

W3C dateTime data type description