OLD | NEW |
1 /** | 1 /** |
2 * \file lzma/vli.h | 2 * \file lzma/vli.h |
3 * \brief Variable-length integer handling | 3 * \brief Variable-length integer handling |
4 * | 4 * |
5 * In the .xz format, most integers are encoded in a variable-length | 5 * In the .xz format, most integers are encoded in a variable-length |
6 * representation, which is sometimes called little endian base-128 encoding. | 6 * representation, which is sometimes called little endian base-128 encoding. |
7 * This saves space when smaller values are more likely than bigger values. | 7 * This saves space when smaller values are more likely than bigger values. |
8 * | 8 * |
9 * The encoding scheme encodes seven bits to every byte, using minimum | 9 * The encoding scheme encodes seven bits to every byte, using minimum |
10 * number of bytes required to represent the given value. Encodings that use | 10 * number of bytes required to represent the given value. Encodings that use |
(...skipping 11 matching lines...) Expand all Loading... |
22 * | 22 * |
23 * See ../lzma.h for information about liblzma as a whole. | 23 * See ../lzma.h for information about liblzma as a whole. |
24 */ | 24 */ |
25 | 25 |
26 #ifndef LZMA_H_INTERNAL | 26 #ifndef LZMA_H_INTERNAL |
27 # error Never include this file directly. Use <lzma.h> instead. | 27 # error Never include this file directly. Use <lzma.h> instead. |
28 #endif | 28 #endif |
29 | 29 |
30 | 30 |
31 /** | 31 /** |
32 * \brief Maximum supported value of variable-length integer | 32 * \brief Maximum supported value of a variable-length integer |
33 */ | 33 */ |
34 #define LZMA_VLI_MAX (UINT64_MAX / 2) | 34 #define LZMA_VLI_MAX (UINT64_MAX / 2) |
35 | 35 |
36 /** | 36 /** |
37 * \brief VLI value to denote that the value is unknown | 37 * \brief VLI value to denote that the value is unknown |
38 */ | 38 */ |
39 #define LZMA_VLI_UNKNOWN UINT64_MAX | 39 #define LZMA_VLI_UNKNOWN UINT64_MAX |
40 | 40 |
41 /** | 41 /** |
42 * \brief Maximum supported length of variable length integers | 42 * \brief Maximum supported encoded length of variable length integers |
43 */ | 43 */ |
44 #define LZMA_VLI_BYTES_MAX 9 | 44 #define LZMA_VLI_BYTES_MAX 9 |
45 | 45 |
46 | |
47 /** | 46 /** |
48 * \brief VLI constant suffix | 47 * \brief VLI constant suffix |
49 */ | 48 */ |
50 #define LZMA_VLI_C(n) UINT64_C(n) | 49 #define LZMA_VLI_C(n) UINT64_C(n) |
51 | 50 |
52 | 51 |
53 /** | 52 /** |
54 * \brief Variable-length integer type | 53 * \brief Variable-length integer type |
55 * | 54 * |
56 * This will always be unsigned integer. Valid VLI values are in the range | 55 * Valid VLI values are in the range [0, LZMA_VLI_MAX]. Unknown value is |
57 * [0, LZMA_VLI_MAX]. Unknown value is indicated with LZMA_VLI_UNKNOWN, | 56 * indicated with LZMA_VLI_UNKNOWN, which is the maximum value of the |
58 * which is the maximum value of the underlaying integer type. | 57 * underlaying integer type. |
59 * | 58 * |
60 * In future, even if lzma_vli is defined to be something other than uint64_t, | 59 * lzma_vli will be uint64_t for the foreseeable future. If a bigger size |
61 * it is guaranteed that 2 * LZMA_VLI_MAX will not overflow lzma_vli. | 60 * is needed in the future, it is guaranteed that 2 * LZMA_VLI_MAX will |
62 * This simplifies integer overflow detection. | 61 * not overflow lzma_vli. This simplifies integer overflow detection. |
63 */ | 62 */ |
64 typedef uint64_t lzma_vli; | 63 typedef uint64_t lzma_vli; |
65 | 64 |
66 | 65 |
67 /** | 66 /** |
68 * \brief Simple macro to validate variable-length integer | 67 * \brief Validate a variable-length integer |
69 * | 68 * |
70 * This is useful to test that application has given acceptable values | 69 * This is useful to test that application has given acceptable values |
71 * for example in the uncompressed_size and compressed_size variables. | 70 * for example in the uncompressed_size and compressed_size variables. |
72 * | 71 * |
73 * \return True if the integer is representable as VLI or if it | 72 * \return True if the integer is representable as VLI or if it |
74 * indicates unknown value. | 73 * indicates unknown value. |
75 */ | 74 */ |
76 #define lzma_vli_is_valid(vli) \ | 75 #define lzma_vli_is_valid(vli) \ |
77 ((vli) <= LZMA_VLI_MAX || (vli) == LZMA_VLI_UNKNOWN) | 76 ((vli) <= LZMA_VLI_MAX || (vli) == LZMA_VLI_UNKNOWN) |
78 | 77 |
79 | 78 |
80 /** | 79 /** |
81 * \brief Encode a variable-length integer | 80 * \brief Encode a variable-length integer |
82 * | 81 * |
83 * This function has two modes: single-call and multi-call. Single-call mode | 82 * This function has two modes: single-call and multi-call. Single-call mode |
84 * encodes the whole integer at once; it is an error if the output buffer is | 83 * encodes the whole integer at once; it is an error if the output buffer is |
85 * too small. Multi-call mode saves the position in *vli_pos, and thus it is | 84 * too small. Multi-call mode saves the position in *vli_pos, and thus it is |
86 * possible to continue encoding if the buffer becomes full before the whole | 85 * possible to continue encoding if the buffer becomes full before the whole |
87 * integer has been encoded. | 86 * integer has been encoded. |
88 * | 87 * |
89 * \param vli Integer to be encoded | 88 * \param vli Integer to be encoded |
90 * \param vli_pos How many VLI-encoded bytes have already been written | 89 * \param vli_pos How many VLI-encoded bytes have already been written |
91 * out. When starting to encode a new integer, *vli_pos | 90 * out. When starting to encode a new integer in |
92 * must be set to zero. To use single-call encoding, | 91 * multi-call mode, *vli_pos must be set to zero. |
93 * set vli_pos to NULL. | 92 * To use single-call encoding, set vli_pos to NULL. |
94 * \param out Beginning of the output buffer | 93 * \param out Beginning of the output buffer |
95 * \param out_pos The next byte will be written to out[*out_pos]. | 94 * \param out_pos The next byte will be written to out[*out_pos]. |
96 * \param out_size Size of the out buffer; the first byte into | 95 * \param out_size Size of the out buffer; the first byte into |
97 * which no data is written to is out[out_size]. | 96 * which no data is written to is out[out_size]. |
98 * | 97 * |
99 * \return Slightly different return values are used in multi-call and | 98 * \return Slightly different return values are used in multi-call and |
100 * single-call modes. | 99 * single-call modes. |
101 * | 100 * |
102 * Single-call (vli_pos == NULL): | 101 * Single-call (vli_pos == NULL): |
103 * - LZMA_OK: Integer successfully encoded. | 102 * - LZMA_OK: Integer successfully encoded. |
(...skipping 15 matching lines...) Expand all Loading... |
119 | 118 |
120 /** | 119 /** |
121 * \brief Decode a variable-length integer | 120 * \brief Decode a variable-length integer |
122 * | 121 * |
123 * Like lzma_vli_encode(), this function has single-call and multi-call modes. | 122 * Like lzma_vli_encode(), this function has single-call and multi-call modes. |
124 * | 123 * |
125 * \param vli Pointer to decoded integer. The decoder will | 124 * \param vli Pointer to decoded integer. The decoder will |
126 * initialize it to zero when *vli_pos == 0, so | 125 * initialize it to zero when *vli_pos == 0, so |
127 * application isn't required to initialize *vli. | 126 * application isn't required to initialize *vli. |
128 * \param vli_pos How many bytes have already been decoded. When | 127 * \param vli_pos How many bytes have already been decoded. When |
129 * starting to decode a new integer, *vli_pos must | 128 * starting to decode a new integer in multi-call |
130 * be initialized to zero. To use single-call decoding, | 129 * mode, *vli_pos must be initialized to zero. To |
131 * set this to NULL. | 130 * use single-call decoding, set vli_pos to NULL. |
132 * \param in Beginning of the input buffer | 131 * \param in Beginning of the input buffer |
133 * \param in_pos The next byte will be read from in[*in_pos]. | 132 * \param in_pos The next byte will be read from in[*in_pos]. |
134 * \param in_size Size of the input buffer; the first byte that | 133 * \param in_size Size of the input buffer; the first byte that |
135 * won't be read is in[in_size]. | 134 * won't be read is in[in_size]. |
136 * | 135 * |
137 * \return Slightly different return values are used in multi-call and | 136 * \return Slightly different return values are used in multi-call and |
138 * single-call modes. | 137 * single-call modes. |
139 * | 138 * |
140 * Single-call (vli_pos == NULL): | 139 * Single-call (vli_pos == NULL): |
141 * - LZMA_OK: Integer successfully decoded. | 140 * - LZMA_OK: Integer successfully decoded. |
(...skipping 16 matching lines...) Expand all Loading... |
158 | 157 |
159 | 158 |
160 /** | 159 /** |
161 * \brief Get the number of bytes required to encode a VLI | 160 * \brief Get the number of bytes required to encode a VLI |
162 * | 161 * |
163 * \return Number of bytes on success (1-9). If vli isn't valid, | 162 * \return Number of bytes on success (1-9). If vli isn't valid, |
164 * zero is returned. | 163 * zero is returned. |
165 */ | 164 */ |
166 extern LZMA_API(uint32_t) lzma_vli_size(lzma_vli vli) | 165 extern LZMA_API(uint32_t) lzma_vli_size(lzma_vli vli) |
167 lzma_nothrow lzma_attr_pure; | 166 lzma_nothrow lzma_attr_pure; |
OLD | NEW |