The JSON document writer. More...

Public Member Functions
	wxJSONWriter (int style=wxJSONWRITER_STYLED, int indent=0, int step=3)
	Ctor. More...

	~wxJSONWriter ()
	Dtor - does nothing.

void	Write (const wxJSONValue &value, wxString &str)
	Write the JSONvalue object to a JSON text. More...

void	Write (const wxJSONValue &value, wxOutputStream &os)

void	SetDoubleFmtString (const char *fmt)
	Set the format string for double values. More...

Protected Member Functions
int	DoWrite (wxOutputStream &os, const wxJSONValue &value, const wxString *key, bool comma)
	Perform the real write operation. More...

int	WriteIndent (wxOutputStream &os)
	Writes the indentation to the JSON text. More...

int	WriteIndent (wxOutputStream &os, int num)
	Write the specified number of indentation (spaces or tabs) More...

bool	IsSpace (wxChar ch)
	Returns TRUE if the character is a space character.

bool	IsPunctuation (wxChar ch)
	Returns TRUE if the character if a puctuation character.

int	WriteString (wxOutputStream &os, const wxString &str)
	Write a generic string. More...

int	WriteStringValue (wxOutputStream &os, const wxString &str)
	Write the provided string to the output object. More...

int	WriteNullValue (wxOutputStream &os)
	Write the NULL JSON value to the output stream. More...

int	WriteIntValue (wxOutputStream &os, const wxJSONValue &v)
	Writes a value of type INT. More...

int	WriteUIntValue (wxOutputStream &os, const wxJSONValue &v)
	Writes a value of type UNSIGNED INT. More...

int	WriteBoolValue (wxOutputStream &os, const wxJSONValue &v)
	Writes a value of type BOOL. More...

int	WriteDoubleValue (wxOutputStream &os, const wxJSONValue &v)
	Writes a value of type DOUBLE. More...

int	WriteMemoryBuff (wxOutputStream &os, const wxMemoryBuffer &buff)
	Write a JSON value of type memory buffer. More...

int	WriteInvalid (wxOutputStream &os)
	Write the invalid JSON value to the output stream. More...

int	WriteSeparator (wxOutputStream &os)
	Writes the separator between values. More...

int	WriteKey (wxOutputStream &os, const wxString &key)
	Write the key of a key/value element to the output stream.

int	WriteComment (wxOutputStream &os, const wxJSONValue &value, bool indent)
	Write the comment strings, if any.

int	WriteError (const wxString &err)

Detailed Description

The JSON document writer.

This class is a JSON document writer and it is used to write a wxJSONValue object to an output stream or to a string object. The ctor accepts some parameters which can be used to change the style of the output. The default output is in human-readable format that uses a three-space indentation for object / array sub-items and separates every value with a linefeed character.

Examples

Using the default writer constructor

// construct the JSON value object and add values to it
wxJSONValue root;
root["key1"] = "some value";
...
// construct the string that will contain the JSON text
wxString     str;
// construct a JSON writer: use the default writer's settings
wxJSONWriter writer;
// call the writer's Write() memberfunction
writer.Write( root, str );

To write a JSON value object using a four-spaces indentation and forcing all comment strings to apear before the value they refer to, use the following code:

wxJSONWriter writer( wxJSONWRITER_STYLED |   // want a styled output
              wxJSONWRITER_WRITE_COMMENTS |  // want comments in the document
              wxJSONWRITER_COMMENTS_BEFORE,  // force comments before value
              0,                             // initial indentation
              4);                            // indentation step
writer.Write( value, document );

The following code construct a JSON writer that produces the most compact text output but it is hard to read by humans:

wxJSONWriter writer( wxJSONWRITER_NONE );

writer.Write( value, document );

The two types of output objects

You can write JSON text to two different kind of objects:

a string object (wxString)
a stream object (wxOutputStream)

When writing to a string object, the output is platform- and mode-dependent. In ANSI builds, the JSON text output in the string object will contain one-byte characters: the actual characters represented is locale dependent. In Unicode builds, the JSON text output in the string contains wide characters which encoding format is platform dependent: UCS-2 in Windows, UCS-4 in GNU/Linux. Starting from wxWidgets version 2.9 the internal encoding for Unicode builds in linux/unix systems is UTF-8.

