sfs3::entities::SFSObject Class Reference

A platform-neutral container of named values, used to exchange data between client and server. More...

#include <SFSObject.h>

Public Member Functions
bool	isNull (const std::string &key) const
	Tells if the value stored under a key is a null value.
bool	containsKey (const std::string &key) const
bool	removeElement (const std::string &key)
	Removes a value from this object.
std::vector< std::string >	getKeys () const
size_t	size () const
std::unique_ptr< ByteBuffer >	toBinary () const
std::string	getDump () const
std::string	getDump (bool noFormat) const
std::string	getHexDump () const
std::optional< bool >	getBool (const std::string &key) const
std::optional< uint8_t >	getByte (const std::string &key) const
std::optional< int16_t >	getShort (const std::string &key) const
std::optional< int32_t >	getInt (const std::string &key) const
std::optional< int64_t >	getLong (const std::string &key) const
std::optional< float >	getFloat (const std::string &key) const
std::optional< double >	getDouble (const std::string &key) const
std::optional< std::string >	getShortString (const std::string &key) const
	Reads a UTF-8 string of at most 255 bytes.
std::optional< std::string >	getString (const std::string &key) const
	Reads a UTF-8 string of at most 32767 bytes.
std::optional< std::string >	getText (const std::string &key) const
	Reads a UTF-8 string of at most 2 GB.
std::optional< SFSVector2 >	getVector2 (const std::string &key) const
std::optional< SFSVector3 >	getVector3 (const std::string &key) const
std::optional< std::vector< bool > >	getBoolArray (const std::string &key) const
std::optional< std::vector< uint8_t > >	getByteArray (const std::string &key) const
const std::vector< uint8_t > *	getByteArrayPtr (const std::string &key) const
	Reads an array of bytes without copying it.
std::optional< std::vector< int16_t > >	getShortArray (const std::string &key) const
std::optional< std::vector< int32_t > >	getIntArray (const std::string &key) const
std::optional< std::vector< int64_t > >	getLongArray (const std::string &key) const
std::optional< std::vector< float > >	getFloatArray (const std::string &key) const
std::optional< std::vector< double > >	getDoubleArray (const std::string &key) const
std::optional< std::vector< std::string > >	getStringArray (const std::string &key) const
	Reads an array of UTF-8 strings, each one of at most 32767 bytes.
std::optional< std::vector< std::string > >	getShortStringArray (const std::string &key) const
	Reads an array of UTF-8 strings, each one of at most 255 bytes.
std::optional< std::vector< SFSVector2 > >	getVector2Array (const std::string &key) const
std::optional< std::vector< SFSVector3 > >	getVector3Array (const std::string &key) const
std::shared_ptr< SFSObject >	getSFSObject (const std::string &key) const
std::shared_ptr< SFSArray >	getSFSArray (const std::string &key) const
void	putNull (std::string key)
	Adds a null value.
void	putBool (std::string key, bool value)
	Adds a boolean.
void	putByte (std::string key, uint8_t value)
	Adds a byte (8 bit).
void	putShort (std::string key, int16_t value)
	Adds a short (signed 16 bit).
void	putInt (std::string key, int32_t value)
	Adds an integer (signed 32 bit).
void	putLong (std::string key, int64_t value)
	Adds a long (signed 64 bit).
void	putFloat (std::string key, float value)
	Adds a float (signed 32 bit).
void	putDouble (std::string key, double value)
	Adds a double (signed 64 bit).
void	putString (std::string key, std::string value)
	Adds a UTF-8 string, with a limit of 32767 bytes.
void	putShortString (std::string key, std::string value)
	Adds a UTF-8 string, with a limit of 255 bytes.
void	putText (std::string key, std::string value)
	Adds a UTF-8 string, with a limit of 2 GB.
void	putVector2 (std::string key, SFSVector2 value)
	Adds a 2D vector.
void	putVector3 (std::string key, SFSVector3 value)
	Adds a 3D vector.
void	putSFSObject (std::string key, std::shared_ptr< SFSObject > value)
	Adds a nested SFSObject.
void	putSFSArray (std::string key, std::shared_ptr< SFSArray > value)
	Adds a nested SFSArray.
void	putSFSObject (std::string key, const SFSObject *value)
	Adds a copy of a nested SFSObject.
void	putSFSArray (std::string key, const SFSArray *value)
	Adds a copy of a nested SFSArray.
void	putBoolArray (std::string key, std::vector< bool > value)
	Adds an array of booleans.
