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

Contents of /trunk/ascend/general/dstring.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2011 - (show annotations) (download) (as text)
Tue Apr 28 08:58:48 2009 UTC (15 years ago) by jpye
File MIME type: text/x-chdr
File size: 6827 byte(s)
Moving libascend components from #/base/generic into #/ascend
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

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