NeoMutt  2020-11-20
Teaching an old dog new tricks
DOXYGEN
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 S_ERR   127
 
#define S_BKG   126
 
#define SKIPWS(ch)
 
#define terminate_string(str, strlen, buflen)   (str)[MIN((strlen), (buflen))] = '\0'
 
#define terminate_buffer(str, strlen)   terminate_string(str, strlen, sizeof(str) - 1)
 

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...
 
int mutt_str_coll (const char *a, const char *b)
 Collate two strings (compare using locale), safely. 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_len (const char *a)
 Calculate the length of a string, safely. More...
 
char * mutt_str_lower (char *s)
 Convert all characters in the string to lowercase. 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...
 
void mutt_str_remove_trailing_ws (char *s)
 Trim trailing whitespace from a string. More...
 
char * mutt_str_replace (char **p, const char *s)
 Replace one string with another. 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...
 
const char * mutt_str_sysexit (int e)
 Return a string matching an error code. More...
 
char * mutt_str_cat (char *buf, size_t buflen, const char *s)
 Concatenate two strings. More...
 
int mutt_str_cmp (const char *a, const char *b)
 Compare two strings, safely. More...
 
size_t mutt_str_copy (char *dest, const char *src, size_t dsize)
 Copy a string into a buffer (guaranteeing NUL-termination) More...
 
char * mutt_str_dup (const char *str)
 Copy a string, safely. More...
 
bool mutt_str_equal (const char *a, const char *b)
 Compare two strings. More...
 
size_t mutt_str_startswith (const char *str, const char *prefix)
 Check whether a string starts with a prefix. More...
 
char * mutt_strn_cat (char *dest, size_t l, const char *s, size_t sl)
 Concatenate two strings. More...
 
char * mutt_strn_copy (char *dest, const char *src, size_t len, size_t dsize)
 Copy a sub-string into a buffer. More...
 
char * mutt_strn_dup (const char *begin, size_t l)
 Duplicate a sub-string. More...
 
bool mutt_strn_equal (const char *a, const char *b, size_t l)
 Check for equality of two strings (to a maximum), safely. More...
 
const char * mutt_strn_rfind (const char *haystack, size_t haystack_length, const char *needle)
 Find last instance of a substring. More...
 
int mutt_istr_cmp (const char *a, const char *b)
 Compare two strings ignoring case, safely. More...
 
bool mutt_istr_equal (const char *a, const char *b)
 Compare two strings, ignoring case. More...
 
const char * mutt_istr_find (const char *haystack, const char *needle)
 Find first occurrence of string (ignoring case) More...
 
int mutt_istr_remall (char *str, const char *target)
 Remove all occurrences of substring, ignoring case. More...
 
size_t mutt_istr_startswith (const char *str, const char *prefix)
 Check whether a string starts with a prefix, ignoring case. More...
 
int mutt_istrn_cmp (const char *a, const char *b, size_t l)
 Compare two strings ignoring case (to a maximum), safely. More...
 
bool mutt_istrn_equal (const char *a, const char *b, size_t l)
 Check for equality of two strings ignoring case (to a maximum), safely. More...
 

Detailed Description

String manipulation functions.

Authors
  • Richard Russon
  • Pietro Cerutti

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.

◆ S_ERR

#define S_ERR   127

Definition at line 41 of file string2.h.

◆ S_BKG

#define S_BKG   126

Definition at line 42 of file string2.h.

◆ SKIPWS

#define SKIPWS (   ch)
Value:
while (*(ch) && isspace((unsigned char) *(ch))) \
ch++;

Definition at line 46 of file string2.h.

◆ terminate_string

#define terminate_string (   str,
  strlen,
  buflen 
)    (str)[MIN((strlen), (buflen))] = '\0'

Definition at line 50 of file string2.h.

◆ terminate_buffer

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

Definition at line 53 of file string2.h.

Function Documentation

◆ mutt_str_adjust()

void mutt_str_adjust ( char **  p)

Shrink-to-fit a string.

Parameters
[out]pString 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 490 of file string.c.

