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/RootingAPI.h"  // JS::Handle, JS::MutableHandle
  18
  19 struct JSContext;
  20 class JSObject;
  21 class JSString;
  22
  23 namespace JS {
  24 union Value;
  25 }
  26
  27 using JSONWriteCallback = bool (*)(const char16_t* buf, uint32_t len,
  28                                    void* data);
  29
  30 /**
  31  * Performs the JSON.stringify operation, as specified by ECMAScript, except
  32  * writing stringified data by repeated calls of |callback|, with each such
  33  * call passed |data| as argument.
  34  */
  35 extern JS_PUBLIC_API bool JS_Stringify(JSContext* cx,
  36                                        JS::MutableHandle<JS::Value> value,
  37                                        JS::Handle<JSObject*> replacer,
  38                                        JS::Handle<JS::Value> space,
  39                                        JSONWriteCallback callback, void* data);
  40
  41 namespace JS {
  42
  43 /**
  44  * An API akin to JS_Stringify but with the goal of not having observable
  45  * side-effects when the stringification is performed.  This means it does not
  46  * allow a replacer or a custom space and has the following constraints on its
  47  * input:
  48  *
  49  * 1) The input must be a plain object or array, not an abitrary value.
  50  * 2) Every value in the graph reached by the algorithm starting with this
  51  *    object must be one of the following: null, undefined, a string (NOT a
  52  *    string object!), a boolean, a finite number (i.e. no NaN or Infinity or
  53  *    -Infinity), a plain object with no accessor properties, or an Array with
  54  *    no holes.
  55  *
  56  * The actual behavior differs from JS_Stringify only in asserting the above and
  57  * NOT attempting to get the "toJSON" property from things, since that could
  58  * clearly have side-effects.
  59  */
  60 extern JS_PUBLIC_API bool ToJSONMaybeSafely(JSContext* cx,
  61                                             JS::Handle<JSObject*> input,
  62                                             JSONWriteCallback callback,
  63                                             void* data);
  64
  65 } /* namespace JS */
  66
  67 /**
  68  * Performs the JSON.parse operation as specified by ECMAScript.
  69  */
  70 extern JS_PUBLIC_API bool JS_ParseJSON(JSContext* cx, const char16_t* chars,
  71                                        uint32_t len,
  72                                        JS::MutableHandle<JS::Value> vp);
  73
  74 /**
  75  * Performs the JSON.parse operation as specified by ECMAScript.
  76  */
  77 extern JS_PUBLIC_API bool JS_ParseJSON(JSContext* cx, JS::Handle<JSString*> str,
  78                                        JS::MutableHandle<JS::Value> vp);
  79
  80 /**
  81  * Performs the JSON.parse operation as specified by ECMAScript, using the
  82  * given |reviver| argument as the corresponding optional argument to that
  83  * function.
  84  */
  85 extern JS_PUBLIC_API bool JS_ParseJSONWithReviver(
  86     JSContext* cx, const char16_t* chars, uint32_t len,
  87     JS::Handle<JS::Value> reviver, JS::MutableHandle<JS::Value> vp);
  88
  89 /**
  90  * Performs the JSON.parse operation as specified by ECMAScript, using the
  91  * given |reviver| argument as the corresponding optional argument to that
  92  * function.
  93  */
  94 extern JS_PUBLIC_API bool JS_ParseJSONWithReviver(
  95     JSContext* cx, JS::Handle<JSString*> str, JS::Handle<JS::Value> reviver,
  96     JS::MutableHandle<JS::Value> vp);
  97
  98 #endif /* js_JSON_h */