void	putByteArray (std::string key, std::vector< uint8_t > value)
	Adds an array of bytes.
void	putByteArray (std::string key, const uint8_t *data, size_t length)
	Adds an array of bytes read from raw memory.
void	putShortArray (std::string key, std::vector< int16_t > value)
	Adds an array of shorts.
void	putIntArray (std::string key, std::vector< int32_t > value)
	Adds an array of integers.
void	putLongArray (std::string key, std::vector< int64_t > value)
	Adds an array of longs.
void	putFloatArray (std::string key, std::vector< float > value)
	Adds an array of floats.
void	putDoubleArray (std::string key, std::vector< double > value)
	Adds an array of doubles.
void	putShortStringArray (std::string key, std::vector< std::string > value)
	Adds an array of UTF-8 strings, each one limited to 255 bytes.
void	putStringArray (std::string key, std::vector< std::string > value)
	Adds an array of UTF-8 strings, each one limited to 32767 bytes.
void	putVector2Array (std::string key, std::vector< SFSVector2 > value)
	Adds an array of 2D vectors.
void	putVector3Array (std::string key, std::vector< SFSVector3 > value)
	Adds an array of 3D vectors.

Detailed Description

A platform-neutral container of named values, used to exchange data between client and server.

SFSObject holds the data as a map of keys and values; SFSArray holds it as a list. Both carry many different data types, from a single byte to arrays of doubles, strings and more.

These are the supported types and their size limits:

Type	Item size	Array length
null	—
bool	1 byte
byte	1 byte
short	2 bytes
int	4 bytes
long	8 bytes
float	4 bytes
double	8 bytes
SFSVector2	8 bytes
SFSVector3	12 bytes
short string	<= 255 bytes
string	<= 2^15 bytes
text	<= 2^31 bytes
bool array	1 byte	<= 2^15
byte array	1 byte	<= 2^31
short array	2 bytes	<= 2^15
int array	4 bytes	<= 2^15
long array	8 bytes	<= 2^15
float array	4 bytes	<= 2^15
double array	8 bytes	<= 2^15
SFSVector2 array	8 bytes	<= 2^15
SFSVector3 array	12 bytes	<= 2^15
short string array	<= 255 bytes	<= 2^15
string array	<= 2^15 bytes	<= 2^15

NOTE 1: every key is sent as a short string, so it must be 255 bytes or shorter. Keep the key names as short as you can, to keep the network overhead low.

NOTE 2: every string is UTF-8, so one character can take more than one byte. A string of 255 characters can need more than 255 bytes.

NOTE 3: an SFSObject and an SFSArray can be nested one inside the other, to build more complex data structures.

NOTE 4: the methods of SFSObject and SFSArray are not thread safe.

See also

SFSArray

Member Function Documentation

isNull()

bool sfs3::entities::SFSObject::isNull

(

const std::string &

key

)

const

Tells if the value stored under a key is a null value.

Parameters

key	the name of the value

Returns

true if the value is null

containsKey()

bool sfs3::entities::SFSObject::containsKey

(

const std::string &

key

)

const

Parameters

key	the name to look for

Returns

true if this object holds a value under that name

removeElement()

bool sfs3::entities::SFSObject::removeElement

(

const std::string &

key

)

Removes a value from this object.

Parameters

key	the name of the value to remove

Returns

true if the value was in this object

getKeys()

std::vector< std::string > sfs3::entities::SFSObject::getKeys

(

)

const

Returns

all the names used in this object

size()

size_t sfs3::entities::SFSObject::size

(

)

const

Returns

the number of values in this object

toBinary()

std::unique_ptr< ByteBuffer > sfs3::entities::SFSObject::toBinary

(

)

const

Returns

this object in its serialized, binary form

getDump() [1/2]

std::string sfs3::entities::SFSObject::getDump

(

)

const

Returns

a detailed, pretty-printed dump of the structure of this object

getDump() [2/2]

std::string sfs3::entities::SFSObject::getDump

(

bool

noFormat

)

const

Parameters

noFormat

if true the dump is not pretty-printed

Returns

a detailed dump of the structure of this object

getHexDump()

std::string sfs3::entities::SFSObject::getHexDump

(

)

const

Returns

a pretty-printed hexadecimal dump of this object

getBool()

std::optional< bool > sfs3::entities::SFSObject::getBool

(

const std::string &

key

)

const

Parameters

key	the name of the value