491 {
492  if (!p || !*p)
493  return;
494  mutt_mem_realloc(p, strlen(*p) + 1);
495 }
void mutt_mem_realloc(void *ptr, size_t size)
Resize a block of memory on the heap.
Definition: memory.c:114
+ 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]strString appended
[in]itemString to append
[in]sepseparator 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 466 of file string.c.

467 {
468  if (!str || !item)
469  return;
470 
471  size_t sz = mutt_str_len(item);
472  size_t ssz = mutt_str_len(*str);
473 
474  mutt_mem_realloc(str, ssz + (((ssz > 0) && (sep != '\0')) ? 1 : 0) + sz + 1);
475  char *p = *str + ssz;
476  if ((ssz > 0) && (sep != '\0'))
477  *p++ = sep;
478  memcpy(p, item, sz + 1);
479 }
void mutt_mem_realloc(void *ptr, size_t size)
Resize a block of memory on the heap.
Definition: memory.c:114
size_t mutt_str_len(const char *a)
Calculate the length of a string, safely.
Definition: string.c:631
+ 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 1095 of file string.c.

1096 {
1097  if (!strp || !fmt)
1098  return -1;
1099 
1100  int rlen = 256;
1101 
1102  *strp = mutt_mem_malloc(rlen);
1103  while (true)
1104  {
1105  va_list ap;
1106  va_start(ap, fmt);
1107  const int n = vsnprintf(*strp, rlen, fmt, ap);
1108  va_end(ap);
1109  if (n < 0)
1110  {
1111  FREE(strp);
1112  return n;
1113  }
1114 
1115  if (n < rlen)
1116  {
1117  /* reduce space to just that which was used. note that 'n' does not
1118  * include the terminal nul char. */
1119  if (n == 0) /* convention is to use NULL for zero-length strings. */
1120  FREE(strp);
1121  else if (n != rlen - 1)
1122  mutt_mem_realloc(strp, n + 1);
1123  return n;
1124  }
1125  /* increase size and try again */
1126  rlen = n + 1;
1127  mutt_mem_realloc(strp, rlen);
1128  }
1129  /* not reached */
1130 }
void mutt_mem_realloc(void *ptr, size_t size)
Resize a block of memory on the heap.
Definition: memory.c:114
void * mutt_mem_malloc(size_t size)
Allocate memory on the heap.
Definition: memory.c:90
#define FREE(x)
Definition: memory.h:40
+ 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]strString to read
[out]dstStore the result
Return values
0Success
-1Error
-2Error, 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 252 of file string.c.

253 {
254  if (dst)
255  *dst = 0;
256 
257  long res = 0;
258  int rc = mutt_str_atol(str, &res);
259  if (rc < 0)
260  return rc;
261  if ((res < INT_MIN) || (res > INT_MAX))
262  return -2;
263 
264  if (dst)
265  *dst = (int) res;
266 
267  return 0;
268 }
int mutt_str_atol(const char *str, long *dst)
Convert ASCII string to a long.
Definition: string.c:188
+ 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]strString to read
[out]dstStore the result
Return values
0Success
-1Error
-2Overflow

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

Definition at line 188 of file string.c.

189 {
190  if (dst)
191  *dst = 0;
192 
193  if (!str || (*str == '\0')) /* no input: 0 */
194  return 0;
195 
196  char *e = NULL;
197  errno = 0;
198 
199  long res = strtol(str, &e, 10);
200  if (dst)
201  *dst = res;
202  if (((res == LONG_MIN) || (res == LONG_MAX)) && (errno == ERANGE))
203  return -2;
204  if (e && (*e != '\0'))
205  return -1;
206  return 0;
207 }
+ 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]strString to read
[out]dstStore the result
Return values
0Success
-1Error
-2Error, 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 222 of file string.c.

223 {
224  if (dst)
225  *dst = 0;
226 
227  long res = 0;
228  int rc = mutt_str_atol(str, &res);
229  if (rc < 0)
230  return rc;
231  if ((res < SHRT_MIN) || (res > SHRT_MAX))
232  return -2;
233 
234  if (dst)
235  *dst = (short) res;
236 
237  return 0;
238 }
int mutt_str_atol(const char *str, long *dst)
Convert ASCII string to a long.
Definition: string.c:188
+ 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]strString to read
[out]dstStore the result
Return values
1Successful conversion, with trailing characters
0Successful conversion
-1Invalid input
-2Input 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 282 of file string.c.

