Skip to main content

Visit Mozilla.org

nsIJSON

From MDC

This article covers features introduced in Firefox 3

DRAFT
This page is not complete.

The nsIJSON interface provides a convenient way to encode and decode JSON strings from JavaScript code.

Note: This interface may only be used from JavaScript code.

Contents

nsIJSON is defined in dom/public/idl/json/nsIJSON.idl. It is scriptable and unfrozen (hasn't changed since Mozilla 1.9).

Inherits from: nsISupports

Implemented by: @mozilla.org/dom/json;1. To create an instance, use: 

var nativeJSON = Components.classes["@mozilla.org/dom/json;1"]
                 .createInstance(Components.interfaces.nsIJSON);

[edit] Method overview

Note: The IDL file has portions of the IDL commented out because they represent things that can't actually be properly described by IDL; however, for the purposes of this article, we'll pretend they can be and ignore that issue.
JSObject decode(in AString str, [optional] in JSObject whitelist);
JSObject decodeFromStream(in nsIInputStream stream, in long contentLength, [optional] in JSObject optFilter);
AString encode(in JSObject value, [optional] in JSObject whitelist);
void encodeToStream(in nsIOutputStream stream, in string charset, in boolean writeBOM, in JSObject value, [optional] in JSObject optFilter);

[edit] Methods

[edit] decode()

Decodes a JSON string, returning the JavaScript object it represents. 

 JSObject decode(
   in AString str,
   [optional] in JSObject whitelist
 );
[edit] Parameters
str
The JSON string to decode.
whitelist
 ?
[edit] Return value

The original JavaScript object, reconstructed from the JSON string.

[edit] decodeFromStream()

Decodes a JSON string read from an input stream, returning the JavaScript object it represents. 

 JSObject decodeFromStream(
   in nsIInputStream stream,
   in long contentLength,
   [optional] in JSObject optFilter
 );
[edit] Parameters
stream
The nsIInputStream from which to read the JSON string.
contentLength
The length of the JSON string to read.
optFilter
 ?
[edit] Return value

A JSObject which is the original JavaScript object, reconstructed from the JSON string.

[edit] encode()

Encodes a JavaScript object into a JSON string. 

 AString encode(
   in JSObject value,
   [optional] in JSObject whitelist
 );
[edit] Parameters
value
The JavaScript object to encode.
whitelist
 ?
[edit] Return value

A JSON string representing the object.

[edit] encodeToStream()

Encodes a JavaScript object into JSON format, writing it to a stream. 

 void encodeToStream(
   in nsIOutputStream stream,
   in string charset,
   in boolean writeBOM
   in JSObject value,
   [optional] in JSObject optFilter
 );
[edit] Parameters
stream
The nsIOutputStream to which to write the JSON string.
charset
The string encoding to use. For example, "UTF-8", "UTF-16LE", "UTF-16BE", and so forth.
writeBOM
Specify true if you wish to write a byte-order mark (BOM) into the stream, otherwise specify false.
value
The JavaScript object to encode.
optFilter
?

[edit] Examples

[edit] Encoding an object

var myObj = {"foo":"bar"};

var myJSONString = nativeJSON.encode(myObj);

The resulting string is '{"foo":"bar"}'.

[edit] Decoding a JSON string

You can then pass that string into decode() to get the original object back, like this: 

var myObj2 = nativeJSON.decode(myJSONString);

[edit] See also

Retrieved from "http://developer.mozilla.org/en/docs/nsIJSON"