ezStandardJSONWriter Class Reference

Standard-compliant JSON writer implementation. More...

#include <JSONWriter.h>

Inheritance diagram for ezStandardJSONWriter:

Classes
struct	CommaWriter
struct	JSONState

Public Member Functions
	ezStandardJSONWriter ()
	Constructor.
	~ezStandardJSONWriter ()
	Destructor.
void	SetOutputStream (ezStreamWriter *pOutput)
	All output is written to this binary stream.
virtual void	WriteBool (bool value) override
	Writes a bool to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteInt32 (ezInt32 value) override
	Writes an int32 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteUInt32 (ezUInt32 value) override
	Writes a uint32 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteInt64 (ezInt64 value) override
	Writes an int64 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteUInt64 (ezUInt64 value) override
	Writes a uint64 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteFloat (float value) override
	Writes a float to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteDouble (double value) override
	Writes a double to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteString (ezStringView value) override
	Writes a string to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteNULL () override
	Writes the value 'null' to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteTime (ezTime value) override
	Writes the time value as a double (i.e. redirects to WriteDouble()).
virtual void	WriteColor (const ezColor &value) override
	Writes {"r":..,"g":..,"b":..,"a":..} with the linear float components.
virtual void	WriteColorGamma (const ezColorGammaUB &value) override
	Writes {"r":..,"g":..,"b":..,"a":..} with the gamma space components, i.e. 0 to 255.
virtual void	WriteVec2 (const ezVec2 &value) override
	Writes {"x":..,"y":..}.
virtual void	WriteVec3 (const ezVec3 &value) override
	Writes {"x":..,"y":..,"z":..}.
virtual void	WriteVec4 (const ezVec4 &value) override
	Writes {"x":..,"y":..,"z":..,"w":..}.
virtual void	WriteVec2I32 (const ezVec2I32 &value) override
	Writes {"x":..,"y":..}.
virtual void	WriteVec3I32 (const ezVec3I32 &value) override
	Writes {"x":..,"y":..,"z":..}.
virtual void	WriteVec4I32 (const ezVec4I32 &value) override
	Writes {"x":..,"y":..,"z":..,"w":..}.
virtual void	WriteQuat (const ezQuat &value) override
	Writes {"x":..,"y":..,"z":..,"w":..}, the same layout the property system uses.
virtual void	WriteMat3 (const ezMat3 &value) override
	Writes the matrix row by row, as an array of arrays.
virtual void	WriteMat4 (const ezMat4 &value) override
	Writes the matrix row by row, as an array of arrays.
virtual void	WriteUuid (const ezUuid &value) override
	Writes the hyphenated string form, i.e. what ezConversionUtils::ToString() produces.
virtual void	WriteAngle (ezAngle value) override
	Writes the angle in degrees (i.e. redirects to WriteFloat()).
virtual void	WriteDataBuffer (const ezDataBuffer &value) override
	Writes the bytes as a hex string, which is twice the size of the data.
virtual void	WriteBinaryData (ezStringView sDataType, const void *pData, ezUInt32 uiBytes, ezStringView sValueString=nullptr) override
	Implements the MongoDB way of writing binary data. First writes a "$type" variable, then a "$binary" variable that represents the raw data (Hex encoded, little endian).
virtual void	BeginVariable (ezStringView sName) override
	Begins outputting a variable. szName is the variable name.
virtual void	EndVariable () override
	Ends outputting a variable.
virtual void	BeginArray (ezStringView sName={}) override
	Begins outputting an array variable.
virtual void	EndArray () override
	Ends outputting an array variable.
virtual void	BeginObject (ezStringView sName={}) override
	Begins outputting an object variable.
virtual void	EndObject () override
	Ends outputting an object variable.
void	WriteRawJson (ezStringView sJson)
	Writes text that is already valid JSON in place, without any escaping of special characters.