283 {
284  if (dst)
285  *dst = 0;
286 
287  unsigned long res = 0;
288  int rc = mutt_str_atoul(str, &res);
289  if (rc < 0)
290  return rc;
291  if (res > UINT_MAX)
292  return -2;
293 
294  if (dst)
295  *dst = (unsigned int) res;
296 
297  return rc;
298 }
int mutt_str_atoul(const char *str, unsigned long *dst)
Convert ASCII string to an unsigned long.
Definition: string.c:311
+ 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]strString to read
[out]dstStore the result
Return values
1Successful conversion, with trailing characters
0Successful conversion
-1Invalid 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 311 of file string.c.

312 {
313  if (dst)
314  *dst = 0;
315 
316  if (!str || (*str == '\0')) /* no input: 0 */
317  return 0;
318 
319  char *e = NULL;
320  errno = 0;
321 
322  unsigned long res = strtoul(str, &e, 10);
323  if (dst)
324  *dst = res;
325  if ((res == ULONG_MAX) && (errno == ERANGE))
326  return -1;
327  if (e && (*e != '\0'))
328  return 1;
329  return 0;
330 }
+ 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]strString to read
[out]dstStore the result
Return values
1Successful conversion, with trailing characters
0Successful conversion
-1Invalid 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 343 of file string.c.

344 {
345  if (dst)
346  *dst = 0;
347 
348  if (!str || (*str == '\0')) /* no input: 0 */
349  return 0;
350 
351  char *e = NULL;
352  errno = 0;
353 
354  unsigned long long res = strtoull(str, &e, 10);
355  if (dst)
356  *dst = res;
357  if ((res == ULLONG_MAX) && (errno == ERANGE))
358  return -1;
359  if (e && (*e != '\0'))
360  return 1;
361  return 0;
362 }
+ Here is the caller graph for this function:

◆ mutt_str_coll()

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

Collate two strings (compare using locale), safely.

Parameters
aFirst string to compare
bSecond string to compare
Return values
-1a precedes b
0a and b are identical
1b precedes a

Definition at line 644 of file string.c.

645 {
646  return strcoll(NONULL(a), NONULL(b));
647 }
#define NONULL(x)
Definition: string2.h:37
+ 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
sString to be un-escaped
Note
The string is changed in-place

Definition at line 839 of file string.c.

840 {
841  if (!s)
842  return;
843 
844  char *w = s;
845 
846  for (; *s; s++)
847  {
848  if (*s == '\\')
849  {
850  if (!*++s)
851  break; /* error? */
852  *w++ = *s;
853  }
854  else if (*s != '\"')
855  {
856  if (w != s)
857  *w = *s;
858  w++;
859  }
860  }
861  *w = '\0';
862 }
+ 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
srcString to search
Return values
ptrEnd 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 971 of file string.c.

972 {
973  if (!src)
974  return NULL;
975 
976  while (*src && strchr(" \t\n", *src))
977  src++;
978  while (*src && !strchr(" \t\n", *src))
979  src++;
980  return src;
981 }
+ Here is the caller graph for this function:

◆ mutt_str_getenv()

const char* mutt_str_getenv ( const char *  name)

Get an environment variable.

Parameters
nameEnvironment variable to get
Return values
ptrValue of variable
NULLVariable isn't set, or is empty
Warning
The caller must not free the returned pointer.

Definition at line 991 of file string.c.

992 {
993  if (!name)
994  return NULL;
995 
996  const char *val = getenv(name);
997  if (val && (val[0] != '\0'))
998  return val;
999 
1000  return NULL;
1001 }
+ 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
bufBuffer to modify
buflenLength of buffer
xlenLength of string to overwrite
rstrReplacement string
Return values
trueSuccess

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

Definition at line 1013 of file string.c.

