[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

docs/source/Compiler.md

@@ -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.
 

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)
 

include/flatbuffers/idl.h

@@ -410,6 +410,7 @@ struct IDLOptions {
   bool gen_compare;
   std::string cpp_object_api_pointer_type;
   std::string cpp_object_api_string_type;
+  bool cpp_object_api_string_flexible_constructor;
   bool gen_nullable;
   bool gen_generated;
   std::string object_prefix;
@@ -486,6 +487,7 @@ struct IDLOptions {
         generate_object_based_api(false),
         gen_compare(false),
         cpp_object_api_pointer_type("std::unique_ptr"),
+        cpp_object_api_string_flexible_constructor(false),
         gen_nullable(false),
         gen_generated(false),
         object_suffix("T"),
@@ -627,6 +629,7 @@ class Parser : public ParserState {
     known_attributes_["cpp_ptr_type"] = true;
     known_attributes_["cpp_ptr_type_get"] = true;
     known_attributes_["cpp_str_type"] = true;
+    known_attributes_["cpp_str_flex_ctor"] = true;
     known_attributes_["native_inline"] = true;
     known_attributes_["native_custom_alloc"] = true;
     known_attributes_["native_type"] = true;

src/flatc.cpp

@@ -107,7 +107,11 @@ std::string FlatCompiler::GetUsageString(const char *program_name) const {
     "                     file.\n"
     "  --cpp-ptr-type T   Set object API pointer type (default std::unique_ptr).\n"
     "  --cpp-str-type T   Set object API string type (default std::string).\n"
-    "                     T::c_str() and T::length() must be supported.\n"
+    "                     T::c_str(), T::length() and T::empty() must be supported.\n"
+    "                     The custom type also needs to be constructible from std::string\n"
+    "                     (see the --cpp-str-flex-ctor option to change this behavior).\n"
+    "  --cpp-str-flex-ctor Don't construct custom string types by passing std::string\n"
+    "                     from Flatbuffers, but (char* + length).\n"
     "  --object-prefix    Customise class prefix for C++ object-based API.\n"
     "  --object-suffix    Customise class suffix for C++ object-based API.\n"
     "                     Default value is \"T\".\n"
@@ -247,6 +251,8 @@ int FlatCompiler::Compile(int argc, const char **argv) {
       } else if (arg == "--cpp-str-type") {
         if (++argi >= argc) Error("missing type following" + arg, true);
         opts.cpp_object_api_string_type = argv[argi];
+      } else if (arg == "--cpp-str-flex-ctor") {
+        opts.cpp_object_api_string_flexible_constructor = true;
       } else if (arg == "--gen-nullable") {
         opts.gen_nullable = true;
       } else if (arg == "--gen-generated") {