BRL-CAD
str.h
Go to the documentation of this file.
1 /* S T R . H
2  * BRL-CAD
3  *
4  * Copyright (c) 2004-2014 United States Government as represented by
5  * the U.S. Army Research Laboratory.
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public License
9  * version 2.1 as published by the Free Software Foundation.
10  *
11  * This library is distributed in the hope that it will be useful, but
12  * WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this file; see the file named COPYING for more
18  * information.
19  */
20 
21 /** @file str.h
22  *
23  */
24 #ifndef BU_STR_H
25 #define BU_STR_H
26 
27 #include "common.h"
28 #include "bu/defines.h"
29 
31 
32 /** @addtogroup str */
33 /** @{ */
34 
35 /** @file libbu/str.c
36  *
37  * Compatibility routines to various string processing functions
38  * including strlcat and strlcpy.
39  *
40  */
41 
42 /**
43  * concatenate one string onto the end of another, returning the
44  * length of the dst string after the concatenation.
45  *
46  * bu_strlcat() is a macro to bu_strlcatm() so that we can report the
47  * file name and line number of any erroneous callers.
48  */
49 BU_EXPORT extern size_t bu_strlcatm(char *dst, const char *src, size_t size, const char *label);
50 #define bu_strlcat(dst, src, size) bu_strlcatm(dst, src, size, BU_FLSTR)
51 
52 /**
53  * copies one string into another, returning the length of the dst
54  * string after the copy.
55  *
56  * bu_strlcpy() is a macro to bu_strlcpym() so that we can report the
57  * file name and line number of any erroneous callers.
58  */
59 BU_EXPORT extern size_t bu_strlcpym(char *dst, const char *src, size_t size, const char *label);
60 #define bu_strlcpy(dst, src, size) bu_strlcpym(dst, src, size, BU_FLSTR)
61 
62 /**
63  * Given a string, allocate enough memory to hold it using
64  * bu_malloc(), duplicate the strings, returns a pointer to the new
65  * string.
66  *
67  * bu_strdup() is a macro that includes the current file name and line
68  * number that can be used when bu debugging is enabled.
69  */
70 BU_EXPORT extern char *bu_strdupm(const char *cp, const char *label);
71 #define bu_strdup(s) bu_strdupm(s, BU_FLSTR)
72 
73 /**
74  * Compares two strings for equality. It performs the comparison more
75  * robustly than the standard library's strcmp() function by defining
76  * consistent behavior for NULL and empty strings. It accepts NULL as
77  * valid input values and considers "" and NULL as equal. Returns 0
78  * if the strings match.
79  */
80 BU_EXPORT extern int bu_strcmp(const char *string1, const char *string2);
81 
82 /**
83  * Compares two strings for equality. No more than n-characters are
84  * compared. It performs the comparison more robustly than the
85  * standard library's strncmp() function by defining consistent
86  * behavior for NULL and empty strings. It accepts NULL as valid
87  * input values and considers "" and NULL as equal. Returns 0 if the
88  * strings match.
89  */
90 BU_EXPORT extern int bu_strncmp(const char *string1, const char *string2, size_t n);
91 
92 /**
93  * Compares two strings for equality without regard for the case in
94  * the string. It performs the comparison more robustly than the
95  * standard strcasecmp()/stricmp() function by defining consistent
96  * behavior for NULL and empty strings. It accepts NULL as valid
97  * input values and considers "" and NULL as equal. Returns 0 if the
98  * strings match.
99  */
100 BU_EXPORT extern int bu_strcasecmp(const char *string1, const char *string2);
101 
102 /**
103  * Compares two strings for equality without regard for the case in
104  * the string. No more than n-characters are compared. It performs
105  * the comparison more robustly than the standard
106  * strncasecmp()/strnicmp() function by defining consistent behavior
107  * for NULL and empty strings. It accepts NULL as valid input values
108  * and considers "" and NULL as equal. Returns 0 if the strings
109  * match.
110  */
111 BU_EXPORT extern int bu_strncasecmp(const char *string1, const char *string2, size_t n);
112 
113 /**
114  * BU_STR_EMPTY() is a convenience macro that tests a string for
115  * emptiness, i.e. "" or NULL.
116  */
117 #define BU_STR_EMPTY(s) (bu_strcmp((s), "") == 0)
118 
119 /**
120  * BU_STR_EQUAL() is a convenience macro for testing two
121  * null-terminated strings for equality. It is equivalent to
122  * (bu_strcmp(s1, s2) == 0) whereby NULL strings are allowed and
123  * equivalent to an empty string. Evaluates true when the strings
124  * match and false if they do not.
125  */
126 #define BU_STR_EQUAL(s1, s2) (bu_strcmp((s1), (s2)) == 0)
127 
128 /**
129  * BU_STR_EQUIV() is a convenience macro that compares two
130  * null-terminated strings for equality without regard for case. Two
131  * strings are equivalent if they are a case-insensitive match. NULL
132  * strings are allowed and equivalent to an empty string. Evaluates
133  * true if the strings are similar and false if they are not.
134  */
135 #define BU_STR_EQUIV(s1, s2) (bu_strcasecmp((s1), (s2)) == 0)
136 
137 
138 /** @file escape.c
139  *
140  * These routines implement support for escaping and unescaping
141  * generalized strings that may represent filesystem paths, URLs,
142  * object lists, and more.
143  *
144  */
145 
146 /**
147  * Escapes an input string with preceding '\'s for any characters
148  * defined in the 'expression' string. The input string is written to the
149  * specified output buffer of 'size' capacity. The input and output
150  * pointers may overlap or be the same memory (assuming adequate space
151  * is available). If 'output' is NULL, then dynamic memory will be
152  * allocated and returned.
153  *
154  * The 'expression' parameter is a regular "bracket expression"
155  * commonly used in globbing and POSIX regular expression character
156  * matching. An expression can be either a matching list (default) or
157  * a non-matching list (starting with a circumflex '^' character).
158  * For example, "abc" matches any of the characters 'a', 'b', or 'c'.
159  * Specifying a non-matching list expression matches any character
160  * except for the ones listed after the circumflex. For example,
161  * "^abc" matches any character except 'a', 'b', or 'c'.
162  *
163  * Backslash escape sequences are not allowed (e.g., \\t or \\x01) as
164  * '\' will be matched literally.
165  *
166  * A range expression consists of two characters separated by a hyphen
167  * and will match any single character between the two characters.
168  * For example, "0-9a-c" is equivalent to "0123456789abc". To match a
169  * '-' dash literally, include it as the last or first (after any '^')
170  * character within the expression.
171  *
172  * The expression may also contain named character classes but only
173  * for ASCII input strings:
174  *
175  * [:alnum:] Alphanumeric characters: a-zA-Z0-9
176  * [:alpha:] Alphabetic characters: a-zA-Z
177  * [:blank:] Space and TAB characters
178  * [:cntrl:] Control characters: ACSII 0x00-0X7F
179  * [:digit:] Numeric characters: 0-9
180  * [:graph:] Characters that are both printable and visible: ASCII 0x21-0X7E
181  * [:lower:] Lowercase alphabetic characters: a-z
182  * [:print:] Visible and space characters (not control characters): ASCII 0x20-0X7E
183  * [:punct:] Punctuation characters (not letters, digits, control, or space): ][!"#$%&'()*+,./:;<=>?@^_`{|}~-\
184  * [:upper:] Uppercase alphabetic characters: A-Z
185  * [:xdigit:] Hexadecimal digits: a-fA-F0-9
186  * [:word:] (non-POSIX) Alphanumeric plus underscore: a-zA-Z0-9_
187  *
188  * A non-NULL output string is always returned. This allows
189  * expression chaining and embedding as function arguments but care
190  * should be taken to free the dynamic memory being returned when
191  * 'output' is NULL.
192  *
193  * If output 'size' is inadequate for holding the escaped input
194  * string, bu_bomb() is called.
195  *
196  * Example:
197  * char *result;
198  * char buf[128];
199  * result = bu_str_escape("my fair lady", " ", buf, 128);
200  * :: result == buf == "my\ fair\ lady"
201  * result = bu_str_escape(buf, "\", NULL, 0);
202  * :: result == "my\\ fair\\ lady"
203  * :: buf == "my\ fair\ lady"
204  * bu_free(result, "bu_str_escape");
205  * result = bu_str_escape(buf, "a-zA-Z", buf, 128);
206  * :: result == buf == "\m\y\ \f\a\i\r\ \l\a\d\y"
207  *
208  * This function should be thread safe and re-entrant if the
209  * input/output buffers are not shared (and strlen() is threadsafe).
210  */
211 BU_EXPORT extern char *bu_str_escape(const char *input, const char *expression, char *output, size_t size);
212 
213 /**
214  * Removes one level of '\' escapes from an input string. The input
215  * string is written to the specified output buffer of 'size'
216  * capacity. The input and output pointers may overlap or be the same
217  * memory. If 'output' is NULL, then dynamic memory will be allocated
218  * and returned.
219  *
220  * A non-NULL output string is always returned. This allows
221  * expression chaining and embedding as function arguments but care
222  * should be taken to free the dynamic memory being returned when
223  * 'output' is NULL.
224  *
225  * If output 'size' is inadequate for holding the unescaped input
226  * string, bu_bomb() is called.
227  *
228  * Example:
229  * char *result;
230  * char buf[128];
231  * result = bu_str_unescape("\m\y\\ \f\a\i\r\\ \l\a\d\y", buf, 128);
232  * :: result == buf == "my\ fair\ lady"
233  * result = bu_str_unescape(buf, NULL, 0);
234  * :: result == "my fair lady"
235  * :: buf == "my\ fair\ lady"
236  * bu_free(result, "bu_str_unescape");
237  *
238  * This function should be thread safe and re-entrant if the
239  * input/output buffers are not shared (and strlen() is threadsafe).
240  */
241 BU_EXPORT extern char *bu_str_unescape(const char *input, char *output, size_t size);
242 
243 
244 /** @file libbu/ctype.c
245  *
246  * Routines for checking ctypes.
247  *
248  */
249 BU_EXPORT extern int bu_str_isprint(const char *cp);
250 
251 /**
252  * Get the current operating host's name. This is usually also the
253  * network name of the current host. The name is written into the
254  * provided hostname buffer of at least len size. The hostname is
255  * always null-terminated and should be sized accordingly.
256  */
257 BU_EXPORT extern int bu_gethostname(char *hostname, size_t len);
258 
260 
261 /** @} */
262 
263 #endif /* BU_STR_H */
264 
265 /*
266  * Local Variables:
267  * mode: C
268  * tab-width: 8
269  * indent-tabs-mode: t
270  * c-file-style: "stroustrup"
271  * End:
272  * ex: shiftwidth=4 tabstop=8
273  */
int bu_gethostname(char *hostname, size_t len)
Definition: gethostname.c:30
Header file for the BRL-CAD common definitions.
int bu_strncmp(const char *string1, const char *string2, size_t n)
Definition: str.c:191
int bu_strncasecmp(const char *string1, const char *string2, size_t n)
Definition: str.c:239
#define __BEGIN_DECLS
Definition: common.h:73
char * bu_str_unescape(const char *input, char *output, size_t size)
Definition: escape.c:149
char * bu_str_escape(const char *input, const char *expression, char *output, size_t size)
Definition: escape.c:53
char * bu_strdupm(const char *cp, const char *label)
int bu_strcmp(const char *string1, const char *string2)
Definition: str.c:171
ustring label
size_t bu_strlcpym(char *dst, const char *src, size_t size, const char *label)
Definition: str.c:96
int bu_str_isprint(const char *cp)
Definition: ctype.c:28
#define __END_DECLS
Definition: common.h:74
size_t bu_strlcatm(char *dst, const char *src, size_t size, const char *label)
Definition: str.c:40
int bu_strcasecmp(const char *string1, const char *string2)
Definition: str.c:211