1014 {
1015  if (!buf || !rstr || (xlen >= buflen))
1016  return false;
1017 
1018  size_t slen = mutt_str_len(buf + xlen);
1019  size_t rlen = mutt_str_len(rstr);
1020 
1021  if ((slen + rlen) >= buflen)
1022  return false;
1023 
1024  memmove(buf + rlen, buf + xlen, slen + 1);
1025  memmove(buf, rstr, rlen);
1026 
1027  return true;
1028 }
size_t mutt_str_len(const char *a)
Calculate the length of a string, safely.
Definition: string.c:631
+ 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
strString to examine
lenLength of string to examine
Return values
trueThere are no 8-bit chars

Definition at line 948 of file string.c.

949 {
950  if (!str)
951  return true;
952 
953  for (; (*str != '\0') && (len > 0); str++, len--)
954  if ((*str & 0x80) != 0)
955  return false;
956 
957  return true;
958 }
+ 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
cCharacter to test
Return values
trueIt is whitespcae

Definition at line 759 of file string.c.

760 {
761  return c && strchr(" \t\r\n", c);
762 }
+ Here is the caller graph for this function:

◆ mutt_str_len()

size_t mutt_str_len ( const char *  a)

Calculate the length of a string, safely.

Parameters
aString to measure
Return values
numLength in bytes

Definition at line 631 of file string.c.

632 {
633  return a ? strlen(a) : 0;
634 }

◆ mutt_str_lower()

char* mutt_str_lower ( char *  s)

Convert all characters in the string to lowercase.

Parameters
sString to lowercase
Return values
ptrLowercase string

The string is transformed in place.

Definition at line 504 of file string.c.

505 {
506  if (!s)
507  return NULL;
508 
509  char *p = s;
510 
511  while (*p)
512  {
513  *p = tolower((unsigned char) *p);
514  p++;
515  }
516 
517  return s;
518 }
+ 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
sString to check
nMaximum number of characters to check
Return values
numCount 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 773 of file string.c.

774 {
775  if (!s)
776  return 0;
777 
778  const char *p = s;
779  size_t len = n;
780 
781  if (n == 0)
782  return 0;
783 
784  for (; p < (s + n); p++)
785  {
786  if (!strchr(" \t\r\n", *p))
787  {
788  len = p - s;
789  break;
790  }
791  }
792 
793  if ((len != 0) && strchr("\r\n", *(p - 1))) /* LWS doesn't end with CRLF */
794  len = 0;
795  return len;
796 }
+ 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
sString to check
nMaximum number of characters to check
Return values
numCount 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 807 of file string.c.

808 {
809  if (!s)
810  return 0;
811 
812  const char *p = s + n - 1;
813  size_t len = n;
814 
815  if (n == 0)
816  return 0;
817 
818  if (strchr("\r\n", *p)) /* LWS doesn't end with CRLF */
819  return 0;
820 
821  for (; p >= s; p--)
822  {
823  if (!strchr(" \t\r\n", *p))
824  {
825  len = s + n - 1 - p;
826  break;
827  }
828  }
829 
830  return len;
831 }

◆ mutt_str_next_word()

const char* mutt_str_next_word ( const char *  s)

Find the next word in a string.

Parameters
sString to examine
Return values
ptrNext 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 898 of file string.c.

899 {
900  if (!s)
901  return NULL;
902 
903  while (*s && !IS_SPACE(*s))
904  s++;
905  SKIPWS(s);
906  return s;
907 }
#define SKIPWS(ch)
Definition: string2.h:46
#define IS_SPACE(ch)
Definition: string2.h:38

◆ mutt_str_remove_trailing_ws()

void mutt_str_remove_trailing_ws ( char *  s)

Trim trailing whitespace from a string.

Parameters
sString to trim

The string is modified in place.

Definition at line 700 of file string.c.

701 {
702  if (!s)
703  return;
704 
705  for (char *p = s + mutt_str_len(s) - 1; (p >= s) && IS_SPACE(*p); p--)
706  *p = '\0';
707 }
#define IS_SPACE(ch)
Definition: string2.h:38
size_t mutt_str_len(const char *a)
Calculate the length of a string, safely.
Definition: string.c:631
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ mutt_str_replace()

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

Replace one string with another.

Parameters
[out]pString to replace
[in]sNew string
Return values
ptrReplaced 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.

