NeoMutt  2019-11-11
Teaching an old dog new tricks
DOXYGEN
buffer.h File Reference

General purpose object for storing and parsing strings. More...

#include <stddef.h>
#include <stdbool.h>
+ Include dependency graph for buffer.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  Buffer
 String manipulation buffer. More...
 

Macros

#define mutt_b2s(buf)   ((buf)->data ? (const char *) (buf)->data : "")
 
#define MoreArgs(buf)   (*(buf)->dptr && (*(buf)->dptr != ';') && (*(buf)->dptr != '#'))
 

Functions

void mutt_buffer_alloc (struct Buffer *buf, size_t size)
 Make sure a buffer can store at least new_size bytes. More...
 
void mutt_buffer_dealloc (struct Buffer *buf)
 Release the memory allocated by a buffer. More...
 
void mutt_buffer_fix_dptr (struct Buffer *buf)
 Move the dptr to end of the Buffer. More...
 
struct Buffermutt_buffer_init (struct Buffer *buf)
 Initialise a new Buffer. More...
 
bool mutt_buffer_is_empty (const struct Buffer *buf)
 Is the Buffer empty? More...
 
size_t mutt_buffer_len (const struct Buffer *buf)
 Calculate the length of a Buffer. More...
 
struct Buffer mutt_buffer_make (size_t size)
 Make a new buffer on the stack. More...
 
void mutt_buffer_reset (struct Buffer *buf)
 Reset an existing Buffer. More...
 
char * mutt_buffer_strdup (struct Buffer *buf)
 Copy a Buffer's string. More...
 
size_t mutt_buffer_addch (struct Buffer *buf, char c)
 Add a single character to a Buffer. More...
 
size_t mutt_buffer_addstr (struct Buffer *buf, const char *s)
 Add a string to a Buffer. More...
 
size_t mutt_buffer_addstr_n (struct Buffer *buf, const char *s, size_t len)
 Add a string to a Buffer, expanding it if necessary. More...
 
int mutt_buffer_add_printf (struct Buffer *buf, const char *fmt,...)
 Format a string appending a Buffer. More...
 
size_t mutt_buffer_concat_path (struct Buffer *buf, const char *dir, const char *fname)
 Join a directory name and a filename. More...
 
size_t mutt_buffer_concatn_path (struct Buffer *dst, const char *dir, size_t dirlen, const char *fname, size_t fnamelen)
 Join a directory name and a filename. More...
 
size_t mutt_buffer_copy (struct Buffer *dst, const struct Buffer *src)
 Copy a Buffer's contents to another Buffer. More...
 
int mutt_buffer_printf (struct Buffer *buf, const char *fmt,...)
 Format a string overwriting a Buffer. More...
 
size_t mutt_buffer_strcpy (struct Buffer *buf, const char *s)
 Copy a string into a Buffer. More...
 
size_t mutt_buffer_strcpy_n (struct Buffer *buf, const char *s, size_t len)
 Copy a string into a Buffer. More...
 
size_t mutt_buffer_substrcpy (struct Buffer *buf, const char *beg, const char *end)
 Copy a partial string into a Buffer. More...
 

Detailed Description

General purpose object for storing and parsing strings.

Authors
  • Ian Zimmerman
  • Richard Russon

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Definition in file buffer.h.

Macro Definition Documentation

◆ mutt_b2s

#define mutt_b2s (   buf)    ((buf)->data ? (const char *) (buf)->data : "")

Definition at line 41 of file buffer.h.

◆ MoreArgs

#define MoreArgs (   buf)    (*(buf)->dptr && (*(buf)->dptr != ';') && (*(buf)->dptr != '#'))

Definition at line 43 of file buffer.h.

Function Documentation

◆ mutt_buffer_alloc()

void mutt_buffer_alloc ( struct Buffer buf,
size_t  new_size 
)

Make sure a buffer can store at least new_size bytes.

Parameters
bufBuffer to change
new_sizeNew size

Definition at line 265 of file buffer.c.

