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...

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 Buffer *	mutt_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 (const struct Buffer *buf)
	Copy a Buffer's string. More...
void	mutt_buffer_seek (struct Buffer *buf, size_t offset)
	Set current read/write position to offset from beginning. 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_insert (struct Buffer *buf, size_t offset, const char *s)
	Add a string in the middle of 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...
static const char *	mutt_buffer_string (const struct Buffer *buf)
	Convert a buffer to a const char * "string". More...

Detailed Description

General purpose object for storing and parsing strings.

Authors

• Ian Zimmerman
• Richard Russon

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

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.

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

buf	Buffer to change
new_size	New size

Note

new_size will be rounded up to BufferStepSize

Definition at line 313 of file buffer.c.

{
  if (!buf)
    return;
 
  if (buf->data && (new_size <= buf->dsize))
    return;
 
  if (new_size > (SIZE_MAX - BufferStepSize))
  {
    mutt_error(_("Out of memory"));
    mutt_exit(1);
  }
 
  const bool was_empty = (buf->dptr == NULL);
  const size_t offset = (buf->dptr && buf->data) ? (buf->dptr - buf->data) : 0;
 
  buf->dsize = ROUND_UP(new_size + 1, BufferStepSize);
 
  mutt_mem_realloc(&buf->data, buf->dsize);
  mutt_buffer_seek(buf, offset);
 
  // Ensures that initially NULL buf->data is properly terminated
  if (was_empty)
  {
    buf->dptr = buf->data;
    *buf->dptr = '\0';
  }
}

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

buf	Buffer to change

Definition at line 347 of file buffer.c.

{
  if (!buf || !buf->data)
    return;
 
  buf->dptr = NULL;
  buf->dsize = 0;
  FREE(&buf->data);
}

mutt_buffer_fix_dptr()

void mutt_buffer_fix_dptr

(

struct Buffer *

buf

)

Move the dptr to end of the Buffer.

Parameters

buf	Buffer to alter

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

Definition at line 189 of file buffer.c.

