string2.h File Reference

String manipulation functions. More...

#include <ctype.h>
#include <stdbool.h>
#include <stdio.h>

Include dependency graph for string2.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	STR_COMMAND   8192
	Enough space for a long command line. More...
#define	NONULL(x)   ((x) ? (x) : "")
#define	IS_SPACE(ch)   isspace((unsigned char) ch)
#define	EMAIL_WSP   " \t\r\n"
#define	S_ERR   127
#define	S_BKG   126
#define	SKIPWS(ch)
#define	terminate_string(str, strlen, buflen)
#define	terminate_buffer(str, strlen)   terminate_string(str, strlen, sizeof(str) - 1)

Enumerations
enum	CaseSensitivity { CASE_MATCH, CASE_IGNORE }
	Should a string's case matter when matching? More...

Functions
void	mutt_str_adjust (char **p)
	Shrink-to-fit a string. More...
void	mutt_str_append_item (char **str, const char *item, char sep)
	Add string to another separated by sep. More...
int	mutt_str_asprintf (char **strp, const char *fmt,...)
int	mutt_str_atoi (const char *str, int *dst)
	Convert ASCII string to an integer. More...
int	mutt_str_atol (const char *str, long *dst)
	Convert ASCII string to a long. More...
int	mutt_str_atos (const char *str, short *dst)
	Convert ASCII string to a short. More...
int	mutt_str_atoui (const char *str, unsigned int *dst)
	Convert ASCII string to an unsigned integer. More...
int	mutt_str_atoul (const char *str, unsigned long *dst)
	Convert ASCII string to an unsigned long. More...
int	mutt_str_atoull (const char *str, unsigned long long *dst)
	Convert ASCII string to an unsigned long long. More...
void	mutt_str_dequote_comment (char *s)
	Un-escape characters in an email address comment. More...
const char *	mutt_str_find_word (const char *src)
	Find the end of a word (non-space) More...
const char *	mutt_str_getenv (const char *name)
	Get an environment variable. More...
bool	mutt_str_inline_replace (char *buf, size_t buflen, size_t xlen, const char *rstr)
	Replace the beginning of a string. More...
bool	mutt_str_is_ascii (const char *str, size_t len)
	Is a string ASCII (7-bit)? More...
bool	mutt_str_is_email_wsp (char c)
	Is this a whitespace character (for an email header) More...
size_t	mutt_str_lws_len (const char *s, size_t n)
	Measure the linear-white-space at the beginning of a string. More...
size_t	mutt_str_lws_rlen (const char *s, size_t n)
	Measure the linear-white-space at the end of a string. More...
const char *	mutt_str_next_word (const char *s)
	Find the next word in a string. More...
int	mutt_str_remall_strcasestr (char *str, const char *target)
	Remove all occurrences of substring, ignoring case. More...
void	mutt_str_remove_trailing_ws (char *s)
	Trim trailing whitespace from a string. More...
void	mutt_str_replace (char **p, const char *s)
	Replace one string with another. More...
const char *	mutt_str_rstrnstr (const char *haystack, size_t haystack_length, const char *needle)
	Find last instance of a substring. More...
char *	mutt_str_skip_email_wsp (const char *s)
	Skip over whitespace as defined by RFC5322. More...
char *	mutt_str_skip_whitespace (const char *p)
	Find the first non-whitespace character in a string. More...
int	mutt_str_strcasecmp (const char *a, const char *b)
	Compare two strings ignoring case, safely. More...
size_t	mutt_str_startswith (const char *str, const char *prefix, enum CaseSensitivity cs)
	Check whether a string starts with a prefix. More...
const char *	mutt_str_strcasestr (const char *haystack, const char *needle)
	Find a substring within a string without worrying about case. More...
char *	mutt_str_strcat (char *buf, size_t buflen, const char *s)
	Concatenate two strings. More...
const char *	mutt_str_strchrnul (const char *s, char c)
	Find first occurrence of character in string. More...
int	mutt_str_strcmp (const char *a, const char *b)
	Compare two strings, safely. More...
int	mutt_str_strcoll (const char *a, const char *b)
	Collate two strings (compare using locale), safely. More...
char *	mutt_str_strdup (const char *str)
	Copy a string, safely. More...
size_t	mutt_str_strfcpy (char *dest, const char *src, size_t dsize)
	Copy a string into a buffer (guaranteeing NUL-termination) More...
const char *	mutt_str_stristr (const char *haystack, const char *needle)
	Find first occurrence of string (ignoring case) More...
