[mLib] / dstr.h

/* -*-c-*-
 *
 * $Id: dstr.h,v 1.5 1999/05/13 22:47:57 mdw Exp $
 *
 * Handle dynamically growing strings
 *
 * (c) 1998 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------* 
 *
 * This file is part of the mLib utilities library.
 *
 * mLib is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Library General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 * 
 * mLib is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Library General Public License for more details.
 * 
 * You should have received a copy of the GNU Library General Public
 * License along with mLib; if not, write to the Free
 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 * MA 02111-1307, USA.
 */

/*----- Revision history --------------------------------------------------*
 *
 * $Log: dstr.h,v $
 * Revision 1.5  1999/05/13 22:47:57  mdw
 * Misc documentation fixes.  Change `-ise' to `-ize' throughout.
 *
 * Revision 1.4  1999/05/06 19:51:35  mdw
 * Reformatted the LGPL notice a little bit.
 *
 * Revision 1.3  1999/05/05 18:50:31  mdw
 * Change licensing conditions to LGPL.
 *
 * Revision 1.2  1998/12/15 23:53:23  mdw
 * New functions `dstr_putf' and `dstr_vputf' which do `printf'-style
 * formatting in a safe way.
 *
 * Revision 1.1.1.1  1998/06/17 23:44:42  mdw
 * Initial version of mLib
 *
 */

#ifndef DSTR_H
#define DSTR_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Rationale ---------------------------------------------------------*
 *
 * This file declares what is hopefully a fairly useful collection of
 * primitive string handling functions.  The idea is that the strings
 * allocate memory for themselves as required.  The @dstr@ routines don't
 * assume any sort of terminator character, so arbitrary binary data can
 * be stored in a dynamic string.  With luck, this should put a stop to
 * any buffer overflow problems.
 */

/*----- Header files ------------------------------------------------------*/

#include <stdarg.h>
#include <stdio.h>

/*----- Data structures ---------------------------------------------------*/

typedef struct dstr {
  char *buf;				/* Pointer to string buffer */
  size_t sz;				/* Size of the buffer */
  size_t len;				/* Length of the string */
} dstr;

/*----- Functions provided ------------------------------------------------*/

/* --- @dstr_create@ --- *
 *
 * Arguments:	@dstr *d@ = pointer to a dynamic string block
 *
 * Returns:	---
 *
 * Use:		Initializes a dynamic string.
 */

extern void dstr_create(dstr */*d*/);

/* --- @dstr_destroy@ --- *
 *
 * Arguments:	@dstr *d@ = pointer to a dynamic string block
 *
 * Returns:	---
 *
 * Use:		Reclaims the space used by a dynamic string.
 */

extern void dstr_destroy(dstr */*d*/);

/* --- @dstr_reset@ --- *
 *
 * Arguments:	@dstr *d@ = pointer to a dynaimc string block
 *
 * Returns:	---
 *
 * Use:		Resets a string so that new data gets put at the beginning.
 */

extern void dstr_reset(dstr */*d*/);

/* --- @dstr_ensure@ --- *
 *
 * Arguments:	@dstr *d@ = pointer to a dynamic string block
 *		@size_t sz@ = amount of free space to ensure
 *
 * Returns:	---
 *
 * Use:		Ensures that at least @sz@ bytes are available in the
 *		given string.
 */

extern void dstr_ensure(dstr */*d*/, size_t /*sz*/);

#define DENSURE(d, rq) do {						\
  if ((d)->len + (rq) > (d)->sz) dstr_ensure((d), (rq));		\
} while (0)

/* --- @dstr_putc@ --- *
 *
 * Arguments:	@dstr *d@ = pointer to a dynamic string block
 *		@char ch@ = character to append
 *
 * Returns:	---
 *
 * Use:		Appends a character to a string.
 */

extern void dstr_putc(dstr */*d*/, char /*ch*/);

#define DPUTC(d, ch) do {						\
  DENSURE((d), 1);							\
  (d)->buf[(d)->len++] = (ch);						\
} while (0)

/* --- @dstr_putz@ --- *
 *
 * Arguments:	@dstr *d@ = pointer to a dynamic string block
 *
 * Returns:	---
 *
 * Use:		Appends a null byte to a string.  The null byte does not
 *		contribute to the string's length, and will be overwritten
 *		by subsequent `put' operations.
 */

extern void dstr_putz(dstr */*d*/);

#define DPUTZ(d) do {							\
  DENSURE((d), 1);							\
  (d)->buf[(d)->len] = 0;						\
} while (0)

/* --- @dstr_puts@ --- *
 *
 * Arguments:	@dstr *d@ = pointer to a dynamic string block
 *		@const char *s@ = pointer to string to append
 *
 * Returns:	---
 *
 * Use:		Appends a character string to a string.  A trailing null
 *		byte is added, as for @dstr_putz@.
 */

extern void dstr_puts(dstr */*d*/, const char */*s*/);

#define DPUTS(d, s) do {						\
  size_t sz = strlen(s);						\
  DENSURE((d), sz + 1);							\
  memcpy((d)->buf + (d)->len, (s), sz + 1);				\
  (d)->len += sz;							\
} while (0)

/* --- @dstr_vputf@ --- *
 *
 * Arguments:	@dstr *d@ = pointer to a dynamic string block
 *		@const char *p@ = pointer to @printf@-style format string
 *		@va_list ap@ = argument handle
 *
 * Returns:	The number of characters written to the string.
 *
 * Use:		As for @dstr_putf@, but may be used as a back-end to user-
 *		supplied functions with @printf@-style interfaces.
 */

extern int dstr_vputf(dstr */*d*/, const char */*p*/, va_list /*ap*/);

/* --- @dstr_putf@ --- *
 *
 * Arguments:	@dstr *d@ = pointer to a dynamic string block
 *		@const char *p@ = pointer to @printf@-style format string
 *		@...@ = argument handle
 *
 * Returns:	The number of characters written to the string.
 *
 * Use:		Writes a piece of text to a dynamic string, doing @printf@-
 *		style substitutions as it goes.  Intended to be robust if
 *		faced with malicious arguments, but not if the format string
 *		itself is malicious.
 */

extern int dstr_putf(dstr */*d*/, const char */*p*/, ...);

/* --- @dstr_putd@ --- *
 *
 * Arguments:	@dstr *d@ = pointer to a dynamic string block
 *		@const dstr *s@ = pointer to a dynamic string to append
 *
 * Returns:	---
 *
 * Use:		Appends a dynamic string to a string.  A trailing null
 *		byte is added, as for @dstr_putz@.
 */

extern void dstr_putd(dstr */*d*/, const dstr */*s*/);

#define DPUTD(d, s) do {						\
  DENSURE((d), (s)->len + 1);						\
  memcpy((d)->buf + (d)->len, (s)->buf, (s)->len);			\
  (d)->len += (s)->len;							\
  (d)->buf[(d)->len] = 0;						\
} while (0)

/* --- @dstr_putm@ --- *
 *
 * Arguments:	@dstr *d@ = pointer to a dynamic string block
 *		@const void *p@ = pointer to a block to append
 *		@size_t sz@ = size of the block
 *
 * Returns:	Appends an arbitrary data block to a string.  No trailing
 *		null is appended.
 */

extern void dstr_putm(dstr */*d*/, const void */*p*/, size_t /*sz*/);

#define DPUTM(d, p, sz) do {						\
  DENSURE((d), (sz));							\
  memcpy((d)->buf + (d)->len, (p), (sz));				\
  (d)->len += (sz);							\
} while (0)

/* --- @dstr_tidy@ --- *
 *
 * Arguments:	@dstr *d@ = pointer to a dynamic string block
 *
 * Returns:	---
 *
 * Use:		Reduces the amount of memory used by a string.  A trailing
 *		null byte is added, as for @dstr_putz@.
 */

extern void dstr_tidy(dstr */*d*/);