Note
Free *p afterwards to handle the case that *p and s reference the same memory

Definition at line 446 of file string.c.

447 {
448  if (!p)
449  return NULL;
450  const char *tmp = *p;
451  *p = mutt_str_dup(s);
452  FREE(&tmp);
453  return *p;
454 }
char * mutt_str_dup(const char *str)
Copy a string, safely.
Definition: string.c:370
#define FREE(x)
Definition: memory.h:40
+ Here is the call 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
sString to search
Return values
ptr
  • First non-whitespace character
  • Terminating NUL character, if the string was entirely whitespace

This is used primarily for parsing header fields.

Definition at line 743 of file string.c.

744 {
745  if (!s)
746  return NULL;
747 
748  for (; mutt_str_is_email_wsp(*s); s++)
749  ; // Do nothing
750 
751  return (char *) s;
752 }
bool mutt_str_is_email_wsp(char c)
Is this a whitespace character (for an email header)
Definition: string.c:759
+ Here is the call graph for this function:
+ 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
pString to search
Return values
ptr
  • First non-whitespace character
  • Terminating NUL character, if the string was entirely whitespace

Definition at line 686 of file string.c.

687 {
688  if (!p)
689  return NULL;
690  SKIPWS(p);
691  return (char *) p;
692 }
#define SKIPWS(ch)
Definition: string2.h:46
+ 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_numError code, e.g. EX_NOPERM
Return values
ptrstring representing the error code

Definition at line 112 of file string.c.

113 {
114  for (size_t i = 0; i < mutt_array_size(sysexits); i++)
115  {
116  if (err_num == sysexits[i].err_num)
117  return sysexits[i].err_str;
118  }
119 
120  return NULL;
121 }
static const struct SysExits sysexits[]
Definition: string.c:58
#define mutt_array_size(x)
Definition: memory.h:33
const char * err_str
Definition: string.c:55
+ Here is the caller graph for this function:

◆ mutt_str_cat()

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

Concatenate two strings.

Parameters
bufBuffer containing source string
buflenLength of buffer
sString to add
Return values
ptrStart of the buffer

Definition at line 385 of file string.c.

386 {
387  if (!buf || (buflen == 0) || !s)
388  return buf;
389 
390  char *p = buf;
391 
392  buflen--; /* Space for the trailing '\0'. */
393 
394  for (; (*buf != '\0') && buflen; buflen--)
395  buf++;
396  for (; *s && buflen; buflen--)
397  *buf++ = *s++;
398 
399  *buf = '\0';
400 
401  return p;
402 }
+ Here is the caller graph for this function:

◆ mutt_str_cmp()

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

Compare two strings, safely.

Parameters
aFirst string to compare
bSecond string to compare
Return values
-1a precedes b
0a and b are identical
1b precedes a

Definition at line 567 of file string.c.

568 {
569  return strcmp(NONULL(a), NONULL(b));
570 }
#define NONULL(x)
Definition: string2.h:37
+ Here is the caller graph for this function:

◆ mutt_str_copy()

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

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

Parameters
destBuffer for the result
srcString to copy
dsizeDestination buffer size
Return values
numDestination string length

Definition at line 716 of file string.c.

717 {
718  if (!dest || (dsize == 0))
719  return 0;
720  if (!src)
721  {
722  dest[0] = '\0';
723  return 0;
724  }
725 
726  char *dest0 = dest;
727  while ((--dsize > 0) && (*src != '\0'))
728  *dest++ = *src++;
729 
730  *dest = '\0';
731  return dest - dest0;
732 }

◆ mutt_str_dup()

char* mutt_str_dup ( const char *  str)

Copy a string, safely.

Parameters
strString to copy
Return values
ptrCopy of the string
NULLif str was NULL or empty

Definition at line 370 of file string.c.

371 {
372  if (!str || (*str == '\0'))
373  return NULL;
374 
375  return strdup(str);
376 }

◆ mutt_str_equal()

bool mutt_str_equal ( const char *  a,
const char *  b 
)

Compare two strings.

Parameters
aFirst string
bSecond string
Return values
trueThe strings are equal
falseThe strings are not equal

Definition at line 871 of file string.c.