void	AddVariableRawJson (ezStringView sName, ezStringView sJson)
	Shorthand for "BeginVariable(sName); WriteRawJson(sJson); EndVariable();".
void	EndAll ()
	Closes every object and array that is still open, so that the output becomes valid JSON.
Public Member Functions inherited from ezJSONWriter
	ezJSONWriter ()
	Constructor.
virtual	~ezJSONWriter ()
	Destructor.
void	SetWhitespaceMode (WhitespaceMode whitespaceMode)
	Configures how much whitespace is output.
void	SetArrayMode (ArrayMode arrayMode)
	Configures how arrays are written.
void	AddVariableBool (ezStringView sName, bool value)
	Shorthand for "BeginVariable(szName); WriteBool(value); EndVariable(); ".
void	AddVariableInt32 (ezStringView sName, ezInt32 value)
	Shorthand for "BeginVariable(szName); WriteInt32(value); EndVariable(); ".
void	AddVariableUInt32 (ezStringView sName, ezUInt32 value)
	Shorthand for "BeginVariable(szName); WriteUInt32(value); EndVariable(); ".
void	AddVariableInt64 (ezStringView sName, ezInt64 value)
	Shorthand for "BeginVariable(szName); WriteInt64(value); EndVariable(); ".
void	AddVariableUInt64 (ezStringView sName, ezUInt64 value)
	Shorthand for "BeginVariable(szName); WriteUInt64(value); EndVariable(); ".
void	AddVariableFloat (ezStringView sName, float value)
	Shorthand for "BeginVariable(szName); WriteFloat(value); EndVariable(); ".
void	AddVariableDouble (ezStringView sName, double value)
	Shorthand for "BeginVariable(szName); WriteDouble(value); EndVariable(); ".
void	AddVariableString (ezStringView sName, ezStringView value)
	Shorthand for "BeginVariable(szName); WriteString(value); EndVariable(); ".
void	AddVariableNULL (ezStringView sName)
	Shorthand for "BeginVariable(szName); WriteNULL(value); EndVariable(); ".
void	AddVariableTime (ezStringView sName, ezTime value)
	Shorthand for "BeginVariable(szName); WriteTime(value); EndVariable(); ".
void	AddVariableUuid (ezStringView sName, ezUuid value)
	Shorthand for "BeginVariable(szName); WriteUuid(value); EndVariable(); ".
void	AddVariableAngle (ezStringView sName, ezAngle value)
	Shorthand for "BeginVariable(szName); WriteAngle(value); EndVariable(); ".
void	AddVariableColor (ezStringView sName, const ezColor &value)
	Shorthand for "BeginVariable(szName); WriteColor(value); EndVariable(); ".
void	AddVariableColorGamma (ezStringView sName, const ezColorGammaUB &value)
	Shorthand for "BeginVariable(szName); WriteColorGamma(value); EndVariable(); ".
void	AddVariableVec2 (ezStringView sName, const ezVec2 &value)
	Shorthand for "BeginVariable(szName); WriteVec2(value); EndVariable(); ".
void	AddVariableVec3 (ezStringView sName, const ezVec3 &value)
	Shorthand for "BeginVariable(szName); WriteVec3(value); EndVariable(); ".
void	AddVariableVec4 (ezStringView sName, const ezVec4 &value)
	Shorthand for "BeginVariable(szName); WriteVec4(value); EndVariable(); ".
void	AddVariableVec2I32 (ezStringView sName, const ezVec2I32 &value)
	Shorthand for "BeginVariable(szName); WriteVec2I32(value); EndVariable(); ".
void	AddVariableVec3I32 (ezStringView sName, const ezVec3I32 &value)
	Shorthand for "BeginVariable(szName); WriteVec3I32(value); EndVariable(); ".
void	AddVariableVec4I32 (ezStringView sName, const ezVec4I32 &value)
	Shorthand for "BeginVariable(szName); WriteVec4I32(value); EndVariable(); ".
