Wyatt Hepler | f9fb90f | 2020-09-30 18:59:33 -0700 | [diff] [blame] | 1 | .. _module-pw_varint: |
Wyatt Hepler | 3c4e5de | 2020-03-03 14:37:52 -0800 | [diff] [blame] | 2 | |
| 3 | --------- |
| 4 | pw_varint |
| 5 | --------- |
Armando Montanez | 0054a9b | 2020-03-13 13:06:24 -0700 | [diff] [blame] | 6 | The ``pw_varint`` module provides functions for encoding and decoding variable |
Wyatt Hepler | 3c4e5de | 2020-03-03 14:37:52 -0800 | [diff] [blame] | 7 | length integers, or varints. For smaller values, varints require less memory |
| 8 | than a fixed-size encoding. For example, a 32-bit (4-byte) integer requires 1--5 |
| 9 | bytes when varint-encoded. |
| 10 | |
| 11 | `Protocol Buffers <https://developers.google.com/protocol-buffers/docs/encoding#varints>`_ |
| 12 | use a variable-length encoding for integers. |
| 13 | |
| 14 | Compatibility |
| 15 | ============= |
| 16 | * C |
Wyatt Hepler | 0132da5 | 2021-10-11 16:20:11 -0700 | [diff] [blame] | 17 | * C++14 (with :doc:`../pw_polyfill/docs`) |
Wyatt Hepler | 3c4e5de | 2020-03-03 14:37:52 -0800 | [diff] [blame] | 18 | |
Alexei Frolov | 388d4b9 | 2020-05-20 13:30:07 -0700 | [diff] [blame] | 19 | API |
| 20 | === |
| 21 | |
| 22 | .. cpp:function:: size_t EncodedSize(uint64_t integer) |
| 23 | |
| 24 | Returns the size of an integer when encoded as a varint. Works on both signed |
| 25 | and unsigned integers. |
| 26 | |
| 27 | .. cpp:function:: size_t ZigZagEncodedSize(int64_t integer) |
| 28 | |
| 29 | Returns the size of a signed integer when ZigZag encoded as a varint. |
| 30 | |
Alexei Frolov | 6fe8ccf | 2021-03-30 13:19:40 -0700 | [diff] [blame] | 31 | .. cpp:function:: uint64_t MaxValueInBytes(size_t bytes) |
| 32 | |
| 33 | Returns the maximum integer value that can be encoded as a varint into the |
| 34 | specified number of bytes. |
| 35 | |
Scott James Remnant | a19e285 | 2021-12-14 17:53:04 -0800 | [diff] [blame] | 36 | |
| 37 | Stream API |
| 38 | ---------- |
| 39 | |
| 40 | .. cpp:function:: StatusWithSize Read(stream::Reader& reader, int64_t* output) |
| 41 | .. cpp:function:: StatusWithSize Read(stream::Reader& reader, uint64_t* output) |
| 42 | |
| 43 | Decoders a varint from the current position of a stream. If reading into a |
| 44 | signed integer, the value is ZigZag decoded. |
| 45 | |
| 46 | Returns the number of bytes read from the stream, places the value in `output`, |
| 47 | if successful. Returns `OutOfRange` if the varint does not fit in to the type, |
| 48 | or if the input is exhausted before the number terminates. |
| 49 | |
| 50 | Reads a maximum of 10 bytes. |
| 51 | |
Wyatt Hepler | 3c4e5de | 2020-03-03 14:37:52 -0800 | [diff] [blame] | 52 | Dependencies |
| 53 | ============ |
Armando Montanez | 0054a9b | 2020-03-13 13:06:24 -0700 | [diff] [blame] | 54 | * ``pw_span`` |
Yuval Peress | b8f3ad2 | 2021-10-26 22:55:27 -0600 | [diff] [blame] | 55 | |
| 56 | Zephyr |
| 57 | ====== |
| 58 | To enable ``pw_varint`` for Zephyr add ``CONFIG_PIGWEED_VARINT=y`` to the |
| 59 | project's configuration. |