4c110a205ccfb5b2684183e79ca2147d1c891b69
[notmuch] / 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 /* Return a talloced string with str sanitized.
30  *
31  * Whitespace characters (tabs and newlines) are replaced with spaces,
32  * non-printable characters with question marks.
33  */
34 char *sanitize_string (const void *ctx, const char *str);
35
36 /* Construct a boolean term query with the specified prefix (e.g.,
37  * "id") and search term, quoting term as necessary.  Specifically, if
38  * term contains any non-printable ASCII characters, non-ASCII
39  * characters, close parenthesis or double quotes, it will be enclosed
40  * in double quotes and any internal double quotes will be doubled
41  * (e.g. a"b -> "a""b").  The result will be a valid notmuch query and
42  * can be parsed by parse_boolean_term.
43  *
44  * Output is into buf; it may be talloc_realloced.
45  * Return: 0 on success, -1 on error.  errno will be set to ENOMEM if
46  * there is an allocation failure.
47  */
48 int make_boolean_term (void *talloc_ctx, const char *prefix, const char *term,
49                        char **buf, size_t *len);
50
51 /* Parse a boolean term query consisting of a prefix, a colon, and a
52  * term that may be quoted as described for make_boolean_term.  If the
53  * term is not quoted, then it ends at the first whitespace or close
54  * parenthesis.  str may containing leading or trailing whitespace,
55  * but anything else is considered a parse error.  This is compatible
56  * with anything produced by make_boolean_term, and supports a subset
57  * of the quoting styles supported by Xapian (and hence notmuch).
58  * *prefix_out and *term_out will be talloc'd with context ctx.
59  *
60  * Return: 0 on success, -1 on error.  errno will be set to EINVAL if
61  * there is a parse error or ENOMEM if there is an allocation failure.
62  */
63 int
64 parse_boolean_term (void *ctx, const char *str,
65                     char **prefix_out, char **term_out);
66
67 /* strcmp that handles NULL strings; in strcmp terms a NULL string is
68  * considered to be less than a non-NULL string.
69  */
70 int strcmp_null (const char *s1, const char *s2);
71
72 /* GLib GEqualFunc compatible strcasecmp wrapper */
73 int strcase_equal (const void *a, const void *b);
74
75 /* GLib GHashFunc compatible case insensitive hash function */
76 unsigned int strcase_hash (const void *ptr);
77
78 void strip_trailing (char *str, char ch);
79
80 const char* skip_space (const char *str);
81
82 #ifdef __cplusplus
83 }
84 #endif
85
86 #endif