Scalar Value Types
A scalar message field can have one of the following types – the table shows the type specified in the .proto file, and the corresponding type in the automatically generated class:
| .proto Type | Notes | Python Type[3] | Go Type | Ruby Type |
|---|---|---|---|---|
| double | float | float64 | Float | |
| float | float | float32 | Float | |
| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int | int32 | Fixnum or Bignum (as required) |
| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int/long[4] | int64 | Bignum |
| uint32 | Uses variable-length encoding. | int/long[4] | uint32 | Fixnum or Bignum (as required) |
| uint64 | Uses variable-length encoding. | int/long[4] | uint64 | Bignum |
| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int | int32 | Fixnum or Bignum (as required) |
| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int/long[4] | int64 | Bignum |
| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 228. | int/long[4] | uint32 | Fixnum or Bignum (as required) |
| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 256. | int/long[4] | uint64 | Bignum |
| sfixed32 | Always four bytes. | int | int32 | Fixnum or Bignum (as required) |
| sfixed64 | Always eight bytes. | int/long[4] | int64 | Bignum |
| bool | bool | bool | TrueClass/FalseClass | |
| string | A string must always contain UTF-8 encoded or 7-bit ASCII text, and cannot be longer than 232. | str/unicode[5] | string | String (UTF-8) |
| bytes | May contain any arbitrary sequence of bytes no longer than 232. | str (Python 2) bytes (Python 3) |
[]byte | String (ASCII-8BIT) |
[3] In all cases, setting values to a field will perform type checking to make sure it is valid.
[4] 64-bit or unsigned 32-bit integers are always represented as long when decoded, but can be an int if an int is given when setting the field. In all cases, the value must fit in the type represented when set. See [2].
[5] Python strings are represented as unicode on decode but can be str if an ASCII string is given (this is subject to change).
Default Values
When a message is parsed, if the encoded message does not contain a particular implicit presence element, accessing the corresponding field in the parsed object returns the default value for that field. These defaults are type-specific:
- For strings, the default value is the empty string.
- For bytes, the default value is empty bytes.
- For bools, the default value is false.
- For numeric types, the default value is zero.
- For enums, the default value is the first defined enum value, which must be 0.
- For message fields, the field is not set. Its exact value is language-dependent. See the generated code guide for details.
The default value for repeated fields is empty (generally an empty list in the appropriate language).
Note that for scalar message fields, once a message is parsed there’s no way of telling whether a field was explicitly set to the default value (for example whether a boolean was set to false) or just not set at all: you should bear this in mind when defining your message types. For example, don’t have a boolean that switches on some behavior when set to false if you don’t want that behavior to also happen by default. Also note that if a scalar message field is set to its default, the value will not be serialized on the wire. If a float or double value is set to +0 it will not be serialized, but -0 is considered distinct and will be serialized.
See the generated code guide for your chosen language for more details about how defaults work in generated code.