266 {
267  if (!buf)
268  {
269  return;
270  }
271 
272  if (!buf->dptr)
273  {
274  buf->dptr = buf->data;
275  }
276 
277  if ((new_size > buf->dsize) || !buf->data)
278  {
279  size_t offset = (buf->dptr && buf->data) ? buf->dptr - buf->data : 0;
280 
281  buf->dsize = new_size;
282  mutt_mem_realloc(&buf->data, buf->dsize);
283  buf->dptr = buf->data + offset;
284  /* This ensures an initially NULL buf->data is now properly terminated. */
285  if (buf->dptr)
286  *buf->dptr = '\0';
287  }
288 }
size_t dsize
Length of data.
Definition: buffer.h:37
void mutt_mem_realloc(void *ptr, size_t size)
Resize a block of memory on the heap.
Definition: memory.c:114
char * dptr
Current read/write position.
Definition: buffer.h:36
char * data
Pointer to data.
Definition: buffer.h:35
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ mutt_buffer_dealloc()

void mutt_buffer_dealloc ( struct Buffer buf)

Release the memory allocated by a buffer.

Parameters
bufBuffer to change

Definition at line 294 of file buffer.c.

295 {
296  if (!buf || !buf->data)
297  return;
298 
299  buf->dptr = NULL;
300  buf->dsize = 0;
301  FREE(&buf->data);
302 }
size_t dsize
Length of data.
Definition: buffer.h:37
char * dptr
Current read/write position.
Definition: buffer.h:36
char * data
Pointer to data.
Definition: buffer.h:35
#define FREE(x)
Definition: memory.h:40

◆ mutt_buffer_fix_dptr()

void mutt_buffer_fix_dptr ( struct Buffer buf)

Move the dptr to end of the Buffer.

Parameters
bufBuffer to alter

Ensure buffer->dptr points to the end of the buffer.

Definition at line 181 of file buffer.c.

182 {
183  if (!buf)
184  return;
185 
186  buf->dptr = buf->data;
187 
188  if (buf->data && (buf->dsize > 0))
189  {
190  buf->data[buf->dsize - 1] = '\0';
191  buf->dptr = strchr(buf->data, '\0');
192  }
193 }
size_t dsize
Length of data.
Definition: buffer.h:37
char * dptr
Current read/write position.
Definition: buffer.h:36
char * data
Pointer to data.
Definition: buffer.h:35
+ Here is the caller graph for this function:

◆ mutt_buffer_init()

struct Buffer* mutt_buffer_init ( struct Buffer buf)

Initialise a new Buffer.

Parameters
bufBuffer to initialise
Return values
ptrInitialised Buffer

This must not be called on a Buffer that already contains data.

Definition at line 46 of file buffer.c.

47 {
48  if (!buf)
49  return NULL;
50  memset(buf, 0, sizeof(struct Buffer));
51  return buf;
52 }
String manipulation buffer.
Definition: buffer.h:33
+ Here is the caller graph for this function:

◆ mutt_buffer_is_empty()

bool mutt_buffer_is_empty ( const struct Buffer buf)

Is the Buffer empty?

Parameters
bufBuffer to inspect
Return values
trueBuffer is empty

Definition at line 252 of file buffer.c.

253 {
254  if (!buf || !buf->data)
255  return true;
256 
257  return (buf->data[0] == '\0');
258 }
char * data
Pointer to data.
Definition: buffer.h:35
+ Here is the caller graph for this function:

◆ mutt_buffer_len()

size_t mutt_buffer_len ( const struct Buffer buf)

Calculate the length of a Buffer.

Parameters
bufBuffer
Return values
numSize of buffer

Definition at line 356 of file buffer.c.

357 {
358  if (!buf || !buf->data || !buf->dptr)
359  return 0;
360 
361  return buf->dptr - buf->data;
362 }
char * dptr
Current read/write position.
Definition: buffer.h:36
char * data
Pointer to data.
Definition: buffer.h:35
+ Here is the caller graph for this function:

◆ mutt_buffer_make()

struct Buffer mutt_buffer_make ( size_t  size)

Make a new buffer on the stack.

Parameters
sizeInitial size
Return values
bufInitialized buffer

The buffer must be released using mutt_buffer_dealloc

Definition at line 61 of file buffer.c.