size_t	mutt_str_strlen (const char *a)
	Calculate the length of a string, safely. More...
char *	mutt_str_strlower (char *s)
	convert all characters in the string to lowercase More...
int	mutt_str_strncasecmp (const char *a, const char *b, size_t l)
	Compare two strings ignoring case (to a maximum), safely. More...
char *	mutt_str_strncat (char *d, size_t l, const char *s, size_t sl)
	Concatenate two strings. More...
int	mutt_str_strncmp (const char *a, const char *b, size_t l)
	Compare two strings (to a maximum), safely. More...
size_t	mutt_str_strnfcpy (char *dest, const char *src, size_t n, size_t dsize)
	Copy a limited string into a buffer (guaranteeing NUL-termination) More...
char *	mutt_str_substr_copy (const char *begin, const char *end, char *buf, size_t buflen)
	Copy a sub-string into a buffer. More...
char *	mutt_str_substr_dup (const char *begin, const char *end)
	Duplicate a sub-string. More...
const char *	mutt_str_sysexit (int e)
	Return a string matching an error code. More...
int	mutt_str_word_casecmp (const char *a, const char *b)
	Find word a in word list b. More...

Detailed Description

String manipulation functions.

Authors

• Richard Russon
• Pietro Cerutti

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

Macro Definition Documentation

STR_COMMAND

#define STR_COMMAND   8192

Enough space for a long command line.

Definition at line 35 of file string2.h.

NONULL

#define NONULL

(

x

)

((x) ? (x) : "")

Definition at line 37 of file string2.h.

IS_SPACE

#define IS_SPACE

(

ch

)

isspace((unsigned char) ch)

Definition at line 38 of file string2.h.

EMAIL_WSP

#define EMAIL_WSP   " \t\r\n"

Definition at line 39 of file string2.h.

S_ERR

#define S_ERR   127

Definition at line 42 of file string2.h.

S_BKG

#define S_BKG   126

Definition at line 43 of file string2.h.

SKIPWS

#define SKIPWS

(

ch

)

Value:

while (*(ch) && isspace((unsigned char) *(ch)))                              \
    ch++;

Definition at line 47 of file string2.h.

terminate_string

#define terminate_string	(		str,
			strlen,
			buflen
	)

Value:

do                                                                           \
  {                                                                            \
    if ((strlen) < (buflen))                                                   \
      str[(strlen)] = '\0';                                                    \
    else                                                                       \
      str[(buflen)] = '\0';                                                    \
  } while (false)

Definition at line 51 of file string2.h.

terminate_buffer

#define terminate_buffer	(		str,
			strlen
	)		terminate_string(str, strlen, sizeof(str) - 1)

Definition at line 60 of file string2.h.

Enumeration Type Documentation

CaseSensitivity

enum CaseSensitivity

Should a string's case matter when matching?

Enumerator
CASE_MATCH	Match case when comparing strings.
CASE_IGNORE	Ignore case when comparing strings.

Definition at line 65 of file string2.h.

{
  CASE_MATCH,  
  CASE_IGNORE, 
};

Function Documentation

mutt_str_adjust()

void mutt_str_adjust

(

char **

p

)

Shrink-to-fit a string.

Parameters

[out]

p

String to alter

Take a string which is allocated on the heap, find its length and reallocate the memory to be exactly the right size.

This function alters the pointer of the caller.

Definition at line 495 of file string.c.

