JSON.parse Function (JavaScript) and JSON.stringify Function (JavaScript)

JSON.parse Function (JavaScript) and JSON.stringify Function (JavaScript)

Deserializes JavaScript Object Notation (JSON) text to produce a JavaScript value.

JSON.parse(text [, reviver]) 

Arguments

text

Required. Valid JSON text.

reviver

Optional. A function that filters and transforms the results. The deserialized object is traversed recursively, and the reviver function is called for each member of the object in post-order (every object is revived after all its members have been revived). For each member, the following occurs:

• If reviver returns a valid value, the member value is replaced with the value returned by reviver.

• If reviver returns what it received, the structure is not modified.

• If reviver returns null or undefined, the object member is deleted.

The reviver argument is often used to transform JSON representation of International Organization for Standardization (ISO) date strings into Coordinated Universal Time (UTC) format Date objects.

Return Value

A JavaScript value—an object or array.

Exceptions

Exception	Condition
JavaScript parser errors	The input text does not comply with JSON syntax. To correct the error, do one of the following: Modify the text argument to comply with JSON syntax. For more information, see the BNF syntax notation of JSON objects. Make sure that the text argument was serialized by a JSON-compliant implementation, such as, JSON.stringify.

Example

This example uses JSON.parse to deserialize JSON text into the contact object.

JavaScript

var jsontext = '{"firstname":"Jesper","surname":"Aaberg","phone":["555-0100","555-0120"]}'; var contact = JSON.parse(jsontext); var fullname = contact.surname + ", " + contact.firstname; // The value of fullname is "Aaberg, Jesper" 

This example uses JSON.parse to deserialize an ISO-formatted date string. The dateReviver function returns Date objects for members that are formatted like ISO date strings.

JavaScript

var jsontext = '{ "hiredate": "2008-01-01T12:00:00Z", "birthdate": "2008-12-25T12:00:00Z" }'; var dates = JSON.parse(jsontext, dateReviver); var string = dates.birthdate.toUTCString(); // The value of string is "Thu, 25 Dec 2008 12:00:00 UTC"  function dateReviver(key, value) {     var a;     if (typeof value === 'string') {         a = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2}(?:\.\d*)?)Z$/.exec(value);         if (a) {             return new Date(Date.UTC(+a[1], +a[2] - 1, +a[3], +a[4],                             +a[5], +a[6]));         }     }     return value; }; 

Requirements

Supported in the following document modes: Internet Explorer 8 standards, Internet Explorer 9 standards. See Version Information.

Not supported in the following document modes: Quirks, Internet Explorer 6 standards, Internet Explorer 7 standards.

Serializes a JavaScript value into JavaScript Object Notation (JSON) text.

JSON.stringify(value [, replacer] [, space]) 

Arguments

value

Required. A JavaScript value, usually an object or array, to be serialized.

replacer

Optional. A function or array that filters and transforms the results.

If replacer is a function, JSON.stringify calls the function, passing in the key and value of each member. The return value is serialized instead of the original value. If the function returns undefined, the member will be excluded from the serialization. The key for the root object is an empty string: "".

If replacer is an array, only members with key values in the array will be serialized. The order of serialization is the same as the order of the keys in the array. Thereplacer array is ignored when the value argument is also an array.

space

Optional. Adds indentation, white space, and line break characters to the return-value JSON text to make it easier to read.

If space is omitted, the return-value text is generated without any extra white space.

If space is a number, the return-value text is indented with the specified number of white spaces at each level. If space is greater than 10, text is indented 10 spaces.

If space is a non-empty string, such as '\t', the return-value text is indented with the characters in the string at each level.

If space is a string that is longer than 10 characters, the first 10 characters are used.

Return Value

A string that contains the serialized JSON text.

Exceptions

Exception	Condition
Invalid replacer argument	The replacer argument is not a function or an array.
Circular reference in value argument not supported	The value argument contains a circular reference.

Remarks

If the value that is being serialized has a toJSON method, the JSON.stringify function calls the toJSON method and uses the return value for serialization. If the return value of the toJSON method is undefined, the member will not be serialized. This enables an object to determine its own JSON representation.

Values that do not have JSON representations, such as undefined, will not be serialized. In objects, they will be dropped. In arrays, they will be replaced with null.

String values begin and end with a quotation mark. All Unicode characters may be enclosed in the quotation marks except for the characters that must be escaped by using a backslash. The following characters must be preceded by a backslash:

• Quotation mark (")

• Backslash (\)

• Backspace (b)

• Formfeed (f)

• Newline (n)

• Carriage return (r)

• Horizontal tab (t)

• Four-hexadecimal-digits (uhhhh)

Order of Execution

During the serialization process, if a toJSON method exists for the value argument, JSON.stringify first calls the toJSON method. If it does not exist, the original value is used. Next, if a replacer argument is provided, the value (original value or toJSON return-value) is replaced with the return-value of the replacer argument. Finally, white spaces are added to the value based on the optional space argument to generate the final serialized JSON text.

Example

This example uses JSON.stringify to serialize the contact object to JSON text. The memberfilter array is defined so that only the surname and phone members are serialized. The firstname member is omitted.

JavaScript

var contact = new Object(); contact.firstname = "Jesper"; contact.surname = "Aaberg"; contact.phone = ["555-0100", "555-0120"];  var memberfilter = new Array(); memberfilter[0] = "surname"; memberfilter[1] = "phone"; var jsonText = JSON.stringify(contact, memberfilter, "\t"); /* The value of jsonText is: '{     "surname": "Aaberg",     "phone": [         "555-0100",         "555-0120"     ] }' */ 

This example uses JSON.stringify to serialize an array. The replaceToUpper function converts every string in the array to uppercase.

JavaScript

var continents = new Array(); continents[0] = "Europe"; continents[1] = "Asia"; continents[2] = "Australia"; continents[3] = "Antarctica"; continents[4] = "North America"; continents[5] = "South America"; continents[6] = "Africa";  var jsonText = JSON.stringify(continents, replaceToUpper); /* The value of jsonText is: '"EUROPE,ASIA,AUSTRALIA,ANTARCTICA,NORTH AMERICA,SOUTH AMERICA,AFRICA"' */  function replaceToUpper(key, value) {     return value.toString().toUpperCase(); } 

This example uses the toJSON method to serialize string member values in uppercase.

JavaScript

var contact = new Object();  contact.firstname = "Jesper"; contact.surname = "Aaberg"; contact.phone = ["555-0100", "555-0120"];  contact.toJSON = function(key)  {     var replacement = new Object();     for (var val in this)     {         if (typeof (this[val]) === 'string')             replacement[val] = this[val].toUpperCase();         else             replacement[val] = this[val]     }     return replacement; };  var jsonText = JSON.stringify(contact);  /* The value of jsonText is: '{"firstname":"JESPER","surname":"AABERG","phone":["555-0100","555-0120"]}' */ 

Requirements

Supported in the following document modes: Internet Explorer 8 standards, Internet Explorer 9 standards. See Version Information.

Not supported in the following document modes: Quirks, Internet Explorer 6 standards, Internet Explorer 7 standards.

http://msdn.microsoft.com/library/cc836459(VS.85).aspx