Returns

the value as a boolean, or an empty optional if there is no such value

getByte()

std::optional< uint8_t > sfs3::entities::SFSObject::getByte

(

const std::string &

key

)

const

Parameters

key	the name of the value

Returns

the value as a byte (8 bit), or an empty optional if there is no such value

getShort()

std::optional< int16_t > sfs3::entities::SFSObject::getShort

(

const std::string &

key

)

const

Parameters

key	the name of the value

Returns

the value as a short (signed 16 bit), or an empty optional if there is no such value

getInt()

std::optional< int32_t > sfs3::entities::SFSObject::getInt

(

const std::string &

key

)

const

Parameters

key	the name of the value

Returns

the value as an integer (signed 32 bit), or an empty optional if there is no such value

getLong()

std::optional< int64_t > sfs3::entities::SFSObject::getLong

(

const std::string &

key

)

const

Parameters

key	the name of the value

Returns

the value as a long (signed 64 bit), or an empty optional if there is no such value

getFloat()

std::optional< float > sfs3::entities::SFSObject::getFloat

(

const std::string &

key

)

const

Parameters

key	the name of the value

Returns

the value as a float (signed decimal 32 bit), or an empty optional if there is no such value

getDouble()

std::optional< double > sfs3::entities::SFSObject::getDouble

(

const std::string &

key

)

const

Parameters

key	the name of the value

Returns

the value as a double (signed decimal 64 bit), or an empty optional if there is no such value

getShortString()

std::optional< std::string > sfs3::entities::SFSObject::getShortString

(

const std::string &

key

)

const

Reads a UTF-8 string of at most 255 bytes.

Parameters

key	the name of the value

Returns

the value as a string, or an empty optional if there is no such value

getString()

std::optional< std::string > sfs3::entities::SFSObject::getString

(

const std::string &

key

)

const

Reads a UTF-8 string of at most 32767 bytes.

Parameters

key	the name of the value

Returns

the value as a string, or an empty optional if there is no such value

getText()

std::optional< std::string > sfs3::entities::SFSObject::getText

(

const std::string &

key

)

const

Reads a UTF-8 string of at most 2 GB.

Parameters

key	the name of the value

Returns

the value as a string, or an empty optional if there is no such value

getVector2()

std::optional< SFSVector2 > sfs3::entities::SFSObject::getVector2

(

const std::string &

key

)

const

Parameters

key	the name of the value

Returns

the value as a 2D vector, or an empty optional if there is no such value

getVector3()

std::optional< SFSVector3 > sfs3::entities::SFSObject::getVector3

(

const std::string &

key

)

const

Parameters

key	the name of the value

Returns

the value as a 3D vector, or an empty optional if there is no such value

getBoolArray()

std::optional< std::vector< bool > > sfs3::entities::SFSObject::getBoolArray

(

const std::string &

key

)

const

Parameters

key	the name of the value

Returns

the value as an array of booleans, or an empty optional if there is no such value

getByteArray()

std::optional< std::vector< uint8_t > > sfs3::entities::SFSObject::getByteArray

(

const std::string &

key

)

const

Parameters

key	the name of the value

Returns

the value as an array of bytes, or an empty optional if there is no such value

See also

SFSObject::getByteArrayPtr

getByteArrayPtr()

const std::vector< uint8_t > * sfs3::entities::SFSObject::getByteArrayPtr

(

const std::string &

key

)

const

Reads an array of bytes without copying it.

Use it in place of SFSObject::getByteArray for a large array. The pointer stays valid as long as this object holds the value and is not changed.

Parameters

key	the name of the value

Returns

a pointer to the array, or nullptr if there is no such value

getShortArray()

std::optional< std::vector< int16_t > > sfs3::entities::SFSObject::getShortArray

(

const std::string &

key

)

const

Parameters

key	the name of the value

Returns

the value as an array of shorts, or an empty optional if there is no such value

getIntArray()

std::optional< std::vector< int32_t > > sfs3::entities::SFSObject::getIntArray

(

const std::string &

key

)

const

Parameters

key	the name of the value

Returns

the value as an array of integers, or an empty optional if there is no such value

getLongArray()

std::optional< std::vector< int64_t > > sfs3::entities::SFSObject::getLongArray

(

const std::string &

key

)

const

Parameters

key	the name of the value

Returns

the value as an array of longs, or an empty optional if there is no such value

getFloatArray()

std::optional< std::vector< float > > sfs3::entities::SFSObject::getFloatArray

