A JSON value represented as a C++ class. More...

#include <json.h>

Public Types
enum	value_type { Number, Boolean, String, Object, Array, Null }
	This enumeration represents the various kinds of JSON values. More...

Public Member Functions
_ASYNCRTIMP	value ()
	Constructor creating a null value More...

_ASYNCRTIMP	value (int32_t value)
	Constructor creating a JSON number value More...

_ASYNCRTIMP	value (uint32_t value)
	Constructor creating a JSON number value More...

_ASYNCRTIMP	value (int64_t value)
	Constructor creating a JSON number value More...

_ASYNCRTIMP	value (uint64_t value)
	Constructor creating a JSON number value More...

_ASYNCRTIMP	value (double value)
	Constructor creating a JSON number value More...

_ASYNCRTIMP	value (bool value)
	Constructor creating a JSON Boolean value More...

_ASYNCRTIMP	value (utility::string_t value)
	Constructor creating a JSON string value More...

_ASYNCRTIMP	value (utility::string_t value, bool has_escape_chars)
	Constructor creating a JSON string value specifying if the string contains characters to escape More...

_ASYNCRTIMP	value (const utility::char_t *value)
	Constructor creating a JSON string value More...

_ASYNCRTIMP	value (const utility::char_t *value, bool has_escape_chars)
	Constructor creating a JSON string value More...

_ASYNCRTIMP	value (const value &)
	Copy constructor More...

_ASYNCRTIMP	value (value &&) CPPREST_NOEXCEPT
	Move constructor More...

_ASYNCRTIMP value &	operator= (const value &)
	Assignment operator. More...

_ASYNCRTIMP value &	operator= (value &&) CPPREST_NOEXCEPT
	Move assignment operator. More...

_ASYNCRTIMP json::value::value_type	type () const
	Accesses the type of JSON value the current value instance is More...

bool	is_null () const
	Is the current value a null value? More...

bool	is_number () const
	Is the current value a number value? More...

_ASYNCRTIMP bool	is_integer () const
	Is the current value represented as an integer number value? More...

_ASYNCRTIMP bool	is_double () const
	Is the current value represented as an double number value? More...

bool	is_boolean () const
	Is the current value a Boolean value? More...

bool	is_string () const
	Is the current value a string value? More...

bool	is_array () const
	Is the current value an array? More...

bool	is_object () const
	Is the current value an object? More...

size_t	size () const
	Gets the number of children of the value. More...

_ASYNCRTIMP utility::string_t	serialize () const
	Serializes the current JSON value to a C++ string. More...

_ASYNCRTIMP void	serialize (utility::ostream_t &stream) const
	Writes the current JSON value to a stream with the native platform character width. More...

_ASYNCRTIMP double	as_double () const
	Converts the JSON value to a C++ double, if and only if it is a number value. Throws json_exception if the value is not a number More...

_ASYNCRTIMP int	as_integer () const
	Converts the JSON value to a C++ integer, if and only if it is a number value. Throws json_exception if the value is not a number More...

_ASYNCRTIMP const json::number &	as_number () const
	Converts the JSON value to a number class, if and only if it is a number value. Throws json_exception if the value is not a number More...

_ASYNCRTIMP bool	as_bool () const
	Converts the JSON value to a C++ bool, if and only if it is a Boolean value. More...

_ASYNCRTIMP json::array &	as_array ()
	Converts the JSON value to a json array, if and only if it is an array value. More...

_ASYNCRTIMP const json::array &	as_array () const
	Converts the JSON value to a json array, if and only if it is an array value. More...

_ASYNCRTIMP json::object &	as_object ()
	Converts the JSON value to a json object, if and only if it is an object value. More...

_ASYNCRTIMP const json::object &	as_object () const
	Converts the JSON value to a json object, if and only if it is an object value. More...

_ASYNCRTIMP const utility::string_t &	as_string () const
	Converts the JSON value to a C++ STL string, if and only if it is a string value. More...

_ASYNCRTIMP bool	operator== (const value &other) const
	Compares two JSON values for equality. More...

bool	operator!= (const value &other) const
	Compares two JSON values for inequality. More...

bool	has_field (const utility::string_t &key) const
	Tests for the presence of a field. More...

value	get (const utility::string_t &key) const
	Accesses a field of a JSON object. More...

_ASYNCRTIMP void	erase (size_t index)
	Erases an element of a JSON array. Throws if index is out of bounds. More...

_ASYNCRTIMP void	erase (const utility::string_t &key)
	Erases an element of a JSON object. Throws if the key doesn't exist. More...

