From e7db7a605275c5f4f138bab7807ac3ef688f58bd Mon Sep 17 00:00:00 2001 From: Protocol Buffer Team Date: Tue, 18 Jun 2024 20:23:50 +0000 Subject: [PATCH] This change includes the following: MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Restructures the landing page (_index.md) to simplify the layout and bring the table of contents to the left side * Removes the `optional` keyword from examples in the editions/features.md topic * In /editions/overview.md: * Clarifies that 2023 is the latest released edition * Adds missing `package` syntax from proto examples * Adds a reserved keyword to the proto examples to show the syntax difference between proto2/proto3 and editions * Corrects syntax for enums in proto examples * Corrects the example from the `list_people` command’s unit tests in getting-started/gotutorial.md * Replaces an outdated link to OKRs with a link to codelabs in /overview.md * Adds information about `ruby_package` to /programming-guides/dos-donts.md * Corrects misspellings in several topics * Reorganizes the content in the presence table in /programming-guides/field_presence.md * Corrects instances of `[[]` that should have been `[` throughout C++ API documentation * Minor text changes in /cpp/arenas.md * Removes some outdated references to `has_foo()` being proto2-only in /cpp/cpp-generated.md * Adds information about `ruby_package` to /reference/ruby/ruby-generated.md * Removes reference to cross-domain mixing of protobuf gencode and runtime from the external docs, since it applies only internally PiperOrigin-RevId: 644492325 Change-Id: I651afbc2d6049818a1b579b4d0e779779cb06c57 --- content/_index.md | 64 +++++------------ content/editions/features.md | 6 +- content/editions/overview.md | 38 +++++++--- content/getting-started/gotutorial.md | 2 +- content/overview.md | 1 + content/programming-guides/dos-donts.md | 3 + content/programming-guides/enum.md | 2 +- content/programming-guides/field_presence.md | 6 +- content/programming-guides/proto2.md | 4 +- content/programming-guides/proto3.md | 4 +- .../cpp/api-docs/google.protobuf.arena.md | 2 +- ...rotobuf.compiler.command_line_interface.md | 4 +- .../google.protobuf.compiler.plugin.md | 2 +- .../api-docs/google.protobuf.descriptor.pb.md | 72 +++++++++---------- .../google.protobuf.descriptor_database.md | 2 +- .../google.protobuf.io.coded_stream.md | 12 ++-- .../google.protobuf.io.zero_copy_stream.md | 2 +- .../cpp/api-docs/google.protobuf.map.md | 2 +- .../google.protobuf.repeated_field.md | 16 ++--- .../api-docs/google.protobuf.text_format.md | 4 +- .../google.protobuf.unknown_field_set.md | 6 +- ...oogle.protobuf.util.message_differencer.md | 12 ++-- content/reference/cpp/arenas.md | 5 +- content/reference/cpp/cpp-generated.md | 24 +++---- .../class/google/protobuf/byte-string.html | 4 +- .../protobuf/well-known-types/mixin.html | 2 +- content/reference/dart/dart-generated.md | 2 +- content/reference/protobuf/google.protobuf.md | 2 +- content/reference/ruby/ruby-generated.md | 9 +++ .../cross-version-runtime-guarantee.md | 5 -- 30 files changed, 153 insertions(+), 166 deletions(-) diff --git a/content/_index.md b/content/_index.md index 27fffa6e..221aa4cf 100644 --- a/content/_index.md +++ b/content/_index.md @@ -7,20 +7,21 @@ type = "docs" no_list = "true" +++ - +## What Are Protocol Buffers? - +Protocol buffers are Google's language-neutral, platform-neutral, extensible +mechanism for serializing structured data – think XML, but smaller, faster, and +simpler. You define how you want your data to be structured once, then you can +use special generated source code to easily write and read your structured data +to and from a variety of data streams and using a variety of languages. + +## Pick Your Favorite Language + +Protocol buffers support generated code in C++, C#, Dart, Go, Java, +Kotlin, +Objective-C, Python, and Ruby. With proto3, you can also work with PHP. -
-
+## Example Implementation ```proto message Person { @@ -30,9 +31,7 @@ message Person { } ``` -

A proto definition. -

-
+**Figure 1.** A proto definition. ```java // Java code @@ -43,12 +42,9 @@ Person john = Person.newBuilder() .build(); output = new FileOutputStream(args[0]); john.writeTo(output); - ``` -

Using a generated class to persist data.

-
-
+**Figure 2.** Using a generated class to persist data. ```cpp // C++ code @@ -59,34 +55,9 @@ john.ParseFromIstream(&input); id = john.id(); name = john.name(); email = john.email(); - ``` -

Using a generated class to parse persisted data.

