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
struct Buffer *	buf_new (const char *str)
	Allocate a new Buffer.
void	buf_free (struct Buffer **ptr)
	Deallocates a buffer.
void	buf_alloc (struct Buffer *buf, size_t size)
	Make sure a buffer can store at least new_size bytes.
void	buf_dealloc (struct Buffer *buf)
	Release the memory allocated by a buffer.
void	buf_fix_dptr (struct Buffer *buf)
	Move the dptr to end of the Buffer.
struct Buffer *	buf_init (struct Buffer *buf)
	Initialise a new Buffer.
bool	buf_is_empty (const struct Buffer *buf)
	Is the Buffer empty?
size_t	buf_len (const struct Buffer *buf)
	Calculate the length of a Buffer.
struct Buffer	buf_make (size_t size)
	Make a new buffer on the stack.
void	buf_reset (struct Buffer *buf)
	Reset an existing Buffer.
char *	buf_strdup (const struct Buffer *buf)
	Copy a Buffer's string.
struct Buffer *	buf_dup (const struct Buffer *buf)
	Copy a Buffer into a new allocated buffer.
void	buf_seek (struct Buffer *buf, size_t offset)
	Set current read/write position to offset from beginning.
const char *	buf_find_string (const struct Buffer *buf, const char *s)
	Return a pointer to a substring found in the buffer.
const char *	buf_find_char (const struct Buffer *buf, const char c)
	Return a pointer to a char found in the buffer.
char	buf_at (const struct Buffer *buf, size_t offset)
	Return the character at the given offset.
bool	buf_str_equal (const struct Buffer *a, const struct Buffer *b)
	Return if two buffers are equal.
bool	buf_istr_equal (const struct Buffer *a, const struct Buffer *b)
	Return if two buffers are equal, case insensitive.
int	buf_coll (const struct Buffer *a, const struct Buffer *b)
	Collate two strings (compare using locale)
size_t	buf_startswith (const struct Buffer *buf, const char *prefix)
	Check whether a buffer starts with a prefix.
size_t	buf_addch (struct Buffer *buf, char c)
	Add a single character to a Buffer.
size_t	buf_addstr (struct Buffer *buf, const char *s)
	Add a string to a Buffer.
size_t	buf_addstr_n (struct Buffer *buf, const char *s, size_t len)
	Add a string to a Buffer, expanding it if necessary.
