generic/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 _DSTRING_H
#define _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;

/*----------------------------------------------------------------------*/
/**
 * <!--  Asc_DStringLength --                                          -->
 *
 *  Return the current length of the string.
 *
 * Results:
 *  The return value is the number of non-NULL characters in
 *      the string, an integer.<br><br>
 *
 * Side effects:
 *  None.
 */
#define Asc_DStringLength(dsPtr) ((dsPtr)->length)


/*----------------------------------------------------------------------*/
/**
 * <!--  Asc_DStringValue --                                           -->
 *
 *  Return the curent value of the string.
 *
 * Results:
 *  The return value is a pointer to the first character in the string,
 *      a char*.  The client should not free or modify this value.<br><br>
 *
 * Side effects:
 *  None.
 */
#define Asc_DStringValue(dsPtr) ((dsPtr)->string)

/*----------------------------------------------------------------------*/
/**
 * <!--  Asc_DStringAppend --                                          -->
 *
 *  Append more characters to the current value of a dynamic string.
 *
 * Results:
 *  The return value is a pointer to the dynamic string's new value.<br><br>
 *
 * Side effects:
 *  Length bytes from string (or all of string if length is less
 *  than zero) are added to the current value of the string.  Memory
 *  gets reallocated if needed to accomodate the string's new size.
 */
extern char *Asc_DStringAppend(Asc_DString *dsPtr,
                               CONST char *string,
                               int length);

/*----------------------------------------------------------------------*/
/**
 * <!--  Asc_DStringFree --                                            -->
 *
 *  Frees up any memory allocated for the dynamic string and
 *  reinitializes the string to an empty state.
 *
 * Results:
 *  None.<br><br>
 *
 * Side effects:
 *  The previous contents of the dynamic string are lost, and
 *  the new value is an empty string.
 */
extern void Asc_DStringFree(Asc_DString *dsPtr);

/*----------------------------------------------------------------------*/
/**
 * <!--  Asc_DStringInit --                                            -->
 *
 *  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).
 *
 * Results:
 *  None.<br><br>
 *
 * Side effects:
 *  The dynamic string is initialized to be empty.
 */
extern void Asc_DStringInit(Asc_DString *dsPtr);

/*----------------------------------------------------------------------*/
/**
 * <!--  Asc_DStringResult --                                          -->
 *
 *  This procedure returns a *copy* of the string held within the
 *  dynamic string. The string itself is reinitialized
 *  to an empty string.<br><br>
 *
 * Results:
 *  The string held.<br><br>
 *
 * Side effects:
 *  DsPtr is reinitialized to an empty string.
 */
extern char *Asc_DStringResult(Asc_DString *dsPtr);

/*----------------------------------------------------------------------*/
/**
 * <!--  Asc_DStringTrunc --                                           -->
 *
 *  Truncate a dynamic string to a given length without freeing
 *  up its storage.
 *
 * Results:
 *  None.<br><br>
 *
 * Side effects:
 *  The length of dsPtr is reduced to length unless it was already
 *  shorter than that.
 */
extern void Asc_DStringTrunc(Asc_DString *dsPtr, int length);

#endif /* _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 _DSTRING_H
39	#define _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	* <!-- Asc_DStringLength -- -->
59	*
60	* Return the current length of the string.
61	*
62	* Results:
63	* The return value is the number of non-NULL characters in
64	* the string, an integer.<br><br>
65	*
66	* Side effects:
67	* None.
68	*/
69	#define Asc_DStringLength(dsPtr) ((dsPtr)->length)
70
71
72	/----------------------------------------------------------------------/
73	/**
74	* <!-- Asc_DStringValue -- -->
75	*
76	* Return the curent value of the string.
77	*
78	* Results:
79	* The return value is a pointer to the first character in the string,
80	* a char*. The client should not free or modify this value.<br><br>
81	*
82	* Side effects:
83	* None.
84	*/
85	#define Asc_DStringValue(dsPtr) ((dsPtr)->string)
86
87	/----------------------------------------------------------------------/
88	/**
89	* <!-- Asc_DStringAppend -- -->
90	*
91	* Append more characters to the current value of a dynamic string.
92	*
93	* Results:
94	* The return value is a pointer to the dynamic string's new value.<br><br>
95	*
96	* Side effects:
97	* Length bytes from string (or all of string if length is less
98	* than zero) are added to the current value of the string. Memory
99	* gets reallocated if needed to accomodate the string's new size.
100	*/
101	extern char Asc_DStringAppend(Asc_DString dsPtr,
102	CONST char *string,
103	int length);
104
105	/----------------------------------------------------------------------/
106	/**
107	* <!-- Asc_DStringFree -- -->
108	*
109	* Frees up any memory allocated for the dynamic string and
110	* reinitializes the string to an empty state.
111	*
112	* Results:
113	* None.<br><br>
114	*
115	* Side effects:
116	* The previous contents of the dynamic string are lost, and
117	* the new value is an empty string.
118	*/
119	extern void Asc_DStringFree(Asc_DString *dsPtr);
120
121	/----------------------------------------------------------------------/
122	/**
123	* <!-- Asc_DStringInit -- -->
124	*
125	* Initializes a dynamic string, discarding any previous contents
126	* of the string (Asc_DStringFree should have been called already
127	* if the dynamic string was previously in use).
128	*
129	* Results:
130	* None.<br><br>
131	*
132	* Side effects:
133	* The dynamic string is initialized to be empty.
134	*/
135	extern void Asc_DStringInit(Asc_DString *dsPtr);
136
137	/----------------------------------------------------------------------/
138	/**
139	* <!-- Asc_DStringResult -- -->
140	*
141	* This procedure returns a copy of the string held within the
142	* dynamic string. The string itself is reinitialized
143	* to an empty string.<br><br>
144	*
145	* Results:
146	* The string held.<br><br>
147	*
148	* Side effects:
149	* DsPtr is reinitialized to an empty string.
150	*/
151	extern char Asc_DStringResult(Asc_DString dsPtr);
152
153	/----------------------------------------------------------------------/
154	/**
155	* <!-- Asc_DStringTrunc -- -->
156	*
157	* Truncate a dynamic string to a given length without freeing
158	* up its storage.
159	*
160	* Results:
161	* None.<br><br>
162	*
163	* Side effects:
164	* The length of dsPtr is reduced to length unless it was already
165	* shorter than that.
166	*/
167	extern void Asc_DStringTrunc(Asc_DString *dsPtr, int length);
168
169	#endif /* _DSTRING_H */
170