{
  if (!buf)
    return;
 
  mutt_buffer_seek(buf, 0);
 
  if (buf->data && (buf->dsize > 0))
  {
    buf->data[buf->dsize - 1] = '\0';
    buf->dptr = strchr(buf->data, '\0');
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_buffer_init()

struct Buffer * mutt_buffer_init

(

struct Buffer *

buf

)

Initialise a new Buffer.

Parameters

buf	Buffer to initialise

Return values

ptr	Initialised Buffer

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

Definition at line 52 of file buffer.c.

{
  if (!buf)
    return NULL;
  memset(buf, 0, sizeof(struct Buffer));
  return buf;
}

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

buf	Buffer to inspect

Return values

true	Buffer is empty

Definition at line 298 of file buffer.c.

{
  if (!buf || !buf->data)
    return true;
 
  return (buf->data[0] == '\0');
}

mutt_buffer_len()

size_t mutt_buffer_len

(

const struct Buffer *

buf

)

Calculate the length of a Buffer.

Parameters

buf

Buffer

Return values

num	Size of buffer

Definition at line 409 of file buffer.c.

{
  if (!buf || !buf->data || !buf->dptr)
    return 0;
 
  return buf->dptr - buf->data;
}

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

size	Initial size

Return values

buf	Initialized buffer

The buffer must be released using mutt_buffer_dealloc

Definition at line 67 of file buffer.c.

{
  struct Buffer buf = { 0 };
  if (size != 0)
  {
    buf.dptr = buf.data = mutt_mem_calloc(1, size);
    buf.dsize = size;
  }
  return buf;
}

Here is the call graph for this function:

mutt_buffer_reset()

void mutt_buffer_reset

(

struct Buffer *

buf

)

Reset an existing Buffer.

Parameters

buf	Buffer to reset

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

Definition at line 85 of file buffer.c.

{
  if (!buf || !buf->data || (buf->dsize == 0))
    return;
  memset(buf->data, 0, buf->dsize);
  mutt_buffer_seek(buf, 0);
}

Here is the call graph for this function:

mutt_buffer_strdup()

char * mutt_buffer_strdup

(

const struct Buffer *

buf

)

Copy a Buffer's string.

Parameters

buf	Buffer to copy

Return values

ptr	Copy of string

Note

Caller must free the returned string

Definition at line 485 of file buffer.c.

{
  if (!buf)
    return NULL;
 
  return mutt_str_dup(buf->data);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_buffer_seek()

void mutt_buffer_seek	(	struct Buffer *	buf,
		size_t	offset
	)

Set current read/write position to offset from beginning.

Parameters

buf	Buffer to use
offset	Distance from the beginning

This is used for cases where the buffer is read from A value is placed in the buffer, and then b->dptr is set back to the beginning as a read marker instead of write marker.

Definition at line 521 of file buffer.c.

{
  if (buf)
  {
    buf->dptr = buf->data ? buf->data + offset : NULL;
  }
}

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

buf	Buffer to add to
c	Character to add

Return values

num	Bytes written to Buffer

If necessary, the Buffer will be expanded.

Definition at line 248 of file buffer.c.

{
  if (!buf)
    return 0;
  return mutt_buffer_addstr_n(buf, &c, 1);
}

Here is the call 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

buf	Buffer to add to
s	String to add

Return values

num	Bytes written to Buffer

If necessary, the Buffer will be expanded.

Definition at line 233 of file buffer.c.

{
  if (!buf || !s)
    return 0;
  return mutt_buffer_addstr_n(buf, s, mutt_str_len(s));
}

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

buf	Buffer to add to
s	String to add
len	Length of the string

Return values

num	Bytes written to Buffer
0	Error

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 105 of file buffer.c.

{
  if (!buf || !s)
    return 0;
 
  if (len > (SIZE_MAX - BufferStepSize))
  {
    mutt_error(_("Out of memory"));
    mutt_exit(1);
  }
 
  if (!buf->data || !buf->dptr || ((buf->dptr + len + 1) > (buf->data + buf->dsize)))
    mutt_buffer_alloc(buf, buf->dsize + MAX(BufferStepSize, len + 1));
 
  memcpy(buf->dptr, s, len);
  buf->dptr += len;
  *(buf->dptr) = '\0';
  return len;
}

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

buf	Buffer
fmt	printf-style format string
...	Arguments to be formatted

Return values

num	Characters written
-1	Error

Definition at line 211 of file buffer.c.

{
  if (!buf || !fmt)
    return -1;
 
  va_list ap;
 
  va_start(ap, fmt);
  int len = buffer_printf(buf, fmt, ap);
  va_end(ap);
 
  return len;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_buffer_insert()

size_t mutt_buffer_insert	(	struct Buffer *	buf,
		size_t	offset,
		const char *	s
	)

Add a string in the middle of a buffer.

Parameters

buf	Buffer
offset	Position for the insertion
s	String to insert

Return values

num	Characters written
-1	Error

Definition at line 263 of file buffer.c.

{
  if (!buf || !s || (*s == '\0'))
  {
    return -1;
  }
 
  const size_t slen = mutt_str_len(s);
  const size_t curlen = mutt_buffer_len(buf);
  mutt_buffer_alloc(buf, curlen + slen + 1);
 
  if (offset > curlen)
  {
    for (size_t i = curlen; i < offset; ++i)
    {
      mutt_buffer_addch(buf, ' ');
    }
    mutt_buffer_addstr(buf, s);
  }
  else
  {
    memmove(buf->data + offset + slen, buf->data + offset, curlen - offset);
    memcpy(buf->data + offset, s, slen);
    buf->data[curlen + slen] = '\0';
    buf->dptr = buf->data + curlen + slen;
  }
 
  return mutt_buffer_len(buf) - curlen;
}

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

buf	Buffer to add to
dir	Directory name
fname	File name

Return values

num	Bytes 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 427 of file buffer.c.

{
  if (!buf)
    return 0;
 
  if (!dir)
    dir = "";
  if (!fname)
    fname = "";
 
  const bool d_set = (dir[0] != '\0');
  const bool f_set = (fname[0] != '\0');
  if (!d_set && !f_set)
    return 0;
 
  const int d_len = strlen(dir);
  const bool slash = d_set && (dir[d_len - 1] == '/');
 
  const char *fmt = "%s/%s";
  if (!f_set || !d_set || slash)
    fmt = "%s%s";
 
  return mutt_buffer_printf(buf, fmt, dir, fname);
}

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

buf	Buffer for the result
dir	Directory name
dirlen	Directory name
fname	File name
fnamelen	File name

Return values

num	Size 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 464 of file buffer.c.

{
  size_t len = 0;
  mutt_buffer_reset(buf);
  if (dirlen != 0)
    len += mutt_buffer_addstr_n(buf, dir, dirlen);
  if ((dirlen != 0) && (fnamelen != 0))
    len += mutt_buffer_addch(buf, '/');
  if (fnamelen != 0)
    len += mutt_buffer_addstr_n(buf, fname, fnamelen);
  return len;
}

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

dst	Buffer for result
src	Buffer to copy

Return values

num	Bytes written to Buffer
0	Error

Definition at line 500 of file buffer.c.

{
  if (!dst)
    return 0;
 
  mutt_buffer_reset(dst);
  if (!src || !src->data)
    return 0;
 
  return mutt_buffer_addstr_n(dst, src->data, mutt_buffer_len(src));
}

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

buf	Buffer
fmt	printf-style format string
...	Arguments to be formatted

Return values

num	Characters written
-1	Error

Definition at line 168 of file buffer.c.

{
  if (!buf || !fmt)
    return -1;
 
  va_list ap;
 
  va_start(ap, fmt);
  mutt_buffer_reset(buf);
  int len = buffer_printf(buf, fmt, ap);
  va_end(ap);
 
  return len;
}

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

buf	Buffer to overwrite
s	String to copy

Return values

num	Bytes written to Buffer

Overwrites any existing content.

Definition at line 365 of file buffer.c.

{
  mutt_buffer_reset(buf);
  return mutt_buffer_addstr(buf, s);
}

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

buf	Buffer to overwrite
s	String to copy
len	Length of string to copy

Return values

num	Bytes written to Buffer

Overwrites any existing content.

Definition at line 380 of file buffer.c.

{
  mutt_buffer_reset(buf);
  return mutt_buffer_addstr_n(buf, s, len);
}

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

buf	Buffer to overwrite
beg	Start of string to copy
end	End of string to copy

Return values

num	Bytes written to Buffer

Overwrites any existing content.

Definition at line 395 of file buffer.c.

{
  mutt_buffer_reset(buf);
  if (end <= beg)
    return 0;
 
  return mutt_buffer_strcpy_n(buf, beg, end - beg);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_buffer_string()

static const char * mutt_buffer_string ( const struct Buffer *  buf )

inlinestatic

Convert a buffer to a const char * "string".

Parameters

buf	Buffer to that is to be converted

Return values

ptr	String inside the Buffer

This method exposes Buffer's underlying data field

Note

Returns an empty string if Buffer isn't initialised

Definition at line 78 of file buffer.h.

{
  if (!buf || !buf->data)
    return "";
 
  return buf->data;
}