_ASYNCRTIMP json::value &	at (size_t index)
	Accesses an element of a JSON array. Throws when index out of bounds. More...

_ASYNCRTIMP const json::value &	at (size_t index) const
	Accesses an element of a JSON array. Throws when index out of bounds. More...

_ASYNCRTIMP json::value &	at (const utility::string_t &key)
	Accesses an element of a JSON object. If the key doesn't exist, this method throws. More...

_ASYNCRTIMP const json::value &	at (const utility::string_t &key) const
	Accesses an element of a JSON object. If the key doesn't exist, this method throws. More...

_ASYNCRTIMP value &	operator[] (const utility::string_t &key)
	Accesses a field of a JSON object. More...

value	get (size_t index) const
	Accesses an element of a JSON array. More...

_ASYNCRTIMP value &	operator[] (size_t index)
	Accesses an element of a JSON array. More...

Static Public Member Functions
static _ASYNCRTIMP value __cdecl	null ()
	Creates a null value More...

static _ASYNCRTIMP value __cdecl	number (double value)
	Creates a number value More...

static _ASYNCRTIMP value __cdecl	number (int32_t value)
	Creates a number value More...

static _ASYNCRTIMP value __cdecl	number (uint32_t value)
	Creates a number value More...

static _ASYNCRTIMP value __cdecl	number (int64_t value)
	Creates a number value More...

static _ASYNCRTIMP value __cdecl	number (uint64_t value)
	Creates a number value More...

static _ASYNCRTIMP value __cdecl	boolean (bool value)
	Creates a Boolean value More...

static _ASYNCRTIMP value __cdecl	string (utility::string_t value)
	Creates a string value More...

static _ASYNCRTIMP value __cdecl	string (utility::string_t value, bool has_escape_chars)
	Creates a string value specifying if the string contains characters to escape More...

static _ASYNCRTIMP json::value __cdecl	object (bool keep_order=false)
	Creates an object value More...

static _ASYNCRTIMP json::value __cdecl	object (std::vector< std::pair<::utility::string_t, value >> fields, bool keep_order=false)
	Creates an object value from a collection of field/values More...

static _ASYNCRTIMP json::value __cdecl	array ()
	Creates an empty JSON array More...

static _ASYNCRTIMP json::value __cdecl	array (size_t size)
	Creates a JSON array More...

static _ASYNCRTIMP json::value __cdecl	array (std::vector< value > elements)
	Creates a JSON array More...

static _ASYNCRTIMP value __cdecl	parse (const utility::string_t &value)
	Parses a string and construct a JSON value. More...

static _ASYNCRTIMP value __cdecl	parse (const utility::string_t &value, std::error_code &errorCode)
	Attempts to parse a string and construct a JSON value. More...

CASABLANCA_DEPRECATED("This API is deprecated and has been renamed to avoid confusion with as_string(), use ::web::json::value::serialize() instead.") _ASYNCRTIMP utility static _ASYNCRTIMP value __cdecl	parse (utility::istream_t &input)
	Serializes the current JSON value to a C++ string. More...

static _ASYNCRTIMP value __cdecl	parse (utility::istream_t &input, std::error_code &errorCode)
	Parses a JSON value from the contents of an input stream using the native platform character width. More...

Friends
class	web::json::details::_Object

class	web::json::details::_Array

template<typename CharType >
class	web::json::details::JSON_Parser

Detailed Description

A JSON value represented as a C++ class.

Member Enumeration Documentation

enum web::json::value::value_type

This enumeration represents the various kinds of JSON values.

Enumerator
Number	Number value.
Boolean	Boolean value.
String	String value.
Object	Object value.
Array	Array value.
Null	Null value.

Constructor & Destructor Documentation

_ASYNCRTIMP web::json::value::value ( )

Constructor creating a null value

_ASYNCRTIMP web::json::value::value ( int32_t value )

Constructor creating a JSON number value

Parameters

value The C++ value to create a JSON value from

_ASYNCRTIMP web::json::value::value ( uint32_t value )

Constructor creating a JSON number value

Parameters

value The C++ value to create a JSON value from

_ASYNCRTIMP web::json::value::value ( int64_t value )

Constructor creating a JSON number value

Parameters

value The C++ value to create a JSON value from

_ASYNCRTIMP web::json::value::value ( uint64_t value )

Constructor creating a JSON number value

Parameters

value The C++ value to create a JSON value from

