BigfootDev/flatbuffers
1
0
Fork 1
mirror of https://github.com/google/flatbuffers.git synced 2026-06-11 15:37:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fix 6348 (#6717)

Browse Source 
* Fixup CPP documentation's markdown errors

Note that I couldn't get the ~~~{.cpp} method to work,
so I switched to using ```cpp which did work.

* Fixup C++ docs, typo in repeated code example

Co-authored-by: Paul Harris <paulharris@computer.org>
This commit is contained in:
paulharris
2021-07-09 04:29:00 +08:00
committed by GitHub
parent 8ab35b2a5f
commit 8f8196e136
2 changed files with 52 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
docs/source/CppUsage.md
View File

@@ -56,7 +56,7 @@ For example, here is how you would read a FlatBuffer binary file in C++:
First, include the library and generated code. Then read the file into
a `char *` array, which you pass to `GetMonster()`.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
```cpp
#include "flatbuffers/flatbuffers.h"
#include "monster_test_generate.h"
#include <iostream> // C++ header file for printing
@@ -73,18 +73,18 @@ a `char *` array, which you pass to `GetMonster()`.
infile.close();
auto monster = GetMonster(data);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
```
`monster` is of type `Monster *`, and points to somewhere *inside* your
buffer (root object pointers are not the same as `buffer_pointer` !).
buffer (root object pointers are not the same as `buffer_pointer` \!).
If you look in your generated header, you'll see it has
convenient accessors for all fields, e.g. `hp()`, `mana()`, etc:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
std::cout << "hp : " << monster->hp() << std::endl; // `80`
std::cout << "mana : " << monster->mana() << std::endl; // default value of `150`
std::cout << "name : " << monster->name()->c_str() << std::endl; // "MyMonster"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
```cpp
std::cout << "hp : " << monster->hp() << std::endl; // '80'
std::cout << "mana : " << monster->mana() << std::endl; // default value of '150'
std::cout << "name : " << monster->name()->c_str() << std::endl; // "MyMonster"
```
*Note: That we never stored a `mana` value, so it will return the default.*
@@ -96,7 +96,7 @@ The following attributes are supported:
Specifically, `CreateXxxDirect` functions and `Pack` functions for object
based API (see below) will use `CreateSharedString` to create strings.
## Object based API. {#flatbuffers_cpp_object_based_api}
## Object based API {#flatbuffers_cpp_object_based_api}
FlatBuffers is all about memory efficiency, which is why its base API is written
around using as little as possible of it. This does make the API clumsier
@@ -109,7 +109,7 @@ construction, access and mutation.
To use:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
```cpp
// Autogenerated class from table Monster.
MonsterT monsterobj;
@@ -123,7 +123,7 @@ To use:
// Serialize into new flatbuffer.
FlatBufferBuilder fbb;
fbb.Finish(Monster::Pack(fbb, &monsterobj));
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
```
The following attributes are specific to the object-based API code generation:
@@ -144,19 +144,19 @@ The following attributes are specific to the object-based API code generation:
This can be used to provide allocation from a pool for example, for faster
unpacking when using the object-based API.
Minimal Example:
Minimal Example:
schema:
schema:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
```cpp
table mytable(native_custom_alloc:"custom_allocator") {
...
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
```
with custom_allocator defined before `flatbuffers.h` is included, as:
with `custom_allocator` defined before `flatbuffers.h` is included, as:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
```cpp
template <typename T> struct custom_allocator : public std::allocator<T> {
typedef T *pointer;
@@ -175,34 +175,35 @@ The following attributes are specific to the object-based API code generation:
}
custom_allocator() throw() {}
template <class U>
custom_allocator(const custom_allocator<U>&) throw() {}
};
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
```
- `native_type("type")` (on a struct): In some cases, a more optimal C++ data
type exists for a given struct. For example, the following schema:
type exists for a given struct. For example, the following schema:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
```cpp
struct Vec2 {
x: float;
y: float;
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
```
generates the following Object-Based API class:
generates the following Object-Based API class:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
```cpp
struct Vec2T : flatbuffers::NativeTable {
float x;
float y;
};
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
```
However, it can be useful to instead use a user-defined C++ type since it
can provide more functionality, eg.
However, it can be useful to instead use a user-defined C++ type since it
can provide more functionality, eg.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
```cpp
struct vector2 {
float x = 0, y = 0;
vector2 operator+(vector2 rhs) const { ... }
@@ -210,22 +211,22 @@ The following attributes are specific to the object-based API code generation:
float length() const { ... }
// etc.
};
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
```
The `native_type` attribute will replace the usage of the generated class
with the given type. So, continuing with the example, the generated
code would use `vector2` in place of `Vec2T` for all generated code of
the Object-Based API.
The `native_type` attribute will replace the usage of the generated class
with the given type. So, continuing with the example, the generated
code would use `vector2` in place of `Vec2T` for all generated code of
the Object-Based API.
However, because the `native_type` is unknown to flatbuffers, the user must
provide the following functions to aide in the serialization process:
However, because the `native_type` is unknown to flatbuffers, the user must
provide the following functions to aide in the serialization process:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
```cpp
namespace flatbuffers {
Vec2 Pack(const vector2& obj);
vector2 UnPack(const Vec2& obj);
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
```
- `native_type_pack_name("name")` (on a struct when `native_type` is
specified, too): when you want to use the same `native_type` multiple times
@@ -235,12 +236,12 @@ The following attributes are specific to the object-based API code generation:
specify `native_type_pack_name("Vec2")` in the above example you now need to
implement these serialization functions instead:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
```cpp
namespace flatbuffers {
Vec2 PackVec2(const vector2& obj);
vector2 UnPackVec2(const Vec2& obj);
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
```
Finally, the following top-level attributes:
@@ -253,7 +254,7 @@ Finally, the following top-level attributes:
- `force_align`: this attribute may not be respected in the object API,
depending on the aligned of the allocator used with `new`.
# External references.
# External references
An additional feature of the object API is the ability to allow you to load
multiple independent FlatBuffers, and have them refer to eachothers objects
@@ -272,7 +273,7 @@ same string (or hash).
When you call `UnPack` (or `Create`), you'll need a function that maps from
hash to the object (see `resolver_function_t` for details).
# Using different pointer types.
# Using different pointer types
By default the object tree is built out of `std::unique_ptr`, but you can
influence this either globally (using the `--cpp-ptr-type` argument to
@@ -283,13 +284,13 @@ 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.
# 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(), T::length() and T::empty() 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
@@ -298,7 +299,7 @@ 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).
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.
@@ -309,7 +310,7 @@ read and write data even if you don't know the exact format of a buffer, and
even allows you to change sizes of strings and vectors in-place.
The way this works is very elegant; there is actually a FlatBuffer schema that
describes schemas (!) which you can find in `reflection/reflection.fbs`.
describes schemas (\!) which you can find in `reflection/reflection.fbs`.
The compiler, `flatc`, can write out any schemas it has just parsed as a binary
FlatBuffer, corresponding to this meta-schema.
@@ -418,9 +419,9 @@ is accessed, all reads will end up inside the buffer.
Each root type will have a verification function generated for it,
e.g. for `Monster`, you can call:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
```cpp
bool ok = VerifyMonsterBuffer(Verifier(buf, len));
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
```
if `ok` is true, the buffer is safe to read.
@@ -486,15 +487,15 @@ Load text (either a schema or json) into an in-memory buffer (there is a
convenient `LoadFile()` utility function in `flatbuffers/util.h` if you
wish). Construct a parser:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
```cpp
flatbuffers::Parser parser;
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
```
Now you can parse any number of text files in sequence:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
```cpp
parser.Parse(text_file.c_str());
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
```
This works similarly to how the command-line compiler works: a sequence
of files parsed by the same `Parser` object allow later files to

2
docs/source/Tutorial.md
View File

@@ -1820,7 +1820,7 @@ Here is a repetition of these lines, to help highlight them more clearly:
<div class="language-cpp">
~~~{.cpp}
monster_builder.add_equipped_type(Equipment_Weapon); // Union type
monster_builder.add_equipped(axe); // Union data
monster_builder.add_equipped(axe.Union()); // Union data
~~~
</div>
<div class="language-java">