BRL-CAD
vls.h
Go to the documentation of this file.
1 /* V L S . 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 /** @defgroup container Data Containers */
22 /** @defgroup vls Variable-length Strings */
23 
24 /** @file vls.h
25  */
26 #ifndef BU_VLS_H
27 #define BU_VLS_H
28 
29 #include "common.h"
30 #include <stdio.h> /* For FILE */
31 #include <sys/types.h> /* for off_t */
32 #include <stddef.h> /* for size_t */
33 #include <stdarg.h> /* For va_list */
34 
35 #include "bu/defines.h"
36 #include "bu/magic.h"
37 
39 
40 /*----------------------------------------------------------------------*/
41 /** @addtogroup vls */
42 /** @{ */
43 /** @file libbu/vls.c
44  *
45  @brief
46  * Variable Length Strings
47  *
48  * This structure provides support for variable length strings,
49  * freeing the programmer from concerns about having character arrays
50  * large enough to hold strings.
51  *
52  * Assumption: libc-provided sprintf() function is safe to use in parallel,
53  * on parallel systems.
54  */
55 
56 struct bu_vls {
57  uint32_t vls_magic;
58  char *vls_str; /**< Dynamic memory for buffer */
59  size_t vls_offset; /**< Positive index into vls_str where string begins */
60  size_t vls_len; /**< Length, not counting the null */
61  size_t vls_max;
62 };
63 typedef struct bu_vls bu_vls_t;
64 #define BU_VLS_NULL ((struct bu_vls *)0)
65 
66 /**
67  * assert the integrity of a bu_vls struct.
68  */
69 #define BU_CK_VLS(_vp) BU_CKMAG(_vp, BU_VLS_MAGIC, "bu_vls")
70 
71 /**
72  * initializes a bu_vls struct without allocating any memory.
73  */
74 #define BU_VLS_INIT(_vp) { \
75  (_vp)->vls_magic = BU_VLS_MAGIC; \
76  (_vp)->vls_str = NULL; \
77  (_vp)->vls_offset = (_vp)->vls_len = (_vp)->vls_max = 0; \
78  }
79 
80 /**
81  * macro suitable for declaration statement initialization of a bu_vls
82  * struct. does not allocate memory.
83  */
84 #define BU_VLS_INIT_ZERO { BU_VLS_MAGIC, NULL, 0, 0, 0 }
85 
86 /**
87  * returns truthfully whether a bu_vls struct has been initialized.
88  * is not reliable unless the struct has been allocated with
89  * BU_ALLOC(), bu_calloc(), or a previous call to bu_vls_init() or
90  * BU_VLS_INIT() has been made.
91  */
92 #define BU_VLS_IS_INITIALIZED(_vp) (((struct bu_vls *)(_vp) != BU_VLS_NULL) && ((_vp)->vls_magic == BU_VLS_MAGIC))
93 
94 /**
95  * No storage should be allocated at this point, and bu_vls_addr()
96  * must be able to live with that.
97  */
98 BU_EXPORT extern void bu_vls_init(struct bu_vls *vp);
99 
100 /**
101  * DEPRECATED: use if (!vls) bu_vls_init(vls)
102  *
103  * If a VLS is uninitialized, initialize it. If it is already
104  * initialized, leave it alone, caller wants to append to it.
105  */
106 DEPRECATED BU_EXPORT extern void bu_vls_init_if_uninit(struct bu_vls *vp);
107 
108 /**
109  * Allocate storage for a struct bu_vls, call bu_vls_init on it, and
110  * return the result. Allows for creation of dynamically allocated
111  * VLS strings.
112  */
113 BU_EXPORT extern struct bu_vls *bu_vls_vlsinit(void);
114 
115 /**
116  * Return a pointer to the null-terminated string in the vls array.
117  * If no storage has been allocated yet, give back a valid string.
118  */
119 BU_EXPORT extern char *bu_vls_addr(const struct bu_vls *vp);
120 
121 /**
122  * Return a pointer to the null-terminated string in the vls array.
123  * If no storage has been allocated yet, give back a valid string.
124  * (At the moment this function is a mnemonically-named convenience
125  * function which returns a call to bu_vls_addr.)
126  */
127 BU_EXPORT extern const char *bu_vls_cstr(const struct bu_vls *vp);
128 
129 /**
130  * Ensure that the provided VLS has at least 'extra' characters of
131  * space available. Additional space is allocated in minimum step
132  * sized amounts and may allocate more than requested.
133  */
134 BU_EXPORT extern void bu_vls_extend(struct bu_vls *vp,
135  size_t extra);
136 
137 /**
138  * Ensure that the vls has a length of at least 'newlen', and make
139  * that the current length.
140  *
141  * Useful for subroutines that are planning on mucking with the data
142  * array themselves. Not advisable, but occasionally useful.
143  *
144  * Does not change the offset from the front of the buffer, if any.
145  * Does not initialize the value of any of the new bytes.
146  */
147 BU_EXPORT extern void bu_vls_setlen(struct bu_vls *vp,
148  size_t newlen);
149 /**
150  * Return length of the string, in bytes, not including the null
151  * terminator.
152  */
153 BU_EXPORT extern size_t bu_vls_strlen(const struct bu_vls *vp);
154 
155 /**
156  * Truncate string to at most 'len' characters. If 'len' is negative,
157  * trim off that many from the end. If 'len' is zero, don't release
158  * storage -- user is probably just going to refill it again,
159  * e.g. with bu_vls_gets().
160  */
161 BU_EXPORT extern void bu_vls_trunc(struct bu_vls *vp,
162  int len);
163 
164 /**
165  * "Nibble" 'len' characters off the front of the string. Changes the
166  * length and offset; no data is copied.
167  *
168  * 'len' may be positive or negative. If negative, characters are
169  * un-nibbled.
170  */
171 BU_EXPORT extern void bu_vls_nibble(struct bu_vls *vp,
172  off_t len);
173 
174 /**
175  * Releases the memory used for the string buffer.
176  */
177 BU_EXPORT extern void bu_vls_free(struct bu_vls *vp);
178 
179 /**
180  * Releases the memory used for the string buffer and the memory for
181  * the vls structure
182  */
183 BU_EXPORT extern void bu_vls_vlsfree(struct bu_vls *vp);
184 /**
185  * Return a dynamic copy of a vls. Memory for the string being
186  * returned is acquired using bu_malloc() implying the caller must
187  * bu_free() the returned string.
188  */
189 BU_EXPORT extern char *bu_vls_strdup(const struct bu_vls *vp);
190 
191 /**
192  * Like bu_vls_strdup(), but destructively grab the string from the
193  * source argument 'vp'. This is more efficient than bu_vls_strdup()
194  * for those instances where the source argument 'vp' is no longer
195  * needed by the caller, as it avoids a potentially long buffer copy.
196  *
197  * The source string is destroyed, as if bu_vls_free() had been
198  * called.
199  */
200 BU_EXPORT extern char *bu_vls_strgrab(struct bu_vls *vp);
201 
202 /**
203  * Empty the vls string, and copy in a regular string.
204  */
205 BU_EXPORT extern void bu_vls_strcpy(struct bu_vls *vp,
206  const char *s);
207 
208 /**
209  * Empty the vls string, and copy in a regular string, up to N bytes
210  * long.
211  */
212 BU_EXPORT extern void bu_vls_strncpy(struct bu_vls *vp,
213  const char *s,
214  size_t n);
215 
216 /**
217  * Concatenate a new string onto the end of the existing vls string.
218  */
219 BU_EXPORT extern void bu_vls_strcat(struct bu_vls *vp,
220  const char *s);
221 
222 /**
223  * Concatenate a new string onto the end of the existing vls string.
224  */
225 BU_EXPORT extern void bu_vls_strncat(struct bu_vls *vp,
226  const char *s,
227  size_t n);
228 
229 /**
230  * Concatenate a new vls string onto the end of an existing vls
231  * string. The storage of the source string is not affected.
232  */
233 BU_EXPORT extern void bu_vls_vlscat(struct bu_vls *dest,
234  const struct bu_vls *src);
235 
236 /**
237  * Concatenate a new vls string onto the end of an existing vls
238  * string. The storage of the source string is released (zapped).
239  */
240 BU_EXPORT extern void bu_vls_vlscatzap(struct bu_vls *dest,
241  struct bu_vls *src);
242 
243 /**
244  * Lexicographically compare two vls strings. Returns an integer
245  * greater than, equal to, or less than 0, according as the string s1
246  * is greater than, equal to, or less than the string s2.
247  */
248 BU_EXPORT extern int bu_vls_strcmp(struct bu_vls *s1,
249  struct bu_vls *s2);
250 
251 /**
252  * Lexicographically compare two vls strings up to n characters.
253  * Returns an integer greater than, equal to, or less than 0,
254  * according as the string s1 is greater than, equal to, or less than
255  * the string s2.
256  */
257 BU_EXPORT extern int bu_vls_strncmp(struct bu_vls *s1,
258  struct bu_vls *s2,
259  size_t n);
260 
261 /**
262  * Given and argc & argv pair, convert them into a vls string of
263  * space-separated words.
264  */
265 BU_EXPORT extern void bu_vls_from_argv(struct bu_vls *vp,
266  int argc,
267  const char *argv[]);
268 
269 /**
270  * Write the VLS to the provided file pointer.
271  */
272 BU_EXPORT extern void bu_vls_fwrite(FILE *fp,
273  const struct bu_vls *vp);
274 
275 /**
276  * Write the VLS to the provided file descriptor.
277  */
278 BU_EXPORT extern void bu_vls_write(int fd,
279  const struct bu_vls *vp);
280 
281 /**
282  * Read the remainder of a UNIX file onto the end of a vls.
283  *
284  * Returns -
285  * nread number of characters read
286  * 0 if EOF encountered immediately
287  * -1 read error
288  */
289 BU_EXPORT extern int bu_vls_read(struct bu_vls *vp,
290  int fd);
291 
292 /**
293  * Append a newline-terminated string from the file pointed to by "fp"
294  * to the end of the vls pointed to by "vp". The newline from the
295  * file is read, but not stored into the vls.
296  *
297  * The most common error is to forget to bu_vls_trunc(vp, 0) before
298  * reading the next line into the vls.
299  *
300  * Returns -
301  * >=0 the length of the resulting vls
302  * -1 on EOF where no characters were read or added to the vls
303  */
304 BU_EXPORT extern int bu_vls_gets(struct bu_vls *vp,
305  FILE *fp);
306 
307 /**
308  * Append the given character to the vls.
309  */
310 BU_EXPORT extern void bu_vls_putc(struct bu_vls *vp,
311  int c);
312 
313 /**
314  * Remove leading and trailing white space from a vls string.
315  */
316 BU_EXPORT extern void bu_vls_trimspace(struct bu_vls *vp);
317 
318 
319 /**
320  * Format a string into a vls using standard variable arguments.
321  *
322  * %s continues to be a regular null-terminated 'C' string (char *).
323  * %V is a libbu variable-length string (struct bu_vls *).
324  *
325  * Other format specifiers should behave identical to printf().
326  *
327  * This routine appends to the given vls similar to how vprintf
328  * appends to stdout (see bu_vls_sprintf for overwriting the vls).
329  * The implementation ends up calling bu_vls_vprintf().
330  */
331 BU_EXPORT extern void bu_vls_printf(struct bu_vls *vls,
332  const char *fmt, ...) _BU_ATTR_PRINTF23;
333 
334 /**
335  * Format a string into a vls, setting the vls to the given print
336  * specifier expansion. This routine truncates any existing vls
337  * contents beforehand (i.e. it doesn't append, see bu_vls_vprintf for
338  * appending to the vls).
339  *
340  * %s continues to be a regular 'C' string, null terminated.
341  * %V is a pointer to a (struct bu_vls *) string.
342  */
343 BU_EXPORT extern void bu_vls_sprintf(struct bu_vls *vls,
344  const char *fmt, ...) _BU_ATTR_PRINTF23;
345 
346 /**
347  * Efficiently append 'cnt' spaces to the current vls.
348  */
349 BU_EXPORT extern void bu_vls_spaces(struct bu_vls *vp,
350  size_t cnt);
351 
352 /**
353  * Returns number of printed spaces used on final output line of a
354  * potentially multi-line vls. Useful for making decisions on when to
355  * line-wrap.
356  *
357  * Accounts for normal UNIX tab-expansion:
358  * 1 2 3 4
359  * 1234567890123456789012345678901234567890
360  * x x x x
361  *
362  * 0-7 --> 8, 8-15 --> 16, 16-23 --> 24, etc.
363  */
364 BU_EXPORT extern size_t bu_vls_print_positions_used(const struct bu_vls *vp);
365 
366 /**
367  * Given a vls, return a version of that string which has had all
368  * "tab" characters converted to the appropriate number of spaces
369  * according to the UNIX tab convention.
370  */
371 BU_EXPORT extern void bu_vls_detab(struct bu_vls *vp);
372 
373 
374 /**
375  * Add a string to the beginning of the vls.
376  */
377 BU_EXPORT extern void bu_vls_prepend(struct bu_vls *vp,
378  char *str);
379 
380 
381 /**
382  * Copy a substring from a source vls into a destination vls
383  *
384  * where:
385  *
386  * begin - the index (0-based) of the beginning character position
387  * in the source vls
388  * nchars - the number of characters to copy
389  *
390  */
391 BU_EXPORT extern void bu_vls_substr(struct bu_vls *dest, const struct bu_vls *src,
392  size_t begin, size_t nchars);
393 
394 
395 /** @file libbu/vls_vprintf.c
396  *
397  @brief
398  * Variable Length Strings
399  *
400  * This structure provides support for variable length strings,
401  * freeing the programmer from concerns about having character arrays
402  * large enough to hold strings.
403  *
404  * Assumption: libc-provided sprintf() function is safe to use in parallel,
405  * on parallel systems.
406  */
407 /**
408  * Format a string into a vls using a varargs list.
409  *
410  * %s continues to be a regular null-terminated 'C' string (char *).
411  * %V is a libbu variable-length string (struct bu_vls *).
412  *
413  * Other format specifiers should behave identical to printf().
414  *
415  * This routine appends to the given vls similar to how vprintf
416  * appends to stdout (see bu_vls_sprintf for overwriting the vls).
417  */
418 BU_EXPORT extern void bu_vls_vprintf(struct bu_vls *vls,
419  const char *fmt,
420  va_list ap);
421 
422 
423 /** @file libbu/encode.c
424  *
425  @brief
426  * Routines to encode/decode strings into bu_vls structures.
427  */
428 /**
429  * given an input string, wrap the string in double quotes if there is
430  * a space and append it to the provided bu_vls. escape any existing
431  * double quotes.
432  *
433  * TODO: consider a specifiable quote character and octal encoding
434  * instead of double quote wrapping. perhaps specifiable encode type:
435  * BU_ENCODE_QUOTE
436  * BU_ENCODE_OCTAL
437  * BU_ENCODE_XML
438  *
439  * More thoughts on encode/decode - the nature of "quoting" is going to
440  * vary depending on the usage context and the language. For some
441  * applications, HEX or BASE64 may be appropriate. For others (like
442  * the problems with arbitrary strings in Tcl which initially motivated
443  * these functions) such wholesale encoding is not needed and it is just
444  * a subset of characters that must be escaped or otherwise identified.
445  *
446  * Given the large set of possible scenarios, it definitely makes sense
447  * to allow an encoding specifiying variable, and probably other optional
448  * variables (which may be NULL, depending on the encoding type) specifying
449  * active characters (that need quoting) and an escape character (or
450  * characters? does it take more than one in some scenarios? perhaps start
451  * and end of escape strings would be the most general?)
452  *
453  * This probably makes sense as its own header given that is is really
454  * a feature on top of vls rather than something integral to vls
455  * itself - it would be workable (maybe even practical, if the final
456  * length of the encoded data can be pre-determined) to just work with
457  * char arrays: see bu_str_escape()
458  *
459  * the behavior of this routine is subject to change but should remain
460  * a reversible operation when used in conjunction with
461  * bu_vls_decode().
462  *
463  * returns a pointer to the encoded string (i.e., the substring held
464  * within the bu_vls)
465  */
466 BU_EXPORT extern const char *bu_vls_encode(struct bu_vls *vp, const char *str);
467 
468 
469 /**
470  * given an encoded input string, unwrap the string from any
471  * surrounding double quotes and unescape any embedded double quotes.
472  *
473  * the behavior of this routine is subject to change but should remain
474  * the reverse operation of bu_vls_encode().
475  *
476  * returns a pointer to the decoded string (i.e., the substring held
477  * within the bu_vls)
478  */
479 BU_EXPORT extern const char *bu_vls_decode(struct bu_vls *vp, const char *str);
480 
482 
483 /** @} */
484 
485 #endif /* BU_VLS_H */
486 
487 /*
488  * Local Variables:
489  * mode: C
490  * tab-width: 8
491  * indent-tabs-mode: t
492  * c-file-style: "stroustrup"
493  * End:
494  * ex: shiftwidth=4 tabstop=8
495  */
void bu_vls_init(struct bu_vls *vp)
Definition: vls.c:56
const char * bu_vls_encode(struct bu_vls *vp, const char *str)
Definition: encode.c:34
void bu_vls_strncat(struct bu_vls *vp, const char *s, size_t n)
Definition: vls.c:390
uint32_t vls_magic
Definition: vls.h:57
void bu_vls_vlsfree(struct bu_vls *vp)
Definition: vls.c:263
if lu s
Definition: nmg_mod.c:3860
void bu_vls_strcat(struct bu_vls *vp, const char *s)
Definition: vls.c:368
void bu_vls_trunc(struct bu_vls *vp, int len)
Definition: vls.c:198
void bu_vls_nibble(struct bu_vls *vp, off_t len)
Definition: vls.c:217
void bu_vls_strncpy(struct bu_vls *vp, const char *s, size_t n)
Definition: vls.c:339
Header file for the BRL-CAD common definitions.
size_t vls_len
Definition: vls.h:60
#define _BU_ATTR_PRINTF23
Definition: defines.h:152
void bu_vls_free(struct bu_vls *vp)
Definition: vls.c:248
#define DEPRECATED
Definition: common.h:303
char * bu_vls_strgrab(struct bu_vls *vp)
Definition: vls.c:290
void bu_vls_from_argv(struct bu_vls *vp, int argc, const char *argv[])
Definition: vls.c:532
#define __BEGIN_DECLS
Definition: common.h:73
void bu_vls_sprintf(struct bu_vls *vls, const char *fmt,...) _BU_ATTR_PRINTF23
Definition: vls.c:707
void bu_vls_fwrite(FILE *fp, const struct bu_vls *vp)
Definition: vls.c:544
const char * bu_vls_decode(struct bu_vls *vp, const char *str)
Definition: encode.c:79
size_t bu_vls_strlen(const struct bu_vls *vp)
Definition: vls.c:189
char * bu_vls_strdup(const struct bu_vls *vp)
Definition: vls.c:274
struct bu_vls * bu_vls_vlsinit(void)
Definition: vls.c:91
const char * bu_vls_cstr(const struct bu_vls *vp)
Definition: vls.c:103
char * bu_vls_addr(const struct bu_vls *vp)
Definition: vls.c:111
size_t vls_offset
Definition: vls.h:59
void bu_vls_vprintf(struct bu_vls *vls, const char *fmt, va_list ap)
Definition: vls_vprintf.c:380
DEPRECATED void bu_vls_init_if_uninit(struct bu_vls *vp)
Definition: vls.c:77
int bu_vls_gets(struct bu_vls *vp, FILE *fp)
Definition: vls.c:621
int bu_vls_strncmp(struct bu_vls *s1, struct bu_vls *s2, size_t n)
Definition: vls.c:505
void bu_vls_printf(struct bu_vls *vls, const char *fmt,...) _BU_ATTR_PRINTF23
Definition: vls.c:694
void bu_vls_extend(struct bu_vls *vp, size_t extra)
Definition: vls.c:136
char * vls_str
Definition: vls.h:58
int bu_vls_strcmp(struct bu_vls *s1, struct bu_vls *s2)
Definition: vls.c:482
void bu_vls_substr(struct bu_vls *dest, const struct bu_vls *src, size_t begin, size_t nchars)
Definition: vls.c:447
void bu_vls_trimspace(struct bu_vls *vp)
Definition: vls.c:678
void bu_vls_strcpy(struct bu_vls *vp, const char *s)
Definition: vls.c:310
#define __END_DECLS
Definition: common.h:74
int bu_vls_read(struct bu_vls *vp, int fd)
Definition: vls.c:586
void bu_vls_spaces(struct bu_vls *vp, size_t cnt)
Definition: vls.c:721
void bu_vls_prepend(struct bu_vls *vp, char *str)
Definition: vls.c:796
void bu_vls_write(int fd, const struct bu_vls *vp)
Definition: vls.c:565
void bu_vls_vlscat(struct bu_vls *dest, const struct bu_vls *src)
Definition: vls.c:415
size_t vls_max
Definition: vls.h:61
void bu_vls_setlen(struct bu_vls *vp, size_t newlen)
Definition: vls.c:176
size_t bu_vls_print_positions_used(const struct bu_vls *vp)
Definition: vls.c:736
Definition: vls.h:56
void bu_vls_putc(struct bu_vls *vp, int c)
Definition: vls.c:666
void bu_vls_detab(struct bu_vls *vp)
Definition: vls.c:762
void bu_vls_vlscatzap(struct bu_vls *dest, struct bu_vls *src)
Definition: vls.c:433