void	AddVariableQuat (ezStringView sName, const ezQuat &value)
	Shorthand for "BeginVariable(szName); WriteQuat(value); EndVariable(); ".
void	AddVariableMat3 (ezStringView sName, const ezMat3 &value)
	Shorthand for "BeginVariable(szName); WriteMat3(value); EndVariable(); ".
void	AddVariableMat4 (ezStringView sName, const ezMat4 &value)
	Shorthand for "BeginVariable(szName); WriteMat4(value); EndVariable(); ".
void	AddVariableDataBuffer (ezStringView sName, const ezDataBuffer &value)
	Shorthand for "BeginVariable(szName); WriteDataBuffer(value); EndVariable(); ".
void	AddVariableVariant (ezStringView sName, const ezVariant &value)
	Shorthand for "BeginVariable(szName); WriteVariant(value); EndVariable(); ".
virtual void	WriteVariant (const ezVariant &value)
	The default implementation dispatches all supported types to WriteBool, WriteInt32, etc. and asserts on the more complex types.
bool	HadWriteError () const
	Indicates if an error was encountered while writing.
void	Abandon ()
	Gives up on the output, so that the writer may be destroyed with containers still open.

Protected Types
enum	State {   Invalid , Empty , Variable , Object ,   NamedObject , Array , NamedArray }

Protected Member Functions
void	End ()
void	WriteFloatComponents (const float *pValues, ezUInt32 uiCount, ezStringView sComponentNames)
	Writes an object with one float member per component, e.g. {"x":1,"y":2}.
void	WriteMatrix (const float *pValues, ezUInt32 uiRowsAndColumns)
	Writes a square matrix row by row, as an array of arrays.
void	OutputString (ezStringView s)
void	OutputEscapedString (ezStringView s)
void	OutputIndentation ()
Protected Member Functions inherited from ezJSONWriter
void	SetWriteErrorState ()
	called internally when there was an error during writing

Protected Attributes
ezInt32	m_iIndentation
ezStreamWriter *	m_pOutput
ezHybridArray< JSONState, 16 >	m_StateStack
Protected Attributes inherited from ezJSONWriter
WhitespaceMode	m_WhitespaceMode = WhitespaceMode::All
ArrayMode	m_ArrayMode = ArrayMode::InOneLine

Additional Inherited Members
Public Types inherited from ezJSONWriter
enum class	WhitespaceMode {   All , LessIndentation , NoIndentation , NewlinesOnly ,   None }
	Modes to configure how much whitespace the JSON writer will output. More...
enum class	ArrayMode { InOneLine , OneLinePerItem }
	Modes to configure how arrays are written. More...

Detailed Description

Standard-compliant JSON writer implementation.

Produces fully compliant JSON that any standard parser reads. The ez types that JSON has no representation for are written as ordinary objects, arrays and strings - a vector as {"x":1,"y":2,"z":3}, a matrix as an array of rows, a uuid as its hyphenated string form, an angle in degrees. Which ez type a value came from is therefore not recorded, so a reader has to know what it is reading; in particular ezColor (linear) and ezColorGammaUB (gamma, 0-255) are indistinguishable from the JSON alone.

WriteBinaryData() writes MongoDB-style {"$type":..,"$binary":"hexdata"} for callers that want raw bytes.

Member Function Documentation

BeginArray()

void ezStandardJSONWriter::BeginArray ( ezStringView  sName = {} )

overridevirtual

Begins outputting an array variable.

If szName is nullptr this will create an anonymous array, which is necessary when you want to put an array as a value into another array. BeginArray() with a non-nullptr value for szName is identical to calling BeginVariable() first. In this case EndArray() will also end the variable definition, so no additional call to EndVariable() is required.

Implements ezJSONWriter.

BeginObject()

void ezStandardJSONWriter::BeginObject ( ezStringView  sName = {} )

overridevirtual

Begins outputting an object variable.