872 {
873  return (a == b) || (mutt_str_cmp(a, b) == 0);
874 }
int mutt_str_cmp(const char *a, const char *b)
Compare two strings, safely.
Definition: string.c:567
+ Here is the call graph for this function:

◆ mutt_str_startswith()

size_t mutt_str_startswith ( const char *  str,
const char *  prefix 
)

Check whether a string starts with a prefix.

Parameters
strString to check
prefixPrefix to match
Return values
numLength of prefix if str starts with prefix
0if str does not start with prefix

Definition at line 160 of file string.c.

161 {
162  return startswith(str, prefix, true);
163 }
static size_t startswith(const char *str, const char *prefix, bool match_case)
Check whether a string starts with a prefix.
Definition: string.c:131
+ Here is the call graph for this function:

◆ mutt_strn_cat()

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

Concatenate two strings.

Parameters
dBuffer containing source string
lLength of buffer
sString to add
slMaximum amount of string to add
Return values
ptrStart of joined string

Add a string to a maximum of sl bytes.

Definition at line 414 of file string.c.

415 {
416  if (!d || (l == 0) || !s)
417  return d;
418 
419  char *p = d;
420 
421  l--; /* Space for the trailing '\0'. */
422 
423  for (; *d && l; l--)
424  d++;
425  for (; *s && l && sl; l--, sl--)
426  *d++ = *s++;
427 
428  *d = '\0';
429 
430  return p;
431 }
+ Here is the caller graph for this function:

◆ mutt_strn_copy()

char* mutt_strn_copy ( char *  dest,
const char *  src,
size_t  len,
size_t  dsize 
)

Copy a sub-string into a buffer.

Parameters
destBuffer for the result
srcStart of the string to copy
lenLength of the string to copy
dsizeDestination buffer size
Return values
ptrDestination buffer

Definition at line 528 of file string.c.

529 {
530  if (!src || !dest || (len == 0) || (dsize == 0))
531  return dest;
532 
533  if (len > (dsize - 1))
534  len = dsize - 1;
535  memcpy(dest, src, len);
536  dest[len] = '\0';
537  return dest;
538 }
+ Here is the caller graph for this function:

◆ mutt_strn_dup()

char* mutt_strn_dup ( const char *  begin,
size_t  len 
)

Duplicate a sub-string.

Parameters
beginStart of the string to copy
lenLength of string to copy
Return values
ptrNew string

The caller must free the returned string.

Definition at line 548 of file string.c.

549 {
550  if (!begin)
551  return NULL;
552 
553  char *p = mutt_mem_malloc(len + 1);
554  memcpy(p, begin, len);
555  p[len] = '\0';
556  return p;
557 }
void * mutt_mem_malloc(size_t size)
Allocate memory on the heap.
Definition: memory.c:90
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ mutt_strn_equal()

bool mutt_strn_equal ( const char *  a,
const char *  b,
size_t  l 
)

Check for equality of two strings (to a maximum), safely.

Parameters
aFirst string to compare
bSecond string to compare
lMaximum number of bytes to compare
Return values
trueFirst l chars of both strings are equal
falseFirst l chars of both strings not equal

Definition at line 593 of file string.c.

594 {
595  return strncmp(NONULL(a), NONULL(b), l) == 0;
596 }
#define NONULL(x)
Definition: string2.h:37
+ Here is the caller graph for this function:

◆ mutt_strn_rfind()

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

Find last instance of a substring.

Parameters
haystackString to search through
haystack_lengthLength of the string
needleString to find
Return values
NULLString not found
ptrLocation 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 920 of file string.c.

921 {
922  if (!haystack || (haystack_length == 0) || !needle)
923  return NULL;
924 
925  int needle_length = strlen(needle);
926  const char *haystack_end = haystack + haystack_length - needle_length;
927 
928  for (const char *p = haystack_end; p >= haystack; --p)
929  {
930  for (size_t i = 0; i < needle_length; i++)
931  {
932  if (p[i] != needle[i])
933  goto next;
934  }
935  return p;
936 
937  next:;
938  }
939  return NULL;
940 }
+ Here is the caller graph for this function:

◆ mutt_istr_cmp()

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

