diff options
author | Wouter van Oortmerssen <aardappel@gmail.com> | 2019-03-11 09:42:02 -0700 |
---|---|---|
committer | Wouter van Oortmerssen <aardappel@gmail.com> | 2019-03-11 09:42:02 -0700 |
commit | eb2a81f73db9893fbe2eec53662fa7f9358e54a8 (patch) | |
tree | 66e49ab15bdf5e1c7502bab16f31c57c391a32b7 /docs/source | |
parent | 3968d0056865cb08c62b367470d18d633908565e (diff) | |
download | flatbuffers-eb2a81f73db9893fbe2eec53662fa7f9358e54a8.tar.gz |
[C++] Object API: document custom string type requirements,
implement better custom string type constructor alternative
for Unpack() and fix bug with vector of custom string types
in Pack().
Squashed commit of the following:
commit e9519c647ef949b22756ed660839dd3af854881c
Author: Luca Longinotti <luca.longinotti@inivation.com>
Date: Tue Mar 5 18:24:49 2019 +0100
tests: regenerate code, reverts change to CreateVectorOfStrings().
commit 117e3b0679209f2aa55cbee18c4036e7da4bd4b3
Author: Luca Longinotti <luca.longinotti@inivation.com>
Date: Tue Mar 5 18:15:05 2019 +0100
idl_gen_cpp.cpp: move clang-format on/off outside of declaration, so they are kept properly aligned automatically.
commit 4791923806965637d5b13f7003329bfbb2fdf18b
Author: Luca Longinotti <luca.longinotti@inivation.com>
Date: Tue Mar 5 18:11:40 2019 +0100
idl_gen_cpp.cpp: full clang-format run with provided Google format file, enforce 80 lines width.
commit 2f0402f9ff43b1af0a29806932e08e6d64373345
Author: Luca Longinotti <luca.longinotti@inivation.com>
Date: Tue Mar 5 18:09:32 2019 +0100
CppUsage: address requested changes.
idl_gen_cpp.cpp: fix formatting, keep CreateVectorOfStrings for normal string cases.
commit 371d4e0b7972a59e5cff418c44e4043c016ce56a
Author: Luca Longinotti <luca.longinotti@inivation.com>
Date: Fri Mar 1 16:35:29 2019 +0100
Fix compile error with a vector of non-std::strings. CreateVectorOfStrings() expects a vector of std::string types, but that's not always the case.
commit 92b90d7f0fbcfc837a94aa06bedccec0f7b4bb62
Author: Luca Longinotti <luca.longinotti@inivation.com>
Date: Fri Mar 1 16:15:36 2019 +0100
Document requirement for custom string types to implement empty() and be constructible from std::string.
Add new option --cpp-str-flex-ctor to construct custom string types not via std::string, but (char * + length).
commit 28cb2e92d5b7684b5df5184da3a3fad2d0cda733
Author: Luca Longinotti <luca.longinotti@inivation.com>
Date: Fri Mar 1 14:31:17 2019 +0100
idl_gen_cpp.cpp: clang-format run, to better separate changes in content from formatting.
Change-Id: I4887ba2f2c632b9e7a8c938659b088cd95690870
Diffstat (limited to 'docs/source')
-rw-r--r-- | docs/source/Compiler.md | 12 | ||||
-rw-r--r-- | docs/source/CppUsage.md | 14 |
2 files changed, 21 insertions, 5 deletions
diff --git a/docs/source/Compiler.md b/docs/source/Compiler.md index d7b44c87..90f8d8b4 100644 --- a/docs/source/Compiler.md +++ b/docs/source/Compiler.md @@ -75,7 +75,7 @@ Additional options: - `--allow-non-utf8` : Pass non-UTF-8 input through parser and emit nonstandard \x escapes in JSON. (Default is to raise parse error on non-UTF-8 input.) -- `--natural-utf8` : Output strings with UTF-8 as human-readable strings. +- `--natural-utf8` : Output strings with UTF-8 as human-readable strings. By default, UTF-8 characters are printed as \uXXXX escapes." - `--defaults-json` : Output fields whose value is equal to the default value @@ -120,7 +120,13 @@ Additional options: - `--cpp-ptr-type T` : Set object API pointer type (default std::unique_ptr) - `--cpp-str-type T` : Set object API string type (default std::string) -- T::c_str() and T::length() must be supported. + T::c_str(), T::length() and T::empty() must be supported. + The custom type also needs to be constructible from std::string (see the + --cpp-str-flex-ctor option to change this behavior). + +- `--cpp-str-flex-ctor` : Don't construct custom string types by passing + std::string from Flatbuffers, but (char* + length). This allows efficient + construction of custom string types, including zero-copy construction. - `--object-prefix` : Customise class prefix for C++ object-based API. @@ -168,7 +174,7 @@ Additional options: an evolution of. Gives errors if not. Useful to check if schema modifications don't break schema evolution rules. -- `--conform-includes PATH` : Include path for the schema given with +- `--conform-includes PATH` : Include path for the schema given with `--conform PATH`. - `--include-prefix PATH` : Prefix this path to any generated include diff --git a/docs/source/CppUsage.md b/docs/source/CppUsage.md index 2808c49c..6cf36d1f 100644 --- a/docs/source/CppUsage.md +++ b/docs/source/CppUsage.md @@ -255,14 +255,24 @@ you, so you'll have to manage their lifecycles manually. To reference the pointer type specified by the `--cpp-ptr-type` argument to `flatc` from a flatbuffer field set the `cpp_ptr_type` attribute to `default_ptr_type`. - # Using different string type. By default the object tree is built out of `std::string`, but you can influence this either globally (using the `--cpp-str-type` argument to `flatc`) or per field using the `cpp_str_type` attribute. -The type must support T::c_str() and T::length() as member functions. +The type must support T::c_str(), T::length() and T::empty() as member functions. + +Further, the type must be constructible from std::string, as by default a +std::string instance is constructed and then used to initialize the custom +string type. This behavior impedes efficient and zero-copy construction of +custom string types; the `--cpp-str-flex-ctor` argument to `flatc` or the +per field attribute `cpp_str_flex_ctor` can be used to change this behavior, +so that the custom string type is constructed by passing the pointer and +length of the FlatBuffers String. The custom string class will require a +constructor in the following format: custom_str_class(const char *, size_t). +Please note that the character array is not guaranteed to be NULL terminated, +you should always use the provided size to determine end of string. ## Reflection (& Resizing) |