More native code gen functionality.

Allow tables to be mapped to native types directly.  For example, a table
representing a vector3 (eg. table Vec3 { x:float; y:float; z:float; }) can
be mapped to a "mathfu::vec3" native type in NativeTables.  This requires
users to provide Pack and UnPack functions that convert between the
Table and native types.  This is done by adding the "native_type" attribute
to the table definition.

To support user-defined flatbuffers::Pack and flatbuffers::UnPack functions,
support a "native_include" markup that will generate a corresponding

Also add an UnPackTo function which allows users to pass in a pointer to
a NativeTable object into which to UnPack the Table.  The existing UnPack
function is now simply:

  NativeTable* UnPack() {
    NativeTable* obj = new NativeTable();
    Table::UnPackTo(obj);
    return obj;
  }

Finally, allow native types to be given a default value as well which are
set in the NativeTable constructor.  This is done by providing a
"native_default" attribute to the member of a table.

Change-Id: Ic45cb48b0e6d7cfa5734b24819e54aa96d847cfd

docs/source/CppUsage.md

@@ -85,7 +85,7 @@ convenient accessors for all fields, e.g. `hp()`, `mana()`, etc:
 
 *Note: That we never stored a `mana` value, so it will return the default.*
 
-## 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
@@ -99,13 +99,79 @@ construction, access and mutation.
 To use:
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
-    auto monsterobj = UnpackMonster(buffer);
+    // Autogenerated class from table Monster.
+    MonsterT monsterobj;
+
+    // Deserialize from buffer into object.
+    UnPackTo(&monsterobj, flatbuffer);
+
+    // Update object directly like a C++ class instance.
     cout << monsterobj->name;  // This is now a std::string!
     monsterobj->name = "Bob";  // Change the name.
+
+    // Serialize into new flatbuffer.
     FlatBufferBuilder fbb;
-    CreateMonster(fbb, monsterobj.get());     // Serialize into new buffer.
+    Pack(fbb, &monsterobj);
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+The following attributes are specific to the object-based API code generation:
+
+-   `native_inline` (on a field): Because FlatBuffer tables and structs are
+    optionally present in a given buffer, they are best represented as pointers
+    (specifically std::unique_ptrs) in the native class since they can be null.
+    This attribute changes the member declaration to use the type directly
+    rather than wrapped in a unique_ptr.
+
+-   `native_default`: "value" (on a field): For members that are declared
+    "native_inline", the value specified with this attribute will be included
+    verbatim in the class constructor initializer list for this member.
+
+-   `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:
+
+      struct Vec2 {
+        x: float;
+        y: float;
+      }
+
+    generates the following Object-Based API class:
+
+      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.
+
+      struct vector2 {
+        float x = 0, y = 0;
+        vector2 operator+(vector2 rhs) const { ... }
+        vector2 operator-(vector2 rhs) const { ... }
+        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.
+
+    However, becuase the native_type is unknown to flatbuffers, the user must
+    provide the following functions to aide in the serialization process:
+
+      namespace flatbuffers {
+        FlatbufferStruct Pack(const native_type& obj);
+        native_type UnPack(const FlatbufferStruct& obj);
+      }
+
+Finally, the following top-level attribute
+
+-   native_include: "path" (at file level): Because the `native_type` attribute
+    can be used to introduce types that are unknown to flatbuffers, it may be
+    necessary to include "external" header files in the generated code.  This
+    attribute can be used to directly add an #include directive to the top of
+    the generated code that includes the specified path directly.
+
 # External references.
 
 An additional feature of the object API is the ability to allow you to load

docs/source/Schemas.md

@@ -309,6 +309,10 @@ Current understood attributes:
     to be stored in any particular order, they are often optimized for
     space by sorting them to size. This attribute stops that from happening.
     There should generally not be any reason to use this flag.
+-   'native_*'.  Several attributes have been added to support the [C++ object
+    Based API](@ref flatbuffers_cpp_object_based_api).  All such attributes
+    are prefixed with the term "native_".
+
 
 ## JSON Parsing