ascend/general/dstring.h

/*
 *  Dynamic String Utilities
 *
 *  Version: $Revision: 1.1 $
 *  Version control file: $RCSfile: dstring.h,v $
 *  Date last modified: $Date: 1997/07/18 11:41:38 $
 *  Last modified by: $Author: mthomas $
 *
 *  This file is part of the Ascend Environment.
 *
 *  The Ascend Environment is free software; you can redistribute it
 *  and/or modify it under the terms of the GNU General Public License as
 *  published by the Free Software Foundation; either version 2 of the
 *  License, or (at your option) any later version.
 *
 *  The Ascend Environment is distributed in 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
 *  General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with the program; if not, write to the Free Software Foundation,
 *  Inc., 675 Mass Ave, Cambridge, MA 02139 USA.  Check the file named
 *  COPYING.
 */

/** @file
 *  Dynamic String Utilities.
 *  These routines are modifications of TCL code by John Osterhout at 
 *  Berkeley, as allowed by the TCL distribution license.  See dstring.c 
 *  for the details. There are minor differences internally.
 *  <pre>
 *  Requires:
 *        #include "utilities/ascConfig.h"
 *  </pre>
 */

#ifndef ASC_DSTRING_H
#define ASC_DSTRING_H

#define ASC_RESULT_SIZE 200
#define ASC_DSTRING_STATIC_SIZE 200
#define ASC_ALL_STRING -1

/** Dynamic string data structure. */
typedef struct Asc_DString {
  char *string;   /**< Points to beginning of string:  either
                       staticSpace below or a malloc'ed array. */
  int length;     /**< Number of non-NULL characters in the string. */
  int spaceAvl;   /**< Total number of bytes available for the
                       string and its terminating NULL char. */
  char staticSpace[ASC_DSTRING_STATIC_SIZE];
                   /**< Space to use in common case where string is small. */
} Asc_DString;

/*----------------------------------------------------------------------*/
/**
 *  Returns the current length of the string.
 *  The return value is the number of non-NULL characters in
 *  the string, an integer.  dsPtr may not be NULL (not
 *  checked - crash probable).
 *
 *  @param dsPtr Asc_DString *, pointer to a structure
 *               describing the dynamic string to query.
 */
#define Asc_DStringLength(dsPtr) ((dsPtr)->length)


/*----------------------------------------------------------------------*/
/**
 *  Returns the current value of the string.
 *  The return value is a pointer to the first character in the
 *  string, a char*.  The client should not free or modify this
 *  value.  dsPtr may not be NULL (not checked - crash probable).
 *
 *  @param dsPtr Asc_DString *, pointer to a structure
 *               describing the dynamic string to query.
 */
#define Asc_DStringValue(dsPtr) ((dsPtr)->string)

/*----------------------------------------------------------------------*/
/**
 *  Appends more characters to the specified dynamic string.
 *  Length bytes from string (or all of string if length is less
 *  than zero) are added to the current value of the string.  If
 *  string is shorter than length, only the length of string 
 *  characters are appended.  The resulting value of the
 *  dynamic string is always null-terminated.
 *  <p />
 *  Memory  gets reallocated if needed to accomodate the string's
 *  new size.  Neither dpPtr nor string may be NULL (checked by
 *  assertion).
 *
 *  @param dsPtr  Structure describing dynamic string (non-NULL).
 *  @param string String to append (non-NULL).  If length is -1
 *                then this must be null-terminated.
 *  @param length Number of characters from string to append. If
 *                < 0, then append all of string, up to null at end.
 *  @return Returns the new value of the dynamic string.
 */
ASC_DLLSPEC char *Asc_DStringAppend(register Asc_DString *dsPtr,
                               CONST char *string,
                               int length);

/*----------------------------------------------------------------------*/
/**
 *  Frees up any memory allocated for the dynamic string and
 *  reinitializes the string to an empty state.  The previous
 *  contents of the dynamic string are lost, and the new value
 *  is an empty string.  Note that dsPtr may not be NULL
 *  (checked by assertion).
 *
 *  @param dsPtr Structure describing dynamic string (non-NULL).
*/
ASC_DLLSPEC void Asc_DStringFree(Asc_DString *dsPtr);

/*----------------------------------------------------------------------*/
/**
 *  Initializes a dynamic string, discarding any previous contents
 *  of the string.  Asc_DStringFree() should have been called already
 *  if the dynamic string was previously in use.  The dynamic string
 *  is initialized to be empty.  The passed pointer dsPtr may not
 *  be NULL (checked by assertion).
 *
 *  @param dsPtr Pointer to structure for dynamic string (non-NULL).
 */
