git.notmuchmail.org Git - notmuch/blob - util/string-util.h

   1 #ifndef _STRING_UTIL_H
   2 #define _STRING_UTIL_H
   3
   4 #include <string.h>
   5
   6 #ifdef __cplusplus
   7 extern "C" {
   8 #endif
   9
  10 /* like strtok(3), but without state, and doesn't modify s.  Return
  11  * value is indicated by pointer and length, not null terminator.
  12  *
  13  * Usage pattern:
  14  *
  15  * const char *tok = input;
  16  * const char *delim = " \t";
  17  * size_t tok_len = 0;
  18  *
  19  * while ((tok = strtok_len (tok + tok_len, delim, &tok_len)) != NULL) {
  20  *     // do stuff with string tok of length tok_len
  21  * }
  22  */
  23
  24 char *strtok_len (char *s, const char *delim, size_t *len);
  25
  26 /* Const version of strtok_len. */
  27 const char *strtok_len_c (const char *s, const char *delim, size_t *len);
  28
  29 /* Simplified version of strtok_len, with a single delimiter.
  30  * Handles escaping delimiters with \
  31  * Usage pattern:
  32  *
  33  * const char *tok = input;
  34  * const char *delim = ';';
  35  * size_t tok_len = 0;
  36  *
  37  * while ((tok = strsplit_len (tok + tok_len, delim, &tok_len)) != NULL) {
  38  *     // do stuff with string tok of length tok_len
  39  * }
  40  */
  41 const char *strsplit_len (const char *s, char delim, size_t *len);
  42
  43 /* Return a talloced string with str sanitized.
  44  *
  45  * Whitespace characters (tabs and newlines) are replaced with spaces,
  46  * non-printable characters with question marks.
  47  */
  48 char *sanitize_string (const void *ctx, const char *str);
  49
  50 /* Construct a boolean term query with the specified prefix (e.g.,
  51  * "id") and search term, quoting term as necessary.  Specifically, if
  52  * term contains any non-printable ASCII characters, non-ASCII
  53  * characters, close parenthesis or double quotes, it will be enclosed
  54  * in double quotes and any internal double quotes will be doubled
  55  * (e.g. a"b -> "a""b").  The result will be a valid notmuch query and
  56  * can be parsed by parse_boolean_term.
  57  *
  58  * Output is into buf; it may be talloc_realloced.
  59  * Return: 0 on success, -1 on error.  errno will be set to ENOMEM if
  60  * there is an allocation failure.
  61  */
  62 int make_boolean_term (void *talloc_ctx, const char *prefix, const char *term,
  63                        char **buf, size_t *len);
  64
  65 /* Parse a boolean term query consisting of a prefix, a colon, and a
  66  * term that may be quoted as described for make_boolean_term.  If the
  67  * term is not quoted, then it ends at the first whitespace or close
  68  * parenthesis.  str may containing leading or trailing whitespace,
  69  * but anything else is considered a parse error.  This is compatible
  70  * with anything produced by make_boolean_term, and supports a subset
  71  * of the quoting styles supported by Xapian (and hence notmuch).
  72  * *prefix_out and *term_out will be talloc'd with context ctx.
  73  *
  74  * Return: 0 on success, -1 on error.  errno will be set to EINVAL if
  75  * there is a parse error or ENOMEM if there is an allocation failure.
  76  */
  77 int
  78 parse_boolean_term (void *ctx, const char *str,
  79                     char **prefix_out, char **term_out);
  80
  81 /* strcmp that handles NULL strings; in strcmp terms a NULL string is
  82  * considered to be less than a non-NULL string.
  83  */
  84 int strcmp_null (const char *s1, const char *s2);
  85
  86 /* GLib GEqualFunc compatible strcasecmp wrapper */
  87 int strcase_equal (const void *a, const void *b);
  88
  89 /* GLib GHashFunc compatible case insensitive hash function */
  90 unsigned int strcase_hash (const void *ptr);
  91
  92 void strip_trailing (char *str, char ch);
  93
  94 const char *skip_space (const char *str);
  95
  96 #ifdef __cplusplus
  97 }
  98 #endif
  99
 100 #endif