When writing to a stream object, the JSON text output is always encoded in UTF-8 in both ANSI and Unicode builds. In ANSI builds the user may want to suppress UTF-8 encoding so that the JSON text can be stored in ANSI format. Note that this is not valid JSON text unless all characters written to the JSON text document are in the US-ASCII character ser (0x00..0x7F). To know more read wxjson_tutorial_unicode_ansi

Efficiency

In versions up to 1.0 the JSON writer wrote every character to the output object (the string or the stream). This is very inefficient becuase the writer converted each char to UTF-8 when writing to streams but we have to note that only string values have to be actually converted. Special JSON characters, numbers and literals do not need the conversion because they lay in the US-ASCII plane (0x00-0x7F) and no conversion is needed as the UTF-8 encoding is the same as US-ASCII.

For more info about the unicode topic see wxjson_tutorial_unicode.

The problem of writing doubles

You can customize the ouput of doubles by specifing the format string that has to be used by the JSON writer class. To know more about this issue read wxjson_tutorial_write_doubles

Constructor & Destructor Documentation

wxJSONWriter::wxJSONWriter	(	int	style = `wxJSONWRITER_STYLED`,
		int	indent = `0`,
		int	step = `3`
	)

Ctor.

Construct the JSON writer object with the specified parameters. Note that if styled is FALSE the indentation is totally suppressed and the values of the other two parameters are simply ignored.

Parameters

indent	the initial indentation in number of spaces. Default is ZERO. If you specify the wxJSONWRITER_TAB_INDENT flag for the style, this value referes to the number of TABs in the initial indentation
step	the indentation increment for new objects/arrays in number of spaces (default is 3). This value is ignored if you specify the wxJSONWRITER_TAB_INDENT flag for the style: the indentation increment is only one TAB character.
style	this is a combination of the following constants OR'ed togheter: wxJSONWRITER_NONE: no indentation is performed and no LF character is written between values. This style produces strict JSON text but it is hard to read by humans wxJSONWRITER_STYLED: output is human-readable: values are separated by LF characters and sub-items are indented. This style produces strict JSON text that is easy to read by humans. wxJSONWRITER_WRITE_COMMENTS: this flag force the writer to write C/C++ comment strings, if any. The comments will be written in their original position. C/C++ comments may not be recognized by other JSON implementations because they are not strict JSON text. wxJSONWRITER_COMMENTS_BEFORE: this flag force the writer to write C/C++ comments always before the value they refer to. In order for this style to take effect, you also have to specify the wxJSONWRITER_WRITE_COMMENTS flag. wxJSONWRITER_COMMENTS_AFTER: this flag force the writer to write C/C++ comments always after the value they refer to. In order for this style to take effect, you also have to specify the wxJSONWRITER_WRITE_COMMENTS flag. wxJSONWRITER_SPLIT_STRINGS: this flag cause the writer to split strings in more than one line if they are too long. wxJSONWRITER_NO_LINEFEEDS: this flag cause the JSON writer to not add newlines between values. It is ignored if wxJSONWRITER_STYLED is not set. This style produces strict JSON text. wxJSONWRITER_ESCAPE_SOLIDUS: the solidus character (/) should only be escaped if the JSON text is meant for embedding in HTML. Unlike in older 0.x versions, it is disabled by default and this flag cause the solidus char to be escaped. This style produces strict JSON text. wxJSONWRITER_MULTILINE_STRING:this is a multiline-string mode where newlines and tabs are not escaped. This is not strict JSON, but it helps immensely when manually editing json files with multiline strings wxJSONWRITER_RECOGNIZE_UNSIGNED: this flag cause the JSON writer to prepend a plus sign (+) to unsigned integer values. This is used by the wxJSON reader to force the integer to be stored in an unsigned int. Note that this feature may be incompatible with other JSON implementations. wxJSONWRITER_TAB_INDENT: this flag cause the indentation of sub-objects / arrays to be done using a TAB character instead of SPACES. In order for this style to take effect, you also have to specify the wxJSONWRITER_STYLED flag. This style produces strict JSON text. wxJSONWRITER_NO_INDENTATION: this flag cause the JSON writer to not add indentation. It is ignored if wxJSONWRITER_STYLED is not set. This style produces strict JSON text. wxJSONWRITER_NOUTF8_STREAM: suppress UTF-8 conversion when writing string values to the stream thus producing ANSI text output; only meaningfull in ANSI builds, this flag is simply ignored in Unicode builds. wxJSONWRITER_MEMORYBUFF: Note that for the style wxJSONWRITER_NONE the JSON text output is a bit different from that of old 0.x versions although it is syntactically equal. If you rely on the old JSON output formatting read the following page wxjson_tutorial_style_none. To know more about the writer's styles see wxjson_tutorial_style