(

const std::string &

key

)

const

Parameters

key	the name of the value

Returns

the value as an array of floats, or an empty optional if there is no such value

getDoubleArray()

std::optional< std::vector< double > > sfs3::entities::SFSObject::getDoubleArray

(

const std::string &

key

)

const

Parameters

key	the name of the value

Returns

the value as an array of doubles, or an empty optional if there is no such value

getStringArray()

std::optional< std::vector< std::string > > sfs3::entities::SFSObject::getStringArray

(

const std::string &

key

)

const

Reads an array of UTF-8 strings, each one of at most 32767 bytes.

Parameters

key	the name of the value

Returns

the value as an array of strings, or an empty optional if there is no such value

getShortStringArray()

std::optional< std::vector< std::string > > sfs3::entities::SFSObject::getShortStringArray

(

const std::string &

key

)

const

Reads an array of UTF-8 strings, each one of at most 255 bytes.

Parameters

key	the name of the value

Returns

the value as an array of strings, or an empty optional if there is no such value

getVector2Array()

std::optional< std::vector< SFSVector2 > > sfs3::entities::SFSObject::getVector2Array

(

const std::string &

key

)

const

Parameters

key	the name of the value

Returns

the value as an array of 2D vectors, or an empty optional if there is no such value

getVector3Array()

std::optional< std::vector< SFSVector3 > > sfs3::entities::SFSObject::getVector3Array

(

const std::string &

key

)

const

Parameters

key	the name of the value

Returns

the value as an array of 3D vectors, or an empty optional if there is no such value

getSFSObject()

std::shared_ptr< SFSObject > sfs3::entities::SFSObject::getSFSObject

(

const std::string &

key

)

const

Parameters

key	the name of the value

Returns

the nested SFSObject, or nullptr if there is no such value

getSFSArray()

std::shared_ptr< SFSArray > sfs3::entities::SFSObject::getSFSArray

(

const std::string &

key

)

const

Parameters

key	the name of the value

Returns

the nested SFSArray, or nullptr if there is no such value

See also

SFSArray

putNull()

void sfs3::entities::SFSObject::putNull

(

std::string

key

)

Adds a null value.

We recommend that you simply do not send a value that is null. On the other side of the connection, check if the key exists instead. This method adds the key and one byte that marks the null value, so it makes the message bigger for nothing.

Parameters

key	the name of the value

putBool()

void sfs3::entities::SFSObject::putBool	(	std::string	key,
		bool	value )

Adds a boolean.

Parameters

key	the name of the value
value	the value

putByte()

void sfs3::entities::SFSObject::putByte	(	std::string	key,
		uint8_t	value )

Adds a byte (8 bit).

Parameters

key	the name of the value
value	the value

putShort()

void sfs3::entities::SFSObject::putShort	(	std::string	key,
		int16_t	value )

Adds a short (signed 16 bit).

Parameters

key	the name of the value
value	the value

putInt()

void sfs3::entities::SFSObject::putInt	(	std::string	key,
		int32_t	value )

Adds an integer (signed 32 bit).

Parameters

key	the name of the value
value	the value

putLong()

void sfs3::entities::SFSObject::putLong	(	std::string	key,
		int64_t	value )

Adds a long (signed 64 bit).

Parameters

key	the name of the value
value	the value

putFloat()

void sfs3::entities::SFSObject::putFloat	(	std::string	key,
		float	value )

Adds a float (signed 32 bit).

Parameters

key	the name of the value
value	the value

putDouble()

void sfs3::entities::SFSObject::putDouble	(	std::string	key,
		double	value )

Adds a double (signed 64 bit).

Parameters

key	the name of the value
value	the value

putString()

void sfs3::entities::SFSObject::putString	(	std::string	key,
		std::string	value )

Adds a UTF-8 string, with a limit of 32767 bytes.

Parameters

key	the name of the value
value	the value

See also

SFSObject::putShortString

SFSObject::putText

putShortString()

void sfs3::entities::SFSObject::putShortString	(	std::string	key,
		std::string	value )

Adds a UTF-8 string, with a limit of 255 bytes.

Parameters

key	the name of the value
value	the value

putText()

void sfs3::entities::SFSObject::putText	(	std::string	key,
		std::string	value )

Adds a UTF-8 string, with a limit of 2 GB.

Parameters

key	the name of the value
value	the value

putVector2()