62 {
63  struct Buffer buf = { 0 };
64  if (size != 0)
65  {
66  buf.dptr = buf.data = mutt_mem_calloc(1, size);
67  buf.dsize = size;
68  }
69  return buf;
70 }
void * mutt_mem_calloc(size_t nmemb, size_t size)
Allocate zeroed memory on the heap.
Definition: memory.c:50
String manipulation buffer.
Definition: buffer.h:33
size_t dsize
Length of data.
Definition: buffer.h:37
char * dptr
Current read/write position.
Definition: buffer.h:36
char * data
Pointer to data.
Definition: buffer.h:35
+ Here is the call graph for this function:

◆ mutt_buffer_reset()

void mutt_buffer_reset ( struct Buffer buf)

Reset an existing Buffer.

Parameters
bufBuffer to reset

This can be called on a Buffer to reset the pointers, effectively emptying it.

Definition at line 79 of file buffer.c.

80 {
81  if (!buf || !buf->data || (buf->dsize == 0))
82  return;
83  memset(buf->data, 0, buf->dsize);
84  buf->dptr = buf->data;
85 }
size_t dsize
Length of data.
Definition: buffer.h:37
char * dptr
Current read/write position.
Definition: buffer.h:36
char * data
Pointer to data.
Definition: buffer.h:35

◆ mutt_buffer_strdup()

char* mutt_buffer_strdup ( struct Buffer buf)

Copy a Buffer's string.

Parameters
bufBuffer to copy
Return values
ptrCopy of string
Note
Caller must free the returned string

Definition at line 432 of file buffer.c.

433 {
434  if (!buf)
435  return NULL;
436 
437  return mutt_str_strdup(buf->data);
438 }
char * data
Pointer to data.
Definition: buffer.h:35
char * mutt_str_strdup(const char *str)
Copy a string, safely.
Definition: string.c:380
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ mutt_buffer_addch()

size_t mutt_buffer_addch ( struct Buffer buf,
char  c 
)

Add a single character to a Buffer.

Parameters
bufBuffer to add to
cCharacter to add
Return values
numBytes written to Buffer

If necessary, the Buffer will be expanded.

Definition at line 240 of file buffer.c.

241 {
242  if (!buf)
243  return 0;
244  return mutt_buffer_addstr_n(buf, &c, 1);
245 }
size_t mutt_buffer_addstr_n(struct Buffer *buf, const char *s, size_t len)
Add a string to a Buffer, expanding it if necessary.
Definition: buffer.c:99
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ mutt_buffer_addstr()

size_t mutt_buffer_addstr ( struct Buffer buf,
const char *  s 
)

Add a string to a Buffer.

Parameters
bufBuffer to add to
sString to add
Return values
numBytes written to Buffer

If necessary, the Buffer will be expanded.

Definition at line 225 of file buffer.c.

226 {
227  if (!buf || !s)
228  return 0;
229  return mutt_buffer_addstr_n(buf, s, mutt_str_strlen(s));
230 }
size_t mutt_str_strlen(const char *a)
Calculate the length of a string, safely.
Definition: string.c:666
size_t mutt_buffer_addstr_n(struct Buffer *buf, const char *s, size_t len)
Add a string to a Buffer, expanding it if necessary.
Definition: buffer.c:99
+ Here is the call graph for this function:

◆ mutt_buffer_addstr_n()

size_t mutt_buffer_addstr_n ( struct Buffer buf,
const char *  s,
size_t  len 
)

Add a string to a Buffer, expanding it if necessary.

Parameters
bufBuffer to add to
sString to add
lenLength of the string
Return values
numBytes written to Buffer
0Error

Dynamically grow a Buffer to accommodate s, in increments of 128 bytes. Always one byte bigger than necessary for the null terminator, and the buffer is always NUL-terminated

Definition at line 99 of file buffer.c.

