ucx/ucx/buffer.h

   1 /*
   2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
   3  *
   4  * Copyright 2017 Mike Becker, Olaf Wintermann All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions are met:
   8  *
   9  *   1. Redistributions of source code must retain the above copyright
  10  *      notice, this list of conditions and the following disclaimer.
  11  *
  12  *   2. Redistributions in binary form must reproduce the above copyright
  13  *      notice, this list of conditions and the following disclaimer in the
  14  *      documentation and/or other materials provided with the distribution.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  17  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  20  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  23  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  24  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  25  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  26  * POSSIBILITY OF SUCH DAMAGE.
  27  */
  28
  29 /**
  30  * @file buffer.h
  31  *
  32  * Advanced buffer implementation.
  33  *
  34  * Instances of UcxBuffer can be used to read from or to write to like one
  35  * would do with a stream. This allows the use of ucx_stream_copy() to copy
  36  * contents from one buffer to another.
  37  *
  38  * Some features for convenient use of the buffer
  39  * can be enabled. See the documentation of the macro constants for more
  40  * information.
  41  *
  42  * @author Mike Becker
  43  * @author Olaf Wintermann
  44  */
  45
  46 #ifndef UCX_BUFFER_H
  47 #define UCX_BUFFER_H
  48
  49 #include "ucx.h"
  50 #include <sys/types.h>
  51 #include <stdio.h>
  52
  53 #ifdef  __cplusplus
  54 extern "C" {
  55 #endif
  56
  57 /**
  58  * No buffer features enabled (all flags cleared).
  59  */
  60 #define UCX_BUFFER_DEFAULT      0x00
  61
  62 /**
  63  * If this flag is enabled, the buffer will automatically free its contents.
  64  */
  65 #define UCX_BUFFER_AUTOFREE     0x01
  66
  67 /**
  68  * If this flag is enabled, the buffer will automatically extends its capacity.
  69  */
  70 #define UCX_BUFFER_AUTOEXTEND   0x02
  71
  72 /** UCX Buffer. */
  73 typedef struct {
  74     /** A pointer to the buffer contents. */
  75     char *space;
  76     /** Current position of the buffer. */
  77     size_t pos;
  78     /** Current capacity (i.e. maximum size) of the buffer. */
  79     size_t capacity;
  80     /** Current size of the buffer content. */
  81     size_t size;
  82     /**
  83      * Flag register for buffer features.
  84      * @see #UCX_BUFFER_DEFAULT
  85      * @see #UCX_BUFFER_AUTOFREE
  86      * @see #UCX_BUFFER_AUTOEXTEND
  87      */
  88     int flags;
  89 } UcxBuffer;
  90
  91 /**
  92  * Creates a new buffer.
  93  *
  94  * <b>Note:</b> you may provide <code>NULL</code> as argument for
  95  * <code>space</code>. Then this function will allocate the space and enforce
  96  * the #UCX_BUFFER_AUTOFREE flag.
  97  *
  98  * @param space pointer to the memory area, or <code>NULL</code> to allocate
  99  * new memory
 100  * @param capacity the capacity of the buffer
 101  * @param flags buffer features (see UcxBuffer.flags)
 102  * @return the new buffer
 103  */
 104 UcxBuffer *ucx_buffer_new(void *space, size_t capacity, int flags);
 105
 106 /**
 107  * Destroys a buffer.
 108  *
 109  * If the #UCX_BUFFER_AUTOFREE feature is enabled, the contents of the buffer
 110  * are also freed.
 111  *
 112  * @param buffer the buffer to destroy
 113  */
 114 void ucx_buffer_free(UcxBuffer* buffer);
 115
 116 /**
 117  * Creates a new buffer and fills it with extracted content from another buffer.
 118  *
 119  * <b>Note:</b> the #UCX_BUFFER_AUTOFREE feature is enforced for the new buffer.
 120  *
 121  * @param src the source buffer
 122  * @param start the start position of extraction
 123  * @param length the count of bytes to extract (must not be zero)
 124  * @param flags feature mask for the new buffer
 125  * @return a new buffer containing the extraction
 126  */
 127 UcxBuffer* ucx_buffer_extract(UcxBuffer *src,
 128         size_t start, size_t length, int flags);
 129
 130 /**
 131  * A shorthand macro for the full extraction of the buffer.
 132  *
 133  * @param src the source buffer
 134  * @param flags feature mask for the new buffer
 135  * @return a new buffer with the extracted content
 136  */
 137 #define ucx_buffer_clone(src,flags) \
 138     ucx_buffer_extract(src, 0, (src)->capacity, flags)
 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
 201 /**
 202  * Moves the position of the buffer.
 203  *
 204  * The new position is relative to the <code>whence</code> argument.
 205  *
 206  * SEEK_SET marks the start of the buffer.
 207  * SEEK_CUR marks the current position.
 208  * SEEK_END marks the end of the buffer.
 209  *
 210  * With an offset of zero, this function sets the buffer position to zero
 211  * (SEEK_SET), the buffer size (SEEK_END) or leaves the buffer position
 212  * unchanged (SEEK_CUR).
 213  *
 214  * @param buffer
 215  * @param offset position offset relative to <code>whence</code>
 216  * @param whence one of SEEK_SET, SEEK_CUR or SEEK_END
 217  * @return 0 on success, non-zero if the position is invalid
 218  *
 219  */
 220 int ucx_buffer_seek(UcxBuffer *buffer, off_t offset, int whence);
 221
 222 /**
 223  * Clears the buffer by resetting the position and deleting the data.
 224  *
 225  * The data is deleted by a zeroing it with call to <code>memset()</code>.
 226  *
 227  * @param buffer the buffer to be cleared
 228  */
 229 #define ucx_buffer_clear(buffer) memset((buffer)->space, 0, (buffer)->size); \
 230         (buffer)->size = 0; (buffer)->pos = 0;
 231
 232 /**
 233  * Tests, if the buffer position has exceeded the buffer capacity.
 234  *
 235  * @param buffer the buffer to test
 236  * @return non-zero, if the current buffer position has exceeded the last
 237  * available byte of the buffer.
 238  */
 239 int ucx_buffer_eof(UcxBuffer *buffer);
 240
 241
 242 /**
 243  * Extends the capacity of the buffer.
 244  *
 245  * <b>Note:</b> The buffer capacity increased by a power of two. I.e.
 246  * the buffer capacity is doubled, as long as it would not hold the current
 247  * content plus the additional required bytes.
 248  *
 249  * <b>Attention:</b> the argument provided is the number of <i>additional</i>
 250  * bytes the buffer shall hold. It is <b>NOT</b> the total number of bytes the
 251  * buffer shall hold.
 252  *
 253  * @param buffer the buffer to extend
 254  * @param additional_bytes the number of additional bytes the buffer shall
 255  * <i>at least</i> hold
 256  * @return 0 on success or a non-zero value on failure
 257  */
 258 int ucx_buffer_extend(UcxBuffer *buffer, size_t additional_bytes);
 259
 260 /**
 261  * Writes data to a UcxBuffer.
 262  *
 263  * The position of the buffer is increased by the number of bytes written.
 264  *
 265  * @param ptr a pointer to the memory area containing the bytes to be written
 266  * @param size the length of one element
 267  * @param nitems the element count
 268  * @param buffer the UcxBuffer to write to
 269  * @return the total count of bytes written
 270  */
 271 size_t ucx_buffer_write(const void *ptr, size_t size, size_t nitems,
 272         UcxBuffer *buffer);
 273
 274 /**
 275  * Reads data from a UcxBuffer.
 276  *
 277  * The position of the buffer is increased by the number of bytes read.
 278  *
 279  * @param ptr a pointer to the memory area where to store the read data
 280  * @param size the length of one element
 281  * @param nitems the element count
 282  * @param buffer the UcxBuffer to read from
 283  * @return the total number of elements read
 284  */
 285 size_t ucx_buffer_read(void *ptr, size_t size, size_t nitems,
 286         UcxBuffer *buffer);
 287
 288 /**
 289  * Writes a character to a buffer.
 290  *
 291  * The least significant byte of the argument is written to the buffer. If the
 292  * end of the buffer is reached and #UCX_BUFFER_AUTOEXTEND feature is enabled,
 293  * the buffer capacity is extended by ucx_buffer_extend(). If the feature is
 294  * disabled or buffer extension fails, <code>EOF</code> is returned.
 295  *
 296  * On successful write the position of the buffer is increased.
 297  *
 298  * @param buffer the buffer to write to
 299  * @param c the character to write as <code>int</code> value
 300  * @return the byte that has bean written as <code>int</code> value or
 301  * <code>EOF</code> when the end of the stream is reached and automatic
 302  * extension is not enabled or not possible
 303  */
 304 int ucx_buffer_putc(UcxBuffer *buffer, int c);
 305
 306 /**
 307  * Gets a character from a buffer.
 308  *
 309  * The current position of the buffer is increased after a successful read.
 310  *
 311  * @param buffer the buffer to read from
 312  * @return the character as <code>int</code> value or <code>EOF</code>, if the
 313  * end of the buffer is reached
 314  */
 315 int ucx_buffer_getc(UcxBuffer *buffer);
 316
 317 /**
 318  * Writes a string to a buffer.
 319  *
 320  * @param buffer the buffer
 321  * @param str the string
 322  * @return the number of bytes written
 323  */
 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)
 333
 334 #ifdef  __cplusplus
 335 }
 336 #endif
 337
 338 #endif  /* UCX_BUFFER_H */
 339