Here is the call graph for this function:

Member Function Documentation

int wxJSONWriter::DoWrite	(	wxOutputStream &	os,
		const wxJSONValue &	value,
		const wxString *	key,
		bool	comma
	)

protected

Perform the real write operation.

This is a recursive function that gets the type of the value object and calls several protected functions depending on the type:

WriteNullvalue for type NULL
WriteStringValue() for STRING and CSTRING types
WriteIntValue for INT types
WriteUIntValue for UINT types
WriteBoolValue for BOOL types
WriteDoubleValue for DOUBLE types
WriteMemoryBuff for MEMORYBUFF types

If the value is an array or key/value map (types ARRAY and OBJECT), the function iterates through all JSON value object in the array/map and calls itself for every item in the container.

Here is the call graph for this function:

Here is the caller graph for this function:

void wxJSONWriter::SetDoubleFmtString ( const char * fmt )

Set the format string for double values.

This function sets the format string used for printing double values. Double values are outputted to JSON text using the snprintf function with a default format string of:

%.10g

which prints doubles with a precision of 10 decimal digits and suppressing trailing ZEROes.

Note that the parameter is a pointer to char and not to wxChar. This is because the JSON writer always procudes UTF-8 encoded text and decimal digits in UTF-8 are made of only one UTF-8 code-unit (1 byte).

Here is the caller graph for this function:

void wxJSONWriter::Write	(	const wxJSONValue &	value,
		wxString &	str
	)

Write the JSONvalue object to a JSON text.

The two overloaded versions of this function let the user choose the output object which can be:

a string object (wxString)
a stream object ( wxOutputStream)

The two types of output object are very different because the text outputted is encoded in different formats depending on the build mode. When writing to a string object, the JSON text output is encoded differently depending on the build mode and the platform. Writing to a stream always produce UTF-8 encoded text. To know more about this topic read wxjson_tutorial_unicode.