-
-
-
-
- -## What Are Protocol Buffers? - -Protocol buffers are Google's language-neutral, platform-neutral, extensible -mechanism for serializing structured data – think XML, but smaller, faster, and -simpler. You define how you want your data to be structured once, then you can -use special generated source code to easily write and read your structured data -to and from a variety of data streams and using a variety of languages. - -
-
- -## Pick Your Favorite Language - -Protocol buffers support generated code in C++, C#, Dart, Go, Java, -Kotlin, -Objective-C, Python, and Ruby. With proto3, you can also work with PHP. - -
-
+**Figure 3.** Using a generated class to parse persisted data. ## How Do I Start? @@ -106,6 +77,3 @@ Objective-C, Python, and Ruby. With proto3, you can also work with PHP. chosen language. - -
-
diff --git a/content/editions/features.md b/content/editions/features.md index 5a82b111..424da25c 100644 --- a/content/editions/features.md +++ b/content/editions/features.md @@ -285,7 +285,7 @@ edition = "2023"; message Foo { message Bar { - optional int32 x = 1; + int32 x = 1; repeated int32 y = 2; } Bar bar = 1 [features.message_encoding = DELIMITED]; @@ -509,8 +509,8 @@ edition = "2023"; import "google/protobuf/cpp_features.proto"; message Foo { - optional string bar = 6; - optional string baz = 7 [features.(pb.cpp).string_type = CORD]; + string bar = 6; + string baz = 7 [features.(pb.cpp).string_type = CORD]; } ``` diff --git a/content/editions/overview.md b/content/editions/overview.md index 07ceb870..382b6d33 100644 --- a/content/editions/overview.md +++ b/content/editions/overview.md @@ -9,7 +9,7 @@ type = "docs" Protobuf Editions replace the proto2 and proto3 designations that we have used for Protocol Buffers. Instead of adding `syntax = "proto2"` or `syntax = "proto3"` at the top of proto definition files, you use an edition number, such -as `edition = "2024"`, to specify the default behaviors your file will have. +as `edition = "2023"`, to specify the default behaviors your file will have. Editions enable the language to evolve incrementally over time. Instead of the hardcoded behaviors that older versions have had, editions @@ -22,6 +22,8 @@ the default behavior for the edition you've selected. You can also override your overrides. The [section later in this topic on lexical scoping](#scoping) goes into more detail on that. +*The latest released edition is 2023.* + ## Lifecycle of a Feature {#lifecycles} Editions provide the fundamental increments for the lifecycle of a feature. @@ -93,6 +95,8 @@ Prototiller tool to change the definition files to use Protobuf Editions syntax. // proto2 file syntax = "proto2"; +package com.example; + message Player { // in proto2, optional fields have explicit presence optional string name = 1; @@ -110,6 +114,8 @@ message Player { // in proto2 enums are closed optional Handed handed = 4; + + reserved "gender"; } ``` @@ -119,6 +125,8 @@ message Player { // Edition version of proto2 file edition = "2023"; +package com.example; + message Player { // fields have explicit presence, so no explicit setting needed string name = 1; @@ -137,6 +145,8 @@ message Player { } Handed handed = 4; + + reserved gender; } ``` @@ -155,6 +165,8 @@ Prototiller tool to change the definition files to use Protobuf Editions syntax. // proto3 file syntax = "proto3"; +package com.example; + message Player { // in proto3, optional fields have explicit presence optional string name = 1; @@ -172,6 +184,8 @@ message Player { // in proto3 enums are open optional Handed handed = 4; + + reserved "gender"; } ``` @@ -181,6 +195,8 @@ message Player { // Editions version of proto3 file edition = "2023"; +package com.example; + message Player { // fields have explicit presence, so no explicit setting needed string name = 1; @@ -197,6 +213,8 @@ message Player { } Handed handed = 4; + + reserved gender; } ``` @@ -229,16 +247,16 @@ message Person { int32 id = 2 [features.presence = IMPLICIT]; enum Pay_Type { - PAY_TYPE_UNSPECIFIED = 1, - PAY_TYPE_SALARY = 2, - PAY_TYPE_HOURLY = 3 + PAY_TYPE_UNSPECIFIED = 1; + PAY_TYPE_SALARY = 2; + PAY_TYPE_HOURLY = 3; } enum Employment { option features.enum_type = OPEN; - EMPLOYMENT_UNSPECIFIED = 0, - EMPLOYMENT_FULLTIME = 1, - EMPLOYMENT_PARTTIME = 2, + EMPLOYMENT_UNSPECIFIED = 0; + EMPLOYMENT_FULLTIME = 1; + EMPLOYMENT_PARTTIME = 2; } Employment employment = 4; } @@ -270,9 +288,9 @@ definition files, and vice versa: syntax = "proto2"; enum Employment { - EMPLOYMENT_UNSPECIFIED = 0, - EMPLOYMENT_FULLTIME = 1, - EMPLOYMENT_PARTTIME = 2, + EMPLOYMENT_UNSPECIFIED = 0; + EMPLOYMENT_FULLTIME = 1; + EMPLOYMENT_PARTTIME = 2; } ``` diff --git a/content/getting-started/gotutorial.md b/content/getting-started/gotutorial.md index b9837230..f295167d 100644 --- a/content/getting-started/gotutorial.md +++ b/content/getting-started/gotutorial.md @@ -232,7 +232,7 @@ p := pb.Person{ Name: "John Doe", Email: "jdoe@example.com", Phones: []*pb.Person_PhoneNumber{ - {Number: "555-4321", Type: pb.Person_PHONE_TYPE_HOME}, + {Number: "555-4321", Type: pb.PhoneType_PHONE_TYPE_HOME}, }, } ``` diff --git a/content/overview.md b/content/overview.md index b90f2b7f..c4565c53 100644 --- a/content/overview.md +++ b/content/overview.md @@ -305,3 +305,4 @@ protobuf developers and users, ## Additional Resources {#additional-resources} * [Protocol Buffers GitHub](https://github.com/protocolbuffers/protobuf/) +* [Codelabs](/getting-started/codelabs) diff --git a/content/programming-guides/dos-donts.md b/content/programming-guides/dos-donts.md index c7895528..65d3abd4 100644 --- a/content/programming-guides/dos-donts.md +++ b/content/programming-guides/dos-donts.md @@ -196,6 +196,9 @@ For example: https://google.github.io/styleguide/cppguide.html#Namespace_Names. If these style guides conflict, use `java_package` for Java. +* `ruby_package` should be in the form `Foo::Bar::Baz` rather than + `Foo.Bar.Baz`. + ## **Don't** use Text Format Messages for Interchange {#text-format-interchange} diff --git a/content/programming-guides/enum.md b/content/programming-guides/enum.md index 9186950b..8f0fae3d 100644 --- a/content/programming-guides/enum.md +++ b/content/programming-guides/enum.md @@ -49,7 +49,7 @@ question: ## Implications of *Closed* Enums -The behavior of *closed* enums has unexpected consquences when parsing a +The behavior of *closed* enums has unexpected consequences when parsing a repeated field. When a `repeated Enum` field is parsed all unknown values will be placed in the [unknown field](/programming-guides/proto3/#unknowns) diff --git a/content/programming-guides/field_presence.md b/content/programming-guides/field_presence.md index c63271d5..215a2c84 100644 --- a/content/programming-guides/field_presence.md +++ b/content/programming-guides/field_presence.md @@ -157,13 +157,13 @@ for generated APIs and using dynamic reflection): Field type | `optional` | Explicit Presence -------------------------------------------- | ---------- | ----------------- Singular numeric (integer or floating point) | No | -Singular enum | No | -Singular string or bytes | No | Singular numeric (integer or floating point) | Yes | ✔️ +Singular enum | No | Singular enum | Yes | ✔️ +Singular string or bytes | No | Singular string or bytes | Yes | ✔️ -Singular message | Yes | ✔️ Singular message | No | ✔️ +Singular message | Yes | ✔️ Repeated | N/A | Oneofs | N/A | ✔️ Maps | N/A | diff --git a/content/programming-guides/proto2.md b/content/programming-guides/proto2.md index 3d588c84..2eeb7856 100644 --- a/content/programming-guides/proto2.md +++ b/content/programming-guides/proto2.md @@ -1939,8 +1939,8 @@ Here are a few of the most commonly used options: message types. This code is highly optimized. * `CODE_SIZE`: The protocol buffer compiler will generate minimal classes and will rely on shared, reflection-based code to implement - serialialization, parsing, and various other operations. The generated - code will thus be much smaller than with `SPEED`, but operations will be + serialization, parsing, and various other operations. The generated code + will thus be much smaller than with `SPEED`, but operations will be slower. Classes will still implement exactly the same public API as they do in `SPEED` mode. This mode is most useful in apps that contain a very large number of `.proto` files and do not need all of them to be diff --git a/content/programming-guides/proto3.md b/content/programming-guides/proto3.md index 4002f77f..7f4227e3 100644 --- a/content/programming-guides/proto3.md +++ b/content/programming-guides/proto3.md @@ -1487,8 +1487,8 @@ Here are a few of the most commonly used options: message types. This code is highly optimized. * `CODE_SIZE`: The protocol buffer compiler will generate minimal classes and will rely on shared, reflection-based code to implement - serialialization, parsing, and various other operations. The generated - code will thus be much smaller than with `SPEED`, but operations will be + serialization, parsing, and various other operations. The generated code + will thus be much smaller than with `SPEED`, but operations will be slower. Classes will still implement exactly the same public API as they do in `SPEED` mode. This mode is most useful in apps that contain a very large number of `.proto` files and do not need all of them to be diff --git a/content/reference/cpp/api-docs/google.protobuf.arena.md b/content/reference/cpp/api-docs/google.protobuf.arena.md index aca36a00..de299288 100644 --- a/content/reference/cpp/api-docs/google.protobuf.arena.md +++ b/content/reference/cpp/api-docs/google.protobuf.arena.md @@ -49,7 +49,7 @@ type = "docs"

This function also accepts any type T that satisfies the arena message allocation protocol, documented above.

template static PROTOBUF_NDEBUG_INLINE T *
    Arena::Create(
        Arena * arena,
        Args &&... args)

API to create any objects on the arena.

Note that only the object will be created on the arena; the underlying ptrs (in case of a proto2 message) will be still heap allocated. Proto messages should usually be allocated with CreateMessage<T>() instead.

Note that even if T satisfies the arena message construction protocol (InternalArenaConstructable_ trait and optional DestructorSkippable_ trait), as described above, this function does not follow the protocol; instead, it treats T as a black-box type, just as if it did not have these traits. Specifically, T's constructor arguments will always be only those passed to Create<T>() – no additional arena pointer is implicitly added. Furthermore, the destructor will always be called at arena destruction time (unless the destructor is trivial). Hence, from T's point of view, it is as if the object were allocated on the heap (except that the underlying memory is obtained from the arena).

-

template static PROTOBUF_NDEBUG_INLINE T *
    Arena::CreateArray(
        Arena * arena,
        size_t num_elements)

Create an array of object type T on the arena without invoking the constructor of T.

If arena is null, then the return value should be freed with delete[[]] x; (or ::operator delete[[]](x);). To ensure safe uses, this function checks at compile time (when compiled as C++11) that T is trivially default-constructible and trivially destructible.

+

template static PROTOBUF_NDEBUG_INLINE T *
    Arena::CreateArray(
        Arena * arena,
        size_t num_elements)

Create an array of object type T on the arena without invoking the constructor of T.

If arena is null, then the return value should be freed with delete[] x; (or ::operator delete[](x);). To ensure safe uses, this function checks at compile time (when compiled as C++11) that T is trivially default-constructible and trivially destructible.

template static Arena * Arena::GetArena(
        const T * value)

Retrieves the arena associated with |value| if |value| is an arena-capable message, or NULL otherwise.

If possible, the call resolves at compile time. Note that we can often devirtualize calls to value->GetArena() so usually calling this method is unnecessary.

template class Arena::InternalHelper

#include <google/protobuf/arena.h>
namespace google::protobuf

template <typename >

Members

static Arena *
GetOwningArena(const T * p)
Provides access to protected GetOwningArena to generated messages.
static Arena *
GetArenaForAllocation(const T * p)
Provides access to protected GetArenaForAllocation to generated messages.

template struct Arena::is_arena_constructable

#include <google/protobuf/arena.h>
namespace google::protobuf

template <typename >

Helper typetraits that indicates support for arenas in a type T at compile time.

This is public only to allow construction of higher-level templated utilities.

is_arena_constructable<T>::value is true if the message type T has arena support enabled, and false otherwise.

diff --git a/content/reference/cpp/api-docs/google.protobuf.compiler.command_line_interface.md b/content/reference/cpp/api-docs/google.protobuf.compiler.command_line_interface.md index 6a42997d..0dbfe78e 100644 --- a/content/reference/cpp/api-docs/google.protobuf.compiler.command_line_interface.md +++ b/content/reference/cpp/api-docs/google.protobuf.compiler.command_line_interface.md @@ -8,7 +8,7 @@ type = "docs"

#include <google/protobuf/compiler/command_line_interface.h>
namespace google::protobuf::compiler

Implements the Protocol Compiler front-end such that it may be reused by custom compilers written to support other languages.

Classes in this file

This class implements the command-line interface to the protocol compiler.

class CommandLineInterface

#include <google/protobuf/compiler/command_line_interface.h>
namespace google::protobuf::compiler

This class implements the command-line interface to the protocol compiler.

It is designed to make it very easy to create a custom protocol compiler supporting the languages of your choice. For example, if you wanted to create a custom protocol compiler binary which includes both the regular C++ support plus support for your own custom output "Foo", you would write a class "FooGenerator" which implements the CodeGenerator interface, then write a main() procedure like this:

-
int main(int argc, char* argv[[]]) {
+
int main(int argc, char* argv[]) {
   google::protobuf::compiler::CommandLineInterface cli;
 
   // Support generation of C++ source and headers.
@@ -54,7 +54,7 @@ type = "docs"
  
void CommandLineInterface::AllowPlugins(
        const std::string & exe_name_prefix)
Enables "plugins". 
In this mode, if a command-line flag ends with "_out" but does not match any registered generator, the compiler will attempt to find a "plugin" to implement the generator. Plugins are just executables. They should live somewhere in the PATH.

 
The compiler determines the executable name to search for by concatenating exe_name_prefix with the unrecognized flag name, removing "_out". So, for example, if exe_name_prefix is "protoc-" and you pass the flag –foo_out, the compiler will try to run the program "protoc-gen-foo".

 
The plugin program should implement the following usage: 

-
plugin [[]--out=OUTDIR] [[]--parameter=PARAMETER] PROTO_FILES < DESCRIPTORS

+
plugin [--out=OUTDIR] [--parameter=PARAMETER] PROTO_FILES < DESCRIPTORS

 
–out indicates the output directory (as passed to the –foo_out parameter); if omitted, the current directory should be used. –parameter gives the generator parameter, if any was provided (see below). The PROTO_FILES list the .proto files which were given on the compiler command-line; these are the files for which the plugin is expected to generate output code. Finally, DESCRIPTORS is an encoded FileDescriptorSet (as defined in descriptor.proto). This is piped to the plugin's stdin. The set will include descriptors for all the files listed in PROTO_FILES as well as all files that they import. The plugin MUST NOT attempt to read the PROTO_FILES directly – it must use the FileDescriptorSet.

 
The plugin should generate whatever files are necessary, as code generators normally do. It should write the names of all files it generates to stdout. The names should be relative to the output directory, NOT absolute names or relative to the current directory. If any errors occur, error messages should be written to stderr. If an error is fatal, the plugin should exit with a non-zero exit code.

 
Plugins can have generator parameters similar to normal built-in generators. Extra generator parameters can be passed in via a matching "_opt" parameter. For example: 

diff --git a/content/reference/cpp/api-docs/google.protobuf.compiler.plugin.md b/content/reference/cpp/api-docs/google.protobuf.compiler.plugin.md
index 45455a98..6e69a512 100644
--- a/content/reference/cpp/api-docs/google.protobuf.compiler.plugin.md
+++ b/content/reference/cpp/api-docs/google.protobuf.compiler.plugin.md
@@ -8,7 +8,7 @@ type = "docs"
 
 
#include <google/protobuf/compiler/plugin.h>
namespace google::protobuf::compiler
Front-end for protoc code generator plugins written in C++. 
To implement a protoc plugin in C++, simply write an implementation of CodeGenerator, then create a main() function like: 

 
-
int main(int argc, char* argv[[]]) {
+
int main(int argc, char* argv[]) {
   MyCodeGenerator generator;
   return google::protobuf::compiler::PluginMain(argc, argv, &generator);
 }

diff --git a/content/reference/cpp/api-docs/google.protobuf.descriptor.pb.md b/content/reference/cpp/api-docs/google.protobuf.descriptor.pb.md
index 16ccd546..b0dfacd6 100644
--- a/content/reference/cpp/api-docs/google.protobuf.descriptor.pb.md
+++ b/content/reference/cpp/api-docs/google.protobuf.descriptor.pb.md
@@ -312,9 +312,9 @@ message MethodDescriptorProto {
   optional MethodOptions options = 4;
 
   // Identifies if client streams multiple client messages
-  optional bool client_streaming = 5 [[]default = false];
+  optional bool client_streaming = 5 [default = false];
   // Identifies if server streams multiple server messages
-  optional bool server_streaming = 6 [[]default = false];
+  optional bool server_streaming = 6 [default = false];
 }
 
 // ===================================================================
@@ -370,10 +370,10 @@ message FileOptions {
   // named by java_outer_classname.  However, the wrapper class will still be
   // generated to contain the file's getDescriptor() method as well as any
   // top-level extensions defined in the file.
-  optional bool java_multiple_files = 10 [[]default = false];
+  optional bool java_multiple_files = 10 [default = false];
 
   // This option does nothing.
-  optional bool java_generate_equals_and_hash = 20 [[]deprecated=true];
+  optional bool java_generate_equals_and_hash = 20 [deprecated=true];
 
   // If set true, then the Java2 code generator will generate code that
   // throws an exception whenever an attempt is made to assign a non-UTF-8
@@ -381,7 +381,7 @@ message FileOptions {
   // Message reflection will do the same.
   // However, an extension field still accepts non-UTF-8 byte sequences.
   // This option has no effect on when used with the lite runtime.
-  optional bool java_string_check_utf8 = 27 [[]default = false];
+  optional bool java_string_check_utf8 = 27 [default = false];
 
   // Generated classes can be optimized for speed or code size.
   enum OptimizeMode {
@@ -390,7 +390,7 @@ message FileOptions {
     CODE_SIZE = 2;     // Use ReflectionOps to implement these methods.
     LITE_RUNTIME = 3;  // Generate code using MessageLite and the lite runtime.
   }
-  optional OptimizeMode optimize_for = 9 [[]default = SPEED];
+  optional OptimizeMode optimize_for = 9 [default = SPEED];
 
   // Sets the Go package where structs generated from this .proto will be
   // placed. If omitted, the Go package will be derived from the following:
@@ -409,20 +409,20 @@ message FileOptions {
   // that generate code specific to your particular RPC system.  Therefore,
   // these default to false.  Old code which depends on generic services should
   // explicitly set them to true.
-  optional bool cc_generic_services = 16 [[]default = false];
-  optional bool java_generic_services = 17 [[]default = false];
-  optional bool py_generic_services = 18 [[]default = false];
-  optional bool php_generic_services = 42 [[]default = false];
+  optional bool cc_generic_services = 16 [default = false];
+  optional bool java_generic_services = 17 [default = false];
+  optional bool py_generic_services = 18 [default = false];
+  optional bool php_generic_services = 42 [default = false];
 
   // Is this file deprecated?
   // Depending on the target platform, this can emit Deprecated annotations
   // for everything in the file, or it will be completely ignored; in the very
   // least, this is a formalization for deprecating files.
-  optional bool deprecated = 23 [[]default = false];
+  optional bool deprecated = 23 [default = false];
 
   // Enables the use of arenas for the proto messages in this file. This applies
   // only to generated classes for C++.
-  optional bool cc_enable_arenas = 31 [[]default = true];
+  optional bool cc_enable_arenas = 31 [default = true];
 
   // Sets the objective c class prefix which is prepended to all objective c
   // generated classes from this .proto. There is no default.
@@ -486,18 +486,18 @@ message MessageOptions {
   //
   // Because this is an option, the above two restrictions are not enforced by
   // the protocol compiler.
-  optional bool message_set_wire_format = 1 [[]default = false];
+  optional bool message_set_wire_format = 1 [default = false];
 
   // Disables the generation of the standard "descriptor()" accessor, which can
   // conflict with a field of the same name.  This is meant to make migration
   // from proto1 easier; new code should avoid fields named "descriptor".
-  optional bool no_standard_descriptor_accessor = 2 [[]default = false];
+  optional bool no_standard_descriptor_accessor = 2 [default = false];
 
   // Is this message deprecated?
   // Depending on the target platform, this can emit Deprecated annotations
   // for the message, or it will be completely ignored; in the very least,
   // this is a formalization for deprecating messages.
-  optional bool deprecated = 3 [[]default = false];
+  optional bool deprecated = 3 [default = false];
 
   reserved 4, 5, 6;
 
@@ -539,7 +539,7 @@ message FieldOptions {
   // representation of the field than it normally would.  See the specific
   // options below.  This option is not yet implemented in the open source
   // release -- sorry, we'll try to include it in a future version!
-  optional CType ctype = 1 [[]default = STRING];
+  optional CType ctype = 1 [default = STRING];
   enum CType {
     // Default mode.
     STRING = 0;
@@ -567,7 +567,7 @@ STRING_PIECE = 2;
   //
   // This option is an enum to permit additional types to be added, e.g.
   // goog.math.Integer.
-  optional JSType jstype = 6 [[]default = JS_NORMAL];
+  optional JSType jstype = 6 [default = JS_NORMAL];
   enum JSType {
     // Use the default type.
     JS_NORMAL = 0;
@@ -608,16 +608,16 @@ JS_NUMBER = 2;
   // implementation must either *always* check its required fields, or *never*
   // check its required fields, regardless of whether or not the message has
   // been parsed.
-  optional bool lazy = 5 [[]default = false];
+  optional bool lazy = 5 [default = false];
 
   // Is this field deprecated?
   // Depending on the target platform, this can emit Deprecated annotations
   // for accessors, or it will be completely ignored; in the very least, this
   // is a formalization for deprecating fields.
-  optional bool deprecated = 3 [[]default = false];
+  optional bool deprecated = 3 [default = false];
 
   // For Google-internal migration only. Do not use.
-  optional bool weak = 10 [[]default = false];
+  optional bool weak = 10 [default = false];
 
   // The parser stores options it doesn't recognize here. See above.
   repeated UninterpretedOption uninterpreted_option = 999;
@@ -646,7 +646,7 @@ message EnumOptions {
   // Depending on the target platform, this can emit Deprecated annotations
   // for the enum, or it will be completely ignored; in the very least, this
   // is a formalization for deprecating enums.
-  optional bool deprecated = 3 [[]default = false];
+  optional bool deprecated = 3 [default = false];
 
   reserved 5;  // javanano_as_lite
 
@@ -662,7 +662,7 @@ message EnumValueOptions {
   // Depending on the target platform, this can emit Deprecated annotations
   // for the enum value, or it will be completely ignored; in the very least,
   // this is a formalization for deprecating enum values.
-  optional bool deprecated = 1 [[]default = false];
+  optional bool deprecated = 1 [default = false];
 
   // The parser stores options it doesn't recognize here. See above.
   repeated UninterpretedOption uninterpreted_option = 999;
@@ -682,7 +682,7 @@ message ServiceOptions {
   // Depending on the target platform, this can emit Deprecated annotations
   // for the service, or it will be completely ignored; in the very least,
   // this is a formalization for deprecating services.
-  optional bool deprecated = 33 [[]default = false];
+  optional bool deprecated = 33 [default = false];
 
   // The parser stores options it doesn't recognize here. See above.
   repeated UninterpretedOption uninterpreted_option = 999;
@@ -702,7 +702,7 @@ message MethodOptions {
   // Depending on the target platform, this can emit Deprecated annotations
   // for the method, or it will be completely ignored; in the very least,
   // this is a formalization for deprecating methods.
-  optional bool deprecated = 33 [[]default = false];
+  optional bool deprecated = 33 [default = false];
 
   // Is this method side-effect-free (or safe in HTTP parlance), or idempotent,
   // or neither? HTTP based RPC implementation may choose GET verb for safe
@@ -713,7 +713,7 @@ message MethodOptions {
     IDEMPOTENT = 2;       // idempotent, but may have side effects
   }
   optional IdempotencyLevel idempotency_level = 34
-      [[]default = IDEMPOTENCY_UNKNOWN];
+      [default = IDEMPOTENCY_UNKNOWN];
 
   // The parser stores options it doesn't recognize here. See above.
   repeated UninterpretedOption uninterpreted_option = 999;
@@ -732,7 +732,7 @@ message UninterpretedOption {
   // The name of the uninterpreted option.  Each string represents a segment in
   // a dot-separated name.  is_extension is true iff a segment represents an
   // extension (denoted with parentheses in options specs in .proto files).
-  // E.g.,{ [[]"foo", false], [[]"bar.baz", true], [[]"qux", false] } represents
+  // E.g.,{ ["foo", false], ["bar.baz", true], ["qux", false] } represents
   // "foo.(bar.baz).qux".
   message NamePart {
     required string name_part = 1;
@@ -771,11 +771,11 @@ message SourceCodeInfo {
   //   a       bc     de  f  ghi
   // We have the following locations:
   //   span   path               represents
-  //   [[]a,i)  [[] 4, 0, 2, 0 ]     The whole field definition.
-  //   [[]a,b)  [[] 4, 0, 2, 0, 4 ]  The label (optional).
-  //   [[]c,d)  [[] 4, 0, 2, 0, 5 ]  The type (string).
-  //   [[]e,f)  [[] 4, 0, 2, 0, 1 ]  The name (foo).
-  //   [[]g,h)  [[] 4, 0, 2, 0, 3 ]  The number (1).
+  //   [a,i)  [ 4, 0, 2, 0 ]     The whole field definition.
+  //   [a,b)  [ 4, 0, 2, 0, 4 ]  The label (optional).
+  //   [c,d)  [ 4, 0, 2, 0, 5 ]  The type (string).
+  //   [e,f)  [ 4, 0, 2, 0, 1 ]  The name (foo).
+  //   [g,h)  [ 4, 0, 2, 0, 3 ]  The number (1).
   //
   // Notes:
   // - A location may refer to a repeated field itself (i.e. not to any
@@ -807,7 +807,7 @@ message SourceCodeInfo {
     // Each element is a field number or an index.  They form a path from
     // the root FileDescriptorProto to the place where the definition.  For
     // example, this path:
-    //   [[] 4, 3, 2, 7, 1 ]
+    //   [ 4, 3, 2, 7, 1 ]
     // refers to:
     //   file.message_type(3)  // 4, 3
     //       .field(7)         // 2, 7
@@ -821,17 +821,17 @@ message SourceCodeInfo {
     //
     // Thus, the above path gives the location of a field name.  If we removed
     // the last element:
-    //   [[] 4, 3, 2, 7 ]
+    //   [ 4, 3, 2, 7 ]
     // this path refers to the whole field declaration (from the beginning
     // of the label to the terminating semicolon).
-    repeated int32 path = 1 [[]packed = true];
+    repeated int32 path = 1 [packed = true];
 
 // Always has exactly three or four elements: start line, start column,
 // end line (optional, otherwise assumed same as start line), end column.
 // These are packed into a single field for efficiency.  Note that line
 // and column numbers are zero-based -- typically you will want to add
 // 1 to each before displaying to a user.
-repeated int32 span = 2 [[]packed = true];
+repeated int32 span = 2 [packed = true];
 
 // If this SourceCodeInfo represents a complete declaration, these are any
 // comments appearing before and after the declaration which appear to be
@@ -896,7 +896,7 @@ message GeneratedCodeInfo {
   message Annotation {
     // Identifies the element in the original source .proto file. This field
     // is formatted the same as SourceCodeInfo.Location.path.
-    repeated int32 path = 1 [[]packed = true];
+    repeated int32 path = 1 [packed = true];
 
 // Identifies the filesystem path to the original source .proto.
 optional string source_file = 2;
diff --git a/content/reference/cpp/api-docs/google.protobuf.descriptor_database.md b/content/reference/cpp/api-docs/google.protobuf.descriptor_database.md
index 8d1133f3..c2f28e43 100644
--- a/content/reference/cpp/api-docs/google.protobuf.descriptor_database.md
+++ b/content/reference/cpp/api-docs/google.protobuf.descriptor_database.md
@@ -19,7 +19,7 @@ type = "docs"
 
This method has a default implementation that always returns false. 

 
 
bool DescriptorDatabase::FindAllPackageNames(
        std::vector< std::string > * output)
Finds the package names and appends them to the output in an undefined order. 
This method is best-effort: it's not guaranteed that the database will find all packages. Returns true if the database supports searching all package names, otherwise returns false and leaves output unchanged. 

 
 
bool DescriptorDatabase::FindAllMessageNames(
        std::vector< std::string > * output)
Finds the message names and appends them to the output in an undefined order. 
This method is best-effort: it's not guaranteed that the database will find all messages. Returns true if the database supports searching all message names, otherwise returns false and leaves output unchanged. 

-
class SimpleDescriptorDatabase: public DescriptorDatabase
#include <google/protobuf/descriptor_database.h>
namespace google::protobuf
A DescriptorDatabase into which you can insert files manually. 
FindFileContainingSymbol() is fully-implemented. When you add a file, its symbols will be indexed for this purpose. Note that the implementation may return false positives, but only if it isn't possible for the symbol to be defined in any other file. In particular, if a file defines a symbol "Foo", then searching for "Foo.[[]anything]" will match that file. This way, the database does not need to aggressively index all children of a symbol.

+
class SimpleDescriptorDatabase: public DescriptorDatabase
#include <google/protobuf/descriptor_database.h>
namespace google::protobuf
A DescriptorDatabase into which you can insert files manually. 
FindFileContainingSymbol() is fully-implemented. When you add a file, its symbols will be indexed for this purpose. Note that the implementation may return false positives, but only if it isn't possible for the symbol to be defined in any other file. In particular, if a file defines a symbol "Foo", then searching for "Foo.[anything]" will match that file. This way, the database does not need to aggressively index all children of a symbol.

 
 
FindFileContainingExtension() is mostly-implemented. It works if and only if the original FieldDescriptorProto defining the extension has a fully-qualified type name in its "extendee" field (i.e. starts with a '.'). If the extendee is a relative name, SimpleDescriptorDatabase will not attempt to resolve the type, so it will not know what type the extension is extending. Therefore, calling FindFileContainingExtension() with the extension's containing type will never actually find that extension. Note that this is an unlikely problem, as all FileDescriptorProtos created by the protocol compiler (as well as ones created by calling FileDescriptor::CopyTo()) will always use fully-qualified names for all types. You only need to worry if you are constructing FileDescriptorProtos yourself, or are calling compiler::Parser directly. 

 
diff --git a/content/reference/cpp/api-docs/google.protobuf.io.coded_stream.md b/content/reference/cpp/api-docs/google.protobuf.io.coded_stream.md
index ee2c6125..04db2bc8 100644
--- a/content/reference/cpp/api-docs/google.protobuf.io.coded_stream.md
+++ b/content/reference/cpp/api-docs/google.protobuf.io.coded_stream.md
@@ -21,7 +21,7 @@ ZeroCopyOutputStream* raw_output = new FileOutputStream(fd);
 CodedOutputStream* coded_output = new CodedOutputStream(raw_output);
 
 int magic_number = 1234;
-char text[[]] = "Hello world!";
+char text[] = "Hello world!";
 coded_output->WriteLittleEndian32(magic_number);
 coded_output->WriteVarint32(strlen(text));
 coded_output->WriteRaw(text, strlen(text));
@@ -46,16 +46,16 @@ if (magic_number != 1234) {
 uint32 size;
 coded_input->ReadVarint32(&size);
 
-char* text = new char[[]size + 1];
+char* text = new char[size + 1];
 coded_input->ReadRaw(buffer, size);
-text[[]size] = '\0';
+text[size] = '\0';
 
 delete coded_input;
 delete raw_input;
 close(fd);
 
 cout << "Text is: " << text << endl;
-delete [[]] text;

+delete [] text;

For those who are interested, varint encoding is defined as follows:

@@ -86,7 +86,7 @@ delete [[]] text;

The value from the wire is interpreted as unsigned. If its value exceeds the representable value of an integer on this platform, instead of truncating we return false. Truncating (as performed by ReadVarint32() above) is an acceptable approach for fields representing an integer, but when we are parsing a size from the wire, truncating the value would result in us misparsing the payload.

uint32 CodedInputStream::ReadTag()

Read a tag.

This calls ReadVarint32() and returns the result, or returns zero (which is not a valid tag) if ReadVarint32() fails. Also, ReadTag (but not ReadTagNoLastTag) updates the last tag value, which can be checked with LastTagWas().

Always inline because this is only called in one place per parse loop but it is called for every iteration of said loop, so it should be fast. GCC doesn't want to inline this by default.

-

std::pair< uint32, bool >
    CodedInputStream::ReadTagWithCutoff(
        uint32 cutoff)

This usually a faster alternative to ReadTag() when cutoff is a manifest constant.

It does particularly well for cutoff >= 127. The first part of the return value is the tag that was read, though it can also be 0 in the cases where ReadTag() would return 0. If the second part is true then the tag is known to be in [[]0, cutoff]. If not, the tag either is above cutoff or is 0. (There's intentional wiggle room when tag is 0, because that can arise in several ways, and for best performance we want to avoid an extra "is tag == 0?" check here.)

+

std::pair< uint32, bool >
    CodedInputStream::ReadTagWithCutoff(
        uint32 cutoff)

This usually a faster alternative to ReadTag() when cutoff is a manifest constant.

It does particularly well for cutoff >= 127. The first part of the return value is the tag that was read, though it can also be 0 in the cases where ReadTag() would return 0. If the second part is true then the tag is known to be in [0, cutoff]. If not, the tag either is above cutoff or is 0. (There's intentional wiggle room when tag is 0, because that can arise in several ways, and for best performance we want to avoid an extra "is tag == 0?" check here.)

bool CodedInputStream::ExpectTag(
        uint32 expected)

Usually returns true if calling ReadVarint32() now would produce the given value.

Will always return false if ReadVarint32() would not return the given value. If ExpectTag() returns true, it also advances past the varint. For best performance, use a compile-time constant as the parameter. Always inline because this collapses to a small number of instructions when given a constant parameter, but GCC doesn't want to inline by default.

bool CodedInputStream::ExpectAtEnd()

Usually returns true if no more bytes can be read.

Always returns false if more bytes can be read. If ExpectAtEnd() returns true, a subsequent call to LastTagWas() will act as if ReadTag() had been called and returned zero, and ConsumedEntireMessage() will return true.

bool CodedInputStream::LastTagWas(
        uint32 expected)

If the last call to ReadTag() or ReadTagWithCutoff() returned the given value, returns true.

Otherwise, returns false. ReadTagNoLastTag/ReadTagWithCutoffNoLastTag do not preserve the last returned value.

@@ -139,7 +139,7 @@ information about underlays.

Note that every method of CodedOutputStream which writes some data has a corresponding static "ToArray" version. These versions write directly to the provided buffer, returning a pointer past the last written byte. They require that the buffer has sufficient capacity for the encoded data. This allows an optimization where we check if an output stream has enough space for an entire message before we start writing and, if there is, we call only the ToArray methods to avoid doing bound checks for each individual value. i.e., in the example above:

CodedOutputStream* coded_output = new CodedOutputStream(raw_output);
 int magic_number = 1234;
-char text[[]] = "Hello world!";
+char text[] = "Hello world!";
 
 int coded_size = sizeof(magic_number) +
                  CodedOutputStream::VarintSize32(strlen(text)) +
diff --git a/content/reference/cpp/api-docs/google.protobuf.io.zero_copy_stream.md b/content/reference/cpp/api-docs/google.protobuf.io.zero_copy_stream.md
index 178c38fc..9ccbcda3 100644
--- a/content/reference/cpp/api-docs/google.protobuf.io.zero_copy_stream.md
+++ b/content/reference/cpp/api-docs/google.protobuf.io.zero_copy_stream.md
@@ -12,7 +12,7 @@ type = "docs"
 
 
As an example, consider the common case in which you are reading bytes from an array that is already in memory (or perhaps an mmap()ed file). With classic I/O streams, you would do something like: 

 
-
char buffer[[]BUFFER_SIZE];
+
char buffer[BUFFER_SIZE];
 input->Read(buffer, BUFFER_SIZE);
 DoSomething(buffer, BUFFER_SIZE);

 
diff --git a/content/reference/cpp/api-docs/google.protobuf.map.md b/content/reference/cpp/api-docs/google.protobuf.map.md
index 3cbe4fe1..f0022eb3 100644
--- a/content/reference/cpp/api-docs/google.protobuf.map.md
+++ b/content/reference/cpp/api-docs/google.protobuf.map.md
@@ -11,7 +11,7 @@ type = "docs"
 
#include <google/protobuf/map.h>
namespace google::protobuf
This file defines the map container and its helpers to support protobuf maps. 
The Map and MapIterator types are provided by this header file. Please avoid using other types defined here, unless they are public types within Map or MapIterator, such as Map::value_type. 

 
 
Classes in this file
This is the class for Map's internal value_type. 
Map is an associative container type used to store protobuf map fields. 
Iterators. 
template alias MapPair
#include <google/protobuf/map.h>
namespace google::protobuf

template <typename , typename >
This is the class for Map's internal value_type, which is just an alias to std::pair. 

-
template class Map
#include <google/protobuf/map.h>
namespace google::protobuf

template <typename , typename >
Map is an associative container type used to store protobuf map fields. 
Each Map instance may or may not use a different hash function, a different iteration order, and so on. E.g., please don't examine implementation details to decide if the following would work: Map<int, int> m0, m1; m0[[]0] = m1[[]0] = m0[[]1] = m1[[]1] = 0; assert(m0.begin()->first == m1.begin()->first); // Bug!

+
template class Map
#include <google/protobuf/map.h>
namespace google::protobuf

template <typename , typename >
Map is an associative container type used to store protobuf map fields. 
Each Map instance may or may not use a different hash function, a different iteration order, and so on. E.g., please don't examine implementation details to decide if the following would work: Map<int, int> m0, m1; m0[0] = m1[0] = m0[1] = m1[1] = 0; assert(m0.begin()->first == m1.begin()->first); // Bug!

 
Map's interface is similar to std::unordered_map, except that Map is not designed to play well with exceptions. 

 
Members
typedef
Key key_type
typedef
T mapped_type
typedef
MapPair< Key, T > value_type
typedef
value_type * pointer
typedef
const value_type * const_pointer
typedef
value_type & reference
typedef
const value_type & const_reference
typedef
size_t size_type
typedef
typename internal::TransparentSupport< Key >::hash hasher
constexpr
Map()
explicit 
Map(Arena * arena)
Map(const Map & other)
Map(Map && other)
Map &
operator=(Map && other)
template 
Map(const InputIt & first, const InputIt & last)
~Map()
iterator
begin()
iterator
end()
const_iterator
begin() const
const_iterator
end() const
const_iterator
cbegin() const
const_iterator
cend() const
size_type
size() const
Capacity. 
bool
empty() const
template T &
operator[](const key_arg< K > & key)
Element access. 
template T &
operator[](key_arg< K > && key)
template const T &
at(const key_arg< K > & key) const
template T &
at(const key_arg< K > & key)
template size_type
count(const key_arg< K > & key) const
Lookup. 
template const_iterator
find(const key_arg< K > & key) const
template iterator
find(const key_arg< K > & key)
template bool
contains(const key_arg< K > & key) const
template std::pair< const_iterator, const_iterator >
equal_range(const key_arg< K > & key) const
template std::pair< iterator, iterator >
equal_range(const key_arg< K > & key)
std::pair< iterator, bool >
insert(const value_type & value)
insert 
template void
insert(InputIt first, InputIt last)
void
insert(std::initializer_list< value_type > values)
template size_type
erase(const key_arg< K > & key)
Erase and clear. 
iterator
erase(iterator pos)
void
erase(iterator first, iterator last)
void
clear()
Map &
operator=(const Map & other)
Assign. 
void
swap(Map & other)
void
InternalSwap(Map & other)
hasher
hash_function() const
Access to hasher.  more...
size_t
SpaceUsedExcludingSelfLong() const
 
hasher Map::hash_function() const
Access to hasher. 
Currently this returns a copy, but it may be modified to return a const reference in the future. 

 
class Map::const_iterator
#include <google/protobuf/map.h>
namespace google::protobuf
Iterators. 
Members
typedef
std::forward_iterator_tag iterator_category
typedef
typename Map::value_type value_type
typedef
ptrdiff_t difference_type
typedef
const value_type * pointer
typedef
const value_type & reference
const_iterator()
explicit 
const_iterator(const InnerIt & it)
const_reference
operator*() const
const_pointer
operator->() const
const_iterator &
operator++()
const_iterator
operator++(int )
class Map::iterator
#include <google/protobuf/map.h>
namespace google::protobuf
Members
typedef
std::forward_iterator_tag iterator_category
typedef
typename Map::value_type value_type
typedef
ptrdiff_t difference_type
typedef
value_type * pointer
typedef
value_type & reference
iterator()
explicit 
iterator(const InnerIt & it)
reference
operator*() const
pointer
operator->() const
iterator &
operator++()
iterator
operator++(int )
operator const_iterator() const
Allow implicit conversion to const_iterator. 

diff --git a/content/reference/cpp/api-docs/google.protobuf.repeated_field.md b/content/reference/cpp/api-docs/google.protobuf.repeated_field.md
index 9fdfe3ae..7dafc1aa 100644
--- a/content/reference/cpp/api-docs/google.protobuf.repeated_field.md
+++ b/content/reference/cpp/api-docs/google.protobuf.repeated_field.md
@@ -17,9 +17,9 @@ temp_field.AddAllocated(new T);
 temp_field.ExtractSubrange(0, temp_field.size(), nullptr);

 
 If you put temp_field on the arena this fails, because the ownership transfers to the arena at the "AddAllocated" call and is not released anymore causing a double delete. Using UnsafeArenaAddAllocated prevents this.

template class RepeatedField

#include <google/protobuf/repeated_field.h>
namespace google::protobuf

template <typename >

RepeatedField is used to represent repeated fields of a primitive type (in other words, everything except strings and nested Messages).

Most users will not ever use a RepeatedField directly; they will use the get-by-index, set-by-index, and add accessors that are generated for all repeated fields.

-

Members

typedef
Element * iterator
STL-like iterator support.
typedef
const Element * const_iterator
typedef
Element value_type
typedef
value_type & reference
typedef
const value_type & const_reference
typedef
value_type * pointer
typedef
const value_type * const_pointer
typedef
int size_type
typedef
ptrdiff_t difference_type
typedef
std::reverse_iterator< const_iterator > const_reverse_iterator
Reverse iterator support.
typedef
std::reverse_iterator< iterator > reverse_iterator
constexpr
RepeatedField()
explicit
RepeatedField(Arena * arena)
RepeatedField(const RepeatedField & other)
template
RepeatedField(Iter begin, Iter end)
~RepeatedField()
RepeatedField &
operator=(const RepeatedField & other)
RepeatedField(RepeatedField && other)
RepeatedField &
operator=(RepeatedField && other)
bool
empty() const
int
size() const
const Element &
Get(int index) const
Element *
Mutable(int index)
const Element &
operator[](int index) const
Element &
operator[](int index)
const Element &
at(int index) const
Element &
at(int index)
void
Set(int index, const Element & value)
void
Add(const Element & value)
Element *
Add()
Appends a new element and return a pointer to it. more...
template void
Add(Iter begin, Iter end)
Append elements in the range [[]begin, end) after reserving the appropriate number of elements.
void
RemoveLast()
Remove the last element in the array.
void
ExtractSubrange(int start, int num, Element * elements)
Extract elements with indices in "[[]start .. start+num-1]". more...
void
Clear()
void
MergeFrom(const RepeatedField & other)
void
CopyFrom(const RepeatedField & other)
template void
Assign(Iter begin, Iter end)
Replaces the contents with RepeatedField(begin, end).
void
Reserve(int new_size)
Reserve space to expand the field to at least the given size. more...
void
Truncate(int new_size)
Resize the RepeatedField to a new, smaller size. This is O(1).
void
AddAlreadyReserved(const Element & value)
Element *
AddAlreadyReserved()
Appends a new element and return a pointer to it. more...
Element *
AddNAlreadyReserved(int elements)
int
Capacity() const
void
Resize(int new_size, const Element & value)
Like STL resize. more...
Element *
mutable_data()
Gets the underlying array. more...
const Element *
data() const
void
Swap(RepeatedField * other)
Swap entire contents with "other". more...
void
UnsafeArenaSwap(RepeatedField * other)
Swap entire contents with "other". more...
void
SwapElements(int index1, int index2)
Swap two elements.
iterator
begin()
const_iterator
begin() const
const_iterator
cbegin() const
iterator
end()
const_iterator
end() const
const_iterator
cend() const
reverse_iterator
rbegin()
const_reverse_iterator
rbegin() const
reverse_iterator
rend()
const_reverse_iterator
rend() const
size_t
SpaceUsedExcludingSelfLong() const
Returns the number of bytes used by the repeated field, excluding sizeof(*this)
int
SpaceUsedExcludingSelf() const
iterator
erase(const_iterator position)
Removes the element referenced by position. more...
iterator
erase(const_iterator first, const_iterator last)
Removes the elements in the range [[]first, last). more...
Arena *
GetArena() const
Get the Arena on which this RepeatedField stores its elements.
void
InternalSwap(RepeatedField * other)
For internal use only. more...
template
RepeatedField(Iter begin, Iter end)

Element * RepeatedField::Add()

Appends a new element and return a pointer to it.

The new element is uninitialized if |Element| is a POD type.

-

void RepeatedField::ExtractSubrange(
        int start,
        int num,
        Element * elements)

Extract elements with indices in "[[]start .. start+num-1]".

Copy them into "elements[[]0 .. num-1]" if "elements" is not NULL. Caution: implementation also moves elements with indices [[]start+num ..]. Calling this routine inside a loop can cause quadratic behavior.

-

void RepeatedField::Reserve(
        int new_size)

Reserve space to expand the field to at least the given size.

Avoid inlining of Reserve(): new, copy, and delete[[]] lead to a significant amount of code bloat.

+

Members

typedef
Element * iterator
STL-like iterator support.
typedef
const Element * const_iterator
typedef
Element value_type
typedef
value_type & reference
typedef
const value_type & const_reference
typedef
value_type * pointer
typedef
const value_type * const_pointer
typedef
int size_type
typedef
ptrdiff_t difference_type
typedef
std::reverse_iterator< const_iterator > const_reverse_iterator
Reverse iterator support.
typedef
std::reverse_iterator< iterator > reverse_iterator
constexpr
RepeatedField()
explicit
RepeatedField(Arena * arena)
RepeatedField(const RepeatedField & other)
template
RepeatedField(Iter begin, Iter end)
~RepeatedField()
RepeatedField &
operator=(const RepeatedField & other)
RepeatedField(RepeatedField && other)
RepeatedField &
operator=(RepeatedField && other)
bool
empty() const
int
size() const
const Element &
Get(int index) const
Element *
Mutable(int index)
const Element &
operator[](int index) const
Element &
operator[](int index)
const Element &
at(int index) const
Element &
at(int index)
void
Set(int index, const Element & value)
void
Add(const Element & value)
Element *
Add()
Appends a new element and return a pointer to it. more...
template void
Add(Iter begin, Iter end)
Append elements in the range [begin, end) after reserving the appropriate number of elements.
void
RemoveLast()
Remove the last element in the array.
void
ExtractSubrange(int start, int num, Element * elements)
Extract elements with indices in "[start .. start+num-1]". more...
void
Clear()
void
MergeFrom(const RepeatedField & other)
void
CopyFrom(const RepeatedField & other)
template void
Assign(Iter begin, Iter end)
Replaces the contents with RepeatedField(begin, end).
void
Reserve(int new_size)
Reserve space to expand the field to at least the given size. more...
void
Truncate(int new_size)
Resize the RepeatedField to a new, smaller size. This is O(1).
void
AddAlreadyReserved(const Element & value)
Element *
AddAlreadyReserved()
Appends a new element and return a pointer to it. more...
Element *
AddNAlreadyReserved(int elements)
int
Capacity() const
void
Resize(int new_size, const Element & value)
Like STL resize. more...
Element *
mutable_data()
Gets the underlying array. more...
const Element *
data() const
void
Swap(RepeatedField * other)
Swap entire contents with "other". more...
void
UnsafeArenaSwap(RepeatedField * other)
Swap entire contents with "other". more...
void
SwapElements(int index1, int index2)
Swap two elements.
iterator
begin()
const_iterator
begin() const
const_iterator
cbegin() const
iterator
end()
const_iterator
end() const
const_iterator
cend() const
reverse_iterator
rbegin()
const_reverse_iterator
rbegin() const
reverse_iterator
rend()
const_reverse_iterator
rend() const
size_t
SpaceUsedExcludingSelfLong() const
Returns the number of bytes used by the repeated field, excluding sizeof(*this)
int
SpaceUsedExcludingSelf() const
iterator
erase(const_iterator position)
Removes the element referenced by position. more...
iterator
erase(const_iterator first, const_iterator last)
Removes the elements in the range [first, last). more...
Arena *
GetArena() const
Get the Arena on which this RepeatedField stores its elements.
void
InternalSwap(RepeatedField * other)
For internal use only. more...
template
RepeatedField(Iter begin, Iter end)

Element * RepeatedField::Add()

Appends a new element and return a pointer to it.

The new element is uninitialized if |Element| is a POD type.

+

void RepeatedField::ExtractSubrange(
        int start,
        int num,
        Element * elements)

Extract elements with indices in "[start .. start+num-1]".

Copy them into "elements[0 .. num-1]" if "elements" is not NULL. Caution: implementation also moves elements with indices [start+num ..]. Calling this routine inside a loop can cause quadratic behavior.

+

void RepeatedField::Reserve(
        int new_size)

Reserve space to expand the field to at least the given size.

Avoid inlining of Reserve(): new, copy, and delete[] lead to a significant amount of code bloat.

If the array is grown, it will always be at least doubled in size.

Element * RepeatedField::AddAlreadyReserved()

Appends a new element and return a pointer to it.

The new element is uninitialized if |Element| is a POD type. Should be called only if Capacity() > Size().

void RepeatedField::Resize(
        int new_size,
        const Element & value)

Like STL resize.

Uses value to fill appended elements. Like Truncate() if new_size <= size(), otherwise this is O(new_size - size()).

@@ -28,11 +28,11 @@ temp_field.ExtractSubrange(0, temp_field.size(), nullptr);

void RepeatedField::UnsafeArenaSwap(
        RepeatedField * other)

Swap entire contents with "other".

Should be called only if the caller can guarantee that both repeated fields are on the same arena or are on the heap. Swapping between different arenas is disallowed and caught by a GOOGLE_DCHECK (see API docs for details).

iterator RepeatedField::erase(
        const_iterator position)

Removes the element referenced by position.

Returns an iterator to the element immediately following the removed element.

Invalidates all iterators at or after the removed element, including end().

-

iterator RepeatedField::erase(
        const_iterator first,
        const_iterator last)

Removes the elements in the range [[]first, last).

Returns an iterator to the element immediately following the removed range.

+

iterator RepeatedField::erase(
        const_iterator first,
        const_iterator last)

Removes the elements in the range [first, last).

Returns an iterator to the element immediately following the removed range.

Invalidates all iterators at or after the removed range, including end().

void RepeatedField::InternalSwap(
        RepeatedField * other)

For internal use only.

This is public due to it being called by generated code.

-

template class RepeatedPtrField

#include <google/protobuf/repeated_field.h>
namespace google::protobuf

template <typename >

RepeatedPtrField is like RepeatedField, but used for repeated strings or Messages.

Members

typedef
internal::RepeatedPtrIterator< Element > iterator
STL-like iterator support.
typedef
internal::RepeatedPtrIterator< const Element > const_iterator
typedef
Element value_type
typedef
value_type & reference
typedef
const value_type & const_reference
typedef
value_type * pointer
typedef
const value_type * const_pointer
typedef
int size_type
typedef
ptrdiff_t difference_type
typedef
std::reverse_iterator< const_iterator > const_reverse_iterator
Reverse iterator support.
typedef
std::reverse_iterator< iterator > reverse_iterator
typedef
internal::RepeatedPtrOverPtrsIterator< Element *, void * > pointer_iterator
Custom STL-like iterator that iterates over and returns the underlying pointers to Element rather than Element itself.
typedef
internal::RepeatedPtrOverPtrsIterator< const Element *const, const void *const > const_pointer_iterator
constexpr
RepeatedPtrField()
explicit
RepeatedPtrField(Arena * arena)
RepeatedPtrField(const RepeatedPtrField & other)
template
RepeatedPtrField(Iter begin, Iter end)
~RepeatedPtrField()
RepeatedPtrField &
operator=(const RepeatedPtrField & other)
RepeatedPtrField(RepeatedPtrField && other)
RepeatedPtrField &
operator=(RepeatedPtrField && other)
bool
empty() const
int
size() const
const Element &
Get(int index) const
Element *
Mutable(int index)
Element *
Add()
void
Add(Element && value)
template void
Add(Iter begin, Iter end)
Append elements in the range [[]begin, end) after reserving the appropriate number of elements.
const Element &
operator[](int index) const
Element &
operator[](int index)
const Element &
at(int index) const
Element &
at(int index)
void
RemoveLast()
Remove the last element in the array. more...
void
DeleteSubrange(int start, int num)
Delete elements with indices in the range [[]start . more...
void
Clear()
void
MergeFrom(const RepeatedPtrField & other)
void
CopyFrom(const RepeatedPtrField & other)
template void
Assign(Iter begin, Iter end)
Replaces the contents with RepeatedPtrField(begin, end).
void
Reserve(int new_size)
Reserve space to expand the field to at least the given size. more...
int
Capacity() const
Element **
mutable_data()
Gets the underlying array. more...
const Element *const *
data() const
void
Swap(RepeatedPtrField * other)
Swap entire contents with "other". more...
void
UnsafeArenaSwap(RepeatedPtrField * other)
Swap entire contents with "other". more...
void
SwapElements(int index1, int index2)
Swap two elements.
iterator
begin()
const_iterator
begin() const
const_iterator
cbegin() const
iterator
end()
const_iterator
end() const
const_iterator
cend() const
reverse_iterator
rbegin()
const_reverse_iterator
rbegin() const
reverse_iterator
rend()
const_reverse_iterator
rend() const
pointer_iterator
pointer_begin()
const_pointer_iterator
pointer_begin() const
pointer_iterator
pointer_end()
const_pointer_iterator
pointer_end() const
size_t
SpaceUsedExcludingSelfLong() const
Returns (an estimate of) the number of bytes used by the repeated field, excluding sizeof(*this).
int
SpaceUsedExcludingSelf() const
template
RepeatedPtrField(Iter begin, Iter end)

Advanced memory management

When hardcore memory management becomes necessary – as it sometimes does here at Google – the following methods may be useful.
void
AddAllocated(Element * value)
Add an already-allocated object, passing ownership to the RepeatedPtrField. more...
PROTOBUF_FUTURE_MUST_USE_RESULT Element *
ReleaseLast()
Remove the last element and return it, passing ownership to the caller. more...
void
UnsafeArenaAddAllocated(Element * value)
Add an already-allocated object, skipping arena-ownership checks. more...
Element *
UnsafeArenaReleaseLast()
Remove the last element and return it. more...
void
ExtractSubrange(int start, int num, Element ** elements)
Extract elements with indices in the range "[[]start .. start+num-1]". more...
void
UnsafeArenaExtractSubrange(int start, int num, Element ** elements)
Identical to ExtractSubrange() described above, except that when this repeated field is on an arena, no object copies are performed. more...
int
ClearedCount() const
Get the number of cleared objects that are currently being kept around for reuse.
void
AddCleared(Element * value)
Add an element to the pool of cleared objects, passing ownership to the RepeatedPtrField. more...
PROTOBUF_FUTURE_MUST_USE_RESULT Element *
ReleaseCleared()
Remove a single element from the cleared pool and return it, passing ownership to the caller. more...
iterator
erase(const_iterator position)
Removes the element referenced by position. more...
iterator
erase(const_iterator first, const_iterator last)
Removes the elements in the range [[]first, last). more...
Arena *
GetArena() const
Gets the arena on which this RepeatedPtrField stores its elements.
void
InternalSwap(RepeatedPtrField * other)
For internal use only. more...

void RepeatedPtrField::RemoveLast()

Remove the last element in the array.

Ownership of the element is retained by the array.

-

void RepeatedPtrField::DeleteSubrange(
        int start,
        int num)

Delete elements with indices in the range [[]start .

. start+num-1]. Caution: implementation moves all elements with indices [[]start+num .. ]. Calling this routine inside a loop can cause quadratic behavior.

+

template class RepeatedPtrField

#include <google/protobuf/repeated_field.h>
namespace google::protobuf

template <typename >

RepeatedPtrField is like RepeatedField, but used for repeated strings or Messages.

Members

typedef
internal::RepeatedPtrIterator< Element > iterator
STL-like iterator support.
typedef
internal::RepeatedPtrIterator< const Element > const_iterator
typedef
Element value_type
typedef
value_type & reference
typedef
const value_type & const_reference
typedef
value_type * pointer
typedef
const value_type * const_pointer
typedef
int size_type
typedef
ptrdiff_t difference_type
typedef
std::reverse_iterator< const_iterator > const_reverse_iterator
Reverse iterator support.
typedef
std::reverse_iterator< iterator > reverse_iterator
typedef
internal::RepeatedPtrOverPtrsIterator< Element *, void * > pointer_iterator
Custom STL-like iterator that iterates over and returns the underlying pointers to Element rather than Element itself.
typedef
internal::RepeatedPtrOverPtrsIterator< const Element *const, const void *const > const_pointer_iterator
constexpr
RepeatedPtrField()
explicit
RepeatedPtrField(Arena * arena)
RepeatedPtrField(const RepeatedPtrField & other)
template
RepeatedPtrField(Iter begin, Iter end)
~RepeatedPtrField()
RepeatedPtrField &
operator=(const RepeatedPtrField & other)
RepeatedPtrField(RepeatedPtrField && other)
RepeatedPtrField &
operator=(RepeatedPtrField && other)
bool
empty() const
int
size() const
const Element &
Get(int index) const
Element *
Mutable(int index)
Element *
Add()
void
Add(Element && value)
template void
Add(Iter begin, Iter end)
Append elements in the range [begin, end) after reserving the appropriate number of elements.
const Element &
operator[](int index) const
Element &
operator[](int index)
const Element &
at(int index) const
Element &
at(int index)
void
RemoveLast()
Remove the last element in the array. more...
void
DeleteSubrange(int start, int num)
Delete elements with indices in the range [start . more...
void
Clear()
void
MergeFrom(const RepeatedPtrField & other)
void
CopyFrom(const RepeatedPtrField & other)
template void
Assign(Iter begin, Iter end)
Replaces the contents with RepeatedPtrField(begin, end).
void
Reserve(int new_size)
Reserve space to expand the field to at least the given size. more...
int
Capacity() const
Element **
mutable_data()
Gets the underlying array. more...
const Element *const *
data() const
void
Swap(RepeatedPtrField * other)
Swap entire contents with "other". more...
void
UnsafeArenaSwap(RepeatedPtrField * other)
Swap entire contents with "other". more...
void
SwapElements(int index1, int index2)
Swap two elements.
iterator
begin()
const_iterator
begin() const
const_iterator
cbegin() const
iterator
end()
const_iterator
end() const
const_iterator
cend() const
reverse_iterator
rbegin()
const_reverse_iterator
rbegin() const
reverse_iterator
rend()
const_reverse_iterator
rend() const
pointer_iterator
pointer_begin()
const_pointer_iterator
pointer_begin() const
pointer_iterator
pointer_end()
const_pointer_iterator
pointer_end() const
size_t
SpaceUsedExcludingSelfLong() const
Returns (an estimate of) the number of bytes used by the repeated field, excluding sizeof(*this).
int
SpaceUsedExcludingSelf() const
template
RepeatedPtrField(Iter begin, Iter end)

Advanced memory management

When hardcore memory management becomes necessary – as it sometimes does here at Google – the following methods may be useful.
void
AddAllocated(Element * value)
Add an already-allocated object, passing ownership to the RepeatedPtrField. more...
PROTOBUF_FUTURE_MUST_USE_RESULT Element *
ReleaseLast()
Remove the last element and return it, passing ownership to the caller. more...
void
UnsafeArenaAddAllocated(Element * value)
Add an already-allocated object, skipping arena-ownership checks. more...
Element *
UnsafeArenaReleaseLast()
Remove the last element and return it. more...
void
ExtractSubrange(int start, int num, Element ** elements)
Extract elements with indices in the range "[start .. start+num-1]". more...
void
UnsafeArenaExtractSubrange(int start, int num, Element ** elements)
Identical to ExtractSubrange() described above, except that when this repeated field is on an arena, no object copies are performed. more...
int
ClearedCount() const
Get the number of cleared objects that are currently being kept around for reuse.
void
AddCleared(Element * value)
Add an element to the pool of cleared objects, passing ownership to the RepeatedPtrField. more...
PROTOBUF_FUTURE_MUST_USE_RESULT Element *
ReleaseCleared()
Remove a single element from the cleared pool and return it, passing ownership to the caller. more...
iterator
erase(const_iterator position)
Removes the element referenced by position. more...
iterator
erase(const_iterator first, const_iterator last)
Removes the elements in the range [first, last). more...
Arena *
GetArena() const
Gets the arena on which this RepeatedPtrField stores its elements.
void
InternalSwap(RepeatedPtrField * other)
For internal use only. more...

void RepeatedPtrField::RemoveLast()

Remove the last element in the array.

Ownership of the element is retained by the array.

+

void RepeatedPtrField::DeleteSubrange(
        int start,
        int num)

Delete elements with indices in the range [start .

. start+num-1]. Caution: implementation moves all elements with indices [start+num .. ]. Calling this routine inside a loop can cause quadratic behavior.

void RepeatedPtrField::Reserve(
        int new_size)

Reserve space to expand the field to at least the given size.

This only resizes the pointer array; it doesn't allocate any objects. If the array is grown, it will always be at least doubled in size.

Element ** RepeatedPtrField::mutable_data()

Gets the underlying array.

This pointer is possibly invalidated by any add or remove operation.

void RepeatedPtrField::Swap(
        RepeatedPtrField * other)

Swap entire contents with "other".

If they are on separate arenas, then copies data.

@@ -53,7 +53,7 @@ temp_field.AddAllocated(new T); temp_field.ExtractSubrange(0, temp_field.size(), nullptr);

If you put temp_field on the arena this fails, because the ownership transfers to the arena at the "AddAllocated" call and is not released anymore causing a double delete. UnsafeArenaAddAllocated prevents this.

Element * RepeatedPtrField::UnsafeArenaReleaseLast()

Remove the last element and return it.

Works only when operating on an arena. The returned pointer is to the original object in the arena, hence has the arena's lifetime. Requires: current_size_ > 0

-

void RepeatedPtrField::ExtractSubrange(
        int start,
        int num,
        Element ** elements)

Extract elements with indices in the range "[[]start .. start+num-1]".

The caller assumes ownership of the extracted elements and is responsible for deleting them when they are no longer needed. If "elements" is non-NULL, then pointers to the extracted elements are stored in "elements[[]0 .. num-1]" for the convenience of the caller. If "elements" is NULL, then the caller must use some other mechanism to perform any further operations (like deletion) on these elements. Caution: implementation also moves elements with indices [[]start+num ..]. Calling this routine inside a loop can cause quadratic behavior.

+

void RepeatedPtrField::ExtractSubrange(
        int start,
        int num,
        Element ** elements)

Extract elements with indices in the range "[start .. start+num-1]".

The caller assumes ownership of the extracted elements and is responsible for deleting them when they are no longer needed. If "elements" is non-NULL, then pointers to the extracted elements are stored in "elements[0 .. num-1]" for the convenience of the caller. If "elements" is NULL, then the caller must use some other mechanism to perform any further operations (like deletion) on these elements. Caution: implementation also moves elements with indices [start+num ..]. Calling this routine inside a loop can cause quadratic behavior.

Memory copying behavior is identical to ReleaseLast(), described above: if this RepeatedPtrField is on an arena, an object copy is performed for each returned element, so that all returned element pointers are to heap-allocated copies. If this copy is not desired, the user should call UnsafeArenaExtractSubrange().

void RepeatedPtrField::UnsafeArenaExtractSubrange(
        int start,
        int num,
        Element ** elements)

Identical to ExtractSubrange() described above, except that when this repeated field is on an arena, no object copies are performed.

Instead, the raw object pointers are returned. Thus, if on an arena, the returned objects must not be freed, because they will not be heap-allocated objects.

void RepeatedPtrField::AddCleared(
        Element * value)

Add an element to the pool of cleared objects, passing ownership to the RepeatedPtrField.

The element must be cleared prior to calling this method.

@@ -62,7 +62,7 @@ temp_field.ExtractSubrange(0, temp_field.size(), nullptr);

This method cannot be called when the repeated field is on an arena; doing so will trigger a GOOGLE_DCHECK-failure.

iterator RepeatedPtrField::erase(
        const_iterator position)

Removes the element referenced by position.

Returns an iterator to the element immediately following the removed element.

Invalidates all iterators at or after the removed element, including end().

-

iterator RepeatedPtrField::erase(
        const_iterator first,
        const_iterator last)

Removes the elements in the range [[]first, last).

Returns an iterator to the element immediately following the removed range.

+

iterator RepeatedPtrField::erase(
        const_iterator first,
        const_iterator last)

Removes the elements in the range [first, last).

Returns an iterator to the element immediately following the removed range.

Invalidates all iterators at or after the removed range, including end().

void RepeatedPtrField::InternalSwap(
        RepeatedPtrField * other)

For internal use only.

This is public due to it being called by generated code.

diff --git a/content/reference/cpp/api-docs/google.protobuf.text_format.md b/content/reference/cpp/api-docs/google.protobuf.text_format.md index 02216947..26ae8ceb 100644 --- a/content/reference/cpp/api-docs/google.protobuf.text_format.md +++ b/content/reference/cpp/api-docs/google.protobuf.text_format.md @@ -36,14 +36,14 @@ type = "docs"

void Parser::AllowUnknownField(
        bool allow)

When an unknown field is met, parsing will fail if this option is set to false (the default).

If true, unknown fields will be ignored and a warning message will be generated. Beware! Setting this option true may hide some errors (e.g. spelling error on field name). This allows data loss; unlike binary format, text format cannot preserve unknown fields. Avoid using this option if possible.

void Parser::SetRecursionLimit(
        int limit)

Sets maximum recursion depth which parser can use.

This is effectively the maximum allowed nesting of proto messages.

class TextFormat::Printer

#include <google/protobuf/text_format.h>
namespace google::protobuf

Class for those users which require more fine-grained control over how a protobuffer message is printed out.

Members

Printer()
bool
Print(const Message & message, io::ZeroCopyOutputStream * output) const
bool
PrintUnknownFields(const UnknownFieldSet & unknown_fields, io::ZeroCopyOutputStream * output) const
bool
PrintToString(const Message & message, std::string * output) const
bool
PrintUnknownFieldsToString(const UnknownFieldSet & unknown_fields, std::string * output) const
void
PrintFieldValueToString(const Message & message, const FieldDescriptor * field, int index, std::string * output) const
void
SetInitialIndentLevel(int indent_level)
Adjust the initial indent level of all output. more...
void
SetSingleLineMode(bool single_line_mode)
If printing in single line mode, then the entire message will be output on a single line with no line breaks.
bool
IsInSingleLineMode() const
void
SetUseFieldNumber(bool use_field_number)
If use_field_number is true, uses field number instead of field name.
void
SetUseShortRepeatedPrimitives(bool use_short_repeated_primitives)
Set true to print repeated primitives in a format like: more...
void
SetUseUtf8StringEscaping(bool as_utf8)
Set true to output UTF-8 instead of ASCII. more...
void
SetDefaultFieldValuePrinter(const FastFieldValuePrinter * printer)
Set the default FastFieldValuePrinter that is used for all fields that don't have a field-specific printer registered. more...
void
SetDefaultFieldValuePrinter(const FieldValuePrinter * printer)
void
SetHideUnknownFields(bool hide)
Sets whether we want to hide unknown fields or not. more...
void
SetPrintMessageFieldsInIndexOrder(bool print_message_fields_in_index_order)
If print_message_fields_in_index_order is true, fields of a proto message will be printed using the order defined in source code instead of the field number, extensions will be printed at the end of the message and their relative order is determined by the extension number. more...
void
SetExpandAny(bool expand)
If expand==true, expand google.protobuf.Any payloads. more...
void
SetFinder(const Finder * finder)
Set how parser finds message for Any payloads.
void
SetTruncateStringFieldLongerThan(const int64 truncate_string_field_longer_than)
If non-zero, we truncate all string fields that are longer than this threshold. more...
bool
RegisterFieldValuePrinter(const FieldDescriptor * field, const FastFieldValuePrinter * printer)
Register a custom field-specific FastFieldValuePrinter for fields with a particular FieldDescriptor. more...
bool
RegisterFieldValuePrinter(const FieldDescriptor * field, const FieldValuePrinter * printer)
bool
RegisterMessagePrinter(const Descriptor * descriptor, const MessagePrinter * printer)
Register a custom message-specific MessagePrinter for messages with a particular Descriptor. more...

void Printer::SetInitialIndentLevel(
        int indent_level)

Adjust the initial indent level of all output.

Each indent level is equal to two spaces.

-

void Printer::SetUseShortRepeatedPrimitives(
        bool use_short_repeated_primitives)

Set true to print repeated primitives in a format like: 

field_name: [[]1, 2, 3, 4]
+

void Printer::SetUseShortRepeatedPrimitives(
        bool use_short_repeated_primitives)

Set true to print repeated primitives in a format like: 

field_name: [1, 2, 3, 4]

instead of printing each value on its own line. Short format applies only to primitive values – i.e. everything except strings and sub-messages/groups.

void Printer::SetUseUtf8StringEscaping(
        bool as_utf8)

Set true to output UTF-8 instead of ASCII.

The only difference is that bytes >= 0x80 in string fields will not be escaped, because they are assumed to be part of UTF-8 multi-byte sequences. This will change the default FastFieldValuePrinter.

void Printer::SetDefaultFieldValuePrinter(
        const FastFieldValuePrinter * printer)

Set the default FastFieldValuePrinter that is used for all fields that don't have a field-specific printer registered.

Takes ownership of the printer.

void Printer::SetHideUnknownFields(
        bool hide)

Sets whether we want to hide unknown fields or not.

Usually unknown fields are printed in a generic way that includes the tag number of the field instead of field name. However, sometimes it is useful to be able to print the message without unknown fields (e.g. for the python protobuf version to maintain consistency between its pure python and c++ implementations).

void Printer::SetPrintMessageFieldsInIndexOrder(
        bool print_message_fields_in_index_order)

If print_message_fields_in_index_order is true, fields of a proto message will be printed using the order defined in source code instead of the field number, extensions will be printed at the end of the message and their relative order is determined by the extension number.

By default, use the field number order.

void Printer::SetExpandAny(
        bool expand)

If expand==true, expand google.protobuf.Any payloads.

The output will be of form

-
[[]type_url] { <value_printed_in_text> }
+
[type_url] { <value_printed_in_text> }

If expand==false, print Any using the default printer. The output will look like 

type_url: "<type_url>"  value: "serialized_content"

void Printer::SetTruncateStringFieldLongerThan(
        const int64 truncate_string_field_longer_than)

If non-zero, we truncate all string fields that are longer than this threshold.

This is useful when the proto message has very long strings, e.g., dump of encoded image file.

diff --git a/content/reference/cpp/api-docs/google.protobuf.unknown_field_set.md b/content/reference/cpp/api-docs/google.protobuf.unknown_field_set.md index 3310a1b5..8eb6e768 100644 --- a/content/reference/cpp/api-docs/google.protobuf.unknown_field_set.md +++ b/content/reference/cpp/api-docs/google.protobuf.unknown_field_set.md @@ -14,13 +14,13 @@ type = "docs"

This class is necessarily tied to the protocol buffer wire format, unlike the Reflection interface which is independent of any serialization scheme.

-

Members

UnknownFieldSet()
~UnknownFieldSet()
void
Clear()
Remove all fields.
void
ClearAndFreeMemory()
Remove all fields and deallocate internal data objects.
bool
empty() const
Is this set empty?
void
MergeFrom(const UnknownFieldSet & other)
Merge the contents of some other UnknownFieldSet with this one.
void
MergeFromAndDestroy(UnknownFieldSet * other)
Similar to above, but this function will destroy the contents of other.
void
Swap(UnknownFieldSet * x)
Swaps the contents of some other UnknownFieldSet with this one.
size_t
SpaceUsedExcludingSelfLong() const
Computes (an estimate of) the total number of bytes currently used for storing the unknown fields in memory. more...
int
SpaceUsedExcludingSelf() const
size_t
SpaceUsedLong() const
Version of SpaceUsed() including sizeof(*this).
int
SpaceUsed() const
int
field_count() const
Returns the number of fields present in the UnknownFieldSet.
const UnknownField &
field(int index) const
Get a field in the set, where 0 <= index < field_count(). more...
UnknownField *
mutable_field(int index)
Get a mutable pointer to a field in the set, where 0 <= index < field_count(). more...
static void
MergeToInternalMetadata(const UnknownFieldSet & other, internal::InternalMetadata * metadata)
Merge the contents an UnknownFieldSet with the UnknownFieldSet in *metadata, if there is one. more...

Adding fields

void
AddVarint(int number, uint64 value)
void
AddFixed32(int number, uint32 value)
void
AddFixed64(int number, uint64 value)
void
AddLengthDelimited(int number, const std::string & value)
std::string *
AddLengthDelimited(int number)
UnknownFieldSet *
AddGroup(int number)
void
AddField(const UnknownField & field)
Adds an unknown field from another set.
void
DeleteSubrange(int start, int num)
Delete fields with indices in the range [[]start . more...
void
DeleteByNumber(int number)
Delete all fields with a specific field number. more...

Parsing helpers

These work exactly like the similarly-named methods of Message.
bool
MergeFromCodedStream(io::CodedInputStream * input)
bool
ParseFromCodedStream(io::CodedInputStream * input)
bool
ParseFromZeroCopyStream(io::ZeroCopyInputStream * input)
bool
ParseFromArray(const void * data, int size)
bool
ParseFromString(const std::string & data)
template bool
MergeFromMessage(const MessageType & message)
Merges this message's unknown field data (if any). more...
static const UnknownFieldSet &
default_instance()

size_t UnknownFieldSet::SpaceUsedExcludingSelfLong() const

Computes (an estimate of) the total number of bytes currently used for storing the unknown fields in memory.

Does NOT include sizeof(*this) in the calculation.

+

Members

UnknownFieldSet()
~UnknownFieldSet()
void
Clear()
Remove all fields.
void
ClearAndFreeMemory()
Remove all fields and deallocate internal data objects.
bool
empty() const
Is this set empty?
void
MergeFrom(const UnknownFieldSet & other)
Merge the contents of some other UnknownFieldSet with this one.
void
MergeFromAndDestroy(UnknownFieldSet * other)
Similar to above, but this function will destroy the contents of other.
void
Swap(UnknownFieldSet * x)
Swaps the contents of some other UnknownFieldSet with this one.
size_t
SpaceUsedExcludingSelfLong() const
Computes (an estimate of) the total number of bytes currently used for storing the unknown fields in memory. more...
int
SpaceUsedExcludingSelf() const
size_t
SpaceUsedLong() const
Version of SpaceUsed() including sizeof(*this).
int
SpaceUsed() const
int
field_count() const
Returns the number of fields present in the UnknownFieldSet.
const UnknownField &
field(int index) const
Get a field in the set, where 0 <= index < field_count(). more...
UnknownField *
mutable_field(int index)
Get a mutable pointer to a field in the set, where 0 <= index < field_count(). more...
static void
MergeToInternalMetadata(const UnknownFieldSet & other, internal::InternalMetadata * metadata)
Merge the contents an UnknownFieldSet with the UnknownFieldSet in *metadata, if there is one. more...

Adding fields

void
AddVarint(int number, uint64 value)
void
AddFixed32(int number, uint32 value)
void
AddFixed64(int number, uint64 value)
void
AddLengthDelimited(int number, const std::string & value)
std::string *
AddLengthDelimited(int number)
UnknownFieldSet *
AddGroup(int number)
void
AddField(const UnknownField & field)
Adds an unknown field from another set.
void
DeleteSubrange(int start, int num)
Delete fields with indices in the range [start . more...
void
DeleteByNumber(int number)
Delete all fields with a specific field number. more...

Parsing helpers

These work exactly like the similarly-named methods of Message.
bool
MergeFromCodedStream(io::CodedInputStream * input)
bool
ParseFromCodedStream(io::CodedInputStream * input)
bool
ParseFromZeroCopyStream(io::ZeroCopyInputStream * input)
bool
ParseFromArray(const void * data, int size)
bool
ParseFromString(const std::string & data)
template bool
MergeFromMessage(const MessageType & message)
Merges this message's unknown field data (if any). more...
static const UnknownFieldSet &
default_instance()

size_t UnknownFieldSet::SpaceUsedExcludingSelfLong() const

Computes (an estimate of) the total number of bytes currently used for storing the unknown fields in memory.

Does NOT include sizeof(*this) in the calculation.

const UnknownField &
    UnknownFieldSet::field(
        int index) const

Get a field in the set, where 0 <= index < field_count().

The fields appear in the order in which they were added.

UnknownField * UnknownFieldSet::mutable_field(
        int index)

Get a mutable pointer to a field in the set, where 0 <= index < field_count().

The fields appear in the order in which they were added.

static void UnknownFieldSet::MergeToInternalMetadata(
        const UnknownFieldSet & other,
        internal::InternalMetadata * metadata)

Merge the contents an UnknownFieldSet with the UnknownFieldSet in *metadata, if there is one.

If *metadata doesn't have an UnknownFieldSet then add one to it and make it be a copy of the first arg.

-

void UnknownFieldSet::DeleteSubrange(
        int start,
        int num)

Delete fields with indices in the range [[]start .

. start+num-1]. Caution: implementation moves all fields with indices [[]start+num .. ].

+

void UnknownFieldSet::DeleteSubrange(
        int start,
        int num)

Delete fields with indices in the range [start .

. start+num-1]. Caution: implementation moves all fields with indices [start+num .. ].

void UnknownFieldSet::DeleteByNumber(
        int number)

Delete all fields with a specific field number.

The order of left fields is preserved. Caution: implementation moves all fields after the first deleted field.

template bool UnknownFieldSet::MergeFromMessage(
        const MessageType & message)

Merges this message's unknown field data (if any).

This works whether the message is a lite or full proto (for legacy reasons, lite and full return different types for MessageType::unknown_fields()).

-

class UnknownField

#include <google/protobuf/unknown_field_set.h>
namespace google::protobuf

Represents one field in an UnknownFieldSet.

Members

enum
Type
uint64
varint_
uint32
fixed32_
uint64
fixed64_
union LengthDelimited
length_delimited_
UnknownFieldSet *
group_
int
number() const
The field's field number, as seen on the wire.
Type
type() const
The field type.

Accessors

Each method works only for UnknownFields of the corresponding type.
uint32
number_
uint32
type_
union google::protobuf::UnknownField::@35
data_
uint64
varint() const
uint32
fixed32() const
uint64
fixed64() const
const std::string &
length_delimited() const
const UnknownFieldSet &
group() const
void
set_varint(uint64 value)
void
set_fixed32(uint32 value)
void
set_fixed64(uint64 value)
void
set_length_delimited(const std::string & value)
std::string *
mutable_length_delimited()
UnknownFieldSet *
mutable_group()
void
SerializeLengthDelimitedNoTag(io::CodedOutputStream * output) const
Serialization API. more...
size_t
GetLengthDelimitedSize() const
uint8 *
InternalSerializeLengthDelimitedNoTag(uint8 * target, io::EpsCopyOutputStream * stream) const
void
Delete()
If this UnknownField contains a pointer, delete it.
void
DeepCopy(const UnknownField & other)
Make a deep copy of any pointers in this UnknownField.
void
SetType(Type type)
Set the wire type of this UnknownField. more...

enum UnknownField::Type {
  TYPE_VARINT,
  TYPE_FIXED32,
  TYPE_FIXED64,
  TYPE_LENGTH_DELIMITED,
  TYPE_GROUP
}

TYPE_VARINT
TYPE_FIXED32
TYPE_FIXED64
TYPE_LENGTH_DELIMITED
TYPE_GROUP

void UnknownField::SerializeLengthDelimitedNoTag(
        io::CodedOutputStream * output) const

Serialization API.

These methods can take advantage of the underlying implementation and may archieve a better performance than using getters to retrieve the data and do the serialization yourself.

+

class UnknownField

#include <google/protobuf/unknown_field_set.h>
namespace google::protobuf

Represents one field in an UnknownFieldSet.

Members

enum
Type
uint64
varint_
uint32
fixed32_
uint64
fixed64_
union LengthDelimited
length_delimited_
UnknownFieldSet *
group_
int
number() const
The field's field number, as seen on the wire.
Type
type() const
The field type.

Accessors

Each method works only for UnknownFields of the corresponding type.
uint32
number_
uint32
type_
union google::protobuf::UnknownField::@35
data_
uint64
varint() const
uint32
fixed32() const
uint64
fixed64() const
const std::string &
length_delimited() const
const UnknownFieldSet &
group() const
void
set_varint(uint64 value)
void
set_fixed32(uint32 value)
void
set_fixed64(uint64 value)
void
set_length_delimited(const std::string & value)
std::string *
mutable_length_delimited()
UnknownFieldSet *
mutable_group()
void
SerializeLengthDelimitedNoTag(io::CodedOutputStream * output) const
Serialization API. more...
size_t
GetLengthDelimitedSize() const
uint8 *
InternalSerializeLengthDelimitedNoTag(uint8 * target, io::EpsCopyOutputStream * stream) const
void
Delete()
If this UnknownField contains a pointer, delete it.
void
DeepCopy(const UnknownField & other)
Make a deep copy of any pointers in this UnknownField.
void
SetType(Type type)
Set the wire type of this UnknownField. more...

enum UnknownField::Type {
  TYPE_VARINT,
  TYPE_FIXED32,
  TYPE_FIXED64,
  TYPE_LENGTH_DELIMITED,
  TYPE_GROUP
}

TYPE_VARINT
TYPE_FIXED32
TYPE_FIXED64
TYPE_LENGTH_DELIMITED
TYPE_GROUP

void UnknownField::SerializeLengthDelimitedNoTag(
        io::CodedOutputStream * output) const

Serialization API.

These methods can take advantage of the underlying implementation and may achieve a better performance than using getters to retrieve the data and do the serialization yourself.

void UnknownField::SetType(
        Type type)

Set the wire type of this UnknownField.

Should only be used when this UnknownField is being created.

union UnknownField::LengthDelimited

#include <google/protobuf/unknown_field_set.h>
namespace google::protobuf

Members

std::string *
string_value
diff --git a/content/reference/cpp/api-docs/google.protobuf.util.message_differencer.md b/content/reference/cpp/api-docs/google.protobuf.util.message_differencer.md index 0ef0fbbb..7ce93b52 100644 --- a/content/reference/cpp/api-docs/google.protobuf.util.message_differencer.md +++ b/content/reference/cpp/api-docs/google.protobuf.util.message_differencer.md @@ -48,12 +48,12 @@ type = "docs"

void MessageDifferencer::TreatAsMapWithMultipleFieldPathsAsKey(
        const FieldDescriptor * field,
        const std::vector< std::vector< const FieldDescriptor * > > & key_field_paths)

Same as TreatAsMapWithMultipleFieldsAsKey, except that each of the field do not necessarily need to be a direct subfield.

Each element in key_field_paths indicate a path from the message being compared, listing successive subfield to reach the key field.

REQUIRES: 

for key_field_path in key_field_paths:
-  key_field_path[[]0]->containing_type() == field->message_type()
-  for i in [[]0, key_field_path.size() - 1):
-    key_field_path[[]i+1]->containing_type() ==
-        key_field_path[[]i]->message_type()
-    key_field_path[[]i]->cpp_type() == FieldDescriptor::CPPTYPE_MESSAGE
-    !key_field_path[[]i]->is_repeated()
+ key_field_path[0]->containing_type() == field->message_type() + for i in [0, key_field_path.size() - 1): + key_field_path[i+1]->containing_type() == + key_field_path[i]->message_type() + key_field_path[i]->cpp_type() == FieldDescriptor::CPPTYPE_MESSAGE + !key_field_path[i]->is_repeated()

void MessageDifferencer::TreatAsMapUsingKeyComparator(
        const FieldDescriptor * field,
        const MapKeyComparator * key_comparator)

Uses a custom MapKeyComparator to determine if two elements have the same key when comparing a repeated field as a map.

The caller is responsible to delete the key_comparator. This method varies from TreatAsMapWithMultipleFieldsAsKey only in the first key matching step. Rather than comparing some specified fields, it will invoke the IsMatch method of the given 'key_comparator' to decide if two elements have the same key.

void MessageDifferencer::AddIgnoreCriteria(
        IgnoreCriteria * ignore_criteria)

Add a custom ignore criteria that is evaluated in addition to the ignored fields added with IgnoreField.

Takes ownership of ignore_criteria.

void MessageDifferencer::IgnoreField(
        const FieldDescriptor * field)

Indicates that any field with the given descriptor should be ignored for the purposes of comparing two messages.

This applies to fields nested in the message structure as well as top level ones. When the MessageDifferencer encounters an ignored field, ReportIgnored is called on the reporter, if one is specified.

diff --git a/content/reference/cpp/arenas.md b/content/reference/cpp/arenas.md index 4173f22d..1c8999bd 100644 --- a/content/reference/cpp/arenas.md +++ b/content/reference/cpp/arenas.md @@ -295,10 +295,7 @@ allocation is enabled. Otherwise, accessor methods just use the ### String Fields {#arenastring} -Currently, string fields store their data on the heap even when their parent -message is on the arena. Because of this, string accessor methods use the -[default behavior](/reference/cpp/cpp-generated#string) -even when arena allocation is enabled. +String fields store their data on the heap even when their parent message is on the arena. Because of this, string accessor methods use the [default behavior](/reference/cpp/cpp-generated#string) even when arena allocation is enabled. ### Repeated Fields {#arenarepeated} diff --git a/content/reference/cpp/cpp-generated.md b/content/reference/cpp/cpp-generated.md index 0fe92d8a..b3b2a61a 100644 --- a/content/reference/cpp/cpp-generated.md +++ b/content/reference/cpp/cpp-generated.md @@ -679,22 +679,20 @@ oneof example_name { The compiler will generate the following accessor methods: -- `bool has_foo() const` (proto2 only): Returns `true` if oneof case is - `kFoo`. +- `bool has_foo() const`: Returns `true` if oneof case is `kFoo`. - `int32 foo() const`: Returns the current value of the field if oneof case is `kFoo`. Otherwise, returns the default value. - `void set_foo(int32 value)`: - If any other oneof field in the same oneof is set, calls `clear_example_name()`. - Sets the value of this field and sets the oneof case to `kFoo`. - - `has_foo()` (proto2 only) will return true, `foo()` will return `value`, - and `example_name_case()` will return `kFoo`. + - `has_foo()` will return true, `foo()` will return `value`, and + `example_name_case()` will return `kFoo`. - `void clear_foo()`: - Nothing will be changed if oneof case is not `kFoo`. - If oneof case is `kFoo`, clears the value of the field and oneof case. - `has_foo()` (proto2 only) will return `false`, `foo()` will return the - default value and `example_name_case()` will return - `EXAMPLE_NAME_NOT_SET`. + `has_foo()` will return `false`, `foo()` will return the default value + and `example_name_case()` will return `EXAMPLE_NAME_NOT_SET`. For other numeric field types (including `bool`),`int32` is replaced with the corresponding C++ type according to the @@ -790,24 +788,22 @@ oneof example_name { The compiler will generate the following accessor methods: -- `bool has_foo() const` (proto2 only): Returns `true` if oneof case is - `kFoo`. +- `bool has_foo() const`: Returns `true` if oneof case is `kFoo`. - `Bar foo() const`: Returns the current value of the field if oneof case is `kFoo`. Otherwise, returns the default value. - `void set_foo(Bar value)`: - If any other oneof field in the same oneof is set, calls `clear_example_name()`. - Sets the value of this field and sets the oneof case to `kFoo`. - - `has_foo()` (proto2 only) will return `true`, `foo()` will return - `value` and `example_name_case()` will return `kFoo`. + - `has_foo()` will return `true`, `foo()` will return `value` and + `example_name_case()` will return `kFoo`. - In debug mode (i.e. NDEBUG is not defined), if `value` does not match any of the values defined for `Bar`, this method will abort the process. - `void clear_foo()`: - Nothing will be changed if the oneof case is not `kFoo`. - If the oneof case is `kFoo`, clears the value of the field and the oneof - case. `has_foo()` (proto2 only) will return `false`, `foo()` will return - the default value and `example_name_case()` will return - `EXAMPLE_NAME_NOT_SET`. + case. `has_foo()` will return `false`, `foo()` will return the default + value and `example_name_case()` will return `EXAMPLE_NAME_NOT_SET`. ### Oneof Embedded Message Fields {#oneof-embedded} diff --git a/content/reference/csharp/api-docs/class/google/protobuf/byte-string.html b/content/reference/csharp/api-docs/class/google/protobuf/byte-string.html index 22a3aab2..afedc479 100644 --- a/content/reference/csharp/api-docs/class/google/protobuf/byte-string.html +++ b/content/reference/csharp/api-docs/class/google/protobuf/byte-string.html @@ -51,7 +51,7 @@

Properties

byte
-
Retuns the byte at the given index.
+
Returns the byte at the given index.
@@ -286,7 +286,7 @@

Length

this[int index]

byte this[int index]
-

Retuns the byte at the given index.

+

Returns the byte at the given index.

Public functions

CopyTo

diff --git a/content/reference/csharp/api-docs/class/google/protobuf/well-known-types/mixin.html b/content/reference/csharp/api-docs/class/google/protobuf/well-known-types/mixin.html index e5b9a19f..54ecb3af 100644 --- a/content/reference/csharp/api-docs/class/google/protobuf/well-known-types/mixin.html +++ b/content/reference/csharp/api-docs/class/google/protobuf/well-known-types/mixin.html @@ -31,7 +31,7 @@ - name: google.storage.v2.Storage mixins: - name: google.acl.v1.AccessControl -

The mixin construct implies that all methods in AccessControl are also declared with same name and request/response types in Storage. A documentation generator or annotation processor will see the effective Storage.GetAcl method after inherting documentation and annotations as follows: 

service Storage {
+

The mixin construct implies that all methods in AccessControl are also declared with same name and request/response types in Storage. A documentation generator or annotation processor will see the effective Storage.GetAcl method after inheriting documentation and annotations as follows: 

service Storage {
   // Get the underlying ACL object.
   rpc GetAcl(GetAclRequest) returns (Acl) {
     option (google.api.http).get = "/v2/{resource=**}:getAcl";
diff --git a/content/reference/dart/dart-generated.md b/content/reference/dart/dart-generated.md
index 2764352e..9ca38c59 100644
--- a/content/reference/dart/dart-generated.md
+++ b/content/reference/dart/dart-generated.md
@@ -421,7 +421,7 @@ extend Foo {
 
 The protocol buffer compiler will generate, in addition to the `Foo` class, a
 class `Foo_test` which will contain a `static Extension` for each extension
-field in the file along with a method for registering all the exensions in an
+field in the file along with a method for registering all the extensions in an
 `ExtensionRegistry` :
 
 -   `static final Extension bar`
diff --git a/content/reference/protobuf/google.protobuf.md b/content/reference/protobuf/google.protobuf.md
index 670d2b47..0b7f835e 100644
--- a/content/reference/protobuf/google.protobuf.md
+++ b/content/reference/protobuf/google.protobuf.md
@@ -1002,7 +1002,7 @@ apis:
 The mixin construct implies that all methods in `AccessControl` are also
 declared with same name and request/response types in `Storage`. A documentation
 generator or annotation processor will see the effective `Storage.GetAcl` method
-after inherting documentation and annotations as follows:
+after inheriting documentation and annotations as follows:
 
 ```proto
 service Storage {
diff --git a/content/reference/ruby/ruby-generated.md b/content/reference/ruby/ruby-generated.md
index 9a852952..be958a2b 100644
--- a/content/reference/ruby/ruby-generated.md
+++ b/content/reference/ruby/ruby-generated.md
@@ -56,6 +56,15 @@ message MyMessage {}
 The protocol compiler generates an output message with the name
 `FooBar::Baz::MyMessage`.
 
+However, if the `.proto` file contains the `ruby_package` option, like this:
+
+```proto
+option ruby_package = "Foo::Bar";
+```
+
+then the generated output will give precedence to the `ruby_package` option
+instead and generate `Foo::Bar::MyMessage`.
+
 ## Messages {#message}
 
 Given a simple message declaration:
diff --git a/content/support/cross-version-runtime-guarantee.md b/content/support/cross-version-runtime-guarantee.md
index 39e6ba99..9ac26e23 100644
--- a/content/support/cross-version-runtime-guarantee.md
+++ b/content/support/cross-version-runtime-guarantee.md
@@ -51,11 +51,6 @@ when a software assembly attempts to use such a configuration.
 Within a single major runtime version, generated code from an older version of
 `protoc` will run on a newer runtime.
 
-## Cross-domain {#cross-domain}
-
-Mixing Protobuf gencode and runtime across the boundary between open source and
-Google-internal will not be supported.
-
 ## Security Exception {#exception}
 
 We reserve the right to violate the above promises if needed for security