prism/util/pm_buffer.h

   1 /**
   2  * @file pm_buffer.h
   3  *
   4  * A wrapper around a contiguous block of allocated memory.
   5  */
   6 #ifndef PRISM_BUFFER_H
   7 #define PRISM_BUFFER_H
   8
   9 #include "prism/defines.h"
  10 #include "prism/util/pm_char.h"
  11
  12 #include <assert.h>
  13 #include <stdbool.h>
  14 #include <stdint.h>
  15 #include <stdlib.h>
  16 #include <string.h>
  17
  18 /**
  19  * A pm_buffer_t is a simple memory buffer that stores data in a contiguous
  20  * block of memory.
  21  */
  22 typedef struct {
  23     /** The length of the buffer in bytes. */
  24     size_t length;
  25
  26     /** The capacity of the buffer in bytes that has been allocated. */
  27     size_t capacity;
  28
  29     /** A pointer to the start of the buffer. */
  30     char *value;
  31 } pm_buffer_t;
  32
  33 /**
  34  * Return the size of the pm_buffer_t struct.
  35  *
  36  * @returns The size of the pm_buffer_t struct.
  37  */
  38 PRISM_EXPORTED_FUNCTION size_t pm_buffer_sizeof(void);
  39
  40 /**
  41  * Initialize a pm_buffer_t with the given capacity.
  42  *
  43  * @param buffer The buffer to initialize.
  44  * @param capacity The capacity of the buffer.
  45  * @returns True if the buffer was initialized successfully, false otherwise.
  46  */
  47 bool pm_buffer_init_capacity(pm_buffer_t *buffer, size_t capacity);
  48
  49 /**
  50  * Initialize a pm_buffer_t with its default values.
  51  *
  52  * @param buffer The buffer to initialize.
  53  * @returns True if the buffer was initialized successfully, false otherwise.
  54  */
  55 PRISM_EXPORTED_FUNCTION bool pm_buffer_init(pm_buffer_t *buffer);
  56
  57 /**
  58  * Return the value of the buffer.
  59  *
  60  * @param buffer The buffer to get the value of.
  61  * @returns The value of the buffer.
  62  */
  63 PRISM_EXPORTED_FUNCTION char * pm_buffer_value(const pm_buffer_t *buffer);
  64
  65 /**
  66  * Return the length of the buffer.
  67  *
  68  * @param buffer The buffer to get the length of.
  69  * @returns The length of the buffer.
  70  */
  71 PRISM_EXPORTED_FUNCTION size_t pm_buffer_length(const pm_buffer_t *buffer);
  72
  73 /**
  74  * Append the given amount of space as zeroes to the buffer.
  75  *
  76  * @param buffer The buffer to append to.
  77  * @param length The amount of space to append and zero.
  78  */
  79 void pm_buffer_append_zeroes(pm_buffer_t *buffer, size_t length);
  80
  81 /**
  82  * Append a formatted string to the buffer.
  83  *
  84  * @param buffer The buffer to append to.
  85  * @param format The format string to append.
  86  * @param ... The arguments to the format string.
  87  */
  88 void pm_buffer_append_format(pm_buffer_t *buffer, const char *format, ...) PRISM_ATTRIBUTE_FORMAT(2, 3);
  89
  90 /**
  91  * Append a string to the buffer.
  92  *
  93  * @param buffer The buffer to append to.
  94  * @param value The string to append.
  95  * @param length The length of the string to append.
  96  */
  97 void pm_buffer_append_string(pm_buffer_t *buffer, const char *value, size_t length);
  98
  99 /**
 100  * Append a list of bytes to the buffer.
 101  *
 102  * @param buffer The buffer to append to.
 103  * @param value The bytes to append.
 104  * @param length The length of the bytes to append.
 105  */
 106 void pm_buffer_append_bytes(pm_buffer_t *buffer, const uint8_t *value, size_t length);
 107
 108 /**
 109  * Append a single byte to the buffer.
 110  *
 111  * @param buffer The buffer to append to.
 112  * @param value The byte to append.
 113  */
 114 void pm_buffer_append_byte(pm_buffer_t *buffer, uint8_t value);
 115
 116 /**
 117  * Append a 32-bit unsigned integer to the buffer as a variable-length integer.