100 {
101  if (!buf || !s)
102  return 0;
103 
104  if (!buf->data || !buf->dptr || ((buf->dptr + len + 1) > (buf->data + buf->dsize)))
105  mutt_buffer_alloc(buf, buf->dsize + MAX(128, len + 1));
106 
107  memcpy(buf->dptr, s, len);
108  buf->dptr += len;
109  *(buf->dptr) = '\0';
110  return len;
111 }
#define MAX(a, b)
Definition: memory.h:30
size_t dsize
Length of data.
Definition: buffer.h:37
char * dptr
Current read/write position.
Definition: buffer.h:36
char * data
Pointer to data.
Definition: buffer.h:35
void mutt_buffer_alloc(struct Buffer *buf, size_t new_size)
Make sure a buffer can store at least new_size bytes.
Definition: buffer.c:265
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ mutt_buffer_add_printf()

int mutt_buffer_add_printf ( struct Buffer buf,
const char *  fmt,
  ... 
)

Format a string appending a Buffer.

Parameters
bufBuffer
fmtprintf-style format string
...Arguments to be formatted
Return values
numCharacters written
-1Error

Definition at line 203 of file buffer.c.

204 {
205  if (!buf || !fmt)
206  return -1;
207 
208  va_list ap;
209 
210  va_start(ap, fmt);
211  int len = buffer_printf(buf, fmt, ap);
212  va_end(ap);
213 
214  return len;
215 }
static int buffer_printf(struct Buffer *buf, const char *fmt, va_list ap)
Format a string into a Buffer.
Definition: buffer.c:121
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ mutt_buffer_concat_path()

size_t mutt_buffer_concat_path ( struct Buffer buf,
const char *  dir,
const char *  fname 
)

Join a directory name and a filename.

Parameters
bufBuffer to add to
dirDirectory name
fnameFile name
Return values
numBytes written to Buffer

If both dir and fname are supplied, they are separated with '/'. If either is missing, then the other will be copied exactly.

Definition at line 374 of file buffer.c.

375 {
376  if (!buf)
377  return 0;
378 
379  if (!dir)
380  dir = "";
381  if (!fname)
382  fname = "";
383 
384  const bool d_set = (dir[0] != '\0');
385  const bool f_set = (fname[0] != '\0');
386  if (!d_set && !f_set)
387  return 0;
388 
389  const int d_len = strlen(dir);
390  const bool slash = d_set && (dir[d_len - 1] == '/');
391 
392  const char *fmt = "%s/%s";
393  if (!f_set || !d_set || slash)
394  fmt = "%s%s";
395 
396  return mutt_buffer_printf(buf, fmt, dir, fname);
397 }
int mutt_buffer_printf(struct Buffer *buf, const char *fmt,...)
Format a string overwriting a Buffer.
Definition: buffer.c:160
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ mutt_buffer_concatn_path()

size_t mutt_buffer_concatn_path ( struct Buffer buf,
const char *  dir,
size_t  dirlen,
const char *  fname,
size_t  fnamelen 
)

Join a directory name and a filename.

Parameters
bufBuffer for the result
dirDirectory name
dirlenDirectory name
fnameFile name
fnamelenFile name
Return values
numSize of buffer

If both dir and fname are supplied, they are separated with '/'. If either is missing, then the other will be copied exactly.

Definition at line 411 of file buffer.c.

413 {
414  size_t len = 0;
415  mutt_buffer_reset(buf);
416  if (dirlen != 0)
417  len += mutt_buffer_addstr_n(buf, dir, dirlen);
418  if ((dirlen != 0) && (fnamelen != 0))
419  len += mutt_buffer_addch(buf, '/');
420  if (fnamelen != 0)
421  len += mutt_buffer_addstr_n(buf, fname, fnamelen);
422  return len;
423 }
void mutt_buffer_reset(struct Buffer *buf)
Reset an existing Buffer.
Definition: buffer.c:79
size_t mutt_buffer_addstr_n(struct Buffer *buf, const char *s, size_t len)
Add a string to a Buffer, expanding it if necessary.
Definition: buffer.c:99
size_t mutt_buffer_addch(struct Buffer *buf, char c)
Add a single character to a Buffer.
Definition: buffer.c:240
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ mutt_buffer_copy()

size_t mutt_buffer_copy ( struct Buffer dst,
const struct Buffer src 
)

Copy a Buffer's contents to another Buffer.

Parameters
dstBuffer for result
srcBuffer to copy

Definition at line 445 of file buffer.c.

