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

#include <document.h>

Collaboration diagram for GenericStringRef< CharType >:

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...

Private Member Functions
SizeType	NotNullStrLen (const CharType *str)

template<SizeType N>
	GenericStringRef (CharType(&str)[N])
	Disallow construction from non-const array. More...

GenericStringRef &	operator= (const GenericStringRef &rhs)
	Copy assignment operator not permitted - immutable type. More...

Static Private Attributes
static const Ch	emptyString [] = { CharType() }
	Empty string - used when passing in a NULL pointer. 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

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 also: StringRef, GenericValue::SetString

Definition at line 256 of file document.h.

Member Typedef Documentation

◆ Ch

typedef CharType Ch

character type of the string

Definition at line 257 of file document.h.

Constructor & Destructor Documentation

◆ GenericStringRef() [1/5]

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

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

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.

Definition at line 285 of file document.h.

286 : s(str), length(N-1) {}

GenericStringRef::s

const Ch *const s

plain CharType pointer

Definition: document.h:329

GenericStringRef::length

const SizeType length

length of the string (excluding the trailing NULL terminator)

Definition: document.h:330

◆ GenericStringRef() [2/5]

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

str	Constant 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.

Definition at line 309 of file document.h.

310 : s(str), length(NotNullStrLen(str)) {}

GenericStringRef::s

const Ch *const s

plain CharType pointer

Definition: document.h:329

GenericStringRef::NotNullStrLen

SizeType NotNullStrLen(const CharType *str)

Definition: document.h:333

GenericStringRef::length

const SizeType length

length of the string (excluding the trailing NULL terminator)

Definition: document.h:330

◆ GenericStringRef() [3/5]

GenericStringRef	(	const CharType *	str,
		SizeType	len
	)

inline

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

Postcondition: s == str && length == len

Note: Constant complexity.

Definition at line 321 of file document.h.

322 : s(RAPIDJSON_LIKELY(str) ? str : emptyString), length(len) { RAPIDJSON_ASSERT(str != 0 || len == 0u); }

GenericStringRef::s

const Ch *const s

plain CharType pointer

Definition: document.h:329

RAPIDJSON_LIKELY

#define RAPIDJSON_LIKELY(x)

Compiler branching hint for expression with high probability to be true.

Definition: rapidjson.h:463

GenericStringRef::length

const SizeType length

length of the string (excluding the trailing NULL terminator)

Definition: document.h:330

GenericStringRef::emptyString

static const Ch emptyString[]

Empty string - used when passing in a NULL pointer.

Definition: document.h:339

RAPIDJSON_ASSERT

#define RAPIDJSON_ASSERT(x)

Assertion.

Definition: rapidjson.h:406

◆ GenericStringRef() [4/5]

GenericStringRef ( const GenericStringRef< CharType > & rhs )

inline

Definition at line 324 of file document.h.

324 : s(rhs.s), length(rhs.length) {}

GenericStringRef::s

const Ch *const s

plain CharType pointer

Definition: document.h:329

GenericStringRef::length

const SizeType length

length of the string (excluding the trailing NULL terminator)

Definition: document.h:330

◆ GenericStringRef() [5/5]

GenericStringRef ( CharType(&) str[N] )

private

Disallow construction from non-const array.

Member Function Documentation

◆ NotNullStrLen()

SizeType NotNullStrLen ( const CharType * str )

inlineprivate

Definition at line 333 of file document.h.

                                                 {
         RAPIDJSON_ASSERT(str != 0);
         return internal::StrLen(str);
     }

Here is the call graph for this function:

◆ operator const Ch *()

operator const Ch * ( ) const

inline

implicit conversion to plain CharType pointer

Definition at line 327 of file document.h.

327 { return s; }

GenericStringRef::s

const Ch *const s

plain CharType pointer

Definition: document.h:329

◆ operator=()

GenericStringRef& operator= ( const GenericStringRef< CharType > & rhs )

private

Copy assignment operator not permitted - immutable type.

Friends And Related Function Documentation

◆ StringRef() [1/2]

GenericStringRef< CharType > StringRef ( const CharType * str )

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

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

Returns: GenericStringRef string reference object

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

Definition at line 364 of file document.h.

                                                                  {
     return GenericStringRef<CharType>(str);
 }

◆ StringRef() [2/2]

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

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

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.

Returns: GenericStringRef string reference object

Definition at line 384 of file document.h.

                                                                                 {
     return GenericStringRef<CharType>(str, SizeType(length));
 }

Member Data Documentation

◆ emptyString

const CharType emptyString = { CharType() }

staticprivate

Empty string - used when passing in a NULL pointer.

Definition at line 339 of file document.h.

◆ length

const SizeType length

length of the string (excluding the trailing NULL terminator)

Definition at line 330 of file document.h.

◆ s

const Ch* const s

plain CharType pointer

Definition at line 329 of file document.h.

The documentation for this struct was generated from the following file:

rapidjson/document.h

Public Types

Public Member Functions

Public Attributes

Private Member Functions

Static Private Attributes

Related Functions

Detailed Description

template<typename CharType> struct GenericStringRef< CharType >

Member Typedef Documentation

◆ Ch

Constructor & Destructor Documentation

◆ GenericStringRef() [1/5]

◆ GenericStringRef() [2/5]

◆ GenericStringRef() [3/5]

◆ GenericStringRef() [4/5]

◆ GenericStringRef() [5/5]

Member Function Documentation

◆ NotNullStrLen()

◆ operator const Ch *()

◆ operator=()

Friends And Related Function Documentation

◆ StringRef() [1/2]

◆ StringRef() [2/2]

Member Data Documentation

◆ emptyString

◆ length

◆ s

template<typename CharType>
struct GenericStringRef< CharType >