_ASYNCRTIMP web::json::value::value ( double value )

Constructor creating a JSON number value

Parameters

value The C++ value to create a JSON value from

_ASYNCRTIMP web::json::value::value ( bool value )

explicit

Constructor creating a JSON Boolean value

Parameters

value The C++ value to create a JSON value from

_ASYNCRTIMP web::json::value::value ( utility::string_t value )

explicit

Constructor creating a JSON string value

Parameters

value The C++ value to create a JSON value from, a C++ STL string of the platform-native character width

This constructor has O(n) performance because it tries to determine if specified string has characters that should be properly escaped in JSON.

_ASYNCRTIMP web::json::value::value	(	utility::string_t	value,
		bool	has_escape_chars
	)

explicit

Constructor creating a JSON string value specifying if the string contains characters to escape

Parameters

value	The C++ value to create a JSON value from, a C++ STL string of the platform-native character width
has_escape_chars	Whether value contains characters that should be escaped in JSON value

This constructor has O(1) performance.

_ASYNCRTIMP web::json::value::value ( const utility::char_t * value )

explicit

Constructor creating a JSON string value

Parameters

value The C++ value to create a JSON value from, a C++ STL string of the platform-native character width

This constructor has O(n) performance because it tries to determine if specified string has characters that should be properly escaped in JSON.

This constructor exists in order to avoid string literals matching another constructor, as is very likely. For example, conversion to bool does not require a user-defined conversion, and will therefore match first, which means that the JSON value turns up as a boolean.

_ASYNCRTIMP web::json::value::value	(	const utility::char_t *	value,
		bool	has_escape_chars
	)

explicit

Constructor creating a JSON string value

Parameters

value	The C++ value to create a JSON value from, a C++ STL string of the platform-native character width
has_escape_chars	Whether value contains characters

This overload has O(1) performance.

This constructor exists in order to avoid string literals matching another constructor, as is very likely. For example, conversion to bool does not require a user-defined conversion, and will therefore match first, which means that the JSON value turns up as a boolean.

_ASYNCRTIMP web::json::value::value ( const value & )

Copy constructor

_ASYNCRTIMP web::json::value::value ( value && )

Move constructor

Member Function Documentation

static _ASYNCRTIMP json::value __cdecl web::json::value::array ( )

static

Creates an empty JSON array

Returns: An empty JSON array value

static _ASYNCRTIMP json::value __cdecl web::json::value::array ( size_t size )

static

Creates a JSON array

Parameters

size	The initial number of elements of the JSON value

Returns: A JSON array value

static _ASYNCRTIMP json::value __cdecl web::json::value::array ( std::vector< value > elements )

static

Creates a JSON array

Parameters

elements A vector of JSON values

Returns: A JSON array value

_ASYNCRTIMP json::array& web::json::value::as_array ( )

Converts the JSON value to a json array, if and only if it is an array value.

The returned json::array should have the same or shorter lifetime as this

Returns: An array representation of the value

_ASYNCRTIMP const json::array& web::json::value::as_array ( ) const

Converts the JSON value to a json array, if and only if it is an array value.

The returned json::array should have the same or shorter lifetime as this

Returns: An array representation of the value

_ASYNCRTIMP bool web::json::value::as_bool ( ) const

Converts the JSON value to a C++ bool, if and only if it is a Boolean value.

Returns: A C++ bool representation of the value

_ASYNCRTIMP double web::json::value::as_double ( ) const

Converts the JSON value to a C++ double, if and only if it is a number value. Throws json_exception if the value is not a number

Returns: A double representation of the value

_ASYNCRTIMP int web::json::value::as_integer ( ) const

Converts the JSON value to a C++ integer, if and only if it is a number value. Throws json_exception if the value is not a number

Returns: An integer representation of the value

_ASYNCRTIMP const json::number& web::json::value::as_number ( ) const

Converts the JSON value to a number class, if and only if it is a number value. Throws json_exception if the value is not a number

Returns: An instance of number class

_ASYNCRTIMP json::object& web::json::value::as_object ( )

Converts the JSON value to a json object, if and only if it is an object value.

Returns: An object representation of the value

_ASYNCRTIMP const json::object& web::json::value::as_object ( ) const

Converts the JSON value to a json object, if and only if it is an object value.

Returns: An object representation of the value

_ASYNCRTIMP const utility::string_t& web::json::value::as_string ( ) const

Converts the JSON value to a C++ STL string, if and only if it is a string value.

Returns: A C++ STL string representation of the value