/* --- @dstr_putline@ --- *
 *
 * Arguments:	@dstr *d@ = pointer to a dynamic string block
 *		@FILE *fp@ = a stream to read from
 *
 * Returns:	The number of characters read into the buffer, or @EOF@ if
 *		end-of-file was reached before any characters were read.
 *
 * Use:		Appends the next line from the given input stream to the
 *		string.  A trailing newline is not added; a trailing null
 *		byte is appended, as for @dstr_putz@.
 */

extern int dstr_putline(dstr */*d*/, FILE */*fp*/);

/* --- @dstr_write@ --- *
 *
 * Arguments:	@dstr *d@ = pointer to a dynamic string block
 *		@FILE *fp@ = a stream to write on
 *
 * Returns:	The number of bytes written (as for @fwrite@).
 *
 * Use:		Writes a dynamic string to a file.
 */

extern size_t dstr_write(const dstr */*d*/, FILE */*fp*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif
Commit	Line	Data
0875b58f	1	/* --c--
0875b58f	2	*
96c5fe33	3	* $Id: dstr.h,v 1.5 1999/05/13 22:47:57 mdw Exp $
0875b58f	4	*
	5	* Handle dynamically growing strings
	6	*
	7	* (c) 1998 Straylight/Edgeware
	8	*/
	9
c846879c	10	/----- Licensing notice --------------------------------------------------
0875b58f	11	*
	12	* This file is part of the mLib utilities library.
	13	*
	14	* mLib is free software; you can redistribute it and/or modify
c846879c	15	* it under the terms of the GNU Library General Public License as
	16	* published by the Free Software Foundation; either version 2 of the
	17	* License, or (at your option) any later version.
	18	*
0875b58f	19	* mLib is distributed in the hope that it will be useful,
	20	* but WITHOUT ANY WARRANTY; without even the implied warranty of
	21	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
c846879c	22	* GNU Library General Public License for more details.
	23	*
	24	* You should have received a copy of the GNU Library General Public
0bd98442	25	* License along with mLib; if not, write to the Free
	26	* Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
	27	* MA 02111-1307, USA.
0875b58f	28	*/
	29
	30	/----- Revision history --------------------------------------------------
	31	*
	32	* $Log: dstr.h,v $
96c5fe33	33	* Revision 1.5 1999/05/13 22:47:57 mdw
	34	* Misc documentation fixes. Change `-ise' to `-ize' throughout.
	35	*
0bd98442	36	* Revision 1.4 1999/05/06 19:51:35 mdw
	37	* Reformatted the LGPL notice a little bit.
	38	*
c846879c	39	* Revision 1.3 1999/05/05 18:50:31 mdw
	40	* Change licensing conditions to LGPL.
	41	*
00c7638b	42	* Revision 1.2 1998/12/15 23:53:23 mdw
	43	* New functions `dstr_putf' and `dstr_vputf' which do `printf'-style
	44	* formatting in a safe way.
	45	*
	46	* Revision 1.1.1.1 1998/06/17 23:44:42 mdw
	47	* Initial version of mLib
0875b58f	48	*
	49	*/
	50
	51	#ifndef DSTR_H
	52	#define DSTR_H
	53
	54	#ifdef __cplusplus
	55	extern "C" {
	56	#endif
	57
	58	/----- Rationale ---------------------------------------------------------
	59	*
	60	* This file declares what is hopefully a fairly useful collection of
	61	* primitive string handling functions. The idea is that the strings
	62	* allocate memory for themselves as required. The @dstr@ routines don't
	63	* assume any sort of terminator character, so arbitrary binary data can
	64	* be stored in a dynamic string. With luck, this should put a stop to
	65	* any buffer overflow problems.
	66	*/
	67
	68	/----- Header files ------------------------------------------------------/
	69
00c7638b	70	#include <stdarg.h>
0875b58f	71	#include <stdio.h>
	72
	73	/----- Data structures ---------------------------------------------------/
	74
	75	typedef struct dstr {
	76	char buf; / Pointer to string buffer */
	77	size_t sz; /* Size of the buffer */
	78	size_t len; /* Length of the string */
	79	} dstr;
	80
	81	/----- Functions provided ------------------------------------------------/
	82
	83	/* --- @dstr_create@ --- *
	84	*
	85	* Arguments: @dstr *d@ = pointer to a dynamic string block
	86	*
	87	* Returns: ---
	88	*
96c5fe33	89	* Use: Initializes a dynamic string.
0875b58f	90	*/
	91
	92	extern void dstr_create(dstr /d*/);
	93
	94	/* --- @dstr_destroy@ --- *
	95	*
	96	* Arguments: @dstr *d@ = pointer to a dynamic string block
	97	*
	98	* Returns: ---
	99	*
	100	* Use: Reclaims the space used by a dynamic string.
	101	*/
	102
	103	extern void dstr_destroy(dstr /d*/);
	104
	105	/* --- @dstr_reset@ --- *
	106	*
	107	* Arguments: @dstr *d@ = pointer to a dynaimc string block
	108	*
	109	* Returns: ---
	110	*
	111	* Use: Resets a string so that new data gets put at the beginning.
	112	*/
	113
	114	extern void dstr_reset(dstr /d*/);
	115
	116	/* --- @dstr_ensure@ --- *
	117	*
	118	* Arguments: @dstr *d@ = pointer to a dynamic string block
	119	* @size_t sz@ = amount of free space to ensure
	120	*
	121	* Returns: ---
	122	*
	123	* Use: Ensures that at least @sz@ bytes are available in the
	124	* given string.
	125	*/
	126
	127	extern void dstr_ensure(dstr /d/, size_t /sz*/);
	128
	129	#define DENSURE(d, rq) do { \
	130	if ((d)->len + (rq) > (d)->sz) dstr_ensure((d), (rq)); \
	131	} while (0)
	132
	133	/* --- @dstr_putc@ --- *
	134	*
	135	* Arguments: @dstr *d@ = pointer to a dynamic string block
	136	* @char ch@ = character to append
	137	*
	138	* Returns: ---
	139	*
	140	* Use: Appends a character to a string.
	141	*/
	142
	143	extern void dstr_putc(dstr /d/, char /ch*/);
	144
	145	#define DPUTC(d, ch) do { \
	146	DENSURE((d), 1); \
	147	(d)->buf[(d)->len++] = (ch); \
	148	} while (0)
	149
	150	/* --- @dstr_putz@ --- *
	151	*
	152	* Arguments: @dstr *d@ = pointer to a dynamic string block
	153	*
154	* Returns: ---
155	*
156	* Use: Appends a null byte to a string. The null byte does not
157	* contribute to the string's length, and will be overwritten
158	* by subsequent `put' operations.
159	*/
160
161	extern void dstr_putz(dstr /d*/);
162
163	#define DPUTZ(d) do { \
164	DENSURE((d), 1); \
165	(d)->buf[(d)->len] = 0; \
166	} while (0)
167
168	/* --- @dstr_puts@ --- *
169	*
170	* Arguments: @dstr *d@ = pointer to a dynamic string block
171	* @const char *s@ = pointer to string to append
172	*
173	* Returns: ---
174	*
175	* Use: Appends a character string to a string. A trailing null
176	* byte is added, as for @dstr_putz@.
177	*/
178
179	extern void dstr_puts(dstr /d/, const char /s/);
180
181	#define DPUTS(d, s) do { \
182	size_t sz = strlen(s); \
183	DENSURE((d), sz + 1); \
184	memcpy((d)->buf + (d)->len, (s), sz + 1); \
185	(d)->len += sz; \
186	} while (0)
187
00c7638b	188	/* --- @dstr_vputf@ --- *
	189	*
	190	* Arguments: @dstr *d@ = pointer to a dynamic string block
	191	* @const char *p@ = pointer to @printf@-style format string
	192	* @va_list ap@ = argument handle
	193	*
96c5fe33	194	* Returns: The number of characters written to the string.
00c7638b	195	*
	196	* Use: As for @dstr_putf@, but may be used as a back-end to user-
	197	* supplied functions with @printf@-style interfaces.
	198	*/
	199
	200	extern int dstr_vputf(dstr /d/, const char /p/, va_list /ap/);
	201
	202	/* --- @dstr_putf@ --- *
	203	*
	204	* Arguments: @dstr *d@ = pointer to a dynamic string block
	205	* @const char *p@ = pointer to @printf@-style format string
	206	* @...@ = argument handle
	207	*
96c5fe33	208	* Returns: The number of characters written to the string.
00c7638b	209	*
	210	* Use: Writes a piece of text to a dynamic string, doing @printf@-
	211	* style substitutions as it goes. Intended to be robust if
	212	* faced with malicious arguments, but not if the format string
	213	* itself is malicious.
	214	*/
	215
	216	extern int dstr_putf(dstr /d/, const char /p/, ...);
	217
0875b58f	218	/* --- @dstr_putd@ --- *
	219	*
	220	* Arguments: @dstr *d@ = pointer to a dynamic string block
	221	* @const dstr *s@ = pointer to a dynamic string to append
	222	*
	223	* Returns: ---
	224	*
	225	* Use: Appends a dynamic string to a string. A trailing null
	226	* byte is added, as for @dstr_putz@.
	227	*/
	228
	229	extern void dstr_putd(dstr /d/, const dstr /s/);
	230
	231	#define DPUTD(d, s) do { \
	232	DENSURE((d), (s)->len + 1); \
	233	memcpy((d)->buf + (d)->len, (s)->buf, (s)->len); \
	234	(d)->len += (s)->len; \
	235	(d)->buf[(d)->len] = 0; \
	236	} while (0)
	237
	238	/* --- @dstr_putm@ --- *
	239	*
	240	* Arguments: @dstr *d@ = pointer to a dynamic string block
	241	* @const void *p@ = pointer to a block to append
	242	* @size_t sz@ = size of the block
	243	*
	244	* Returns: Appends an arbitrary data block to a string. No trailing
	245	* null is appended.
	246	*/
	247
	248	extern void dstr_putm(dstr /d/, const void /p/, size_t /sz/);
	249
	250	#define DPUTM(d, p, sz) do { \
	251	DENSURE((d), (sz)); \
	252	memcpy((d)->buf + (d)->len, (p), (sz)); \
	253	(d)->len += (sz); \
	254	} while (0)
	255
	256	/* --- @dstr_tidy@ --- *
	257	*
	258	* Arguments: @dstr *d@ = pointer to a dynamic string block
	259	*
	260	* Returns: ---
	261	*
	262	* Use: Reduces the amount of memory used by a string. A trailing
	263	* null byte is added, as for @dstr_putz@.
	264	*/
	265
	266	extern void dstr_tidy(dstr /d*/);
	267
	268	/* --- @dstr_putline@ --- *
	269	*
	270	* Arguments: @dstr *d@ = pointer to a dynamic string block
	271	* @FILE *fp@ = a stream to read from
	272	*
	273	* Returns: The number of characters read into the buffer, or @EOF@ if
	274	* end-of-file was reached before any characters were read.
	275	*
	276	* Use: Appends the next line from the given input stream to the
	277	* string. A trailing newline is not added; a trailing null
	278	* byte is appended, as for @dstr_putz@.
	279	*/
	280
	281	extern int dstr_putline(dstr /d/, FILE /fp/);
282
283	/* --- @dstr_write@ --- *
284	*
285	* Arguments: @dstr *d@ = pointer to a dynamic string block
286	* @FILE *fp@ = a stream to write on
287	*
288	* Returns: The number of bytes written (as for @fwrite@).
289	*
290	* Use: Writes a dynamic string to a file.
291	*/
292
96c5fe33	293	extern size_t dstr_write(const dstr /d/, FILE /fp/);
0875b58f	294
	295	/----- That's all, folks -------------------------------------------------/
	296
	297	#ifdef __cplusplus
	298	}
	299	#endif
	300
	301	#endif