Compare two strings ignoring case, safely.

Parameters
aFirst string to compare
bSecond string to compare
Return values
-1a precedes b
0a and b are identical
1b precedes a

Definition at line 580 of file string.c.

581 {
582  return strcasecmp(NONULL(a), NONULL(b));
583 }
#define NONULL(x)
Definition: string2.h:37
+ Here is the caller graph for this function:

◆ mutt_istr_equal()

bool mutt_istr_equal ( const char *  a,
const char *  b 
)

Compare two strings, ignoring case.

Parameters
aFirst string
bSecond string
Return values
trueThe strings are equal
falseThe strings are not equal

Definition at line 883 of file string.c.

884 {
885  return (a == b) || (mutt_istr_cmp(a, b) == 0);
886 }
int mutt_istr_cmp(const char *a, const char *b)
Compare two strings ignoring case, safely.
Definition: string.c:580
+ Here is the call graph for this function:

◆ mutt_istr_find()

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

Find first occurrence of string (ignoring case)

Parameters
haystackString to search through
needleString to find
Return values
ptrFirst match of the search string
NULLNo match, or an error

Definition at line 656 of file string.c.

657 {
658  if (!haystack)
659  return NULL;
660  if (!needle)
661  return haystack;
662 
663  const char *p = NULL, *q = NULL;
664 
665  while (*(p = haystack))
666  {
667  for (q = needle;
668  *p && *q && (tolower((unsigned char) *p) == tolower((unsigned char) *q));
669  p++, q++)
670  {
671  }
672  if ((*q == '\0'))
673  return haystack;
674  haystack++;
675  }
676  return NULL;
677 }
+ Here is the caller graph for this function:

◆ mutt_istr_remall()

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

Remove all occurrences of substring, ignoring case.

Parameters
strString containing the substring
targetTarget substring for removal
Return values
0String contained substring and substring was removed successfully
1String did not contain substring

Definition at line 1037 of file string.c.

1038 {
1039  int rc = 1;
1040  if (!str || !target)
1041  return rc;
1042 
1043  // Look through an ensure all instances of the substring are gone.
1044  while ((str = (char *) strcasestr(str, target)))
1045  {
1046  size_t target_len = mutt_str_len(target);
1047  memmove(str, str + target_len, 1 + strlen(str + target_len));
1048  rc = 0; // If we got here, then a substring existed and has been removed.
1049  }
1050 
1051  return rc;
1052 }
size_t mutt_str_len(const char *a)
Calculate the length of a string, safely.
Definition: string.c:631
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ mutt_istr_startswith()

size_t mutt_istr_startswith ( const char *  str,
const char *  prefix 
)

Check whether a string starts with a prefix, ignoring case.

Parameters
strString to check
prefixPrefix to match
Return values
numLength of prefix if str starts with prefix
0if str does not start with prefix

Definition at line 172 of file string.c.

173 {
174  return startswith(str, prefix, false);
175 }
static size_t startswith(const char *str, const char *prefix, bool match_case)
Check whether a string starts with a prefix.
Definition: string.c:131
+ Here is the call graph for this function:

◆ mutt_istrn_cmp()

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

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

Parameters
aFirst string to compare
bSecond string to compare
lMaximum number of bytes to compare
Return values
-1a precedes b
0a and b are identical
1b precedes a

Definition at line 607 of file string.c.

608 {
609  return strncasecmp(NONULL(a), NONULL(b), l);
610 }
#define NONULL(x)
Definition: string2.h:37
+ Here is the caller graph for this function:

◆ mutt_istrn_equal()

bool mutt_istrn_equal ( const char *  a,
const char *  b,
size_t  l 
)

Check for equality of two strings ignoring case (to a maximum), safely.

Parameters
aFirst string to compare
bSecond string to compare
lMaximum number of bytes to compare
Return values
-1a precedes b
trueFirst l chars of both strings are equal, ignoring case
falseFirst l chars of both strings not equal, ignoring case

Definition at line 621 of file string.c.

622 {
623  return strncasecmp(NONULL(a), NONULL(b), l) == 0;
624 }
#define NONULL(x)
Definition: string2.h:37
+ Here is the caller graph for this function: