]> mj.ucw.cz Git - libucw.git/blob - ucw/string.h
Documented ucw/string.h.
[libucw.git] / ucw / string.h
1 /*
2  *      UCW Library -- String Routines
3  *
4  *      (c) 2006 Pavel Charvat <pchar@ucw.cz>
5  *      (c) 2007--2011 Martin Mares <mj@ucw.cz>
6  *
7  *      This software may be freely distributed and used according to the terms
8  *      of the GNU Lesser General Public License.
9  */
10
11 #ifndef _UCW_STRING_H
12 #define _UCW_STRING_H
13
14 /* string.c */
15
16 #ifdef CONFIG_DARWIN
17 uns strnlen(const char *str, uns n);
18 #endif
19
20 /**
21  * Format a set of flag bits. When the i-th bit of @flags is 1,
22  * set the i-th character of @dest to @fmt[i], otherwise to '-'.
23  **/
24 char *str_format_flags(char *dest, const char *fmt, uns flags);
25
26 /** Counts occurrences of @chr in @str. **/
27 uns str_count_char(const char *str, uns chr);
28
29 /* str-esc.c */
30
31 /**
32  * Decode a string with backslash escape sequences as in C99 strings.
33  * It is safe to pass @dest equal to @src.
34  **/
35 char *str_unesc(char *dest, const char *src);
36
37 /* str-split.c */
38
39 /**
40  * Split @str to at most @max fields separated by @sep. Occurrences of the
41  * separator are rewritten to string terminators, @rec[i] is set to point
42  * to the i-th field. The total number of fields is returned.
43  *
44  * When there are more than @max fields in @str, the first @max fields
45  * are processed and -1 is returned.
46  **/
47 int str_sepsplit(char *str, uns sep, char **rec, uns max);
48
49 /**
50  * Split @str to words separated by white-space characters. The spaces
51  * are replaced by string terminators, @rec[i] is set to point to the
52  * i-th field. The total number of fields is returned.
53  *
54  * When there are more than @max fields in @str, the first @max fields
55  * are processed and -1 is returned.
56  *
57  * Fields surrounded by double quotes are also recognized. They can contain
58  * spaces, but no mechanism for escaping embedded quotes is defined.
59  **/
60 int str_wordsplit(char *str, char **rec, uns max);
61
62 /* str-(i)match.c: Matching of shell patterns */
63
64 /**
65  * Test whether the string @str matches the shell-like pattern @patt. Only
66  * "*" and "?" meta-characters are supported.
67  **/
68 int str_match_pattern(const char *patt, const char *str);
69
70 /** A case-insensitive version of @str_match_pattern(). **/
71 int str_match_pattern_nocase(const char *patt, const char *str);
72
73 /* str-hex.c */
74
75 /**
76  * Create a hexdump of a memory block of @bytes bytes starting at @src.
77  * The @flags contain an optional separator of bytes (0 if bytes should
78  * not be separated), possibly OR-ed with `MEM_TO_HEX_UPCASE` when upper-case
79  * characters should be used.
80  **/
81 void mem_to_hex(char *dest, const byte *src, uns bytes, uns flags);
82
83 /**
84  * An inverse function to @mem_to_hex(). Takes a hexdump of at most @max_bytes
85  * bytes and stores the bytes to a buffer starting at @dest. Returns a pointer
86  * at the first character after the dump.
87  **/
88 const char *hex_to_mem(byte *dest, const char *src, uns max_bytes, uns flags);
89
90 // Bottom 8 bits of flags are an optional separator of bytes, the rest is:
91 #define MEM_TO_HEX_UPCASE 0x100
92
93 /* str-fix.c */
94
95 int str_has_prefix(char *str, char *prefix);            /** Tests if @str starts with @prefix. **/
96 int str_has_suffix(char *str, char *suffix);            /** Tests if @str ends with @suffix. **/
97
98 /**
99  * Let @str and @prefix be hierarchical names with components separated by
100  * a character @sep. Returns true if @str starts with @prefix, respecting
101  * component boundaries.
102  *
103  * For example, when @sep is '/' and @str is "/usr/local/bin", then:
104  *
105  * - "/usr/local" is a prefix
106  * - "/usr/local/" is a prefix, too
107  * - "/usr/loc" is not,
108  * - "/usr/local/bin" is a prefix,
109  * - "/usr/local/bin/" is not,
110  * - "/" is a prefix,
111  * - "" is a prefix.
112  **/
113 int str_hier_prefix(char *str, char *prefix, uns sep);
114 int str_hier_suffix(char *str, char *suffix, uns sep);  /** Like @str_hier_prefix(), but for suffixes. **/
115
116 #endif