92 lines
4.9 KiB
Markdown
92 lines
4.9 KiB
Markdown
# nlohmann::basic_json_view::get_string
|
|
|
|
```
|
|
string_view_t get_string() const;
|
|
```
|
|
|
|
Returns the string value as a [`string_view_t`](https://json.nlohmann.me/api/basic_json_view/#member-types), without copying it.
|
|
|
|
## Return value
|
|
|
|
The string, as a [`string_view_t`](https://json.nlohmann.me/api/basic_json_view/#member-types) that points either into the document's [`source()`](https://json.nlohmann.me/api/basic_json_document/source/index.md) text (a string with no escape sequences), or into the document's own buffer of decoded strings (a string that contains escape sequences, such as `"\n"` or `"\u00e9"`, which had to be decoded once when the document was parsed).
|
|
|
|
## Exception safety
|
|
|
|
Strong guarantee: there are no changes to the view or the document it refers to.
|
|
|
|
## Exceptions
|
|
|
|
Throws [`type_error.302`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error302) if the value is not a string; example: `"type must be string, but is array"`.
|
|
|
|
This exception does not carry a [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) path: the view has no `BasicJsonType` value to point at, so the exception is created without one, even if `BasicJsonType` was built with `JSON_DIAGNOSTICS` enabled.
|
|
|
|
## Complexity
|
|
|
|
Constant.
|
|
|
|
## Notes
|
|
|
|
`basic_json_view` has no `BasicJsonType` value stored anywhere, so unlike `BasicJsonType`, it has no `get_ref()` to hand out a reference to a stored `string_t`. `get_string()` (equivalently, [`get<string_view_t>()`](https://json.nlohmann.me/api/basic_json_view/get/index.md)) is the zero-copy alternative: [`BasicJsonType::get_ref<const string_t&>()`](https://json.nlohmann.me/api/basic_json/get_ref/index.md) is its closest counterpart, except that it returns a view instead of a reference to a value that must already exist.
|
|
|
|
`get_string()` borrows the string: nothing is copied, whereas [`get<std::string>()`](https://json.nlohmann.me/api/basic_json_view/get/index.md) copies it. For a borrowed document, the returned [`string_view_t`](https://json.nlohmann.me/api/basic_json_view/#member-types) is valid as long as the caller's buffer; for an owned one, as long as the document.
|
|
|
|
The returned [`string_view_t`](https://json.nlohmann.me/api/basic_json_view/#member-types) is valid exactly as long as the view that produced it -- see the [validity rules](https://json.nlohmann.me/api/basic_json_view/index.md) of `basic_json_view` -- and, for a string with no escapes, for as long as the document's source text, which for a borrowed document must remain valid **and unmodified** for as long as the document exists, since floating-point values and unescaped strings are read from the source lazily.
|
|
|
|
## Examples
|
|
|
|
Example
|
|
|
|
The example below pulls one field out of a JSON text that stands in for a large API response, and shows that no `std::string` was allocated for it: the returned view still points inside the original buffer. A field that contains an escape sequence cannot point into the original text -- it was decoded once into the document's own buffer instead -- but still avoids a per-field allocation.
|
|
|
|
```
|
|
#include <iostream>
|
|
#include <nlohmann/json_view.hpp>
|
|
#include <string>
|
|
|
|
using json_document = nlohmann::json_document;
|
|
using json_view = nlohmann::json_view;
|
|
|
|
int main()
|
|
{
|
|
// a "large response" stand-in: only the "id" field is ever read out of it
|
|
const std::string text =
|
|
R"({"id": "8f14e45f-ceea-467e-bb92-963f5e3c7a08", "note": "created via API\n", "payload": "..."})";
|
|
const json_document doc = json_document::parse(text);
|
|
const json_view response = doc.root();
|
|
|
|
const json_view::string_view_t id = response["id"].get_string();
|
|
std::cout << id << '\n';
|
|
|
|
// no std::string was allocated for "id": its bytes still live inside
|
|
// the original buffer, so id's data lies inside [text.data(),
|
|
// text.data() + text.size())
|
|
const bool id_in_source = id.data() >= text.data() && id.data() + id.size() <= text.data() + text.size();
|
|
std::cout << std::boolalpha << id_in_source << '\n';
|
|
|
|
// "note" contains an escape sequence ('\n'), so it was decoded once
|
|
// into the document's own buffer -- get_string() still avoids a copy
|
|
// into a new std::string, but the bytes no longer live inside "text"
|
|
const json_view::string_view_t note = response["note"].get_string();
|
|
const bool note_in_source = note.data() >= text.data() && note.data() + note.size() <= text.data() + text.size();
|
|
std::cout << std::boolalpha << note_in_source << '\n';
|
|
}
|
|
```
|
|
|
|
Output:
|
|
|
|
```
|
|
8f14e45f-ceea-467e-bb92-963f5e3c7a08
|
|
true
|
|
false
|
|
```
|
|
|
|
## See also
|
|
|
|
- [get](https://json.nlohmann.me/api/basic_json_view/get/index.md) - convert the value to a given type (`get<string_view_t>()` is equivalent to this function)
|
|
- [number_token](https://json.nlohmann.me/api/basic_json_view/number_token/index.md) - a number's token text, without a copy
|
|
- [`BasicJsonType::get_ref`](https://json.nlohmann.me/api/basic_json/get_ref/index.md) - the closest counterpart of `basic_json`
|
|
|
|
## Version history
|
|
|
|
- Added in version 3.13.0 unreleased.
|