js/public/JSON.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /*
   7  * JSON serialization and deserialization operations.
   8  */
   9
  10 #ifndef js_JSON_h
  11 #define js_JSON_h
  12
  13 #include <stdint.h>  // uint32_t
  14
  15 #include "jstypes.h"  // JS_PUBLIC_API
  16
  17 #include "js/TypeDecls.h"
  18
  19 using JSONWriteCallback = bool (*)(const char16_t* buf, uint32_t len,
  20                                    void* data);
  21
  22 /**
  23  * Performs the JSON.stringify operation, as specified by ECMAScript, except
  24  * writing stringified data by repeated calls of |callback|, with each such
  25  * call passed |data| as argument.
  26  */
  27 extern JS_PUBLIC_API bool JS_Stringify(JSContext* cx,
  28                                        JS::MutableHandle<JS::Value> value,
  29                                        JS::Handle<JSObject*> replacer,
  30                                        JS::Handle<JS::Value> space,
  31                                        JSONWriteCallback callback, void* data);
  32
  33 namespace JS {
  34
  35 /**
  36  * An API akin to JS_Stringify but with the goal of not having observable
  37  * side-effects when the stringification is performed.  This means it does not
  38  * allow a replacer or a custom space and has the following constraints on its
  39  * input:
  40  *
  41  * 1) The input must be a plain object or array, not an abitrary value.
  42  * 2) Every value in the graph reached by the algorithm starting with this
  43  *    object must be one of the following: null, undefined, a string (NOT a
  44  *    string object!), a boolean, a finite number (i.e. no NaN or Infinity or
  45  *    -Infinity), a plain object with no accessor properties, or an Array with
  46  *    no holes.
  47  *
  48  * The actual behavior differs from JS_Stringify only in asserting the above and
  49  * NOT attempting to get the "toJSON" property from things, since that could
  50  * clearly have side-effects.
  51  */
  52 extern JS_PUBLIC_API bool ToJSONMaybeSafely(JSContext* cx,
  53                                             JS::Handle<JSObject*> input,
  54                                             JSONWriteCallback callback,
  55                                             void* data);
  56
  57 } /* namespace JS */
  58
  59 /**
  60  * Performs the JSON.parse operation as specified by ECMAScript.
  61  */
  62 extern JS_PUBLIC_API bool JS_ParseJSON(JSContext* cx, const char16_t* chars,
  63                                        uint32_t len,
  64                                        JS::MutableHandle<JS::Value> vp);
  65
  66 /**
  67  * Performs the JSON.parse operation as specified by ECMAScript.
  68  */
  69 extern JS_PUBLIC_API bool JS_ParseJSON(JSContext* cx, JS::Handle<JSString*> str,
  70                                        JS::MutableHandle<JS::Value> vp);
  71
  72 /**
  73  * Performs the JSON.parse operation as specified by ECMAScript, using the
  74  * given |reviver| argument as the corresponding optional argument to that
  75  * function.
  76  */
  77 extern JS_PUBLIC_API bool JS_ParseJSONWithReviver(
  78     JSContext* cx, const char16_t* chars, uint32_t len,
  79     JS::Handle<JS::Value> reviver, JS::MutableHandle<JS::Value> vp);
  80
  81 /**
  82  * Performs the JSON.parse operation as specified by ECMAScript, using the
  83  * given |reviver| argument as the corresponding optional argument to that
  84  * function.
  85  */
  86 extern JS_PUBLIC_API bool JS_ParseJSONWithReviver(
  87     JSContext* cx, JS::Handle<JSString*> str, JS::Handle<JS::Value> reviver,
  88     JS::MutableHandle<JS::Value> vp);
  89
  90 #endif /* js_JSON_h */