{
  if (!p || !*p)
    return;
  mutt_mem_realloc(p, strlen(*p) + 1);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_str_append_item()

void mutt_str_append_item	(	char **	str,
		const char *	item,
		char	sep
	)

Add string to another separated by sep.

Parameters

[out]	str	String appended
[in]	item	String to append
[in]	sep	separator between string item

Append a string to another, separating them by sep if needed.

This function alters the pointer of the caller.

Definition at line 471 of file string.c.

{
  if (!str || !item)
    return;

  size_t sz = mutt_str_strlen(item);
  size_t ssz = mutt_str_strlen(*str);

  mutt_mem_realloc(str, ssz + (((ssz > 0) && (sep != '\0')) ? 1 : 0) + sz + 1);
  char *p = *str + ssz;
  if ((ssz > 0) && (sep != '\0'))
    *p++ = sep;
  memcpy(p, item, sz + 1);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_str_asprintf()

int mutt_str_asprintf	(	char **	strp,
		const char *	fmt,
			...
	)

Definition at line 1195 of file string.c.

{
  if (!strp || !fmt)
    return -1;

  int rlen = 256;

  *strp = mutt_mem_malloc(rlen);
  while (true)
  {
    va_list ap;
    va_start(ap, fmt);
    const int n = vsnprintf(*strp, rlen, fmt, ap);
    va_end(ap);
    if (n < 0)
    {
      FREE(strp);
      return n;
    }

    if (n < rlen)
    {
      /* reduce space to just that which was used.  note that 'n' does not
       * include the terminal nul char.  */
      if (n == 0) /* convention is to use NULL for zero-length strings. */
        FREE(strp);
      else if (n != rlen - 1)
        mutt_mem_realloc(strp, n + 1);
      return n;
    }
    /* increase size and try again */
    rlen = n + 1;
    mutt_mem_realloc(strp, rlen);
  }
  /* not reached */
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_str_atoi()

int mutt_str_atoi	(	const char *	str,
		int *	dst
	)

Convert ASCII string to an integer.

Parameters

[in]	str	String to read
[out]	dst	Store the result

Return values

0	Success
-1	Error
-2	Error, overflow

This is a strtol() wrapper with range checking. If dst is NULL, the string will be tested only (without conversion). errno may be set on error, e.g. ERANGE

Definition at line 262 of file string.c.

{
  if (dst)
    *dst = 0;

  long res = 0;
  int rc = mutt_str_atol(str, &res);
  if (rc < 0)
    return rc;
  if ((res < INT_MIN) || (res > INT_MAX))
    return -2;

  if (dst)
    *dst = (int) res;

  return 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_str_atol()

int mutt_str_atol	(	const char *	str,
		long *	dst
	)

Convert ASCII string to a long.

Parameters

[in]	str	String to read
[out]	dst	Store the result

Return values

0	Success
-1	Error
-2	Overflow

This is a strtol() wrapper with range checking. errno may be set on error, e.g. ERANGE

Definition at line 198 of file string.c.

{
  if (dst)
    *dst = 0;

  if (!str || !*str) /* no input: 0 */
    return 0;

  char *e = NULL;
  errno = 0;

  long res = strtol(str, &e, 10);
  if (dst)
    *dst = res;
  if (((res == LONG_MIN) || (res == LONG_MAX)) && (errno == ERANGE))
    return -2;
  if (e && (*e != '\0'))
    return -1;
  return 0;
}

Here is the caller graph for this function:

mutt_str_atos()

int mutt_str_atos	(	const char *	str,
		short *	dst
	)

Convert ASCII string to a short.

Parameters

[in]	str	String to read
[out]	dst	Store the result

Return values

0	Success
-1	Error
-2	Error, overflow

This is a strtol() wrapper with range checking. If dst is NULL, the string will be tested only (without conversion).

errno may be set on error, e.g. ERANGE

Definition at line 232 of file string.c.

{
  if (dst)
    *dst = 0;

  long res = 0;
  int rc = mutt_str_atol(str, &res);
  if (rc < 0)
    return rc;
  if ((res < SHRT_MIN) || (res > SHRT_MAX))
    return -2;

  if (dst)
    *dst = (short) res;

  return 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_str_atoui()

int mutt_str_atoui	(	const char *	str,
		unsigned int *	dst
	)

Convert ASCII string to an unsigned integer.

Parameters

[in]	str	String to read
[out]	dst	Store the result

Return values

1	Successful conversion, with trailing characters
0	Successful conversion
-1	Invalid input
-2	Input out of range

Note

This function's return value differs from the other functions. They return -1 if there is input beyond the number.

Definition at line 292 of file string.c.

{
  if (dst)
    *dst = 0;

  unsigned long res = 0;
  int rc = mutt_str_atoul(str, &res);
  if (rc < 0)
    return rc;
  if (res > UINT_MAX)
    return -2;

  if (dst)
    *dst = (unsigned int) res;

  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_str_atoul()

int mutt_str_atoul	(	const char *	str,
		unsigned long *	dst
	)

Convert ASCII string to an unsigned long.

Parameters

[in]	str	String to read
[out]	dst	Store the result

Return values

1	Successful conversion, with trailing characters
0	Successful conversion
-1	Invalid input

Note

This function's return value differs from the other functions. They return -1 if there is input beyond the number.

Definition at line 321 of file string.c.

{
  if (dst)
    *dst = 0;

  if (!str || !*str) /* no input: 0 */
    return 0;

  char *e = NULL;
  errno = 0;

  unsigned long res = strtoul(str, &e, 10);
  if (dst)
    *dst = res;
  if ((res == ULONG_MAX) && (errno == ERANGE))
    return -1;
  if (e && (*e != '\0'))
    return 1;
  return 0;
}

Here is the caller graph for this function:

mutt_str_atoull()

int mutt_str_atoull	(	const char *	str,
		unsigned long long *	dst
	)

Convert ASCII string to an unsigned long long.

Parameters

[in]	str	String to read
[out]	dst	Store the result

Return values

1	Successful conversion, with trailing characters
0	Successful conversion
-1	Invalid input

Note

This function's return value differs from the other functions. They return -1 if there is input beyond the number.

Definition at line 353 of file string.c.

{
  if (dst)
    *dst = 0;

  if (!str || !*str) /* no input: 0 */
    return 0;

  char *e = NULL;
  errno = 0;

  unsigned long long res = strtoull(str, &e, 10);
  if (dst)
    *dst = res;
  if ((res == ULLONG_MAX) && (errno == ERANGE))
    return -1;
  if (e && (*e != '\0'))
    return 1;
  return 0;
}

Here is the caller graph for this function:

mutt_str_dequote_comment()

void mutt_str_dequote_comment

(

char *

s

)

Un-escape characters in an email address comment.

Parameters

s	String to be un-escaped

Note

The string is changed in-place

Definition at line 881 of file string.c.

{
  if (!s)
    return;

  char *w = s;

  for (; *s; s++)
  {
    if (*s == '\\')
    {
      if (!*++s)
        break; /* error? */
      *w++ = *s;
    }
    else if (*s != '\"')
    {
      if (w != s)
        *w = *s;
      w++;
    }
  }
  *w = '\0';
}

Here is the caller graph for this function:

mutt_str_find_word()

const char* mutt_str_find_word

(

const char *

src

)

Find the end of a word (non-space)

Parameters

src	String to search

Return values

ptr	End of the word

Skip to the end of the current word. Skip past any whitespace characters.

Note

If there aren't any more words, this will return a pointer to the final NUL character.

Definition at line 1029 of file string.c.

{
  if (!src)
    return NULL;

  while (*src && strchr(" \t\n", *src))
    src++;
  while (*src && !strchr(" \t\n", *src))
    src++;
  return src;
}

Here is the caller graph for this function:

mutt_str_getenv()

const char* mutt_str_getenv

(

const char *

name

)

Get an environment variable.

Parameters

name	Environment variable to get

Return values

ptr	Value of variable
NULL	Variable isn't set, or is empty

Warning

The caller must not free the returned pointer.

Definition at line 1049 of file string.c.

{
  if (!name)
    return NULL;

  const char *val = getenv(name);
  if (val && (val[0] != '\0'))
    return val;

  return NULL;
}

Here is the caller graph for this function:

mutt_str_inline_replace()

bool mutt_str_inline_replace	(	char *	buf,
		size_t	buflen,
		size_t	xlen,
		const char *	rstr
	)

Replace the beginning of a string.

Parameters

buf	Buffer to modify
buflen	Length of buffer
xlen	Length of string to overwrite
rstr	Replacement string

Return values

true

Success

String (XX<OOOOOO>......, 16, 2, RRRR) becomes RRRR<OOOOOO>....

Definition at line 1071 of file string.c.

{
  if (!buf || !rstr || (xlen >= buflen))
    return false;

  size_t slen = mutt_str_strlen(buf + xlen);
  size_t rlen = mutt_str_strlen(rstr);

  if ((slen + rlen) >= buflen)
    return false;

  memmove(buf + rlen, buf + xlen, slen + 1);
  memmove(buf, rstr, rlen);

  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_str_is_ascii()

bool mutt_str_is_ascii	(	const char *	str,
		size_t	len
	)

Is a string ASCII (7-bit)?

Parameters

str	String to examine
len	Length of string to examine

Return values

true	There are no 8-bit chars

Definition at line 1006 of file string.c.

{
  if (!str)
    return true;

  for (; (*str != '\0') && (len > 0); str++, len--)
    if ((*str & 0x80) != 0)
      return false;

  return true;
}

Here is the caller graph for this function:

mutt_str_is_email_wsp()

bool mutt_str_is_email_wsp

(

char

c

)

Is this a whitespace character (for an email header)

Parameters

c	Character to test

Return values

true	It is whitespcae

Definition at line 788 of file string.c.

{
  return c && (strchr(EMAIL_WSP, c));
}

Here is the caller graph for this function:

mutt_str_lws_len()

size_t mutt_str_lws_len	(	const char *	s,
		size_t	n
	)

Measure the linear-white-space at the beginning of a string.

Parameters

s	String to check
n	Maximum number of characters to check

Return values

num	Count of whitespace characters

Count the number of whitespace characters at the beginning of a string. They can be <space>, <tab>, <cr> or <lf>.

Definition at line 815 of file string.c.

{
  if (!s)
    return 0;

  const char *p = s;
  size_t len = n;

  if (n == 0)
    return 0;

  for (; p < (s + n); p++)
  {
    if (!strchr(" \t\r\n", *p))
    {
      len = p - s;
      break;
    }
  }

  if ((len != 0) && strchr("\r\n", *(p - 1))) /* LWS doesn't end with CRLF */
    len = 0;
  return len;
}

Here is the caller graph for this function:

mutt_str_lws_rlen()

size_t mutt_str_lws_rlen	(	const char *	s,
		size_t	n
	)

Measure the linear-white-space at the end of a string.

Parameters

s	String to check
n	Maximum number of characters to check

Return values

num	Count of whitespace characters

Count the number of whitespace characters at the end of a string. They can be <space>, <tab>, <cr> or <lf>.

Definition at line 849 of file string.c.

{
  if (!s)
    return 0;

  const char *p = s + n - 1;
  size_t len = n;

  if (n == 0)
    return 0;

  if (strchr("\r\n", *p)) /* LWS doesn't end with CRLF */
    return 0;

  for (; p >= s; p--)
  {
    if (!strchr(" \t\r\n", *p))
    {
      len = s + n - 1 - p;
      break;
    }
  }

  return len;
}

Here is the caller graph for this function:

mutt_str_next_word()

const char* mutt_str_next_word

(

const char *

s

)

Find the next word in a string.

Parameters

s	String to examine

Return values

ptr

Next word

If the s is pointing to a word (non-space) is is skipped over. Then, any whitespace is skipped over.

Note

What is/isn't a word is determined by isspace()

Definition at line 916 of file string.c.

{
  if (!s)
    return NULL;

  while (*s && !IS_SPACE(*s))
    s++;
  SKIPWS(s);
  return s;
}

Here is the caller graph for this function:

mutt_str_remall_strcasestr()

int mutt_str_remall_strcasestr	(	char *	str,
		const char *	target
	)

Remove all occurrences of substring, ignoring case.

Parameters

str	String containing the substring
target	Target substring for removal

Return values

0	String contained substring and substring was removed successfully
1	String did not contain substring

Definition at line 1095 of file string.c.

{
  int rc = 1;

  // Look through an ensure all instances of the substring are gone.
  while ((str = (char *) mutt_str_strcasestr(str, target)))
  {
    size_t target_len = mutt_str_strlen(target);
    memmove(str, str + target_len, 1 + strlen(str + target_len));
    rc = 0; // If we got here, then a substring existed and has been removed.
  }

  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_str_remove_trailing_ws()

void mutt_str_remove_trailing_ws

(

char *

s

)

Trim trailing whitespace from a string.

Parameters

s	String to trim

The string is modified in place.

Definition at line 734 of file string.c.

{
  if (!s)
    return;

  for (char *p = s + mutt_str_strlen(s) - 1; (p >= s) && IS_SPACE(*p); p--)
    *p = '\0';
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_str_replace()

void mutt_str_replace	(	char **	p,
		const char *	s
	)

Replace one string with another.

Parameters

[out]	p	String to replace
[in]	s	New string

This function free()s the original string, strdup()s the new string and overwrites the pointer to the first string.

This function alters the pointer of the caller.

Definition at line 453 of file string.c.

{
  if (!p)
    return;
  FREE(p);
  *p = mutt_str_strdup(s);
}

Here is the call graph for this function:

mutt_str_rstrnstr()

const char* mutt_str_rstrnstr	(	const char *	haystack,
		size_t	haystack_length,
		const char *	needle
	)

Find last instance of a substring.

Parameters

haystack	String to search through
haystack_length	Length of the string
needle	String to find

Return values

NULL	String not found
ptr	Location of string

Return the last instance of needle in the haystack, or NULL. Like strstr(), only backwards, and for a limited haystack length.

Definition at line 938 of file string.c.

{
  if (!haystack || (haystack_length == 0) || !needle)
    return NULL;

  int needle_length = strlen(needle);
  const char *haystack_end = haystack + haystack_length - needle_length;

  for (const char *p = haystack_end; p >= haystack; --p)
  {
    for (size_t i = 0; i < needle_length; i++)
    {
      if (p[i] != needle[i])
        goto next;
    }
    return p;

  next:;
  }
  return NULL;
}

Here is the caller graph for this function:

mutt_str_skip_email_wsp()

char* mutt_str_skip_email_wsp

(

const char *

s

)

Skip over whitespace as defined by RFC5322.

Parameters

s	String to search

Return values

ptr	First non-whitespace character
ptr	Terminating NUL character, if the string was entirely whitespace

This is used primarily for parsing header fields.

Definition at line 776 of file string.c.

{
  if (!s)
    return NULL;
  return (char *) (s + strspn(s, EMAIL_WSP));
}

Here is the caller graph for this function:

mutt_str_skip_whitespace()

char* mutt_str_skip_whitespace

(

const char *

p

)

Find the first non-whitespace character in a string.

Parameters

p	String to search

Return values

ptr	First non-whitespace character
ptr	Terminating NUL character, if the string was entirely whitespace

Definition at line 720 of file string.c.

{
  if (!p)
    return NULL;
  SKIPWS(p);
  return (char *) p;
}

Here is the caller graph for this function:

mutt_str_strcasecmp()

int mutt_str_strcasecmp	(	const char *	a,
		const char *	b
	)

Compare two strings ignoring case, safely.

Parameters

a	First string to compare
b	Second string to compare

Return values

-1	a precedes b
0	a and b are identical
1	b precedes a

Definition at line 628 of file string.c.

{
  return strcasecmp(NONULL(a), NONULL(b));
}

mutt_str_startswith()

size_t mutt_str_startswith	(	const char *	str,
		const char *	prefix,
		enum CaseSensitivity	cs
	)

Check whether a string starts with a prefix.

Parameters

str	String to check
prefix	Prefix to match
cs	Case sensitivity setting

Return values

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

Definition at line 168 of file string.c.

{
  if (!str || (str[0] == '\0') || !prefix || (prefix[0] == '\0'))
  {
    return 0;
  }

  const char *saved_prefix = prefix;
  for (char_cmp fn = get_char_cmp(cs); *str && *prefix; str++, prefix++)
  {
    if (!fn(*str, *prefix))
    {
      return 0;
    }
  }

  return (!*prefix) ? prefix - saved_prefix : 0;
}

Here is the call graph for this function:

mutt_str_strcasestr()

const char* mutt_str_strcasestr	(	const char *	haystack,
		const char *	needle
	)

Find a substring within a string without worrying about case.

Parameters

haystack	String that may or may not contain the substring
needle	Substring we're looking for

Return values

ptr	Beginning of substring
NULL	Substring is not in substring

This performs a byte-to-byte check so it will return unspecified results for multibyte locales.

Definition at line 1120 of file string.c.

{
  if (!needle)
    return NULL;

  size_t haystack_len = mutt_str_strlen(haystack);
  size_t needle_len = mutt_str_strlen(needle);

  // Empty string exists at the front of a string. Check strstr if you don't believe me.
  if (needle_len == 0)
    return haystack;

  // Check size conditions. No point wasting CPU cycles.
  if ((haystack_len == 0) || (haystack_len < needle_len))
    return NULL;

  // Only check space that needle could fit in.
  // Conditional has + 1 to handle when the haystack and needle are the same length.
  for (size_t i = 0; i < (haystack_len - needle_len) + 1; i++)
  {
    for (size_t j = 0; j < needle_len; j++)
    {
      if (tolower((unsigned char) haystack[i + j]) != tolower((unsigned char) needle[j]))
        break;

      // If this statement is true, the needle has been found.
      if (j == (needle_len - 1))
        return haystack + i;
    }
  }

  return NULL;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_str_strcat()

char* mutt_str_strcat	(	char *	buf,
		size_t	buflen,
		const char *	s
	)

Concatenate two strings.

Parameters

buf	Buffer containing source string
buflen	Length of buffer
s	String to add

Return values

ptr	Start of the buffer

Definition at line 395 of file string.c.

{
  if (!buf || (buflen == 0) || !s)
    return buf;

  char *p = buf;

  buflen--; /* Space for the trailing '\0'. */

  for (; (*buf != '\0') && buflen; buflen--)
    buf++;
  for (; *s && buflen; buflen--)
    *buf++ = *s++;

  *buf = '\0';

  return p;
}

Here is the caller graph for this function:

mutt_str_strchrnul()

const char* mutt_str_strchrnul	(	const char *	s,
		char	c
	)

Find first occurrence of character in string.

Parameters

s	Haystack
c	Needle

Return values

ptr	Success, first occurrence of the character
ptr	Failure, pointer to the terminating NUL character

This function is like GNU's strchrnul, which is similar to the standard strchr function: it looks for the c character in the NULL-terminated string s and returns a pointer to its location. If c is not in s, instead of returning NULL like its standard counterpart, this function returns a pointer to the terminating NUL character.

Definition at line 538 of file string.c.

{
  if (!s)
    return NULL;

  for (; *s && (*s != c); s++)
    ;
  return s;
}

Here is the caller graph for this function:

mutt_str_strcmp()

int mutt_str_strcmp	(	const char *	a,
		const char *	b
	)

Compare two strings, safely.

Parameters

a	First string to compare
b	Second string to compare

Return values

-1	a precedes b
0	a and b are identical
1	b precedes a

Definition at line 615 of file string.c.

{
  return strcmp(NONULL(a), NONULL(b));
}

mutt_str_strcoll()

int mutt_str_strcoll	(	const char *	a,
		const char *	b
	)

Collate two strings (compare using locale), safely.

Parameters

a	First string to compare
b	Second string to compare

Return values

-1	a precedes b
0	a and b are identical
1	b precedes a

Definition at line 679 of file string.c.

{
  return strcoll(NONULL(a), NONULL(b));
}

Here is the caller graph for this function:

mutt_str_strdup()

char* mutt_str_strdup

(

const char *

str

)

Copy a string, safely.

Parameters

str	String to copy

Return values

ptr	Copy of the string
NULL	if str was NULL or empty

Definition at line 380 of file string.c.

{
  if (!str || !*str)
    return NULL;

  return strdup(str);
}

mutt_str_strfcpy()

size_t mutt_str_strfcpy	(	char *	dest,
		const char *	src,
		size_t	dsize
	)

Copy a string into a buffer (guaranteeing NUL-termination)

Parameters

dest	Buffer for the result
src	String to copy
dsize	Destination buffer size

Return values

num	Destination string length

Definition at line 750 of file string.c.

{
  if (!dest || (dsize == 0))
    return 0;
  if (!src)
  {
    dest[0] = '\0';
    return 0;
  }

  char *dest0 = dest;
  while ((--dsize > 0) && (*src != '\0'))
    *dest++ = *src++;

  *dest = '\0';
  return dest - dest0;
}

mutt_str_stristr()

const char* mutt_str_stristr	(	const char *	haystack,
		const char *	needle
	)

Find first occurrence of string (ignoring case)

Parameters

haystack	String to search through
needle	String to find

Return values

ptr	First match of the search string
NULL	No match, or an error

Definition at line 691 of file string.c.

{
  if (!haystack)
    return NULL;
  if (!needle)
    return haystack;

  const char *p = NULL, *q = NULL;

  while (*(p = haystack))
  {
    for (q = needle;
         *p && *q && (tolower((unsigned char) *p) == tolower((unsigned char) *q));
         p++, q++)
    {
    }
    if (!*q)
      return haystack;
    haystack++;
  }
  return NULL;
}

Here is the caller graph for this function:

mutt_str_strlen()

size_t mutt_str_strlen

(

const char *

a

)

Calculate the length of a string, safely.

Parameters

a	String to measure

Return values

num	Length in bytes

Definition at line 666 of file string.c.

{
  return a ? strlen(a) : 0;
}

mutt_str_strlower()

char* mutt_str_strlower

(

char *

s

)

convert all characters in the string to lowercase

Parameters

s	String to lowercase

Return values

ptr	Lowercase string

The string is transformed in place.

Definition at line 509 of file string.c.

{
  if (!s)
    return NULL;

  char *p = s;

  while (*p)
  {
    *p = tolower((unsigned char) *p);
    p++;
  }

  return s;
}

Here is the caller graph for this function:

mutt_str_strncasecmp()

int mutt_str_strncasecmp	(	const char *	a,
		const char *	b,
		size_t	l
	)

Compare two strings ignoring case (to a maximum), safely.

Parameters

a	First string to compare
b	Second string to compare
l	Maximum number of bytes to compare

Return values

-1	a precedes b
0	a and b are identical
1	b precedes a

Definition at line 656 of file string.c.

{
  return strncasecmp(NONULL(a), NONULL(b), l);
}

Here is the caller graph for this function:

mutt_str_strncat()

char* mutt_str_strncat	(	char *	d,
		size_t	l,
		const char *	s,
		size_t	sl
	)

Concatenate two strings.

Parameters

d	Buffer containing source string
l	Length of buffer
s	String to add
sl	Maximum amount of string to add

Return values

ptr	Start of joined string

Add a string to a maximum of sl bytes.

Definition at line 424 of file string.c.

{
  if (!d || (l == 0) || !s)
    return d;

  char *p = d;

  l--; /* Space for the trailing '\0'. */

  for (; *d && l; l--)
    d++;
  for (; *s && l && sl; l--, sl--)
    *d++ = *s++;

  *d = '\0';

  return p;
}

Here is the caller graph for this function:

mutt_str_strncmp()

int mutt_str_strncmp	(	const char *	a,
		const char *	b,
		size_t	l
	)

Compare two strings (to a maximum), safely.

Parameters

a	First string to compare
b	Second string to compare
l	Maximum number of bytes to compare

Return values

-1	a precedes b
0	a and b are identical
1	b precedes a

Definition at line 642 of file string.c.

{
  return strncmp(NONULL(a), NONULL(b), l);
}

Here is the caller graph for this function:

mutt_str_strnfcpy()

size_t mutt_str_strnfcpy	(	char *	dest,
		const char *	src,
		size_t	n,
		size_t	dsize
	)

Copy a limited string into a buffer (guaranteeing NUL-termination)

Parameters

dest	Buffer for the result
src	String to copy
n	Maximum number of characters to copy
dsize	Destination buffer size

Return values

num	Destination string length

Definition at line 801 of file string.c.

{
  return mutt_str_strfcpy(dest, src, MIN(n + 1, dsize));
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_str_substr_copy()

char* mutt_str_substr_copy	(	const char *	begin,
		const char *	end,
		char *	buf,
		size_t	buflen
	)

Copy a sub-string into a buffer.

Parameters

begin	Start of the string to copy
end	End of the string to copy
buf	Buffer for the result
buflen	Length of buffer

Return values

ptr	Destination buffer

Definition at line 556 of file string.c.

{
  if (!begin || !end || !buf || (buflen == 0))
    return buf;

  size_t len = end - begin;
  if (len > (buflen - 1))
    len = buflen - 1;
  memcpy(buf, begin, len);
  buf[len] = '\0';
  return buf;
}

Here is the caller graph for this function:

mutt_str_substr_dup()

char* mutt_str_substr_dup	(	const char *	begin,
		const char *	end
	)

Duplicate a sub-string.

Parameters

begin	Start of the string to copy
end	End of the string to copy

Return values

ptr	New string

If end is NULL, then the rest of the string from begin will be copied.

The caller must free the returned string.

Definition at line 579 of file string.c.

{
  size_t len;
  char *p = NULL;

  if (!begin)
  {
    mutt_debug(LL_DEBUG1, "%s: ERROR: 'begin' is NULL\n", __func__);
    return NULL;
  }

  if (end)
  {
    if (begin > end)
      return NULL;
    len = end - begin;
  }
  else
  {
    len = strlen(begin);
  }

  p = mutt_mem_malloc(len + 1);
  memcpy(p, begin, len);
  p[len] = '\0';
  return p;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_str_sysexit()

const char* mutt_str_sysexit

(

int

err_num

)

Return a string matching an error code.

Parameters

err_num

Error code, e.g. EX_NOPERM

Return values

ptr	string representing the error code

Definition at line 112 of file string.c.

{
  for (size_t i = 0; i < mutt_array_size(sysexits); i++)
  {
    if (err_num == sysexits[i].err_num)
      return sysexits[i].err_str;
  }

  return NULL;
}

Here is the caller graph for this function:

mutt_str_word_casecmp()

int mutt_str_word_casecmp	(	const char *	a,
		const char *	b
	)

Find word a in word list b.

Parameters

a	Word to find
b	String to check

Return values

0	Word was found
!=0	Word was not found

Given a word "apple", check if it exists at the start of a string of words, e.g. "apple banana". It must be an exact match, so "apple" won't match "apples banana".

The case of the words is ignored.

Definition at line 973 of file string.c.

{
  if (!b)
  {
    if (a)
      return 1;
    else
      return 0;
  }

  char tmp[128] = { 0 };

  int i;
  for (i = 0; i < (sizeof(tmp) - 2); i++, b++)
  {
    if (!*b || IS_SPACE(*b))
    {
      tmp[i] = '\0';
      break;
    }
    tmp[i] = *b;
  }
  tmp[i + 1] = '\0';

  return mutt_str_strcasecmp(a, tmp);
}

Here is the call graph for this function:

Here is the caller graph for this function: