UTOD( ) function

Converts a Unicode string containing a formatted date to an Analytics date value. Abbreviation for "Unicode to Date".

Note

This function is specific to the Unicode edition of Analytics. It is not a supported function in the non-Unicode edition.

Use this function when working with dates in languages and formats that are different from your default installation. If the string you want to convert is in your default language, use CTOD( ) instead.

Syntax

UTOD(string <,locale> <,style>)

Parameters

Name	Type	Description
string	character	The Unicode string to convert to a date. The Unicode string can contain a datetime value, but the time portion of the value is ignored. Standalone time values are not supported. string must match the input format required by the style value for the date's locale.
locale optional	character	The code that specifies the language and locale of the output string, and optionally the version of the language associated with a particular country or region. For example, "zh" specifies Chinese, and "pt_BR" specifies Brazilian Portuguese. If omitted, the default locale for your computer is used. If a language is specified, but no country is specified, the default country for the language is used. You cannot specify locale if you have not specified date. For more information about locale codes, see www.unicode.org.
style optional	numeric	The date format style to use for the Unicode string. The format style matches the standard for the locale you specify: 0 – full specification format, such as "Sunday, September 18, 2016" 1 – long format, such as "September 18, 2016" 2 – medium format, such as "Sep 18, 2016" 3 – short, numeric format such as "9/18/16" If omitted, the default value of 2 is used. You cannot specify style if you have not specified locale. Tip For help determining the expected format of your input string, do one of the following: Use the DTOU( ) function to generate an example value using the style and locale. In the command line, use the DISPLAY command to print the value: DISPLAY DTOU(`20160909`, "es_MX", 3) Consult an authoritative source on the standard date format for the style in the specific locale.

Name

Type

Description

string

character

The Unicode string to convert to a date.

The Unicode string can contain a datetime value, but the time portion of the value is ignored. Standalone time values are not supported.

string must match the input format required by the style value for the date's locale.

locale

optional

character

The code that specifies the language and locale of the output string, and optionally the version of the language associated with a particular country or region.

For example, "zh" specifies Chinese, and "pt_BR" specifies Brazilian Portuguese.

If omitted, the default locale for your computer is used. If a language is specified, but no country is specified, the default country for the language is used.

You cannot specify locale if you have not specified date.

For more information about locale codes, see www.unicode.org.

style

optional

numeric

The date format style to use for the Unicode string. The format style matches the standard for the locale you specify:

0 – full specification format, such as "Sunday, September 18, 2016"
1 – long format, such as "September 18, 2016"
2 – medium format, such as "Sep 18, 2016"
3 – short, numeric format such as "9/18/16"

If omitted, the default value of 2 is used. You cannot specify style if you have not specified locale.

Tip

For help determining the expected format of your input string, do one of the following:

Use the DTOU( ) function to generate an example value using the style and locale.

In the command line, use the DISPLAY command to print the value:
```
DISPLAY DTOU(`20160909`, "es_MX", 3)
```
Consult an authoritative source on the standard date format for the style in the specific locale.

Output

Datetime. The date value is output using the current Analytics date display format.

Examples

Basic examples

Note

All examples assume a current Analytics date display format of DD MMM YYYY.

In the examples below, the locale code for Chinese ( "zh" ) and Simplified Chinese ( "zh_CN" ) match different input strings and are not interchangeable.

You must also specify the correct style. A long Unicode date string (that is, style is 1 ) does not return an Analytics date if you specify a style of 2.

Literal input values

Returns `20141231` displayed as 31 Dec 2014:

UTOD("31 de dezembro de 2014", "pt_BR", 1)

Returns `20141231` displayed as 31 Dec 2014:

UTOD("31 grudnia 2014", "pl", 1)

Field input values

Returns the date equivalent for each Unicode string in the Invoice_date field:

UTOD(Invoice_date, "zh", 1)

Input uses full date style

Returns `20141231` displayed as 31 Dec 2014 (no region identifier specified):

UTOD("星期三, 2014 十二月 31", "zh", 0)

Returns `20141231` displayed as 31 Dec 2014 (region identifier specified):

UTOD("2014年12月31日星期三", "zh_CN", 0)

Input uses long date style

Returns `20141231` displayed as 31 Dec 2014 (no region identifier specified):

UTOD("2014 十二月 31", "zh", 1)

Returns `20141231` displayed as 31 Dec 2014 (region identifier specified):

UTOD("2014年12月31日", "zh_CN", 1)

Remarks

Date and time functions can sometimes be challenging to use correctly. In the Help, function topics describe the specific details of how each function works. For information about some general considerations when using date and time functions, see the following topics:

Converting Unicode strings successfully

To successfully convert Unicode strings containing dates into Analytics dates you must specify locale and style parameters that match the language country/region (if applicable), and style of the date in the Unicode string.

Related functions

UTOD( ) is the inverse of DTOU( ), which converts a date to a Unicode string. If you are uncertain which country/region and style to specify for UTOD( ), you can use DTOU( ) and experiment with different parameters to produce an output Unicode string that matches the form of the input Unicode strings you want to convert with UTOD( ).