# xs:date

Converts $string-var (a string in the date format) to the date 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 date format the following error is reported:

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

Where invalid_date_string is the string not valid to the date format, for example: "2003-04-31".

### Signatures

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

### Arguments

Data Type | Argument | Description
--- | --- | ---
xs:string | $string-var | Represents a string with the date specified with one of the following formats: YYYY-MM-DD YYYY-MM-DD Z YYYY-MM-DD+hh:mm YYYY-MM-DD-hh:mm
| YYYY | Year.
MM | Month (as a number).
DD | Day.
- | Separator between year, month, and day.
hh | Number of hours.
mm | Number of minutes.
: | Separator between hours and minutes.
+ | Positive time zone offset (If a plus or minus is not specified, + is assumed.)
- | Negative time zone offset.
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 in the date data type.

### Examples

#### Simple

Invoking date("2003-08-16")returns a date value corresponding to August 16th, 2003 in the current time zone, as shown in the following example query:

    let $mydate := xs:date("2003-08-16")
    return
    <components>
    	<year>{xf:get-year-from-date($mydate)}</year>
    	<month>{xf:get-month-from-date($mydate)}</month>
    	<day>{xf:get-day-from-date($mydate)}</day>
    </components>

The preceding query, generates the following XML result:

    <components>
    	<year>2003</year>
    	<month>8</month>
    	<day>16</day>
    </components>

#### UTC Time Zone

Invoking date("2003-08-16Z") returns a date value corresponding to August 16th, 2003 in the UTC time zone, as shown in the following example query:

    let $mydate := xs:date("2003-08-16Z")
    return
    <components>
    	<year>{xf:get-year-from-date($mydate)}</year>
    	<month>{xf:get-month-from-date($mydate)}</month>
    	<day>{xf:get-day-from-date($mydate)}</day>
    </components>

Note: The Z in the a date string, specifies that the date is specified in the UTC time zone.

The preceding query, generates the following XML result:

    <components>
    	<year>2003</year>
    	<month>8</month>
    	<day>16</day>
    </components>

#### Offset Time Zone

Invoking date("2003-08-16-02:00") returns a date value corresponding to August 16th, 2003 in a time zone that is offset by -2 hours from UTC, as shown in the following example query:

    let $mydate := xs:date("2003-08-16-02:00")
    return
    <components>
    	<year>{xf:get-year-from-date($mydate)}</year>
    	<month>{xf:get-month-from-date($mydate)}</month>
    	<day>{xf:get-day-from-date($mydate)}</day>
    </components>

The preceding query, generates the following XML result:

    <components>
    	<year>2003</year>
    	<month>8</month>
    	<day>16</day>
    </components>

#### Error—Not A Valid Date

Invoking date("2003-04-31") outputs an error because April 31, 2003 is not a valid date. (There are not 31 days in April.)

For example, the following example query:

    <result>{xs:date("2003-04-31")}</result>

Produces the following error:

    Error occurred while executing XQuery: Could not cast "2003-04-31" to type [date@http://www.w3.org/2001/XMLSchema]

#### Error—Incorrect Format

Invoking date("2003-8-16") outputs an error because the month is not specified using two digits.

For example, the following example query:

    <result>{xs:date("2003-8-16")}</result>

Produces the following error:

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

Related Topics

W3C date data type description