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