Protocol Buffer Types: Difference between revisions
(→enum) |
|||
(17 intermediate revisions by the same user not shown) | |||
Line 15: | Line 15: | ||
=Scalar Number Types= | =Scalar Number Types= | ||
==<tt>int32</tt>== | ==<span id='int32'></span><span id='sint32'></span><tt>int32</tt>, <tt>sint32</tt>== | ||
Signed integers on 32 bits (4 bytes). | |||
<syntaxhighlight lang='protobuf'> | <syntaxhighlight lang='protobuf'> | ||
int32 some_int = 1; | int32 some_int = 1; | ||
Line 21: | Line 22: | ||
The default value is 0. | The default value is 0. | ||
It allows to represent -2,147,483,648 to 2,147,483,647. | |||
<code>int32</code> does not encode negative values efficiently. <code>sint32</code> does. | |||
==<tt>uint32</tt>== | ==<tt>uint32</tt>== | ||
<code>uint32</code> allows to represent 0 to 4,294,967,295. | |||
==<tt>fixed32</tt>== | ==<tt>fixed32</tt>== | ||
==<tt>sfixed32</tt>== | ==<tt>sfixed32</tt>== | ||
==<tt>int64</tt>== | ==<span id='int64'></span><span id='sint64'></span><tt>int64</tt>, <tt>sint64</tt>== | ||
Signed integers on 64 bits (8 bytes). | |||
<syntaxhighlight lang='protobuf'> | |||
int64 some_int = 1; | |||
</syntaxhighlight> | |||
The default value is 0. | |||
It allows to represent -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807. | |||
<code>int64</code> does not encode negative values efficiently, <code>sint64</code> does. | |||
==<tt>uint64</tt>== | ==<tt>uint64</tt>== | ||
==<tt>fixed64</tt>== | ==<tt>fixed64</tt>== | ||
==<tt>sfixed64</tt>== | ==<tt>sfixed64</tt>== | ||
==<tt>float</tt>== | ==<tt>float</tt>== | ||
==<tt>double</tt>== | ==<tt>double</tt>== | ||
=<span id='byte'></span>Bytes= | =<span id='byte'></span>Bytes= | ||
<syntaxhighlight lang='protobuf'> | <syntaxhighlight lang='protobuf'> | ||
Line 52: | Line 69: | ||
The default value is the empty list. | The default value is the empty list. | ||
=<tt>map</tt>= | |||
<syntaxhighlight lang='protobuf'> | |||
message SomeMessage { | |||
int32 id = 1; | |||
map<string, Result> results = 2; | |||
} | |||
</syntaxhighlight> | |||
The keys can be scalars (except float/double) to values of any type. | |||
Map fields cannot be repeated. | |||
The order is undefined. | |||
=<span id='Enum'></span><tt>enum</tt>= | =<span id='Enum'></span><tt>enum</tt>= | ||
The <code>enum</code> must start with the tag 0. The default value is the first value. | The <code>enum</code> must start with the tag 0. The default value is the first value and it is a good practice to use that value with an "UNSPECIFIED" semantics, as shown below. | ||
<code>enum</code>s can be defined at the top level of a [[Protocol_Buffer_Concepts#.proto_Files|<code>.proto</code>]] file or they can be embedded. | <code>enum</code>s can be defined at the top level of a [[Protocol_Buffer_Concepts#.proto_Files|<code>.proto</code>]] file or they can be embedded. | ||
Line 73: | Line 103: | ||
To see what Go code is generated for an <code>enum</code>, go to: {{Internal|Protocol_Buffers_Data_Type_Go_Code_Generation#Generated_enums|Protocol Buffers Go Code Generation | <tt>enum</tt>s}} | To see what Go code is generated for an <code>enum</code>, go to: {{Internal|Protocol_Buffers_Data_Type_Go_Code_Generation#Generated_enums|Protocol Buffers Go Code Generation | <tt>enum</tt>s}} | ||
=<tt>oneof</tt>= | |||
<syntaxhighlight lang='protobuf'> | |||
message SomeMessage { | |||
int32 id = 1; | |||
oneof something { | |||
string some_string = 2; | |||
int32 some_int = 3; | |||
} | |||
} | |||
</syntaxhighlight> | |||
<code>oneof</code> fields cannot be repeated with <code>repeated</code>. | |||
<code>oneof</code> fields are complicated to evolve. | |||
=Well-Known Types= | |||
{{External|https://protobuf.dev/reference/protobuf/google.protobuf/}} | |||
Protocol Buffers contains a set of Well Known Types, in the <code>google.protobuf</code> package. | |||
<font color=darkkhaki>Understand this better, and what and when to use.</font> | |||
==<tt>Duration</tt>== | |||
{{External|https://protobuf.dev/reference/protobuf/google.protobuf/#duration}} | |||
<font color=darkkhaki>TODO</font> | |||
==<tt>Timestamp</tt>== | |||
{{External|https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp}} | |||
<font color=darkkhaki>TODO</font> | |||
=Other Common Types= | =Other Common Types= |
Latest revision as of 00:36, 11 May 2024
Internal
Overview
String
string some_string = 1;
The default value is empty string (""
). The field contains UTF-8 encoded or 7-bit ASCII text.
Boolean
bool some_bool = 1;
The default value is false
.
Scalar Number Types
int32, sint32
Signed integers on 32 bits (4 bytes).
int32 some_int = 1;
The default value is 0.
It allows to represent -2,147,483,648 to 2,147,483,647.
int32
does not encode negative values efficiently. sint32
does.
uint32
uint32
allows to represent 0 to 4,294,967,295.
fixed32
sfixed32
int64, sint64
Signed integers on 64 bits (8 bytes).
int64 some_int = 1;
The default value is 0.
It allows to represent -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807.
int64
does not encode negative values efficiently, sint64
does.
uint64
fixed64
sfixed64
float
double
Bytes
bytes some_bytes = 1;
The default value is the empty byte array.
List (Array)
Use pluralized names for repeated fields.
repeated <some_other_type> <field_name> = <tag>;
Example:
repeated int32 sizes = 1;
repeated string names = 1;
The default value is the empty list.
map
message SomeMessage {
int32 id = 1;
map<string, Result> results = 2;
}
The keys can be scalars (except float/double) to values of any type.
Map fields cannot be repeated.
The order is undefined.
enum
The enum
must start with the tag 0. The default value is the first value and it is a good practice to use that value with an "UNSPECIFIED" semantics, as shown below.
enum
s can be defined at the top level of a .proto
file or they can be embedded.
Use PascalCase (with an initial capital) for enum type names and CAPITALS_WITH_UNDERSCORES for value names. Each enum value should end with a semicolon, not a comma. Prefer prefixing enum values instead of surrounding them in an enclosing message. Since some languages don’t support an enum being defined inside a “struct” type, this ensures a consistent approach across binding languages. The zero value enum should have the suffix UNSPECIFIED, because a server or application that gets an unexpected enum value will mark the field as unset in the proto instance. The field accessor will then return the default value, which for enum fields is the first enum value.
enum FooBar {
FOO_BAR_UNSPECIFIED = 0;
FOO_BAR_FIRST_VALUE = 1;
FOO_BAR_SECOND_VALUE = 2;
}
message Something {
FooBar foo_bar = 1;
}
To see what Go code is generated for an enum
, go to:
oneof
message SomeMessage {
int32 id = 1;
oneof something {
string some_string = 2;
int32 some_int = 3;
}
}
oneof
fields cannot be repeated with repeated
.
oneof
fields are complicated to evolve.
Well-Known Types
Protocol Buffers contains a set of Well Known Types, in the google.protobuf
package.
Understand this better, and what and when to use.
Duration
TODO
Timestamp
TODO