GenericStringRef< CharType > Struct Template Reference

GenericStringRef&lt; CharType &gt; Struct Template Reference#

Composable Kernel: GenericStringRef< CharType > Struct Template Reference
Public Types | Public Member Functions | Public Attributes | Related Functions | List of all members
GenericStringRef< CharType > Struct Template Reference

Reference to a constant string (not taking a copy) More...

#include <document.h>

Public Types

typedef CharType Ch
 character type of the string More...
 

Public Member Functions

template<SizeType N>
 GenericStringRef (const CharType(&str)[N]) RAPIDJSON_NOEXCEPT
 Create string reference from const character array. More...
 
 GenericStringRef (const CharType *str)
 Explicitly create string reference from const character pointer. More...
 
 GenericStringRef (const CharType *str, SizeType len)
 Create constant string reference from pointer and length. More...
 
 GenericStringRef (const GenericStringRef &rhs)
 
 operator const Ch * () const
 implicit conversion to plain CharType pointer More...
 

Public Attributes

const Ch *const s
 plain CharType pointer More...
 
const SizeType length
 length of the string (excluding the trailing NULL terminator) More...
 

Related Functions

(Note that these are not member functions.)

template<typename CharType >
GenericStringRef< CharType > StringRef (const CharType *str)
 Mark a character pointer as constant string. More...
 
template<typename CharType >
GenericStringRef< CharType > StringRef (const CharType *str, size_t length)
 Mark a character pointer as constant string. More...
 

Detailed Description

template<typename CharType>
struct GenericStringRef< CharType >

Reference to a constant string (not taking a copy)

Template Parameters
CharTypecharacter 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
GenericValue
Represents a JSON value. Use Value for UTF8 encoding and default allocator.
Definition: document.h:668
GenericStringRef::StringRef
GenericStringRef< CharType > StringRef(const CharType *str)
Mark a character pointer as constant string.
Definition: document.h:454
See also
StringRef, GenericValue::SetString

Member Typedef Documentation

◆ Ch

template<typename CharType >
typedef CharType GenericStringRef< CharType >::Ch

character type of the string

Constructor & Destructor Documentation

◆ GenericStringRef() [1/4]

template<typename CharType >
template<SizeType N>
GenericStringRef< CharType >::GenericStringRef ( const CharType(&)  str[N])
inline

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.

Template Parameters
Nlength of the string, automatically inferred
Parameters
strConstant character array, lifetime assumed to be longer than the use of the string in e.g. a GenericValue
Postcondition
s == str
Note
Constant complexity.
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() [2/4]

template<typename CharType >
GenericStringRef< CharType >::GenericStringRef ( const CharType *  str)
inlineexplicit

Explicitly create string reference from const character pointer.

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

See also
StringRef(const CharType*)
Parameters
strConstant character pointer, lifetime assumed to be longer than the use of the string in e.g. a GenericValue
Postcondition
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() [3/4]

template<typename CharType >
GenericStringRef< CharType >::GenericStringRef ( const CharType *  str,
SizeType  len 
)
inline

Create constant string reference from pointer and length.

Parameters
strconstant string, lifetime assumed to be longer than the use of the string in e.g. a GenericValue
lenlength of the string, excluding the trailing NULL terminator
Postcondition
s == str && length == len
Note
Constant complexity.

◆ GenericStringRef() [4/4]

template<typename CharType >
GenericStringRef< CharType >::GenericStringRef ( const GenericStringRef< CharType > &  rhs)
inline

Member Function Documentation

◆ operator const Ch *()

template<typename CharType >
GenericStringRef< CharType >::operator const Ch * ( ) const
inline

implicit conversion to plain CharType pointer

Friends And Related Function Documentation

◆ StringRef() [1/2]

template<typename CharType >
GenericStringRef< CharType > StringRef ( const CharType *  str)
related

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.

Template Parameters
CharTypeCharacter type of the string
Parameters
strConstant string, lifetime assumed to be longer than the use of the string in e.g. a GenericValue
Returns
GenericStringRef string reference object
See also
GenericValue::GenericValue(StringRefType), GenericValue::operator=(StringRefType), GenericValue::SetString(StringRefType), GenericValue::PushBack(StringRefType, Allocator&), GenericValue::AddMember

◆ StringRef() [2/2]

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

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.

Template Parameters
CharTypecharacter type of the string
Parameters
strConstant string, lifetime assumed to be longer than the use of the string in e.g. a GenericValue
lengthThe length of source string.
Returns
GenericStringRef string reference object

Member Data Documentation

◆ length

template<typename CharType >
const SizeType GenericStringRef< CharType >::length

length of the string (excluding the trailing NULL terminator)

◆ s

template<typename CharType >
const Ch* const GenericStringRef< CharType >::s

plain CharType pointer

The documentation for this struct was generated from the following file:
  • /home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-composable-kernel/checkouts/develop/include/rapidjson/document.h