_ASYNCRTIMP json::value& web::json::value::at ( size_t index )

Accesses an element of a JSON array. Throws when index out of bounds.

Parameters

index The index of an element in the JSON array.

Returns: A reference to the value.

_ASYNCRTIMP const json::value& web::json::value::at ( size_t index ) const

Accesses an element of a JSON array. Throws when index out of bounds.

Parameters

index The index of an element in the JSON array.

Returns: A reference to the value.

_ASYNCRTIMP json::value& web::json::value::at ( const utility::string_t & key )

Accesses an element of a JSON object. If the key doesn't exist, this method throws.

Parameters

key	The key of an element in the JSON object.

Returns: If the key exists, a reference to the value.

_ASYNCRTIMP const json::value& web::json::value::at ( const utility::string_t & key ) const

Accesses an element of a JSON object. If the key doesn't exist, this method throws.

Parameters

key	The key of an element in the JSON object.

Returns: If the key exists, a reference to the value.

static _ASYNCRTIMP value __cdecl web::json::value::boolean ( bool value )

static

Creates a Boolean value

Parameters

value The C++ value to create a JSON value from

Returns: A JSON Boolean value

_ASYNCRTIMP void web::json::value::erase ( size_t index )

Erases an element of a JSON array. Throws if index is out of bounds.

Parameters

index The index of the element to erase in the JSON array.

_ASYNCRTIMP void web::json::value::erase ( const utility::string_t & key )

Erases an element of a JSON object. Throws if the key doesn't exist.

Parameters

key	The key of the element to erase in the JSON object.

value web::json::value::get ( const utility::string_t & key ) const

Accesses a field of a JSON object.

Parameters

key	The name of the field

Returns: The value kept in the field; null if the field does not exist

value web::json::value::get ( size_t index ) const

Accesses an element of a JSON array.

Parameters

index The index of an element in the JSON array

Returns: The value kept at the array index; null if outside the boundaries of the array

bool web::json::json::value::has_field ( const utility::string_t & key ) const

inline

Tests for the presence of a field.

Test for the presence of a field.

Parameters

key	The name of the field

Returns: True if the field exists, false otherwise.

bool web::json::value::is_array ( ) const

inline

Is the current value an array?

Returns: true if the value is an array, false otherwise

bool web::json::value::is_boolean ( ) const

inline

Is the current value a Boolean value?

Returns: true if the value is a Boolean value, false otherwise

_ASYNCRTIMP bool web::json::value::is_double ( ) const

Is the current value represented as an double number value?

Note that if a json value is a number but represented as a int it can still be retrieved as a double using as_double().

Returns: true if the value is an double value, false otherwise.

_ASYNCRTIMP bool web::json::value::is_integer ( ) const

Is the current value represented as an integer number value?

Note that if a json value is a number but represented as a double it can still be retrieved as a integer using as_integer(), however the value will be truncated.

Returns: true if the value is an integer value, false otherwise.

bool web::json::value::is_null ( ) const

inline

Is the current value a null value?

Returns: true if the value is a null value, false otherwise

bool web::json::value::is_number ( ) const

inline

Is the current value a number value?

Returns: true if the value is a number value, false otherwise

bool web::json::value::is_object ( ) const

inline

Is the current value an object?

Returns: true if the value is an object, false otherwise

bool web::json::value::is_string ( ) const

inline

Is the current value a string value?

Returns: true if the value is a string value, false otherwise

static _ASYNCRTIMP value __cdecl web::json::value::null ( )

static

Creates a null value

Returns: A JSON null value

static _ASYNCRTIMP value __cdecl web::json::value::number ( double value )

static

Creates a number value

Parameters

value The C++ value to create a JSON value from

Returns: A JSON number value

static _ASYNCRTIMP value __cdecl web::json::value::number ( int32_t value )

static

Creates a number value

Parameters

value The C++ value to create a JSON value from

Returns: A JSON number value

static _ASYNCRTIMP value __cdecl web::json::value::number ( uint32_t value )

static

Creates a number value

Parameters

value The C++ value to create a JSON value from

Returns: A JSON number value

static _ASYNCRTIMP value __cdecl web::json::value::number ( int64_t value )

static

Creates a number value

Parameters

value The C++ value to create a JSON value from

Returns: A JSON number value

static _ASYNCRTIMP value __cdecl web::json::value::number ( uint64_t value )

static

Creates a number value

Parameters

value The C++ value to create a JSON value from

Returns: A JSON number value

static _ASYNCRTIMP json::value __cdecl web::json::value::object ( bool keep_order = false )