int	buf_add_printf (struct Buffer *buf, const char *fmt,...) __attribute__((__format__(__printf__
int size_t	buf_insert (struct Buffer *buf, size_t offset, const char *s)
	Add a string in the middle of a buffer.
size_t	buf_concat_path (struct Buffer *buf, const char *dir, const char *fname)
	Join a directory name and a filename.
size_t	buf_concatn_path (struct Buffer *dst, const char *dir, size_t dirlen, const char *fname, size_t fnamelen)
	Join a directory name and a filename.
size_t	buf_copy (struct Buffer *dst, const struct Buffer *src)
	Copy a Buffer's contents to another Buffer.
int	buf_printf (struct Buffer *buf, const char *fmt,...) __attribute__((__format__(__printf__
int size_t	buf_strcpy (struct Buffer *buf, const char *s)
	Copy a string into a Buffer.
size_t	buf_strcpy_n (struct Buffer *buf, const char *s, size_t len)
	Copy a string into a Buffer.
size_t	buf_substrcpy (struct Buffer *buf, const char *beg, const char *end)
	Copy a partial string into a Buffer.
void	buf_dequote_comment (struct Buffer *buf)
	Un-escape characters in an email address comment.
void	buf_lower (struct Buffer *buf)
	Sets a buffer to lowercase.
void	buf_upper (struct Buffer *buf)
	Sets a buffer to uppercase.
static const char *	buf_string (const struct Buffer *buf)
	Convert a buffer to a const char * "string".

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

buf_new()

struct Buffer * buf_new

(

const char *

str

)

Allocate a new Buffer.

Parameters

str	String to initialise the buffer with, can be NULL

Return values

ptr	Pointer to new buffer

Definition at line 316 of file buffer.c.

{
  struct Buffer *buf = mutt_mem_calloc(1, sizeof(struct Buffer));
 
  if (str)
    buf_addstr(buf, str);
  else
    buf_alloc(buf, 1);
  return buf;
}

Here is the call graph for this function:

Here is the caller graph for this function:

buf_free()

void buf_free

(

struct Buffer **

ptr

)

Deallocates a buffer.

Parameters

ptr	Buffer to free

Definition at line 331 of file buffer.c.

{
  if (!ptr || !*ptr)
    return;
 
  struct Buffer *buf = *ptr;
  buf_dealloc(buf);
 
  FREE(ptr);
}

Here is the call graph for this function:

Here is the caller graph for this function:

buf_alloc()

void buf_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 349 of file buffer.c.

{
  if (!buf)
    return;
 
  if (buf->data && (new_size <= buf->dsize))
  {
    // Extra sanity-checking
    if (!buf->dptr || (buf->dptr < buf->data) || (buf->dptr > (buf->data + buf->dsize)))
      buf->dptr = buf->data; // LCOV_EXCL_LINE
    return;
  }
 
  if (new_size > (SIZE_MAX - BufferStepSize))
  {
    // LCOV_EXCL_START
    mutt_error(_("Out of memory"));
    mutt_exit(1);
    // LCOV_EXCL_STOP
  }
 
  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);
  buf->dptr = buf->data + offset;
 
  // Ensures that initially NULL buf->data is properly terminated
  if (was_empty)
  {
    *buf->dptr = '\0';
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

buf_dealloc()

void buf_dealloc

(

struct Buffer *

buf

)

Release the memory allocated by a buffer.

Parameters

buf	Buffer to change

Definition at line 389 of file buffer.c.

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

Here is the caller graph for this function:

buf_fix_dptr()

void buf_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 194 of file buffer.c.

{
  if (!buf)
    return;
 
  buf_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:

buf_init()

struct Buffer * buf_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 55 of file buffer.c.

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

Here is the caller graph for this function:

buf_is_empty()

bool buf_is_empty

(

const struct Buffer *

buf

)

Is the Buffer empty?

Parameters

buf	Buffer to inspect

Return values

true	Buffer is empty

Definition at line 303 of file buffer.c.

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

buf_len()

size_t buf_len

(

const struct Buffer *

buf

)

Calculate the length of a Buffer.

Parameters

buf

Buffer

Return values

num	Size of buffer

Definition at line 466 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:

buf_make()

struct Buffer buf_make

(

size_t

size

)

Make a new buffer on the stack.

Parameters

size	Initial size

Return values

obj	Initialized buffer

The buffer must be released using buf_dealloc

Definition at line 70 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:

Here is the caller graph for this function:

buf_reset()

void buf_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 88 of file buffer.c.

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

Here is the call graph for this function:

buf_strdup()

char * buf_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 542 of file buffer.c.

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

Here is the call graph for this function:

buf_dup()

struct Buffer * buf_dup

(

const struct Buffer *

buf

)

Copy a Buffer into a new allocated buffer.

Parameters

buf	Buffer to copy

Return values

buf	New allocated copy of buffer

Note

Caller must free the returned buffer

Definition at line 557 of file buffer.c.

{
  if (!buf)
    return NULL;
 
  return buf_new(buf_string(buf));
}

Here is the call graph for this function:

Here is the caller graph for this function:

buf_seek()

void buf_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 593 of file buffer.c.

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

Here is the call graph for this function:

Here is the caller graph for this function:

buf_find_string()

const char * buf_find_string	(	const struct Buffer *	buf,
		const char *	s
	)

Return a pointer to a substring found in the buffer.

Parameters

buf	Buffer to search
s	Substring to find

Return values

NULL	substring not found
n	Pointer to the beginning of the found substring

Definition at line 608 of file buffer.c.

{
  if (!buf || !s)
    return NULL;
 
  return strstr(buf->data, s);
}

Here is the caller graph for this function:

buf_find_char()

const char * buf_find_char	(	const struct Buffer *	buf,
		const char	c
	)

Return a pointer to a char found in the buffer.

Parameters

buf	Buffer to search
c	Char to find

Return values

NULL	char not found
ptr	Pointer to the found char

Definition at line 623 of file buffer.c.

{
  if (!buf)
    return NULL;
 
  return strchr(buf->data, c);
}

Here is the caller graph for this function:

buf_at()

char buf_at	(	const struct Buffer *	buf,
		size_t	offset
	)

Return the character at the given offset.

Parameters

buf	Buffer to search
offset	Offset to get

Return values

NUL	Offset out of bounds

Returns

n The char at the offset

Definition at line 638 of file buffer.c.

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

Here is the call graph for this function:

Here is the caller graph for this function:

buf_str_equal()

bool buf_str_equal	(	const struct Buffer *	a,
		const struct Buffer *	b
	)

Return if two buffers are equal.

Parameters

a	- Buffer to compare
b	- Buffer to compare

Return values

true	Strings are equal
false	String are not equal

Definition at line 653 of file buffer.c.

{
  return mutt_str_equal(buf_string(a), buf_string(b));
}

Here is the call graph for this function:

Here is the caller graph for this function:

buf_istr_equal()

bool buf_istr_equal	(	const struct Buffer *	a,
		const struct Buffer *	b
	)

Return if two buffers are equal, case insensitive.

Parameters

a	- First buffer to compare
b	- Second buffer to compare

Return values

true	Strings are equal
false	String are not equal

Definition at line 665 of file buffer.c.

{
  return mutt_istr_equal(buf_string(a), buf_string(b));
}

Here is the call graph for this function:

Here is the caller graph for this function:

buf_coll()

int buf_coll	(	const struct Buffer *	a,
		const struct Buffer *	b
	)

Collate two strings (compare using locale)

Parameters

a	First buffer to compare
b	Second buffer to compare

Return values

<0	a precedes b
0	a and b are identical
>0	b precedes a

Definition at line 690 of file buffer.c.

{
  return mutt_str_coll(buf_string(a), buf_string(b));
}

Here is the call graph for this function:

Here is the caller graph for this function:

buf_startswith()

size_t buf_startswith	(	const struct Buffer *	buf,
		const char *	prefix
	)

Check whether a buffer starts with a prefix.

Parameters

buf	Buffer to check
prefix	Prefix to match

Return values

num	Length of prefix if str starts with prefix
0	str does not start with prefix

Definition at line 677 of file buffer.c.

{
  return mutt_str_startswith(buf_string(buf), prefix);
}

Here is the call graph for this function:

Here is the caller graph for this function:

buf_addch()

size_t buf_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 253 of file buffer.c.

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

Here is the call graph for this function:

buf_addstr()

size_t buf_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 238 of file buffer.c.

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

Here is the call graph for this function:

buf_addstr_n()

size_t buf_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 108 of file buffer.c.

{
  if (!buf || !s)
    return 0;
 
  if (len > (SIZE_MAX - BufferStepSize))
  {
    // LCOV_EXCL_START
    mutt_error(_("Out of memory"));
    mutt_exit(1);
    // LCOV_EXCL_STOP
  }
 
  if (!buf->data || !buf->dptr || ((buf->dptr + len + 1) > (buf->data + buf->dsize)))
    buf_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:

buf_add_printf()

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

buf_insert()

int size_t buf_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 268 of file buffer.c.

{
  if (!buf || !s || (*s == '\0'))
  {
    return -1;
  }
 
  const size_t slen = mutt_str_len(s);
  const size_t curlen = buf_len(buf);
  buf_alloc(buf, curlen + slen + 1);
 
  if (offset > curlen)
  {
    for (size_t i = curlen; i < offset; ++i)
    {
      buf_addch(buf, ' ');
    }
    buf_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 buf_len(buf) - curlen;
}

Here is the call graph for this function:

Here is the caller graph for this function:

buf_concat_path()

size_t buf_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 484 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 buf_printf(buf, fmt, dir, fname);
}

Here is the call graph for this function:

Here is the caller graph for this function:

buf_concatn_path()

size_t buf_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 521 of file buffer.c.

{
  size_t len = 0;
  buf_reset(buf);
  if (dirlen != 0)
    len += buf_addstr_n(buf, dir, dirlen);
  if ((dirlen != 0) && (fnamelen != 0))
    len += buf_addch(buf, '/');
  if (fnamelen != 0)
    len += buf_addstr_n(buf, fname, fnamelen);
  return len;
}

Here is the call graph for this function:

Here is the caller graph for this function:

buf_copy()

size_t buf_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 572 of file buffer.c.

{
  if (!dst)
    return 0;
 
  buf_reset(dst);
  if (!src || !src->data)
    return 0;
 
  return buf_addstr_n(dst, src->data, buf_len(src));
}

Here is the call graph for this function:

Here is the caller graph for this function:

buf_printf()

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

buf_strcpy()

int size_t buf_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 407 of file buffer.c.

{
  buf_reset(buf);
  return buf_addstr(buf, s);
}

Here is the call graph for this function:

buf_strcpy_n()

size_t buf_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 422 of file buffer.c.

{
  buf_reset(buf);
  return buf_addstr_n(buf, s, len);
}

Here is the call graph for this function:

Here is the caller graph for this function:

buf_substrcpy()

size_t buf_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 452 of file buffer.c.

{
  buf_reset(buf);
  if (end <= beg)
    return 0;
 
  return buf_strcpy_n(buf, beg, end - beg);
}

Here is the call graph for this function:

Here is the caller graph for this function:

buf_dequote_comment()

void buf_dequote_comment

(

struct Buffer *

buf

)

Un-escape characters in an email address comment.

Parameters

buf	Buffer to be un-escaped

Note

the buffer is modified

Definition at line 434 of file buffer.c.

{
  if (!buf)
    return;
 
  mutt_str_dequote_comment(buf->data);
  buf_fix_dptr(buf);
}

Here is the call graph for this function:

Here is the caller graph for this function:

buf_lower()

void buf_lower

(

struct Buffer *

buf

)

Sets a buffer to lowercase.

Parameters

[out]

buf

Buffer to transform to lowercase

Note

Modifies the buffer

Definition at line 701 of file buffer.c.

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

Here is the call graph for this function:

Here is the caller graph for this function:

buf_upper()

void buf_upper

(

struct Buffer *

buf

)

Sets a buffer to uppercase.

Parameters

[out]

buf

Buffer to transform to uppercase

Note

Modifies the buffer

Definition at line 715 of file buffer.c.

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

Here is the call graph for this function:

buf_string()

static const char * buf_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 93 of file buffer.h.

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