/[ascend]/trunk/base/generic/general/dstring.h
ViewVC logotype

Contents of /trunk/base/generic/general/dstring.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 55 - (show annotations) (download) (as text)
Sat Sep 3 01:25:36 2005 UTC (17 years, 5 months ago) by jds
File MIME type: text/x-chdr
File size: 5471 byte(s)
Minor comment updates, add doc subdir to tclck98 subdir
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

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22