Zen API

- Home
- Help Topics
- Types by Category
- All Types
- Files

All Classes Files Functions Variables Typedefs Macros Groups Pages
kString.h
Go to the documentation of this file.
1 /**
2 * @file kString.h
3 * @brief Declares the kString class.
4 *
5 * @internal
6 * Copyright (C) 2005-2014 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #ifndef K_API_STRING_H
11 #define K_API_STRING_H
12
13 #include <kApi/kApiDef.h>
14
15 kBeginHeader()
16
17 /**
18 * @class kString
19 * @extends kObject
20 * @ingroup kApi-Data
21 * @brief Represents a character string.
22 *
23 * kString represents a variable-length, null-terminated sequence of kChar elements.
24 */
25 //typedef kObject kString; --forward-declared in kApiDef.x.h
26
27 /**
28 * Constructs a kString object.
29 *
30 * @public @memberof kString
31 * @param str Receives constructed string object.
32 * @param content Initial string content (or kNULL).
33 * @param allocator Memory allocator.
34 * @return Operation status.
35 */
36 kFx(kStatus) kString_Construct(kString* str, const kChar* content, kAlloc allocator);
37
38 /**
39 * Copies the source string content.
40 *
41 * @public @memberof kString
42 * @param str String object.
43 * @param source Source string to be copied.
44 * @return Operation status.
45 */
46 kFx(kStatus) kString_Assign(kString str, kString source);
47
48 /**
49 * Sets the length of the string to zero.
50 *
51 * @public @memberof kString
52 * @param str String object.
53 * @return Operation status.
54 */
55 kFx(kStatus) kString_Clear(kString str);
56
57 /**
58 * Ensures that capacity is reserved for at least the specified number of character units (excluding null terminator).
59 *
60 * Existing string content is preserved.
61 *
62 * @public @memberof kString
63 * @param str String object.
64 * @param minimumCapacity Minimum string capacity, in character units.
65 * @return Operation status.
66 */
67 kFx(kStatus) kString_Reserve(kString str, kSize minimumCapacity);
68
69 /**
70 * Sets the content of the string.
71 *
72 * @public @memberof kString
73 * @param str String object.
74 * @param content String content to copy.
75 * @return Operation status.
76 */
77 kFx(kStatus) kString_Set(kString str, const kChar* content);
78
79 /**
80 * Sets the content of the string using a printf-like format string and arguments.
81 *
82 * This function relies on formatting support from underlying system libraries; results can vary.
83 *
84 * @public @memberof kString
85 * @param str String object.
86 * @param format Print format string.
87 * @return Operation status.
88 */
89 kFx(kStatus) kString_Setf(kString str, const kChar* format, ...);
90
91 /**
92 * Variable-argument version of kString_Setf.
93 *
94 * @public @memberof kString
95 * @param str String object.
96 * @param format Print format string.
97 * @param argList Variable argument list.
98 * @return Operation status.
99 */
100 kFx(kStatus) kString_Setvf(kString str, const kChar* format, kVarArgList argList);
101
102 /**
103 * Appends content to the string.
104 *
105 * @public @memberof kString
106 * @param str String object.
107 * @param content String content to append.
108 * @return Operation status.
109 */
110 kFx(kStatus) kString_Add(kString str, const kChar* content);
111
112 /**
113 * Appends content to the string using a printf-like format string and arguments.
114 *
115 * This function relies on formatting support from underlying system libraries; results can vary.
116 *
117 * @public @memberof kString
118 * @param str String object.
119 * @param format Print format string.
120 * @return Operation status.
121 */
122 kFx(kStatus) kString_Addf(kString str, const kChar* format, ...);
123
124 /**
125 * Variable-argument version of kString_Addf.
126 *
127 * @public @memberof kString
128 * @param str String object.
129 * @param format Print format string.
130 * @param argList Variable argument list.
131 * @return Operation status.
132 */
133 kFx(kStatus) kString_Addvf(kString str, const kChar* format, kVarArgList argList);
134
135 /**
136 * Appends a portion of another string to this string.
137 *
138 * @public @memberof kString
139 * @param str String object.
140 * @param content String content to append.
141 * @param start Starting offset with content argument.
142 * @param count Count of characters to append.
143 * @return Operation status.
144 */
145 kFx(kStatus) kString_AddSubstring(kString str, const kChar* content, kSize start, kSize count);
146
147 /**
148 * Compares this string to another string.
149 *
150 * The result is negative if the string object is lexically less than the input, positive
151 * if the string object is lexically greater than the input, and zero if they are equal.
152 *
153 * This function performs comparison of UTF-8 encoded characters by Unicode code point.
154 *
155 * @public @memberof kString
156 * @param str String object.
157 * @param content String content to be compared.
158 * @return Comparison result.
159 */
160 kFx(k32s) kString_Compare(kString str, const kChar* content);
161
162 /**
163 * Compares this string to another character sequence to determine equality.
164 *
165 * @public @memberof kString
166 * @param str String object.
167 * @param content String content to be compared.
168 * @return kTRUE if the character sequences are equal; otherwise, kFALSE.
169 */
170 kFx(kBool) kString_Equals(kString str, const kChar* content);
171
172 /**
173 * Removes leading and trailing whitespace.
174 *
175 * @public @memberof kString
176 * @param str String object.
177 * @return Comparison result.
178 */
179 kFx(kStatus) kString_Trim(kString str);
180
181 /**
182 * Splits this string into substrings using the supplied delimiters.
183 *
184 * This function currently supports delimiters only within the ASCII character range.
185 *
186 * @public @memberof kString
187 * @param str String object.
188 * @param delimiters Null-terminated string containing delimiter characters.
189 * @param tokens Receives a list substrings.
190 * @param allocator Memory allocator (or kNULL for default).
191 * @return Comparison result.
192 */
193 kFx(kStatus) kString_Split(kString str, const kChar* delimiters, kArrayList* tokens, kAlloc allocator);
194
195 /**
196 * Returns a pointer to the internal character buffer.
197 *
198 * @public @memberof kString
199 * @param str String object.
200 * @return Pointer to null-terminated character buffer.
201 */
202 kFx(kChar*) kString_Chars(kString str);
203
204 /**
205 * Returns the number of character units in the string buffer (excluding null-terminator).
206 *
207 * kString assumes UTF8-encoded data; the string length refers to the number of encoded
208 * character units (bytes), rather than the number of characters.
209 *
210 * @public @memberof kString
211 * @param str String object.
212 * @return Count of character units (excluding null-terminator).
213 */
214 kFx(kSize) kString_Length(kString str);
215
216 /**
217 * Explicitly sets the length of the string.
218 *
219 * This function can be used to specify the string length if the string buffer has been directly
220 * manipulated. Use with caution; no error-checking is performed to ensure that the string is properly
221 * formatted.
222 *
223 * @public @memberof kString
224 * @param str String object.
225 * @param length New string length, in character units (excluding null-terminator).
226 * @return Operation status.
227 */
228 kFx(kStatus) kString_SetLength(kString str, kSize length);
229
230 /**
231 * Returns the number of character units that can be stored without reallocation.
232 *
233 * @public @memberof kString
234 * @param str String object.
235 * @return String capacity.
236 */
237 kFx(kSize) kString_Capacity(kString str);
238
239 #define kString_Chars_(STRING) kxString_Chars_(STRING) ///< Macro version of kString_Chars.
240 #define kString_Length_(STRING) kxString_Length_(STRING) ///< Macro version of kString_Length.
241 #define kString_SetLength_(STRING, L) kxString_SetLength_(STRING, L) ///< Macro version of kString_SetLength.
242 #define kString_Capacity_(STRING) kxString_Capacity_(STRING) ///< Macro version of kString_Capacity.
243
244 kEndHeader()
245
246 #include <kApi/Data/kString.x.h>
247
248 #endif
kString::kString_SetLength
kStatus kString_SetLength(kString str, kSize length)
Explicitly sets the length of the string.
kString::kString_Addvf
kStatus kString_Addvf(kString str, const kChar *format, kVarArgList argList)
Variable-argument version of kString_Addf.
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kString::kString_Reserve
kStatus kString_Reserve(kString str, kSize minimumCapacity)
Ensures that capacity is reserved for at least the specified number of character units (excluding nul...
kString::kString_Construct
kStatus kString_Construct(kString *str, const kChar *content, kAlloc allocator)
Constructs a kString object.
kChar
Represents a single unit (byte) in a UTF-8 character.
kString::kString_Trim
kStatus kString_Trim(kString str)
Removes leading and trailing whitespace.
kString::kString_AddSubstring
kStatus kString_AddSubstring(kString str, const kChar *content, kSize start, kSize count)
Appends a portion of another string to this string.
kString::kString_Setvf
kStatus kString_Setvf(kString str, const kChar *format, kVarArgList argList)
Variable-argument version of kString_Setf.
kString::kString_Assign
kStatus kString_Assign(kString str, kString source)
Copies the source string content.
kString::kString_Add
kStatus kString_Add(kString str, const kChar *content)
Appends content to the string.
kString::kString_Equals
kBool kString_Equals(kString str, const kChar *content)
Compares this string to another character sequence to determine equality.
kString::kString_Length
kSize kString_Length(kString str)
Returns the number of character units in the string buffer (excluding null-terminator).
kApiDef.h
Essential API declarations.
k32s
Represents a 32-bit signed integer.
kString::kString_Chars
kChar * kString_Chars(kString str)
Returns a pointer to the internal character buffer.
kString::kString_Set
kStatus kString_Set(kString str, const kChar *content)
Sets the content of the string.
kString
Represents a character string.
kString::kString_Addf
kStatus kString_Addf(kString str, const kChar *format,...)
Appends content to the string using a printf-like format string and arguments.
kArrayList
Represents a list implemented with a dynamic array.
kStatus
Represents an enumeration of error codes.
kString::kString_Split
kStatus kString_Split(kString str, const kChar *delimiters, kArrayList *tokens, kAlloc allocator)
Splits this string into substrings using the supplied delimiters.
kString::kString_Clear
kStatus kString_Clear(kString str)
Sets the length of the string to zero.
kString::kString_Compare
k32s kString_Compare(kString str, const kChar *content)
Compares this string to another string.
kBool
Represents a boolean value.
kString::kString_Setf
kStatus kString_Setf(kString str, const kChar *format,...)
Sets the content of the string using a printf-like format string and arguments.
kString::kString_Capacity
kSize kString_Capacity(kString str)
Returns the number of character units that can be stored without reallocation.