static

Creates an object value

Parameters

keep_order Whether to preserve the original order of the fields

Returns: An empty JSON object value

static _ASYNCRTIMP json::value __cdecl web::json::value::object	(	std::vector< std::pair<::utility::string_t, value >>	fields,
		bool	keep_order = `false`
	)

static

Creates an object value from a collection of field/values

Parameters

fields	Field names associated with JSON values
keep_order	Whether to preserve the original order of the fields

Returns: A non-empty JSON object value

bool web::json::value::operator!= ( const value & other ) const

inline

Compares two JSON values for inequality.

Parameters

other The JSON value to compare with.

Returns: True iff the values are unequal.

_ASYNCRTIMP value& web::json::value::operator= ( const value & )

Assignment operator.

Returns: The JSON value object that contains the result of the assignment.

_ASYNCRTIMP value& web::json::value::operator= ( value && )

Move assignment operator.

Returns: The JSON value object that contains the result of the assignment.

_ASYNCRTIMP bool web::json::value::operator== ( const value & other ) const

Compares two JSON values for equality.

Parameters

other The JSON value to compare with.

Returns: True iff the values are equal.

_ASYNCRTIMP value& web::json::value::operator[] ( const utility::string_t & key )

Accesses a field of a JSON object.

Parameters

key	The name of the field

Returns: A reference to the value kept in the field.

_ASYNCRTIMP value& web::json::value::operator[] ( size_t index )

Accesses an element of a JSON array.

Parameters

index The index of an element in the JSON array.

Returns: A reference to the value kept in the field.

static _ASYNCRTIMP value __cdecl web::json::value::parse ( const utility::string_t & value )

static

Parses a string and construct a JSON value.

Parameters

value The C++ value to create a JSON value from, a C++ STL double-byte string

static _ASYNCRTIMP value __cdecl web::json::value::parse	(	const utility::string_t &	value,
		std::error_code &	errorCode
	)

static

Attempts to parse a string and construct a JSON value.

Parameters

value	The C++ value to create a JSON value from, a C++ STL double-byte string
errorCode	If parsing fails, the error code is greater than 0

Returns: The parsed object. Returns web::json::value::null if failed

CASABLANCA_DEPRECATED ("This API is deprecated and has been renamed to avoid confusion with as_string(), use ::web::json::value::serialize() instead.") _ASYNCRTIMP utility static _ASYNCRTIMP value __cdecl web::json::value::parse ( utility::istream_t & input )

static

Serializes the current JSON value to a C++ string.

Returns: A string representation of the value

Parses a JSON value from the contents of an input stream using the native platform character width.

Parameters

input The stream to read the JSON value from

Returns: The JSON value object created from the input stream.

static _ASYNCRTIMP value __cdecl web::json::value::parse	(	utility::istream_t &	input,
		std::error_code &	errorCode
	)

static

Parses a JSON value from the contents of an input stream using the native platform character width.

Parameters

input	The stream to read the JSON value from
errorCode	If parsing fails, the error code is greater than 0

Returns: The parsed object. Returns web::json::value::null if failed

_ASYNCRTIMP utility::string_t web::json::value::serialize ( ) const

Serializes the current JSON value to a C++ string.

Returns: A string representation of the value

_ASYNCRTIMP void web::json::value::serialize ( utility::ostream_t & stream ) const

Writes the current JSON value to a stream with the native platform character width.

Parameters

stream The stream that the JSON string representation should be written to.

size_t web::json::json::value::size ( ) const

inline

Gets the number of children of the value.

Returns: The number of children. 0 for all non-composites.

static _ASYNCRTIMP value __cdecl web::json::value::string ( utility::string_t value )

static

Creates a string value

Parameters

value The C++ value to create a JSON value from

Returns: A JSON string value

This overload has O(n) performance because it tries to determine if specified string has characters that should be properly escaped in JSON.

static _ASYNCRTIMP value __cdecl web::json::value::string	(	utility::string_t	value,
		bool	has_escape_chars
	)

static

Creates a string value specifying if the string contains characters to escape

Parameters

value	The C++ value to create a JSON value from
has_escape_chars	Whether value contains characters that should be escaped in JSON value

Returns: A JSON string value

This overload has O(1) performance.

_ASYNCRTIMP json::value::value_type web::json::value::type ( ) const

Accesses the type of JSON value the current value instance is

Returns: The value's type

The documentation for this class was generated from the following file:

include/cpprest/json.h

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation