#

Jump to Table of Contents

# DataType

The DataType Utility is a collection of classes that provide type-conversion and string-formatting convenience methods for numbers, dates, and XML documents.

## Getting Started

To include the source files for DataType and its dependencies, first load the YUI seed file if you haven't already loaded it.

    <script src="http://yui.yahooapis.com/3.10.3/build/yui/yui-min.js"></script>

Next, create a new YUI instance for your application and populate it with the modules you need by specifying them as arguments to the `YUI().use()` method. YUI will automatically load any dependencies required by the modules you specify.

    <script>
    // Create a new YUI instance and populate it with the required modules.
    YUI().use('datatype', function (Y) {
        // DataType is available and ready for use. Add implementation
        // code here.
    });
    </script>

For more information on creating YUI instances and on the `use()` method, see the documentation for the YUI Global Object.

## Using the DataType utility

### Dates

#### Formatting dates

`Y.Date.format()` will output dates as strings formatted using `strftime` tokens. Some of the formats are localizable, so be sure to specify the `lang` property of the YUI instance's config object.

    YUI({lang:"ko-KR"}).use("datatype-date", function(Y) {
        // display the current date and time in localized format
        Y.log(Y.Date.format(new Date(), {format:"%x %X"}));
    });

The module has support for a large number of languages built in. If you need a language that's not supported, you can register the necessary localized data yourself using facilities of the Internationalization utility. The resource bundle you provide needs to have properties corresponding to the locale-sensitive strftime format specifiers:

- a: list of abbreviated weekday names, from Sunday to Saturday
- A: list of full weekday names, from Sunday to Saturday
- b: list of abbreviated month names, from January to December
- B: list of full month names, from January to December
- c: preferred date and time representation
- p: list of strings corresponding to "AM" and "PM"
- P: same as "p", but lower case
- x: preferred date representation without the time
- X: preferred time representation without the date

    YUI().use("intl", "datatype-date-format", function(Y) {
        // provide data for Punjabi in India
        Y.Intl.add("datatype-date-format", "pa-IN", {
            "a":["ਐਤ.","ਸੋਮ.","ਮੰਗਲ.","ਬੁਧ.","ਵੀਰ.","ਸ਼ੁਕਰ.","ਸ਼ਨੀ."],
            "A":["ਐਤਵਾਰ","ਸੋਮਵਾਰ","ਮੰਗਲਵਾਰ","ਬੁਧਵਾਰ","ਵੀਰਵਾਰ","ਸ਼ੁੱਕਰਵਾਰ","ਸ਼ਨੀਚਰਵਾਰ"],
            "b":["ਜਨਵਰੀ","ਫ਼ਰਵਰੀ","ਮਾਰਚ","ਅਪ੍ਰੈਲ","ਮਈ","ਜੂਨ","ਜੁਲਾਈ","ਅਗਸਤ","ਸਤੰਬਰ","ਅਕਤੂਬਰ","ਨਵੰਬਰ","ਦਸੰਬਰ"],
            "B":["ਜਨਵਰੀ","ਫ਼ਰਵਰੀ","ਮਾਰਚ","ਅਪ੍ਰੈਲ","ਮਈ","ਜੂਨ","ਜੁਲਾਈ","ਅਗਸਤ","ਸਤੰਬਰ","ਅਕਤੂਬਰ","ਨਵੰਬਰ","ਦਸੰਬਰ"],
            "c":"%a, %Y %b %d %l:%M:%S %p %Z",
            "p":["ਸਵੇਰੇ","ਸ਼ਾਮ"],
            "P":["ਸਵੇਰੇ","ਸ਼ਾਮ"],
            "x":"%d/%m/%Y",
            "X":"%l:%M:%S %p"
        });
        // switch to Punjabi
        Y.Intl.setLang("datatype-date-format", "pa-IN");
        // now dates are formatted in Punjabi
        Y.log(Y.Date.format(new Date(), {format:"%A %x %X"}));
    });

#### Parsing dates

`Y.Date.parse()` accepts any single value supported by the JavaScript `Date()` constructor and converts it to a Date object. Invalid values will return null.

    var date1 = Y.Date.parse("December 17, 1995 03:24:00");

    var date2 = Y.Date.parse("1995,11,17");

    var date3 = Y.Date.parse(948548583);

### Numbers

#### Formatting numbers

JavaScript Number values can be formatted with a variety options into string values using `Y.Number.format()`.

    Y.log(Y.Number.format(123123123.176,{
        prefix: "€",
        thousandsSeparator: ".",
        decimalSeparator: ",",
        decimalPlaces: 2,
        suffix: " (EUR)"
    }));

#### Parsing numbers

String values can be converted into Number objects with `Y.Number.parse()`.

    var number = Y.Number.parse("123123");

### XML

#### Formatting XML

`Y.XML.format()` will accept an XML document and return its string representation. Note that browsers may slightly differ in the exact string that is returned.

    var myString = Y.XML.format(myXMLDocument);

#### Parsing XML

`Y.XML.parse()` will accept a string representation of XML and return an XML document object. Note that browsers differ in their handling of invalid syntax but will in general return an XML document even under error conditions.

    var myXMLDocument = Y.XML.parse("<myroot><item type='foo'><name>Abc</name><rank>1</rank></item><item type='bar'><name>Def</name><rank>2</rank></item><item type='bat'><name>Ghhi</name><rank>3</rank></item></myroot>");

### Y.Parsers shortcuts

The functions `Y.Date.parse()` and `Y.Number.parse()` are registered with the `Parsers` object for seamless integration with the DataSchema Utility. For dynamic type enforcing when data is being normalized against a schema, simply point to the appropriate function using the built-in shortcut in your schema definition. Parsing your data in this manner is essential if your numerical or date data comes over the wire as JSON, since all the values will be strings.

    YUI().use("datatype", "dataschema", function(Y) {
        var data_in = {
                "results":[
                    {"string":"aardvark", "number":"1", "date":"Jan 1, 2001"},
                    {"string":"bat", "number":"2", "date":"Feb 2, 2002"},
                    {"string":"camel", "number":"3", "date":"March 3, 2003"}
                ]
            },
            schema = {
                resultListLocator: "results",
                resultFields: [
                    "string", // needs no parsing
                    {key:"number", parser: "number"}, // converts string values to numbers
                    {key:"date", parser: "date"}] // converts string values to dates
            },
            data_out = Y.DataSchema.JSON.apply(schema, data_in);
    });