API: json YAHOO.lang.JSON (YUI Library)

# Yahoo! UI Library

### json 2.8.1

Yahoo! UI Library > json > YAHOO.lang.JSON
Search:
Filters Show Private Show Protected Show Deprecated

## `static` Class YAHOO.lang.JSON

Provides methods to parse JSON strings and convert objects to JSON strings.

### Properties

#### _BRACKETS - `private static {RegExp}`

Third step in the safety evaluation. Regex used to remove all open square brackets following a colon, comma, or at the beginning of the string.

#### _CHARS - `private static {Object}`

Character substitution map for common escapes and special characters.

#### _ESCAPES - `private static {RegExp}`

First step in the safety evaluation. Regex used to replace all escape sequences (i.e. "\\", etc) with '@' characters (a non-JSON character).

#### _SPECIAL_CHARS - `private static {RegExp}`

Regex used to replace special characters in strings for JSON stringification.

#### _UNICODE_EXCEPTIONS - `private {RegExp}`

Replace certain Unicode characters that JavaScript may handle incorrectly during eval--either by deleting them or treating them as line endings--with escape sequences. IMPORTANT NOTE: This regex will be used to modify the input if a match is found.

#### _UNSAFE - `private static {RegExp}`

Final step in the safety evaluation. Regex used to test the string left after all previous replacements for invalid characters.

#### _VALUES - `private static {RegExp}`

Second step in the safety evaluation. Regex used to replace all simple values with ']' characters.

#### useNativeParse - `static Boolean`

Leverage native JSON parse if the browser has a native implementation. In general, this is a good idea. See the Known Issues section in the JSON user guide for caveats. The default value is true for browsers with native JSON support.
Default Value: true

#### useNativeStringify - `static Boolean`

Leverage native JSON stringify if the browser has a native implementation. In general, this is a good idea. See the Known Issues section in the JSON user guide for caveats. The default value is true for browsers with native JSON support.
Default Value: true

### Methods

#### _prepare

`private String _prepare ( s )`
Replace certain Unicode characters that may be handled incorrectly by some browser implementations.

Parameters:
  `s <String>` parse input

Returns: `String`
  sanitized JSON string ready to be validated/parsed

#### _revive

`private MIXED _revive ( data , reviver )`
Traverses nested objects, applying a filter or reviver function to each value. The value returned from the function will replace the original value in the key:value pair. If the value returned is undefined, the key will be omitted from the returned object.

Parameters:
  `data <MIXED>` Any JavaScript data
  `reviver <Function>` filter or mutation function

Returns: `MIXED`
  The results of the filtered/mutated data structure

#### dateToString

`static String dateToString ( d )`
Serializes a Date instance as a UTC date string. Used internally by the JavaScript implementation of stringify. If you need a different Date serialization format, override this method. If you change this, you should also set useNativeStringify to false, since native JSON implementations serialize Dates per the ECMAScript 5 spec. You've been warned.

Parameters:
  `d <Date>` The Date to serialize

Returns: `String`
  stringified Date in UTC format YYYY-MM-DDTHH:mm:SSZ

#### isSafe

`static boolean isSafe ( str )`
Four step determination whether a string is safe to eval. In three steps, escape sequences, safe values, and properly placed open square brackets are replaced with placeholders or removed. Then in the final step, the result of all these replacements is checked for invalid characters.

Parameters:
  `str <String>` JSON string to be tested

Returns: `boolean`
  is the string safe for eval?

#### isValid

`static boolean isValid ( str )`

Four step determination whether a string is safe to eval. In three steps, escape sequences, safe values, and properly placed open square brackets are replaced with placeholders or removed. Then in the final step, the result of all these replacements is checked for invalid characters.

This is an alias for isSafe.

Parameters:
  `str <String>` JSON string to be tested

Returns: `boolean`
  is the string safe for eval?

Deprecated use isSafe

#### parse

`static MIXED parse ( s , reviver )`

Parse a JSON string, returning the native JavaScript representation.

When lang.JSON.useNativeParse is true, this will defer to the native JSON.parse if the browser has a native implementation. Otherwise, a JavaScript implementation based on http://www.json.org/json2.js is used.

Parameters:
  `s <string>` JSON string data
  `reviver <function>` (optional) function(k,v) passed each key:value pair of object literals, allowing pruning or altering values

Returns: `MIXED`
  the native JavaScript representation of the JSON string

#### stringify

`static string stringify ( o , w , space )`

Converts an arbitrary value to a JSON string representation.

Objects with cyclical references will trigger an exception.

If a whitelist is provided, only matching object keys will be included. Alternately, a replacer function may be passed as the second parameter. This function is executed on every value in the input, and its return value will be used in place of the original value. This is useful to serialize specialized objects or class instances.

If a positive integer or non-empty string is passed as the third parameter, the output will be formatted with carriage returns and indentation for readability. If a String is passed (such as "\t") it will be used once for each indentation level. If a number is passed, that number of spaces will be used.

When lang.JSON.useNativeStringify is true, this will defer to the native JSON.stringify if the browser has a native implementation. Otherwise, a JavaScript implementation is used.

Parameters:
  `o <MIXED>` any arbitrary object to convert to JSON string
  `w <Array|Function>` (optional) whitelist of acceptable object keys to include OR a function(value,key) to alter values before serialization
  `space <Number|String>` (optional) indentation character(s) or depthy of spaces to format the output

Returns: `string`
  JSON string representation of the input

#### stringToDate

`Date stringToDate ( str )`
Reconstitute Date instances from the default JSON UTC serialization. Reference this from a reviver function to rebuild Dates during the parse operation.

Parameters:
  `str <String>` String serialization of a Date

Copyright © 2010 Yahoo! Inc. All rights reserved.