ASC_DLLSPEC void Asc_DStringInit(register Asc_DString *dsPtr);

/*----------------------------------------------------------------------*/
/**
 *  Returns a *copy* of the string held within the dynamic string.
 *  The returned string is owned by the caller, who is responsible
 *  for free'ing it when done with it.  The dynamic string itself
 *  is reinitialized to an empty string.  dsPtr may not be NULL
 *  (checked by assertion).
 *
 *  @param dsPtr dsPtr Dynamic string holding the returned result.
 *  @return Returns a copy of the original value of the dynamic string.
*/
ASC_DLLSPEC char *Asc_DStringResult(Asc_DString *dsPtr);

/*----------------------------------------------------------------------*/
/**
 *  Truncates a dynamic string to a given length without freeing
 *  up its storage.     The length of dsPtr is reduced to length
 *  unless it was already shorter than that.  Passing a length
 *  < 0 sets the new length to zero.  dsPtr may not be NULL
 *  (checked by assertion).
 *
 *  @param dsPtr  Structure describing dynamic string (non-NULL).
 *  @param length New maximum length for the dynamic string.
 */
ASC_DLLSPEC void Asc_DStringTrunc(Asc_DString *dsPtr, int length);

/*----------------------------------------------------------------------*/
/**
 *  Sets the value of the dynamic string to the specified string.
 *  String must be null-terminated.
 *  Memory gets reallocated if needed to accomodate the string's new
 *  size.  Neither dsPtr nor string may be NULL (checked by assertion).
 *
 *  @param dsPtr   Structure describing dynamic string (non-NULL).
 *  @param string  String to append (non-NULL, null-terminated).
 *  @return Returns the new value of the dynamic string.
 */
ASC_DLLSPEC char *Asc_DStringSet(Asc_DString *dsPtr, CONST char *string);

#endif /* ASC_DSTRING_H */