446 {
447  if (!dst)
448  return 0;
449 
450  mutt_buffer_reset(dst);
451  if (!src || !src->data)
452  return 0;
453 
454  return mutt_buffer_addstr_n(dst, src->data, mutt_buffer_len(src));
455 }
void mutt_buffer_reset(struct Buffer *buf)
Reset an existing Buffer.
Definition: buffer.c:79
size_t mutt_buffer_len(const struct Buffer *buf)
Calculate the length of a Buffer.
Definition: buffer.c:356
size_t mutt_buffer_addstr_n(struct Buffer *buf, const char *s, size_t len)
Add a string to a Buffer, expanding it if necessary.
Definition: buffer.c:99
char * data
Pointer to data.
Definition: buffer.h:35
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ mutt_buffer_printf()

int mutt_buffer_printf ( struct Buffer buf,
const char *  fmt,
  ... 
)

Format a string overwriting a Buffer.

Parameters
bufBuffer
fmtprintf-style format string
...Arguments to be formatted
Return values
numCharacters written
-1Error

Definition at line 160 of file buffer.c.

161 {
162  if (!buf || !fmt)
163  return -1;
164 
165  va_list ap;
166 
167  va_start(ap, fmt);
168  mutt_buffer_reset(buf);
169  int len = buffer_printf(buf, fmt, ap);
170  va_end(ap);
171 
172  return len;
173 }
void mutt_buffer_reset(struct Buffer *buf)
Reset an existing Buffer.
Definition: buffer.c:79
static int buffer_printf(struct Buffer *buf, const char *fmt, va_list ap)
Format a string into a Buffer.
Definition: buffer.c:121
+ Here is the call graph for this function:

◆ mutt_buffer_strcpy()

size_t mutt_buffer_strcpy ( struct Buffer buf,
const char *  s 
)

Copy a string into a Buffer.

Parameters
bufBuffer to overwrite
sString to copy
Return values
numBytes written to Buffer

Overwrites any existing content.

Definition at line 312 of file buffer.c.

313 {
314  mutt_buffer_reset(buf);
315  return mutt_buffer_addstr(buf, s);
316 }
void mutt_buffer_reset(struct Buffer *buf)
Reset an existing Buffer.
Definition: buffer.c:79
size_t mutt_buffer_addstr(struct Buffer *buf, const char *s)
Add a string to a Buffer.
Definition: buffer.c:225
+ Here is the call graph for this function:

◆ mutt_buffer_strcpy_n()

size_t mutt_buffer_strcpy_n ( struct Buffer buf,
const char *  s,
size_t  len 
)

Copy a string into a Buffer.

Parameters
bufBuffer to overwrite
sString to copy
lenLength of string to copy
Return values
numBytes written to Buffer

Overwrites any existing content.

Definition at line 327 of file buffer.c.

328 {
329  mutt_buffer_reset(buf);
330  return mutt_buffer_addstr_n(buf, s, len);
331 }
void mutt_buffer_reset(struct Buffer *buf)
Reset an existing Buffer.
Definition: buffer.c:79
size_t mutt_buffer_addstr_n(struct Buffer *buf, const char *s, size_t len)
Add a string to a Buffer, expanding it if necessary.
Definition: buffer.c:99
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ mutt_buffer_substrcpy()

size_t mutt_buffer_substrcpy ( struct Buffer buf,
const char *  beg,
const char *  end 
)

Copy a partial string into a Buffer.

Parameters
bufBuffer to overwrite
begStart of string to copy
endEnd of string to copy
Return values
numBytes written to Buffer

Overwrites any existing content.

Definition at line 342 of file buffer.c.

343 {
344  mutt_buffer_reset(buf);
345  if (end <= beg)
346  return 0;
347 
348  return mutt_buffer_strcpy_n(buf, beg, end - beg);
349 }
void mutt_buffer_reset(struct Buffer *buf)
Reset an existing Buffer.
Definition: buffer.c:79
size_t mutt_buffer_strcpy_n(struct Buffer *buf, const char *s, size_t len)
Copy a string into a Buffer.
Definition: buffer.c:327
+ Here is the call graph for this function:
+ Here is the caller graph for this function: