Mouse Melon: Software for editing Protocol Buffers data

As you can see there is plenty of choice in integer data types. After deciding what range (unsigned/signed, 32-bit/64-bit) you need for your data type, there are still some options to choose from. The difference between these options, for example between int32, sint32 and sfixed32, is only how the data is encoded. It's about saving a few bytes. You're probably not transfering Protocol Buffer messages that are gigabytes in size, so it won't really matter. But in case you're interested, here are a few pointers:

• The sint32, sint64, uint32 and uint64 types take a variable amount of space. They are encoded in such a way that values closer to zero use less bytes. These should be your default choice.
• The fixed32, fixed64, sfixed32 and sfixed64 store the data as-is. That is, using 4 or 8 bytes. These data types are efficient when your application likely uses the high bits of the integer. A typical example is when you store a hash such as CRC32, fixed32 is perfect for that.
• The int32 and int64 types store positive values the same way as uint32 and uint64. Negative values always take 10 bytes to be stored, even for int32. You could use int32/int64 as alternative to uint32/uint64 if you know you won't need the highest bit anyway. But when you need to store negative values you'll be better off with an other data type in almost all cases.

For the exact amount of storage for each encoding, see the tables at the end of this page.

It may happen that your initial choice for a data type turns out to not be the best choice. Can you still use an other data type in your proto file without losing compatibility with existing serialized data? In some cases, you can.

The following protocol buffer data types are compatible with each other:

• int32, int64, uint32, uint64
• sint32, sint64
• fixed32, sfixed32
• fixed64, sfixed64

In this context, compatible means that values that are in the supported range of both data types are encoded the same way. A few cases that you may encounter in practice:

It can happen that you chose a 32-bit data type, but later it turned out that 32 bits were not enough. You can safely make the following changes in your proto file without losing backwards compatibility with existing data:

• int32 → int64
• uint32 → uint64
• sint32 → sint64

If you make such a change, you have to keep in mind that your old software (that uses the 32-bit data type) will not read values outside of the range of the 32-bit data type correctly. The Protocol Buffers standard specifies that all the higher bits must be dropped.

Similarly, if you have an unsigned data type in your proto file, but in a later version of your software it turns out you need negative values, then you could make the following replacements:

• uint32 → int64
• uint32 → int32 (if already stored values are < 2³¹)
• fixed32 → sfixed32 (if already stored values are < 2³¹)
• uint64 → int64 (if already stored values are < 2⁶³)
• fixed64 → sfixed64 (if already stored values are < 2⁶³)

Here the same remark: Your new software will be compatible with your old data, but your old software will not be compatible with new values that are outside of the range of your old data type.

An alternative is to just make a new field, and of course planning ahead can save you a lot of trouble.

These tables give the amount of bytes it takes to store a number using a certain encoding. This is only the number itself, not including the field tag.

	uint32	fixed32
0 ≤ k < 27	1	4
27 ≤ k < 214	2	4
214 ≤ k < 221	3	4
221 ≤ k < 228	4	4
228 ≤ k < 232	5	4

	uint64	fixed64
0 ≤ k < 27	1	8
27 ≤ k < 214	2	8
214 ≤ k < 221	3	8
221 ≤ k < 228	4	8
228 ≤ k < 235	5	8
235 ≤ k < 242	6	8
242 ≤ k < 249	7	8
249 ≤ k < 256	8	8
256 ≤ k < 263	9	8
263 ≤ k < 264	10	8

	int32	sint32	sfixed32
-231 ≤ k < -227	10	5	4
-227 ≤ k < -220	10	4	4
-220 ≤ k < -213	10	3	4
-213 ≤ k < -26	10	2	4
-26 ≤ k < 0	10	1	4
0 ≤ k < 26	1	1	4
26 ≤ k < 27	1	2	4
27 ≤ k < 213	2	2	4
213 ≤ k < 214	2	3	4
214 ≤ k < 220	3	3	4
220 ≤ k < 221	3	4	4
221 ≤ k < 227	4	4	4
227 ≤ k < 228	4	5	4
228 ≤ k < 231	5	5	4

	int64	sint64	sfixed64
-263 ≤ k < -262	10	10	8
-262 ≤ k < -255	10	9	8
-255 ≤ k < -248	10	8	8
-248 ≤ k < -241	10	7	8
-241 ≤ k < -234	10	6	8
-234 ≤ k < -227	10	5	8
-227 ≤ k < -220	10	4	8
-220 ≤ k < -213	10	3	8
-213 ≤ k < -26	10	2	8
-26 ≤ k < 0	10	1	8
0 ≤ k < 26	1	1	8
26 ≤ k < 27	1	2	8
27 ≤ k < 213	2	2	8
213 ≤ k < 214	2	3	8
214 ≤ k < 220	3	3	8
220 ≤ k < 221	3	4	8
221 ≤ k < 227	4	4	8
227 ≤ k < 228	4	5	8
228 ≤ k < 234	5	5	8
234 ≤ k < 235	5	6	8
235 ≤ k < 241	6	6	8
241 ≤ k < 242	6	7	8
242 ≤ k < 248	7	7	8
248 ≤ k < 249	7	8	8
249 ≤ k < 255	8	8	8
255 ≤ k < 256	8	9	8
256 ≤ k < 262	9	9	8
262 ≤ k < 263	9	10	8