If szName is nullptr this will create an anonymous object, which is necessary when you want to put an object as a value into an array. BeginObject() with a non-nullptr value for szName is identical to calling BeginVariable() first. In this case EndObject() will also end the variable definition, so no additional call to EndVariable() is required.

Implements ezJSONWriter.

BeginVariable()

void ezStandardJSONWriter::BeginVariable ( ezStringView  sName )

overridevirtual

Begins outputting a variable. szName is the variable name.

Between BeginVariable() and EndVariable() you can call the WriteXYZ functions once to write out the variable's data. You can also call BeginArray() and BeginObject() without a variable name to output an array or object variable.

Implements ezJSONWriter.

EndAll()

void ezStandardJSONWriter::EndAll

(

)

Closes every object and array that is still open, so that the output becomes valid JSON.

For code that has to stop writing part way through - a lookup failed, the data turned out to be unusable - but still wants to return what it has. Without this, the only options are matching every Begin with an End on the error path or letting the destructor assert.

A variable that was begun but has no value yet gets a null written for it, because a JSON object member without a value cannot be represented. Does nothing if nothing is open.

EndArray()

void ezStandardJSONWriter::EndArray ( )

overridevirtual

Ends outputting an array variable.

Implements ezJSONWriter.

EndObject()

void ezStandardJSONWriter::EndObject ( )

overridevirtual

Ends outputting an object variable.

Implements ezJSONWriter.

EndVariable()

void ezStandardJSONWriter::EndVariable ( )

overridevirtual

Ends outputting a variable.

Implements ezJSONWriter.

WriteAngle()

void ezStandardJSONWriter::WriteAngle ( ezAngle  value )

overridevirtual

Writes the angle in degrees (i.e. redirects to WriteFloat()).

Implements ezJSONWriter.

WriteBinaryData()

void ezStandardJSONWriter::WriteBinaryData ( ezStringView  sDataType, const void *  pData, ezUInt32  uiBytes, ezStringView  sValueString = nullptr  )

overridevirtual

Implements the MongoDB way of writing binary data. First writes a "$type" variable, then a "$binary" variable that represents the raw data (Hex encoded, little endian).

Implements ezJSONWriter.

WriteBool()

void ezStandardJSONWriter::WriteBool ( bool  value )

overridevirtual

Writes a bool to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Implements ezJSONWriter.

WriteColor()

void ezStandardJSONWriter::WriteColor ( const ezColor &  value )

overridevirtual

Writes {"r":..,"g":..,"b":..,"a":..} with the linear float components.

Implements ezJSONWriter.

WriteColorGamma()

void ezStandardJSONWriter::WriteColorGamma ( const ezColorGammaUB &  value )

overridevirtual

Writes {"r":..,"g":..,"b":..,"a":..} with the gamma space components, i.e. 0 to 255.

Implements ezJSONWriter.

WriteDataBuffer()

void ezStandardJSONWriter::WriteDataBuffer ( const ezDataBuffer &  value )

overridevirtual

Writes the bytes as a hex string, which is twice the size of the data.

Implements ezJSONWriter.

WriteDouble()

void ezStandardJSONWriter::WriteDouble ( double  value )

overridevirtual

Writes a double to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Implements ezJSONWriter.

WriteFloat()

void ezStandardJSONWriter::WriteFloat ( float  value )

overridevirtual

Writes a float to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Implements ezJSONWriter.

WriteFloatComponents()

void ezStandardJSONWriter::WriteFloatComponents ( const float *  pValues, ezUInt32  uiCount, ezStringView  sComponentNames  )

protected

Writes an object with one float member per component, e.g. {"x":1,"y":2}.

Parameters

sComponentNames

One character per component, in order, e.g. "xyzw" or "rgba".

WriteInt32()

void ezStandardJSONWriter::WriteInt32 ( ezInt32  value )

overridevirtual

Writes an int32 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Implements ezJSONWriter.

WriteInt64()

