RapidJSON: rapidjson::GenericStringRef< CharType > Struct Template Reference

Public Types | Public Member Functions | Public Attributes | Related Functions | List of all members
rapidjson::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

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

## Public Attributes
const Ch *const | s
| plain CharType pointer
const SizeType | length
| length of the string (excluding the trailing NULL terminator)

## 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...
template<typename CharType >
GenericStringRef< CharType > | StringRef (const std::basic_string< CharType > &str)
| Mark a string object as constant string. More...

## Detailed Description

### template<typename CharType>
struct rapidjson::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

## Constructor & Destructor Documentation

## ◆ GenericStringRef() [1/3]

template<typename CharType >
template<SizeType N>

rapidjson::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

  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.

## ◆ GenericStringRef() [2/3]

template<typename CharType >

rapidjson::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

  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.

## ◆ GenericStringRef() [3/3]

template<typename CharType >

rapidjson::GenericStringRef< CharType >::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.

## Friends And Related Function Documentation

## ◆ StringRef() [1/3]

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

  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

## ◆ StringRef() [2/3]

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

  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

## ◆ StringRef() [3/3]

template<typename CharType >

GenericStringRef< CharType > StringRef | ( | const std::basic_string< CharType > & | str | ) |
| related

Mark a string object as constant string.

Mark a string object (e.g. `std::string`) as a "string literal". This function can be used to avoid copying a 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

Note
  Requires the definition of the preprocessor symbol RAPIDJSON_HAS_STDSTRING.

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

- include/rapidjson/document.h

rapidjson::GenericStringRef::StringRef
GenericStringRef< CharType > StringRef(const CharType *str)
Mark a character pointer as constant string.
Definition: document.h:443
rapidjson::Value
GenericValue< UTF8<> > Value
GenericValue with UTF8 encoding.
Definition: document.h:2189