JSON.stringify()

  • Revision slug: Web/JavaScript/Reference/Global_Objects/JSON/stringify
  • Revision title: stringify
  • Revision id: 417587
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment 54 words added, 3 words removedMoved From JavaScript/Reference/Global_Objects/JSON/stringify to Web/JavaScript/Reference/Global_Objects/JSON/stringify

Revision Content

Summary

Convert a value to JSON, optionally replacing values if a replacer function is specified, or optionally including only the specified properties if a replacer array is specified.

Method of JSON
Implemented in JavaScript 1.7
ECMAScript Edition ECMAScript 5th Edition

Syntax

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

Parameters

value
The value to convert to a JSON string.
replacer
If a function, transforms values and properties encountered while stringifying; if an array, specifies the set of properties included in objects in the final string.
A detailed description of the replacer function is provided in Using native JSON#The_replacer_parameter.
space
Causes the resulting string to be pretty-printed.

Description

JSON.stringify converts an object to JSON notation representing it.

assert(JSON.stringify({}) === '{}');
assert(JSON.stringify(true) === 'true');
assert(JSON.stringify("foo") === '"foo"');
assert(JSON.stringify([1, "false", false]) === '[1,"false",false]');
assert(JSON.stringify({ x: 5 }) === '{"x":5}');
JSON.stringify({x: 5, y: 6}); // '{"x":5,"y":6}' or '{"y":6,"x":5}'

Properties of non-array objects are not guaranteed to be stringified in any particular order. Do not rely on ordering of properties within the same object within the stringification.

Boolean, Number, and String objects are converted to the corresponding primitive values during stringification, in accord with the traditional conversion semantics.

If undefined, a function, or an XML value is encountered during conversion it is either omitted (when it is found in an object) or censored to null (when it is found in an array).

space argument

The space argument may be used to control spacing in the final string. If it is a number, successive levels in the stringification will each be indented by this many space characters (up to 10). If it is a string, successive levels will indented by this string (or the first ten characters of it).

JSON.stringify({ a: 2 }, null, " ");   // '{\n "a": 2\n}'

Using a tab character mimics standard pretty-print appearance:

JSON.stringify({ uno: 1, dos : 2 }, null, '\t')
// returns the string:
// '{            \
//     "uno": 1, \
//     "dos": 2  \
// }' 

 

toJSON behavior

If an object being stringified has a property named toJSON whose value is a function, then the toJSON method customizes JSON stringification behavior: instead of the object being serialized, the value returned by the toJSON method when called will be serialized. For example:

var x = {
  foo: 'foo',
  toJSON: function () {
    return 'bar';
  }
};
var json = JSON.stringify({x: x});

json will be the string '{"x":"bar"}'.

Revision Source

<h3 id="Summary" name="Summary">Summary</h3>
<p>Convert a value to JSON, optionally replacing values if a replacer function is specified, or optionally including only the specified properties if a replacer array is specified.</p>
<table class="standard-table"> <thead> <tr> <th class="header" colspan="2">Method of <a href="/en/JavaScript/Reference/Global_Objects/JSON" title="en/JavaScript/Reference/Global_Objects/JSON"><code>JSON</code></a></th> </tr> </thead> <tbody> <tr> <td>Implemented in</td> <td>JavaScript 1.7</td> </tr> <tr> <td>ECMAScript Edition</td> <td>ECMAScript 5th Edition</td> </tr> </tbody>
</table>
<h3 id="Syntax" name="Syntax">Syntax</h3>
<p><code>JSON.stringify(<em>value</em>[, <em>replacer</em> [, <em>space</em>]])</code></p>
<h3 id="Parameters" name="Parameters">Parameters</h3>
<dl> <dt><code>value</code></dt> <dd>The value to convert to a JSON string.</dd> <dt><code>replacer</code></dt> <dd>If a function, transforms values and properties encountered while stringifying; if an array, specifies the set of properties included in objects in the final string.<br> A detailed description of the <code>replacer</code> function is provided in <a href="/En/Using_native_JSON#The_replacer_parameter" title="en/Using native JSON#The_replacer_parameter">Using native JSON#The_replacer_parameter</a>.</dd> <dt><code>space</code></dt> <dd>Causes the resulting string to be pretty-printed.</dd>
</dl>
<h3 id="Description">Description</h3>
<p><code>JSON.stringify</code> converts an object to JSON notation representing it.</p>
<pre class="brush: js">assert(JSON.stringify({}) === '{}');
assert(JSON.stringify(true) === 'true');
assert(JSON.stringify("foo") === '"foo"');
assert(JSON.stringify([1, "false", false]) === '[1,"false",false]');
assert(JSON.stringify({ x: 5 }) === '{"x":5}');
JSON.stringify({x: 5, y: 6}); // '{"x":5,"y":6}' or '{"y":6,"x":5}'
</pre>
<p>Properties of non-array objects are not guaranteed to be stringified in any particular order. Do not rely on ordering of properties within the same object within the stringification.</p>
<p>Boolean, Number, and String objects are converted to the corresponding primitive values during stringification, in accord with the traditional conversion semantics.</p>
<p>If <code>undefined</code>, a function, or an XML value is encountered during conversion it is either omitted (when it is found in an object) or censored to null (when it is found in an array).</p>
<h4 id="space_argument"><code>space</code> argument</h4>
<p>The space argument may be used to control spacing in the final string. If it is a number, successive levels in the stringification will each be indented by this many space characters (up to 10). If it is a string, successive levels will indented by this string (or the first ten characters of it).</p>
<pre class="brush: js">JSON.stringify({ a: 2 }, null, " ");   // '{\n "a": 2\n}'</pre>
<p>Using a tab character mimics standard pretty-print appearance:</p>
<pre class="brush: js">JSON.stringify({ uno: 1, dos : 2 }, null, '\t')
// returns the string:
// '{            \
//     "uno": 1, \
//     "dos": 2  \
// }' </pre>
<p> </p>
<h4 id="toJSON_behavior">toJSON behavior</h4>
<p>If an object being stringified has a property named <code>toJSON</code> whose value is a function, then the <code>toJSON</code> method customizes JSON stringification behavior: instead of the object being serialized, the value returned by the <code>toJSON</code> method when called will be serialized. For example:</p>
<pre class="brush: js">var x = {
  foo: 'foo',
  toJSON: function () {
    return 'bar';
  }
};
var json = JSON.stringify({x: x});
</pre>
<p><code>json</code> will be the string <code>'{"x":"bar"}'</code>.</p>
Revert to this revision