mozilla

Revision 313345 of Using native JSON

  • Revision slug: Using_native_JSON
  • Revision title: Using native JSON
  • Revision id: 313345
  • Created:
  • Creator: Allasso
  • Is current revision? No
  • Comment corrected typo error

Revision Content

{{ gecko_minversion_header("1.9.1") }}

This article covers the ECMAScript 5 compliant native JSON object added in Gecko 1.9.1.  For basic information on using JSON in previous versions of Firefox, see JSON.

The native JSON object includes two key methods.  The JSON.parse() method parses a JSON string, reconstructing the original JavaScript object, while the JSON.stringify() method accepts a JavaScript object and returns its JSON equivalent.

Note: JSON does not support objects that include methods.  Attempting to convert such an object into JSON format will result in a TypeError exception.

Parsing JSON strings

To convert a JSON string into a JavaScript object, you simply pass the JSON string into the JSON.parse() method, like this:

var jsObject = JSON.parse(jsonString);

{{ js_minversion_note("1.8.5", "Starting in JavaScript 1.8.5 (Firefox 4), JSON.parse() does not allow trailing commas") }}

// both will throw an SyntaxError as of JavaScript 1.8.5
var jsObject = JSON.parse("[1, 2, 3, 4, ]");
var jsObject = JSON.parse("{ \"foo\" : 1, }");

Converting objects into JSON

To convert a JavaScript object into a JSON string, pass the object into the JSON.stringify() method:

var foo = {};
foo.bar = "new property";
foo.baz = 3;

var jsonString = JSON.stringify(foo);

jsonString now holds '{"bar":"new property","baz":3}'.

{{ fx_minversion_header("3.5.4") }}

Starting in Firefox 3.5.4, JSON.stringify() offers additional customization capabilities through the use of optional parameters. The syntax is:

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

value
The JavaScript object to convert into a JSON string.
replacer
A function that alters the behavior of the stringification process, or an array of String and Number objects that serve as a whitelist for selecting the properties of the value object to be included in the JSON string. If this value is null or not provided, all properties of the object are included in the resulting JSON string.
space
A String or Number object that's used to insert white space into the output JSON string for readability purposes. If this is a Number, it indicates the number of space characters to use as white space; this number is capped at 10 if it's larger than that. Values less than 1 indicate that no space should be used. If this is a String, the string (or the first 10 characters of the string, if it's longer than that) is used as white space. If this parameter is not provided (or is null), no white space is used.

The replacer parameter

The replacer parameter can be either a function or an array. As a function, it takes two parameters, the key and the value being stringified. Initially it gets called with an empty key representing the object being stringified, and it then gets called for each property on the object or array being stringified. It should return the value that should be added to the JSON string, as follows:

  • If you return a Number, the string corresponding to that number is used as the value for the property when added to the JSON string.
  • If you return a String, that string is used as the property's value when adding it to the JSON string.
  • If you return a Boolean, "true" or "false" is used as the property's value, as appropriate, when adding it to the JSON string.
  • If you return any other object, the object is recursively stringified into the JSON string, calling the replacer function on each property, unless the object is a function, in which case nothing is added to the JSON string.
  • If you return undefined, the property is not included in the output JSON string.
Note: You cannot use the replacer function to remove values from an array. If you return undefined or a function then null is used instead.

Example

function censor(key, value) {
  if (typeof(value) == "string") {
    return undefined;
  }
  return value;
}

var foo = {foundation: "Mozilla", model: "box", week: 45, transport: "car", month: 7};
var jsonString = JSON.stringify(foo, censor);

The resulting JSON string is {"week":45,"month":7}.

If replacer is an array, the array's values indicate the names of the properties in the object that should be included in the resulting JSON string.

See also

{{ languages( { "ja": "ja/Using_native_JSON" ,"zh-cn": "zh-cn/Using_native_JSON" } ) }}

Revision Source

<p>{{ gecko_minversion_header("1.9.1") }}</p>
<p>This article covers the ECMAScript 5 compliant native JSON&nbsp;object added in Gecko 1.9.1.&nbsp; For basic information on using JSON&nbsp;in previous versions of Firefox, see <a class="internal" href="/en/JSON" title="En/JSON">JSON</a>.</p>
<p>The native JSON&nbsp;object includes two key methods.&nbsp; The <code>JSON.parse()</code>&nbsp;method parses a JSON string, reconstructing the original JavaScript object, while the <code>JSON.stringify()</code>&nbsp;method accepts a JavaScript object and returns its JSON&nbsp;equivalent.</p>
<div class="note">
  <strong>Note:</strong> JSON&nbsp;does not support objects that include methods.&nbsp; Attempting to convert such an object into JSON&nbsp;format will result in a <code>TypeError</code> exception.</div>
<h2 id="Parsing_JSON.C2.A0strings">Parsing JSON&nbsp;strings</h2>
<p>To convert a JSON&nbsp;string into a JavaScript object, you simply pass the JSON string into the <code>JSON.parse()</code>&nbsp;method, like this:</p>
<pre>
var jsObject = JSON.parse(jsonString);</pre>
<p>{{ js_minversion_note("1.8.5", "Starting in JavaScript 1.8.5 (Firefox 4), <code>JSON.parse()</code> does not allow trailing commas") }}</p>
<pre>
// both will <code>throw an SyntaxError</code> as of JavaScript 1.8.5
var jsObject = JSON.parse("[1, 2, 3, 4, ]");
var jsObject = JSON.parse("{ \"foo\" : 1, }");
</pre>
<h2 id="Converting_objects_into_JSON">Converting objects into JSON</h2>
<p>To convert a JavaScript object into a JSON&nbsp;string, pass the object into the <code>JSON.stringify()</code>&nbsp;method:</p>
<pre class="brush: js">
var foo = {};
foo.bar = "new property";
foo.baz = 3;

var jsonString = JSON.stringify(foo);
</pre>
<p><code>jsonString</code> now holds <code>'{"bar":"new property","baz":3}'</code>.</p>
<p>{{ fx_minversion_header("3.5.4") }}</p>
<p>Starting in Firefox 3.5.4, <code>JSON.stringify()</code> offers additional customization capabilities through the use of optional parameters. The syntax is:</p>
<p><code>jsonString = JSON.stringify(<em>value</em> [, <em>replacer</em> [, <em>space</em>]])</code></p>
<dl>
  <dt>
    <code>value</code></dt>
  <dd>
    The JavaScript object to convert into a JSON&nbsp;string.</dd>
  <dt>
    <code>replacer</code></dt>
  <dd>
    A function that alters the behavior of the stringification process, or an array of <a href="/en/JavaScript/Guide/Obsolete_Pages/Predefined_Core_Objects/String_Object" title="en/Core JavaScript 1.5 Guide/Predefined Core Objects/String Object"><code>String</code></a> and <a href="/En/Core_JavaScript_1.5_Reference/Global_Objects/Number" title="en/Core JavaScript 1.5 Reference/Global Objects/Number"><code>Number</code></a> objects that serve as a whitelist for selecting the properties of the value object to be included in the JSON&nbsp;string. If this value is null or not provided, all properties of the object are included in the resulting JSON&nbsp;string.</dd>
  <dt>
    <code>space</code></dt>
  <dd>
    A <a href="/en/JavaScript/Guide/Obsolete_Pages/Predefined_Core_Objects/String_Object" title="en/Core JavaScript 1.5 Guide/Predefined Core
    Objects/String Object"><code>String</code></a> or <a href="/En/Core_JavaScript_1.5_Reference/Global_Objects/Number" title="en/Core JavaScript 1.5 Reference/Global
    Objects/Number"><code>Number</code></a> object that's used to insert white space into the output JSON&nbsp;string for readability purposes. If this is a <code>Number</code>, it indicates the number of space characters to use as white space; this number is capped at 10 if it's larger than that. Values less than 1 indicate that no space should be used. If this is a <code>String</code>, the string (or the first 10 characters of the string, if it's longer than that) is used as white space. If this parameter is not provided (or is null), no white space is used.</dd>
</dl>
<h3 id="The_replacer_parameter">The replacer parameter</h3>
<p>The <code>replacer</code> parameter can be either a function or an array. As a function, it takes two parameters, the key and the value being stringified. Initially it gets called with an empty key representing the object being stringified, and it then gets called for each property on the object or array being stringified. It should return the value that should be added to the JSON&nbsp;string, as follows:</p>
<ul>
  <li>If you return a <a href="/En/Core_JavaScript_1.5_Reference/Global_Objects/Number" title="en/Core JavaScript 1.5 Reference/Global Objects/Number"><code>Number</code></a>, the string corresponding to that number is used as the value for the property when added to the JSON&nbsp;string.</li>
  <li>If you return a <a href="/en/Core_JavaScript_1.5_Guide/Predefined_Core_Objects/String" title="en/Core JavaScript 1.5 Guide/Predefined Core Objects/String"><code>String</code></a>, that string is used as the property's value when adding it to the JSON string.</li>
  <li>If you return a <a href="/en/JavaScript/Reference/Global_Objects/Boolean" title="en/Core JavaScript 1.5 Reference/Global Objects/Boolean"><code>Boolean</code></a>, "true" or "false" is used as the property's value, as appropriate, when adding it to the JSON string.</li>
  <li>If you return any other object, the object is recursively stringified into the JSON string, calling the <code>replacer</code> function on each property, unless the object is a function, in which case nothing is added to the JSON string.</li>
  <li>If you return <code>undefined</code>, the property is not included in the output JSON string.</li>
</ul>
<div class="note">
  <strong>Note:</strong> You cannot use the <code>replacer</code> function to remove values from an array. If you return <code>undefined</code> or a function then <code>null</code> is used instead.</div>
<h4 id="Example">Example</h4>
<pre class="brush: js">
function censor(key, value) {
&nbsp; if (typeof(value) == "string") {
&nbsp;&nbsp;&nbsp; return undefined;
&nbsp; }
&nbsp; return value;
}

var foo = {foundation: "Mozilla", model: "box", week: 45, transport: "car", month: 7};
var jsonString = JSON.stringify(foo, censor);
</pre>
<p>The resulting JSON&nbsp;string is <code>{"week":45,"month":7}</code>.</p>
<p>If <code>replacer</code> is an array, the array's values indicate the names of the properties in the object that should be included in the resulting JSON&nbsp;string.</p>
<h2 id="See_also">See also</h2>
<ul>
  <li><a class="internal" href="/En/JavaScript/ECMAScript_5_support_in_Mozilla" title="En/JavaScript/ECMAScript 5 support in Mozilla">ECMAScript 5 support in Mozilla</a></li>
  <li><a class="internal" href="/en/JSON" title="En/JSON">JSON</a></li>
</ul>
<p>{{ languages( { "ja": "ja/Using_native_JSON" ,"zh-cn": "zh-cn/Using_native_JSON" } ) }}</p>
Revert to this revision