1	/*
2	* Dynamic String Utilities
3	*
4	* Version: $Revision: 1.1 $
5	* Version control file: $RCSfile: dstring.h,v $
6	* Date last modified: $Date: 1997/07/18 11:41:38 $
7	* Last modified by: $Author: mthomas $
8	*
9	* This file is part of the Ascend Environment.
10	*
11	* The Ascend Environment is free software; you can redistribute it
12	* and/or modify it under the terms of the GNU General Public License as
13	* published by the Free Software Foundation; either version 2 of the
14	* License, or (at your option) any later version.
15	*
16	* The Ascend Environment is distributed in hope that it will be useful,
17	* but WITHOUT ANY WARRANTY; without even the implied warranty of
18	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19	* General Public License for more details.
20	*
21	* You should have received a copy of the GNU General Public License
22	* along with the program; if not, write to the Free Software Foundation,
23	* Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check the file named
24	* COPYING.
25	*/
26
27	/** @file
28	* Dynamic String Utilities.
29	* These routines are modifications of TCL code by John Osterhout at
30	* Berkeley, as allowed by the TCL distribution license. See dstring.c
31	* for the details. There are minor differences internally.
32	* <pre>
33	* Requires:
34	* #include "utilities/ascConfig.h"
35	* </pre>
36	*/
37
38	#ifndef ASC_DSTRING_H
39	#define ASC_DSTRING_H
40
41	#define ASC_RESULT_SIZE 200
42	#define ASC_DSTRING_STATIC_SIZE 200
43	#define ASC_ALL_STRING -1
44
45	/** Dynamic string data structure. */
46	typedef struct Asc_DString {
47	char string; /*< Points to beginning of string: either
48	staticSpace below or a malloc'ed array. */
49	int length; /*< Number of non-NULL characters in the string. /
50	int spaceAvl; /**< Total number of bytes available for the
51	string and its terminating NULL char. */
52	char staticSpace[ASC_DSTRING_STATIC_SIZE];
53	/*< Space to use in common case where string is small. /
54	} Asc_DString;
55
56	/----------------------------------------------------------------------/
57	/**
58	* Returns the current length of the string.
59	* The return value is the number of non-NULL characters in
60	* the string, an integer. dsPtr may not be NULL (not
61	* checked - crash probable).
62	*
63	* @param dsPtr Asc_DString *, pointer to a structure
64	* describing the dynamic string to query.
65	*/
66	#define Asc_DStringLength(dsPtr) ((dsPtr)->length)
67
68
69	/----------------------------------------------------------------------/
70	/**
71	* Returns the current value of the string.
72	* The return value is a pointer to the first character in the
73	* string, a char*. The client should not free or modify this
74	* value. dsPtr may not be NULL (not checked - crash probable).
75	*
76	* @param dsPtr Asc_DString *, pointer to a structure
77	* describing the dynamic string to query.
78	*/
79	#define Asc_DStringValue(dsPtr) ((dsPtr)->string)
80
81	/----------------------------------------------------------------------/
82	/**
83	* Appends more characters to the specified dynamic string.
84	* Length bytes from string (or all of string if length is less
85	* than zero) are added to the current value of the string. If
86	* string is shorter than length, only the length of string
87	* characters are appended. The resulting value of the
88	* dynamic string is always null-terminated.
89	* <p />
90	* Memory gets reallocated if needed to accomodate the string's
91	* new size. Neither dpPtr nor string may be NULL (checked by
92	* assertion).
93	*
94	* @param dsPtr Structure describing dynamic string (non-NULL).
95	* @param string String to append (non-NULL). If length is -1
96	* then this must be null-terminated.
97	* @param length Number of characters from string to append. If
98	* < 0, then append all of string, up to null at end.
99	* @return Returns the new value of the dynamic string.
100	*/
101	ASC_DLLSPEC char Asc_DStringAppend(register Asc_DString dsPtr,
102	CONST char *string,
103	int length);
104
105	/----------------------------------------------------------------------/
106	/**
107	* Frees up any memory allocated for the dynamic string and
108	* reinitializes the string to an empty state. The previous
109	* contents of the dynamic string are lost, and the new value
110	* is an empty string. Note that dsPtr may not be NULL
111	* (checked by assertion).
112	*
113	* @param dsPtr Structure describing dynamic string (non-NULL).
114	*/
115	ASC_DLLSPEC void Asc_DStringFree(Asc_DString *dsPtr);
116
117	/----------------------------------------------------------------------/
118	/**
119	* Initializes a dynamic string, discarding any previous contents
120	* of the string. Asc_DStringFree() should have been called already
121	* if the dynamic string was previously in use. The dynamic string
122	* is initialized to be empty. The passed pointer dsPtr may not
123	* be NULL (checked by assertion).
124	*
125	* @param dsPtr Pointer to structure for dynamic string (non-NULL).
126	*/
127	ASC_DLLSPEC void Asc_DStringInit(register Asc_DString *dsPtr);
128
129	/----------------------------------------------------------------------/
130	/**
131	* Returns a copy of the string held within the dynamic string.
132	* The returned string is owned by the caller, who is responsible
133	* for free'ing it when done with it. The dynamic string itself
134	* is reinitialized to an empty string. dsPtr may not be NULL
135	* (checked by assertion).
136	*
137	* @param dsPtr dsPtr Dynamic string holding the returned result.
138	* @return Returns a copy of the original value of the dynamic string.
139	*/
140	ASC_DLLSPEC char Asc_DStringResult(Asc_DString dsPtr);
141
142	/----------------------------------------------------------------------/
143	/**
144	* Truncates a dynamic string to a given length without freeing
145	* up its storage. The length of dsPtr is reduced to length
146	* unless it was already shorter than that. Passing a length
147	* < 0 sets the new length to zero. dsPtr may not be NULL
148	* (checked by assertion).
149	*
150	* @param dsPtr Structure describing dynamic string (non-NULL).
151	* @param length New maximum length for the dynamic string.
152	*/
153	ASC_DLLSPEC void Asc_DStringTrunc(Asc_DString *dsPtr, int length);
154
155	/----------------------------------------------------------------------/
156	/**
157	* Sets the value of the dynamic string to the specified string.
158	* String must be null-terminated.
159	* Memory gets reallocated if needed to accomodate the string's new
160	* size. Neither dsPtr nor string may be NULL (checked by assertion).
161	*
162	* @param dsPtr Structure describing dynamic string (non-NULL).
163	* @param string String to append (non-NULL, null-terminated).
164	* @return Returns the new value of the dynamic string.
165	*/
166	ASC_DLLSPEC char Asc_DStringSet(Asc_DString dsPtr, CONST char *string);
167
168	#endif /* ASC_DSTRING_H */
169