void ezStandardJSONWriter::WriteInt64 ( ezInt64  value )

overridevirtual

Writes an int64 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Implements ezJSONWriter.

WriteMat3()

void ezStandardJSONWriter::WriteMat3 ( const ezMat3 &  value )

overridevirtual

Writes the matrix row by row, as an array of arrays.

Implements ezJSONWriter.

WriteMat4()

void ezStandardJSONWriter::WriteMat4 ( const ezMat4 &  value )

overridevirtual

Writes the matrix row by row, as an array of arrays.

Implements ezJSONWriter.

WriteNULL()

void ezStandardJSONWriter::WriteNULL ( )

overridevirtual

Writes the value 'null' to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Implements ezJSONWriter.

WriteQuat()

void ezStandardJSONWriter::WriteQuat ( const ezQuat &  value )

overridevirtual

Writes {"x":..,"y":..,"z":..,"w":..}, the same layout the property system uses.

Implements ezJSONWriter.

WriteRawJson()

void ezStandardJSONWriter::WriteRawJson

(

ezStringView

sJson

)

Writes text that is already valid JSON in place, without any escaping of special characters.

For values that were authored as JSON elsewhere and are embedded in this document. Anything else, in particular a plain string or data from outside, produces a malformed document, use WriteString() for that instead.

Counts as one value, so it can be used wherever WriteBool() and friends can. Indentation and the whitespace mode do not apply to the embedded text.

WriteString()

void ezStandardJSONWriter::WriteString ( ezStringView  value )

overridevirtual

Writes a string to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Implements ezJSONWriter.

WriteTime()

void ezStandardJSONWriter::WriteTime ( ezTime  value )

overridevirtual

Writes the time value as a double (i.e. redirects to WriteDouble()).

Implements ezJSONWriter.

WriteUInt32()

void ezStandardJSONWriter::WriteUInt32 ( ezUInt32  value )

overridevirtual

Writes a uint32 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Implements ezJSONWriter.

WriteUInt64()

void ezStandardJSONWriter::WriteUInt64 ( ezUInt64  value )

overridevirtual

Writes a uint64 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Implements ezJSONWriter.

WriteUuid()

void ezStandardJSONWriter::WriteUuid ( const ezUuid &  value )

overridevirtual

Writes the hyphenated string form, i.e. what ezConversionUtils::ToString() produces.

Implements ezJSONWriter.

WriteVec2()

void ezStandardJSONWriter::WriteVec2 ( const ezVec2 &  value )

overridevirtual

Writes {"x":..,"y":..}.

Implements ezJSONWriter.

WriteVec2I32()

void ezStandardJSONWriter::WriteVec2I32 ( const ezVec2I32 &  value )

overridevirtual

Writes {"x":..,"y":..}.

Implements ezJSONWriter.

WriteVec3()

void ezStandardJSONWriter::WriteVec3 ( const ezVec3 &  value )

overridevirtual

Writes {"x":..,"y":..,"z":..}.

Implements ezJSONWriter.

WriteVec3I32()

void ezStandardJSONWriter::WriteVec3I32 ( const ezVec3I32 &  value )

overridevirtual

Writes {"x":..,"y":..,"z":..}.

Implements ezJSONWriter.

WriteVec4()

void ezStandardJSONWriter::WriteVec4 ( const ezVec4 &  value )

overridevirtual

Writes {"x":..,"y":..,"z":..,"w":..}.

Implements ezJSONWriter.

WriteVec4I32()

void ezStandardJSONWriter::WriteVec4I32 ( const ezVec4I32 &  value )

overridevirtual

Writes {"x":..,"y":..,"z":..,"w":..}.

Implements ezJSONWriter.

---

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

• /home/runner/work/ezEngine/ezEngine/Code/Engine/Foundation/IO/JSONWriter.h
• /home/runner/work/ezEngine/ezEngine/Code/Engine/Foundation/IO/Implementation/StandardJSONWriter.cpp