void sfs3::entities::SFSObject::putVector2	(	std::string	key,
		SFSVector2	value )

Adds a 2D vector.

Parameters

key	the name of the value
value	the value

putVector3()

void sfs3::entities::SFSObject::putVector3	(	std::string	key,
		SFSVector3	value )

Adds a 3D vector.

Parameters

key	the name of the value
value	the value

putSFSObject() [1/2]

void sfs3::entities::SFSObject::putSFSObject	(	std::string	key,
		std::shared_ptr< SFSObject >	value )

Adds a nested SFSObject.

Parameters

key	the name of the value
value	the value

putSFSArray() [1/2]

void sfs3::entities::SFSObject::putSFSArray	(	std::string	key,
		std::shared_ptr< SFSArray >	value )

Adds a nested SFSArray.

Parameters

key	the name of the value
value	the value

See also

SFSArray

putSFSObject() [2/2]

void sfs3::entities::SFSObject::putSFSObject	(	std::string	key,
		const SFSObject *	value )

Adds a copy of a nested SFSObject.

The caller keeps the ownership of the object it passes: this method copies it, so that this SFSObject owns its whole tree. A nullptr does nothing.

Parameters

key	the name of the value
value	the object to copy

putSFSArray() [2/2]

void sfs3::entities::SFSObject::putSFSArray	(	std::string	key,
		const SFSArray *	value )

Adds a copy of a nested SFSArray.

The caller keeps the ownership of the array it passes: this method copies it, so that this SFSObject owns its whole tree. A nullptr does nothing.

Parameters

key	the name of the value
value	the array to copy

putBoolArray()

void sfs3::entities::SFSObject::putBoolArray	(	std::string	key,
		std::vector< bool >	value )

Adds an array of booleans.

Parameters

key	the name of the value
value	the value

putByteArray() [1/2]

void sfs3::entities::SFSObject::putByteArray	(	std::string	key,
		std::vector< uint8_t >	value )

Adds an array of bytes.

Parameters

key	the name of the value
value	the value

putByteArray() [2/2]

void sfs3::entities::SFSObject::putByteArray	(	std::string	key,
		const uint8_t *	data,
		size_t	length )

Adds an array of bytes read from raw memory.

The bytes are copied, so the caller keeps the ownership of the memory it passes.

Parameters

key	the name of the value
data	the first byte to copy
length	how many bytes to copy

putShortArray()

void sfs3::entities::SFSObject::putShortArray	(	std::string	key,
		std::vector< int16_t >	value )

Adds an array of shorts.

Parameters

key	the name of the value
value	the value

putIntArray()

void sfs3::entities::SFSObject::putIntArray	(	std::string	key,
		std::vector< int32_t >	value )

Adds an array of integers.

Parameters

key	the name of the value
value	the value

putLongArray()

void sfs3::entities::SFSObject::putLongArray	(	std::string	key,
		std::vector< int64_t >	value )

Adds an array of longs.

Parameters

key	the name of the value
value	the value

putFloatArray()

void sfs3::entities::SFSObject::putFloatArray	(	std::string	key,
		std::vector< float >	value )

Adds an array of floats.

Parameters

key	the name of the value
value	the value

putDoubleArray()

void sfs3::entities::SFSObject::putDoubleArray	(	std::string	key,
		std::vector< double >	value )

Adds an array of doubles.

Parameters

key	the name of the value
value	the value

putShortStringArray()

void sfs3::entities::SFSObject::putShortStringArray	(	std::string	key,
		std::vector< std::string >	value )

Adds an array of UTF-8 strings, each one limited to 255 bytes.

The array itself is limited to 32767 strings.

Parameters

key	the name of the value
value	the value

putStringArray()

void sfs3::entities::SFSObject::putStringArray	(	std::string	key,
		std::vector< std::string >	value )

Adds an array of UTF-8 strings, each one limited to 32767 bytes.

The array itself is limited to 32767 strings.

Parameters

key	the name of the value
value	the value

putVector2Array()

void sfs3::entities::SFSObject::putVector2Array	(	std::string	key,
		std::vector< SFSVector2 >	value )

Adds an array of 2D vectors.

Parameters

key	the name of the value
value	the value

putVector3Array()

void sfs3::entities::SFSObject::putVector3Array	(	std::string	key,
		std::vector< SFSVector3 >	value )

Adds an array of 3D vectors.

Parameters

key	the name of the value
value	the value

---

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

• entities/SFSObject.h
• entities/SFSObject.cpp