comparison: ucx/ucx/buffer.h
ucx/ucx/buffer.h
- changeset 505
- 481802342fdf
- parent 335
- c1bc13faadaa
equal
deleted
inserted
replaced
| 504:bf3695fee719 | 505:481802342fdf |
|---|---|
| 135 * @return a new buffer with the extracted content | 135 * @return a new buffer with the extracted content |
| 136 */ | 136 */ |
| 137 #define ucx_buffer_clone(src,flags) \ | 137 #define ucx_buffer_clone(src,flags) \ |
| 138 ucx_buffer_extract(src, 0, (src)->capacity, flags) | 138 ucx_buffer_extract(src, 0, (src)->capacity, flags) |
| 139 | 139 |
| 140 | |
| 141 /** | |
| 142 * Shifts the contents of the buffer by the given offset. | |
| 143 * | |
| 144 * If the offset is positive, the contents are shifted to the right. | |
| 145 * If auto extension is enabled, the buffer grows, if necessary. | |
| 146 * In case the auto extension fails, this function returns a non-zero value and | |
| 147 * no contents are changed. | |
| 148 * If auto extension is disabled, the contents that do not fit into the buffer | |
| 149 * are discarded. | |
| 150 * | |
| 151 * If the offset is negative, the contents are shifted to the left where the | |
| 152 * first <code>shift</code> bytes are discarded. | |
| 153 * The new size of the buffer is the old size minus | |
| 154 * the absolute shift value. | |
| 155 * If this value is larger than the buffer size, the buffer is emptied (but | |
| 156 * not cleared, see the security note below). | |
| 157 * | |
| 158 * The buffer position gets shifted alongside with the content but is kept | |
| 159 * within the boundaries of the buffer. | |
| 160 * | |
| 161 * <b>Security note:</b> the shifting operation does <em>not</em> erase the | |
| 162 * previously occupied memory cells. You can easily do that manually, e.g. by | |
| 163 * calling <code>memset(buffer->space, 0, shift)</code> for a right shift or | |
| 164 * <code>memset(buffer->size, 0, buffer->capacity-buffer->size)</code> | |
| 165 * for a left shift. | |
| 166 * | |
| 167 * @param buffer the buffer | |
| 168 * @param shift the shift offset (negative means left shift) | |
| 169 * @return 0 on success, non-zero if a required auto-extension fails | |
| 170 */ | |
| 171 int ucx_buffer_shift(UcxBuffer* buffer, off_t shift); | |
| 172 | |
| 173 /** | |
| 174 * Shifts the buffer to the right. | |
| 175 * See ucx_buffer_shift() for details. | |
| 176 * | |
| 177 * @param buffer the buffer | |
| 178 * @param shift the shift offset | |
| 179 * @return 0 on success, non-zero if a required auto-extension fails | |
| 180 * @see ucx_buffer_shift() | |
| 181 */ | |
| 182 int ucx_buffer_shift_right(UcxBuffer* buffer, size_t shift); | |
| 183 | |
| 184 /** | |
| 185 * Shifts the buffer to the left. | |
| 186 * | |
| 187 * See ucx_buffer_shift() for details. Note, however, that this method expects | |
| 188 * a positive shift offset. | |
| 189 * | |
| 190 * Since a left shift cannot fail due to memory allocation problems, this | |
| 191 * function always returns zero. | |
| 192 * | |
| 193 * @param buffer the buffer | |
| 194 * @param shift the shift offset | |
| 195 * @return always zero | |
| 196 * @see ucx_buffer_shift() | |
| 197 */ | |
| 198 int ucx_buffer_shift_left(UcxBuffer* buffer, size_t shift); | |
| 199 | |
| 200 | |
| 140 /** | 201 /** |
| 141 * Moves the position of the buffer. | 202 * Moves the position of the buffer. |
| 142 * | 203 * |
| 143 * The new position is relative to the <code>whence</code> argument. | 204 * The new position is relative to the <code>whence</code> argument. |
| 144 * | 205 * |
| 163 * | 224 * |
| 164 * The data is deleted by a zeroing it with call to <code>memset()</code>. | 225 * The data is deleted by a zeroing it with call to <code>memset()</code>. |
| 165 * | 226 * |
| 166 * @param buffer the buffer to be cleared | 227 * @param buffer the buffer to be cleared |
| 167 */ | 228 */ |
| 168 #define ucx_buffer_clear(buffer) memset(buffer->space, 0, buffer->size); \ | 229 #define ucx_buffer_clear(buffer) memset((buffer)->space, 0, (buffer)->size); \ |
| 169 buffer->size = 0; buffer->pos = 0; | 230 (buffer)->size = 0; (buffer)->pos = 0; |
| 170 | 231 |
| 171 /** | 232 /** |
| 172 * Tests, if the buffer position has exceeded the buffer capacity. | 233 * Tests, if the buffer position has exceeded the buffer capacity. |
| 173 * | 234 * |
| 174 * @param buffer the buffer to test | 235 * @param buffer the buffer to test |
| 258 * | 319 * |
| 259 * @param buffer the buffer | 320 * @param buffer the buffer |
| 260 * @param str the string | 321 * @param str the string |
| 261 * @return the number of bytes written | 322 * @return the number of bytes written |
| 262 */ | 323 */ |
| 263 size_t ucx_buffer_puts(UcxBuffer *buffer, char *str); | 324 size_t ucx_buffer_puts(UcxBuffer *buffer, const char *str); |
| 325 | |
| 326 /** | |
| 327 * Returns the complete buffer content as sstr_t. | |
| 328 * @param buffer the buffer | |
| 329 * @return the result of <code>sstrn()</code> with the buffer space and size | |
| 330 * as arguments | |
| 331 */ | |
| 332 #define ucx_buffer_to_sstr(buffer) sstrn((buffer)->space, (buffer)->size) | |
| 264 | 333 |
| 265 #ifdef __cplusplus | 334 #ifdef __cplusplus |
| 266 } | 335 } |
| 267 #endif | 336 #endif |
| 268 | 337 |
