Torque3D Documentation / _generateds / GenericStringRef

GenericStringRef

Engine/source/persistence/rapidjson/document.h

Reference to a constant string (not taking a copy)

More...

Public Types

CharType
Ch 

character type of the string

Public Attributes

length of the string (excluding the trailing NULL terminator)

s 

plain CharType pointer

Private Static Attributes

Empty string - used when passing in a NULL pointer.

Public Functions

GenericStringRef(const CharType * str)

Explicitly create string reference from

const
character pointer.

GenericStringRef(const CharType * str, SizeType len)

Create constant string reference from pointer and length.

GenericStringRef(const CharType(&) str)

Create string reference from

const
character array.

implicit conversion to plain CharType pointer

Private Functions

GenericStringRef(CharType(&) str)

Disallow construction from non-const array.

NotNullStrLen(const CharType * str)

Copy assignment operator not permitted - immutable type.

Public Related

GenericStringRef< CharType >
StringRef(const CharType * str)

Mark a character pointer as constant string.

GenericStringRef< CharType >
StringRef(const CharType * str, size_t length)

Mark a character pointer as constant string.

Detailed Description

Reference to a constant string (not taking a copy)

Parameters:

CharType

character type of the string

This helper class is used to automatically infer constant string references for string literals, especially from
const
(!) character arrays.

The main use is for creating JSON string values without copying the source string via an Allocator. This requires that the referenced string pointers have a sufficient lifetime, which exceeds the lifetime of the associated GenericValue.

Example

Value v("foo");   // ok, no need to copy & calculate length
const char foo[] = "foo";
v.SetString(foo); // ok

const char* bar = foo;
// Value x(bar); // not ok, can't rely on bar's lifetime
Value x(StringRef(bar)); // lifetime explicitly guaranteed by user
Value y(StringRef(bar, 3));  // ok, explicitly pass length

see:

StringRef, GenericValue::SetString

Public Types

typedef CharType Ch 

character type of the string

Public Attributes

const SizeType length 

length of the string (excluding the trailing NULL terminator)

const Ch *const s 

plain CharType pointer

Private Static Attributes

const Ch emptyString []

Empty string - used when passing in a NULL pointer.

Public Functions

GenericStringRef(const CharType * str)

Explicitly create string reference from

const
character pointer.

This constructor can be used to explicitly create a reference to a constant string pointer.

Parameters:
str

Constant character pointer, lifetime assumed to be longer than the use of the string in e.g. a GenericValue

post:

s == str

note:

There is a hidden, private overload to disallow references to non-const character arrays to be created via this constructor. By this, e.g. function-scope arrays used to be filled via

snprintf
are excluded from consideration. In such cases, the referenced string should be copied to the GenericValue instead.

GenericStringRef(const CharType * str, SizeType len)

Create constant string reference from pointer and length.

Parameters:

str

constant string, lifetime assumed to be longer than the use of the string in e.g. a GenericValue

len

length of the string, excluding the trailing NULL terminator

post:

s == str && length == len

note:

Constant complexity.

GenericStringRef(const CharType(&) str)

Create string reference from

const
character array.

This constructor implicitly creates a constant string reference from a

const
character array. It has better performance than StringRef(const CharType*) by inferring the string length from the array length, and also supports strings containing null characters.

Parameters:

N

length of the string, automatically inferred

Parameters:
str

Constant character array, lifetime assumed to be longer than the use of the string in e.g. a GenericValue

post:

s == str

note:

Constant complexity.

note:

There is a hidden, private overload to disallow references to non-const character arrays to be created via this constructor. By this, e.g. function-scope arrays used to be filled via

snprintf
are excluded from consideration. In such cases, the referenced string should be copied to the GenericValue instead.

GenericStringRef(const GenericStringRef & rhs)

operator const Ch*()

implicit conversion to plain CharType pointer

Private Functions

GenericStringRef(CharType(&) str)

Disallow construction from non-const array.

NotNullStrLen(const CharType * str)

operator=(const GenericStringRef & rhs)

Copy assignment operator not permitted - immutable type.

Public Related

StringRef(const CharType * str)

Mark a character pointer as constant string.

Mark a plain character pointer as a "string literal". This function can be used to avoid copying a character string to be referenced as a value in a JSON GenericValue object, if the string's lifetime is known to be valid long enough. Parameters:

CharType

Character type of the string

Parameters:
str

Constant string, lifetime assumed to be longer than the use of the string in e.g. a GenericValue

return:

GenericStringRef string reference object

see:

GenericValue::GenericValue(StringRefType), GenericValue::operator=(StringRefType), GenericValue::SetString(StringRefType), GenericValue::PushBack(StringRefType, Allocator&), GenericValue::AddMember

StringRef(const CharType * str, size_t length)

Mark a character pointer as constant string.

Mark a plain character pointer as a "string literal". This function can be used to avoid copying a character string to be referenced as a value in a JSON GenericValue object, if the string's lifetime is known to be valid long enough.

This version has better performance with supplied length, and also supports string containing null characters.

Parameters:

CharType

character type of the string

Parameters:
str

Constant string, lifetime assumed to be longer than the use of the string in e.g. a GenericValue

length

The length of source string.

return:

GenericStringRef string reference object