src/helper/membuf.h

   1 #ifndef HELPER_MEMBUF_H
   2 #define HELPER_MEMBUF_H
   3
   4 /** @file */
   5
   6 /** @page MEMBUF - an auto-growing string buffer
   7  *
   8  * With OpenOCD often, one must write code that sends text to
   9  * different places.. the historical command_ctx, or JIM output,
  10  * and/or other places.
  11  *
  12  * This is a simple 'string buffer' that auto-grows.
  13  *
  14  * More correctly put, this is a "memory buffer"
  15  * it may contain binary data
  16  *
  17  * Note: Internally the buffer always has a 'null terminator'
  18  */
  19
  20 /* contents of this structure are 'opaque' */
  21 struct membuf;
  22
  23
  24 /** Create a new membuf
  25  * By default the memory buffer has "some non-zero-size"
  26  * (couple hundred bytes, exact amount is opaque)
  27  */
  28 struct membuf *membuf_new(void);
  29
  30 /** delete (destroy) the mem buffer
  31  * @param pBuf - buffer to release
  32  */
  33 void membuf_delete(struct membuf *pBuf);
  34
  35
  36 /** grow/shrink a membuf by specified amount.
  37  * @param pBuf   - the buffer
  38  * @param amount - the amount to grow or shrink by.
  39  *
  40  * Symantics of 'realloc()' return NULL on failure
  41  */
  42 struct membuf *membuf_grow(struct membuf *pBuf, int amount);
  43
  44 /** how long is this buffer (memlen(), strlen())
  45  * @param pBuf - the buffer
  46  *
  47  * @returns: length of current buffer.
  48  */
  49 size_t membuf_len(struct membuf *pBuf);
  50
  51
  52 /** reset an membuf to zero length.
  53  * @param pBuf - buffer to reset
  54  *
  55  * Note this does not 'release' the memory buffer
  56  */
  57 void membuf_reset(struct membuf *pBuf);
  58
  59
  60 /** sprintf() to the string buffer
  61  * @param pBuf - buffer to capture sprintf() data into
  62  * @param fmt  - printf format
  63  *
  64  * Returns 0 on success
  65  * Returns non-zero on failure
  66  */
  67 int membuf_sprintf(struct membuf *pBuf , const char *fmt, ...);
  68
  69 /** vsprintf() to the string buffer
  70  * @param pBuf - buffer to capture sprintf() data into
  71  * @param fmt  - printf format
  72  * @param ap   - va_list for fmt
  73  *
  74  * Returns 0 on success
  75  * Returns non-zero on failure
  76  */
  77 int membuf_vsprintf(struct membuf *pBuf , const char *fmt, va_list ap);
  78
  79 /** Tokenize lines using strtok()
  80  * @param pBuf - buffer to tokenize
  81  * @param delim - delimiter parameter for strtok_r()
  82  * @param pSave - pointer to string context for tokenization
  83  *
  84  * Identical to "strtok()" - pass "pBuff = NULL" on second call
  85  *
  86  * NOTE: This call is <b > destructive</b> to the buffer.
  87  */
  88 const char *membuf_strtok(struct membuf *pBuf, const char *delim, void **pSave);
  89
  90 /** Return pointer to the memory in the buffer
  91  * @param pBuf - buffer
  92  *
  93  * NOTE: Thou shall not modify this pointer, it is <b > CONST</b>
  94  */
  95 const void *membuf_datapointer(struct membuf *pBuf);
  96
  97
  98 /** Append data to the buffer
  99  * @param pBuf  - buffer to append
 100  * @param pData - pointer to data to append
 101  * @param len   - length of data to append
 102  *
 103  * Modified symantics of "memcpy()".  On memory allocation failure
 104  * returns NULL.  On success, returns pointer to orginal membuf.
 105  */
 106 struct membuf *membuf_append(struct membuf *pBuf, const void *pData, size_t len);
 107
 108
 109 /** Append string to the buffer
 110  * @param pBuf  - buffer to append
 111  * @param str   - string to append
 112  *
 113  * Modified symantics of "strcat()".  On memory allocation failure
 114  * returns NULL.  On success, returns pointer to orginal membuf.
 115  */
 116 struct membuf *membuf_strcat(struct membuf *pBuf, const char *str);
 117
 118
 119 #endif