Also note that the Write() function does not return a status code. If you are writing to a string, you do not have to warry about this issue: no errors can occur when writing to strings. On the other hand, wehn writing to a stream there could be errors in the write operation. If an error occurs, the Write(9 function immediatly returns without trying further output operations. You have to check the status of the stream by calling the stream's memberfunctions. Example:

// construct the JSON value object and add values to it
wxJSONValue root;
root["key1"] = "some value";
// write to a stream
wxMemoryOutputStream mem;
wxJSONWriter writer;
writer.Write( root, mem );
wxStreamError err = mem.GetLastError();
if ( err != wxSTREAM_NO_ERROR )  {
  MessageBox( _T("ERROR: cannot write the JSON text output"));
}

void wxJSONWriter::Write	(	const wxJSONValue &	value,
		wxOutputStream &	os
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Here is the call graph for this function:

int wxJSONWriter::WriteBoolValue	(	wxOutputStream &	os,
		const wxJSONValue &	value
	)

protected

Writes a value of type BOOL.

This function is called for every value objects of BOOL type. This function prints the literals true or false depending on the value in value. Returns -1 on stream errors or ZERO if no errors.

Here is the call graph for this function:

Here is the caller graph for this function:

int wxJSONWriter::WriteDoubleValue	(	wxOutputStream &	os,
		const wxJSONValue &	value
	)

protected

Writes a value of type DOUBLE.

This function is called for every value objects of DOUBLE type. This function uses the
snprintf function to get the US-ASCII representation of the integer and simply copy it to the output stream. Returns -1 on stream errors or ZERO if no errors.

Note that writing a double to a decimal ASCII representation could lay to unexpected results depending on the format string used in the conversion. See SetDoubleFmtString for details.

Here is the call graph for this function:

Here is the caller graph for this function:

int wxJSONWriter::WriteIndent ( wxOutputStream & os )

protected

Writes the indentation to the JSON text.

The two functions write the indentation as spaces in the JSON output text. When called with a int parameter, the function writes the specified number of spaces. If no parameter is given, the function computes the number of spaces using the following formula: If the wxJSONWRITER_TAB_INDENT flag is used in the writer's cnstructor, the function calls WriteTabIndent().

The function also checks that wxJSONWRITER_STYLED is set and the wxJSONWRITER_NO_INDENTATION is not set.

Here is the caller graph for this function:

int wxJSONWriter::WriteIndent	(	wxOutputStream &	os,
		int	num
	)

protected

Write the specified number of indentation (spaces or tabs)

The function is called by WriteIndent() and other writer's functions. It writes the indentation as specified in the num parameter which is the actual level of annidation. The function checks if wxJSONWRITER_STYLED is set: if not, no indentation is performed. Also, the function checks if wxJSONWRITER_TAB_INDENT is set: if it is, indentation is done by writing num TAB characters otherwise, it is performed by writing a number of spaces computed as:

numSpaces = m_indent + ( m_step * num )

int wxJSONWriter::WriteIntValue	(	wxOutputStream &	os,
		const wxJSONValue &	value
	)

protected

Writes a value of type INT.

This function is called for every value objects of INT type. This function uses the
snprintf function to get the US-ASCII representation of the integer and simply copy it to the output stream. Returns -1 on stream errors or ZERO if no errors.

Here is the call graph for this function:

Here is the caller graph for this function:

int wxJSONWriter::WriteInvalid ( wxOutputStream & os )

protected

Write the invalid JSON value to the output stream.

An invalid wxJSONValue is a value that was not initialized and it is an error. You should never write invalid values to JSON text because the output is not valid JSON text. Note that the NULL value is a legal JSON text and it is written:

null

This function writes a non-JSON text to the output stream:

In debug mode, the function always fails with an wxFAIL_MSG failure.

Here is the caller graph for this function:

int wxJSONWriter::WriteMemoryBuff	(	wxOutputStream &	os,
		const wxMemoryBuffer &	buff
	)

protected

Write a JSON value of type memory buffer.

The type wxJSONTYPE_MEMORYBUFF is a wxJSON extension that is not correctly read by other JSON implementations. By default, the function writes such a type as an array of INTs as follows:

[ 0,32,45,255,6,...]

If the writer object was constructed using the wxJSONWRITER_MEMORYBUFF flag, then the output is much more compact and recognized by the wxJSON reader as a memory buffer type:

'00203FFF06..'

Here is the call graph for this function:

Here is the caller graph for this function:

int wxJSONWriter::WriteNullValue ( wxOutputStream & os )

protected

Write the NULL JSON value to the output stream.

The function writes the null literal string to the output stream.

Here is the caller graph for this function:

int wxJSONWriter::WriteSeparator ( wxOutputStream & os )

protected

Writes the separator between values.

The function is called when a value has been written to the JSON text output and it writes the separator character: LF. The LF char is actually written only if the wxJSONWRITER_STYLED flag is specified and wxJSONWRITER_NO_LINEFEEDS is not set.

Returns the last character written which is LF itself or -1 in case of errors. Note that LF is returned even if the character is not actually written.

Here is the caller graph for this function:

int wxJSONWriter::WriteString	(	wxOutputStream &	os,
		const wxString &	str
	)

protected

Write a generic string.

The function writes the wxString object str to the output object. The string is written as is; you cannot use it to write JSON strings to the output text. The function converts the string str to UTF-8 and writes the buffer..

Here is the caller graph for this function:

int wxJSONWriter::WriteStringValue	(	wxOutputStream &	os,
		const wxString &	str
	)

protected

Write the provided string to the output object.

The function writes the string str to the output object that was specified in the wxJSONWriter::Write() function. The function may split strings in two or more lines if the string contains LF characters if the m_style data member contains the wxJSONWRITER_SPLIT_STRING flag.

The function does not actually write the string: for every character in the provided string the function calls WriteChar() which does the actual character output.

The function returns ZERO on success or -1 in case of errors.

Here is the call graph for this function:

Here is the caller graph for this function:

int wxJSONWriter::WriteUIntValue	(	wxOutputStream &	os,
		const wxJSONValue &	value
	)

protected

Writes a value of type UNSIGNED INT.

This function is called for every value objects of UINT type. This function uses the
snprintf function to get the US-ASCII representation of the integer and simply copy it to the output stream. The function prepends a plus sign if the wxJSONWRITER_RECOGNIZE_UNSIGNED flag is set in the m_flags data member. Returns -1 on stream errors or ZERO if no errors.

Here is the call graph for this function:

Here is the caller graph for this function:

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

/home/bishop/work/projects/nextgismanager/include/wxgis/core/json/jsonwriter.h
/home/bishop/work/projects/nextgismanager/src/core/json/jsonwriter.cpp

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation