1 /*****************************************************************************/
2 /* Software Testing Automation Framework (STAF) */
3 /* (C) Copyright IBM Corp. 2001 */
4 /* */
5 /* This software is licensed under the Eclipse Public License (EPL) V1.0. */
6 /*****************************************************************************/
7
8 #ifndef STAF_String
9 #define STAF_String
10
11 #include "STAFError.h"
12 #include "STAFOSTypes.h"
13
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17
18 /* Begin C language definitions */
19
20 typedef struct STAFStringImplementation *STAFString_t;
21 typedef const struct STAFStringImplementation *STAFStringConst_t;
22
23
24 typedef enum STAFUTF8Char_e
25 {
26 kUTF8_NULL = 0, /* Single byte null */
27 kUTF8_SPACE = 1, /* Space */
28 kUTF8_LCURLY = 2, /* Left curly brace */
29 kUTF8_RCURLY = 3, /* Right curly brace */
30 kUTF8_LPAREN = 4, /* Left parenthesis */
31 kUTF8_RPAREN = 5, /* Right parenthesis */
32 kUTF8_LANGLE = 6, /* Left angle bracket (a.k.a, less than sign) */
33 kUTF8_RANGLE = 7, /* Right angle bracket (a.k.a, greater than sign) */
34 kUTF8_COLON = 8, /* Colon */
35 kUTF8_SCOLON = 9, /* Semi-colon */
36 kUTF8_COMMA = 10, /* Comma */
37 kUTF8_PERIOD = 11, /* Period */
38 kUTF8_BSLASH = 12, /* Back-slash */
39 kUTF8_SLASH = 13, /* Slash (a.k.a., forward-slash) */
40 kUTF8_EQUAL = 14, /* Equal sign */
41 kUTF8_SQUOTE = 15, /* Single quote (a.k.a., apostrophe) */
42 kUTF8_DQUOTE = 16, /* Double quote */
43 kUTF8_VBAR = 17, /* Vertical bar (a.k.a., pipe) */
44 kUTF8_NULL2 = 18, /* Double-byte null */
45 kUTF8_POUND = 19, /* Pound sign (a.k.a. number sign or hash) */
46 kUTF8_CR = 20, /* Carriage return */
47 kUTF8_LF = 21, /* Line feed */
48 kUTF8_STAR = 22, /* Star (a.k.a, asterisk) */
49 kUTF8_HYPHEN = 23, /* Hyphen (a.k.a., dash) */
50 kUTF8_PERCENT = 24, /* Percent sign */
51 kUTF8_QUESTION = 25, /* Question mark */
52 kUTF8_CARET = 26, /* Caret (^) */
53 kUTF8_AMP = 27, /* Ampersand (&) */
54 kUTF8_AT = 28, /* At (@) */
55 kUTF8_TAB = 29, /* Tab */
56 kUTF8_BANG = 30 /* Bang (a.k.a, exclaimation mark) */
57 } STAFUTF8Char_t;
58
59 typedef enum STAFUTF8CharType_e
60 {
61 kUTF8_TYPE_SPACE = 0, kUTF8_TYPE_WHITESPACE = 1,
62 kUTF8_TYPE_ASCII = 2, kUTF8_TYPE_DIGIT = 3,
63 kUTF8_TYPE_ZERO = 4
64 } STAFUTF8CharType_t;
65
66 typedef enum STAFStringCaseSensitive_e
67 {
68 kSTAFStringCaseInsensitive = 0,
69 kSTAFStringCaseSensitive = 1
70 } STAFStringCaseSensitive_t;
71
72
73 /***********************************************************************/
74 /* STAFStringConstruct - Creates a STAFString from buffer of size len */
75 /* */
76 /* Accepts: (Out) A pointer to a STAFString_t */
77 /* (In) A pointer to a buffer of UTF-8 chars */
78 /* (In) The length of the buffer */
79 /* (Out) A pointer to an OS return code (may be NULL) */
80 /* */
81 /* Returns: kSTAFOk on success */
82 /* other on error */
83 /***********************************************************************/
84
85 STAFRC_t STAFStringConstruct(STAFString_t *pString,
86 const char *buffer,
87 unsigned int len,
88 unsigned int *osRC);
89
90 /***********************************************************************/
91 /* STAFStringConstructCopy - Creates a STAFString from a STAFString */
92 /* */
93 /* Accepts: (Out) A pointer to a STAFString_t */
94 /* (In) A STAFString_t */
95 /* (Out) A pointer to an OS return code (may be NULL) */
96 /* */
97 /* Returns: kSTAFOk on success */
98 /* other on error */
99 /***********************************************************************/
100
101 STAFRC_t STAFStringConstructCopy(STAFString_t *pString,
102 STAFStringConst_t aString,
103 unsigned int *osRC);
104
105 /***********************************************************************/
106 /* STAFStringConstructFromCurrentCodePage - Creates a STAFString from */
107 /* a buffer of size len con- */
108 /* sisting of current code- */
109 /* page characters */
110 /* */
111 /* Accepts: (Out) A pointer to a STAFString_t */
112 /* (In) A pointer to a buffer of local codepage chars */
113 /* (In) The length of the buffer */
114 /* (Out) A pointer to an OS return code (may be NULL) */
115 /* */
116 /* Returns: kSTAFOk on success */
117 /* other on error */
118 /***********************************************************************/
119
120 STAFRC_t STAFStringConstructFromCurrentCodePage(
121 STAFString_t *pString,
122 const char *from,
123 unsigned int len,
124 unsigned int *osRC);
125
126 /***********************************************************************/
127 /* STAFStringConstructFromUInt - Creates a STAFString from an unsigned */
128 /* integer */
129 /* Note: This is still here for legacy reasons. */
130 /* Use STAFStringContructFromUInt64 instead for new code. */
131 /* */
132 /* Accepts: (Out) A pointer to a STAFString_t */
133 /* (In) The value to be represented as a string */
134 /* (In) The base in which to represent the value [1..16] */
135 /* (Out) A pointer to an OS return code (may be NULL) */
136 /* */
137 /* Returns: kSTAFOk on success */
138 /* other on error */
139 /***********************************************************************/
140
141 STAFRC_t STAFStringConstructFromUInt(STAFString_t *pString,
142 unsigned int value,
143 unsigned int base,
144 unsigned int *osRC);
145
146 /***********************************************************************/
147 /* STAFStringConstructFromUInt64 - Creates a STAFString from an */
148 /* STAFUInt64_t number */
149 /* */
150 /* Accepts: (Out) A pointer to a STAFString_t */
151 /* (In) The value to be represented as a string */
152 /* (In) The base in which to represent the value [1..16] */
153 /* (Out) A pointer to an OS return code (may be NULL) */
154 /* */
155 /* Returns: kSTAFOk on success */
156 /* other on error */
157 /***********************************************************************/
158
159 STAFRC_t STAFStringConstructFromUInt64(STAFString_t *pString,
160 STAFUInt64_t value,
161 unsigned int base,
162 unsigned int *osRC);
163
164 /***********************************************************************/
165 /* STAFStringConstructFromInt64 - Creates a STAFString from a */
166 /* STAFInt64_t number */
167 /* */
168 /* Accepts: (Out) A pointer to a STAFString_t */
169 /* (In) The value to be represented as a string */
170 /* (In) The base in which to represent the value [1..16] */
171 /* (Out) A pointer to an OS return code (may be NULL) */
172 /* */
173 /* Returns: kSTAFOk on success */
174 /* other on error */
175 /***********************************************************************/
176
177 STAFRC_t STAFStringConstructFromInt64(STAFString_t *pString,
178 STAFInt64_t value,
179 unsigned int base,
180 unsigned int *osRC);
181
182 /***********************************************************************/
183 /* STAFStringConstructSubString - Creates a substring of a STAFString */
184 /* with index and len refering to ei- */
185 /* ther UTF-8 chars (0) or bytes (1) */
186 /* */
187 /* Accepts: (Out) A pointer to a STAFString_t */
188 /* (In) A STAFString_t */
189 /* (In) The index of the char or byte to start from */
190 /* (In) Len of chars or bytes to get from string */
191 /* (In) 0->index/len are in chars; 1->index/len are in bytes */
192 /* (Out) A pointer to an OS return code (may be NULL) */
193 /* */
194 /* Returns: kSTAFOk on success */
195 /* other on error */
196 /***********************************************************************/
197
198 STAFRC_t STAFStringConstructSubString(STAFString_t *pSubStr,
199 STAFStringConst_t aString,
200 unsigned int index,
201 unsigned int len,
202 unsigned int corb,
203 unsigned int *osRC);
204
205 /***********************************************************************/
206 /* STAFStringConstructSubWord - Creates a subword string from a */
207 /* STAFString */
208 /* */
209 /* Accepts: (Out) A pointer to a STAFString_t */
210 /* (In) A STAFString_t */
211 /* (In) The starting word from the string (0 based) */
212 /* (In) The number of words to retrieve (0 meaning all) */
213 /* (Out) A pointer to an OS return code (may be NULL) */
214 /* */
215 /* Returns: kSTAFOk on success */
216 /* other on error */
217 /***********************************************************************/
218
219 STAFRC_t STAFStringConstructSubWord(STAFString_t *pWord,
220 STAFStringConst_t aString,
221 unsigned int index,
222 unsigned int count,
223 unsigned int *osRC);
224
225 /***********************************************************************/
226 /* STAFStringConstructChar - Creates a string of length 1 representing */
227 /* a specified character in UTF8 */
228 /* */
229 /* Accepts: (Out) A pointer to a STAFString_t */
230 /* (In) A STAFString_t */
231 /* (In) The starting word from the string (0 based) */
232 /* (In) The number of words to retrieve (0 meaning all) */
233 /* (Out) A pointer to an OS return code (may be NULL) */
234 /* */
235 /* Returns: kSTAFOk on success */
236 /* other on error */
237 /***********************************************************************/
238
239 STAFRC_t STAFStringConstructChar(STAFString_t *pChar,
240 STAFUTF8Char_t aChar,
241 unsigned int *osRC);
242
243 /***********************************************************************/
244 /* STAFStringConstructJoin - Creates a STAFString by joining all of */
245 /* the strings in an array */
246 /* */
247 /* Accepts: (Out) A pointer to a STAFString_t */
248 /* (In) An array of STAFString_t */
249 /* (In) The size of the array */
250 /* (Out) A pointer to an OS return code (may be NULL) */
251 /* */
252 /* Returns: kSTAFOk on success */
253 /* other on error */
254 /***********************************************************************/
255
256 STAFRC_t STAFStringConstructJoin(STAFString_t *pString,
257 STAFString_t aStringArray[],
258 unsigned int arraySize,
259 unsigned int *osRC);
260
261 /***********************************************************************/
262 /* STAFStringNumOfWords - Returns the number of words in a STAFString */
263 /* */
264 /* Accepts: (In) A STAFString_t */
265 /* (Out) The number of words */
266 /* (Out) A pointer to an OS return code (may be NULL) */
267 /* */
268 /* Returns: kSTAFOk on success */
269 /* other on error */
270 /***********************************************************************/
271
272 STAFRC_t STAFStringNumOfWords(STAFStringConst_t aString,
273 unsigned int *num,
274 unsigned int *osRC);
275
276 /***********************************************************************/
277 /* STAFStringAssign - Assigns a STAFString to another STAFString, clea-*/
278 /* ning up any resources taken by the target string */
279 /* */
280 /* Accepts: (In) A STAFString_t (target) */
281 /* (In) A STAFString_t (source) */
282 /* (Out) A pointer to an OS return code (may be NULL) */
283 /* */
284 /* Returns: kSTAFOk on success */
285 /* other on error */
286 /***********************************************************************/
287
288 STAFRC_t STAFStringAssign(STAFString_t aTarget,
289 STAFStringConst_t aSource,
290 unsigned int *osRC);
291
292 /***********************************************************************/
293 /* STAFStringGetBuffer - Returns a pointer to the buffer containing */
294 /* the bytes that represent a STAFString */
295 /* */
296 /* Accepts: (In) A STAFString_t */
297 /* (Out) A pointer to the buffer */
298 /* (Out) A pointer to the length of the buffer */
299 /* (Out) A pointer to an OS return code (may be NULL) */
300 /* */
301 /* Returns: kSTAFOk on success */
302 /* other on error */
303 /***********************************************************************/
304
305 STAFRC_t STAFStringGetBuffer(STAFStringConst_t aString,
306 const char **buffer,
307 unsigned int *len,
308 unsigned int *osRC);
309
310 /***********************************************************************/
311 /* STAFStringToLowerCase - Converts only Latin Alphabet letters A-Z to */
312 /* a-z from a STAFString */
313 /* */
314 /* Accepts: (In)/(Out) A STAFString_t to convert */
315 /* (Out) A pointer to an OS return code (may be NULL) */
316 /* */
317 /* Returns: kSTAFOk on success */
318 /* other on error */
319 /***********************************************************************/
320
321 STAFRC_t STAFStringToLowerCase(STAFString_t aString,
322 unsigned int *osRC);
323
324 /***********************************************************************/
325 /* STAFStringToUpperCase - Converts only Latin Alphabet letters a-z to */
326 /* A-Z from a STAFString */
327 /* */
328 /* Accepts: (In)/(Out) A STAFString_t to convert */
329 /* (Out) A pointer to an OS return code (may be NULL) */
330 /* */
331 /* Returns: kSTAFOk on success */
332 /* other on error */
333 /***********************************************************************/
334
335 STAFRC_t STAFStringToUpperCase(STAFString_t aString,
336 unsigned int *osRC);
337
338 /***********************************************************************/
339 /* STAFStringReplace - Replaces all oldStrings in a STAFString with */
340 /* newString fixing the length of the string if */
341 /* necessary */
342 /* */
343 /* Accepts: (In)/(Out) A STAFString_t to modify */
344 /* (In) The STAFString to be replaced */
345 /* (In) The STAFString to replace with */
346 /* (Out) A pointer to an OS return code (may be NULL) */
347 /* */
348 /* Returns: kSTAFOk on success */
349 /* other on error */
350 /***********************************************************************/
351
352 STAFRC_t STAFStringReplace(STAFString_t aString,
353 STAFStringConst_t oldString,
354 STAFStringConst_t newString,
355 unsigned int *osRC);
356
357 /***********************************************************************/
358 /* STAFStringToCurrentCodePage - Returns a buffer of size len contain- */
359 /* ing the current codepage representa- */
360 /* tion of a STAFString */
361 /* */
362 /* Accepts: (In) A STAFString_t */
363 /* (Out) A buffer with the local codepage characters */
364 /* (Out) The size of the allocated buffer */
365 /* (Out) A pointer to an OS return code (may be NULL) */
366 /* */
367 /* Returns: kSTAFOk on success */
368 /* other on error */
369 /* */
370 /* Note : This function allocates memory that must be freed up with */
371 /* STAFStringFreeBuffer. */
372 /* */
373 /* Note : The returned buffer has a terminating NULL byte. This */
374 /* byte is not counted in the length which is returned. */
375 /* */
376 /***********************************************************************/
377
378 STAFRC_t STAFStringToCurrentCodePage(STAFStringConst_t aString,
379 char **to,
380 unsigned int *len,
381 unsigned int *osRC);
382
383 /***********************************************************************/
384 /* STAFStringConcatenate - Concatenates a STAFString with another */
385 /* STAFString */
386 /* */
387 /* Accepts: (In)/(Out) A STAFString_t */
388 /* (In) A STAFString_t */
389 /* (Out) A pointer to an OS return code (may be NULL) */
390 /* */
391 /* Returns: kSTAFOk on success */
392 /* other on error */
393 /***********************************************************************/
394
395 STAFRC_t STAFStringConcatenate(STAFString_t aString,
396 STAFStringConst_t aSource,
397 unsigned int *osRC);
398
399 /***********************************************************************/
400 /* STAFStringCountSubStrings - Counts the number of times a particular */
401 /* substring appears in a STAFString */
402 /* */
403 /* Accepts: (In) A STAFString_t */
404 /* (In) A STAFString_t */
405 /* (Out) The count of substrings */
406 /* (Out) A pointer to an OS return code (may be NULL) */
407 /* */
408 /* Returns: kSTAFOk on success */
409 /* other on error */
410 /***********************************************************************/
411
412 STAFRC_t STAFStringCountSubStrings(STAFStringConst_t aString,
413 STAFStringConst_t aSubStr,
414 unsigned int *count,
415 unsigned int *osRC);
416
417
418 /***********************************************************************/
419 /* STAFStringStripCharsOfType - Strips chars of a type from the left, */
420 /* right, or both sides of a STAFString */
421 /* */
422 /* Accepts: (In)/(Out) A STAFString_t */
423 /* (In) A STAFUTF8CharType_t */
424 /* (In) 0->trim left, 1->trim right, 2->trim both */
425 /* (Out) A pointer to an OS return code (may be NULL) */
426 /* */
427 /* Returns: kSTAFOk on success */
428 /* other on error */
429 /***********************************************************************/
430
431 STAFRC_t STAFStringStripCharsOfType(STAFString_t aInOutStr,
432 STAFUTF8CharType_t aType,
433 unsigned int side,
434 unsigned int *osRC);
435
436 /***********************************************************************/
437 /* STAFStringToUInt - Returns the numeric value of a STAFString as an */
438 /* unsigned integer (range is 0 to 4294967295) */
439 /* */
440 /* Accepts: (In) A STAFString_t */
441 /* (Out) A pointer to the numeric value of the string */
442 /* (In) The base in which the value is represented [1..16] */
443 /* (Out) A pointer to an OS return code (may be NULL) */
444 /* */
445 /* Returns: kSTAFOk on success */
446 /* other on error */
447 /***********************************************************************/
448
449 STAFRC_t STAFStringToUInt(STAFStringConst_t aString,
450 unsigned int *value, unsigned int base,
451 unsigned int *osRC);
452
453 /***********************************************************************/
454 /* STAFStringToUInt64 - Returns the numeric value of a STAFString as */
455 /* a STAFUInt64_t (range is 18446744073709551615) */
456 /* */
457 /* Accepts: (In) A STAFString_t */
458 /* (Out) A pointer to the numeric value of the string */
459 /* (In) The base in which the value is represented [1..16] */
460 /* (Out) A pointer to an OS return code (may be NULL) */
461 /* */
462 /* Returns: kSTAFOk on success */
463 /* other on error */
464 /***********************************************************************/
465 /* XXX: Commented out until get UINT64_MAX working on Solaris
466 STAFRC_t STAFStringToUInt64(STAFStringConst_t aString,
467 STAFUInt64_t *value, unsigned int base,
468 unsigned int *osRC);
469 */
470
471 /***********************************************************************/
472 /* STAFStringLength - Returns the char or byte length of a STAFString */
473 /* */
474 /* Accepts: (In) A STAFString_t */
475 /* (Out) A pointer to the char length of the string */
476 /* (In) 0->char length of string, 1->byte length of string */
477 /* (Out) A pointer to an OS return code (may be NULL) */
478 /* */
479 /* Returns: kSTAFOk on success */
480 /* other on error */
481 /***********************************************************************/
482
483 STAFRC_t STAFStringLength(STAFStringConst_t aString,
484 unsigned int *len,
485 unsigned int corb,
486 unsigned int *osRC);
487
488 /***********************************************************************/
489 /* STAFStringSizeOfChar - Returns the number of bytes contained in a */
490 /* particular char of a STAFString */
491 /* */
492 /* Accepts: (In) A STAFString_t */
493 /* (In) The index of the char to measure (0 based) */
494 /* (In) 0->char index, 1->byte index */
495 /* (Out) A pointer to the byte length of a char of a string */
496 /* (Out) A pointer to an OS return code (may be NULL) */
497 /* */
498 /* Returns: kSTAFOk on success */
499 /* other on error */
500 /***********************************************************************/
501
502 STAFRC_t STAFStringSizeOfChar(STAFStringConst_t aString,
503 unsigned int index,
504 unsigned int corb,
505 unsigned int *len,
506 unsigned int *osRC);
507
508
509 /***********************************************************************/
510 /* STAFStringByteIndexOfChar - Returns the byte location in the string */
511 /* buffer of a specified char */
512 /* */
513 /* Accepts: (In) A STAFString_t */
514 /* (In) The char index */
515 /* (Out) A pointer to the byte location of the char */
516 /* (Out) A pointer to an OS return code (may be NULL) */
517 /* */
518 /* Returns: kSTAFOk on success */
519 /* other on error */
520 /***********************************************************************/
521
522 STAFRC_t STAFStringByteIndexOfChar(STAFStringConst_t aString,
523 unsigned int index,
524 unsigned int *pos,
525 unsigned int *osRC);
526
527 /***********************************************************************/
528 /* STAFStringIsCharsOfType - Checks a STAFString to be of a specific */
529 /* character type (white, digits, ascii) */
530 /* */
531 /* Accepts: (In) A STAFString_t */
532 /* (In) A STAFUTF8CharType_t */
533 /* (Out) A pointer set to 0 if false, >0 if true */
534 /* (Out) A pointer to an OS return code (may be NULL) */
535 /* */
536 /* Returns: kSTAFOk on success */
537 /* other on error */
538 /* */
539 /* Note : If the empty string is passed in as the first argument, */
540 /* the result of this function will always return kSTAFOk */
541 /* as we are considering the empty string to be a character */
542 /* of every type. */
543 /***********************************************************************/
544
545 STAFRC_t STAFStringIsCharsOfType(STAFStringConst_t aFirst,
546 const STAFUTF8CharType_t aType,
547 unsigned int *result,
548 unsigned int *osRC);
549
550 /***********************************************************************/
551 /* STAFStringIsEqualTo - Compares a STAFString to another STAFString */
552 /* */
553 /* Accepts: (In) A STAFString_t */
554 /* (In) A STAFString_t */
555 /* (In) Case sensitivity indicator */
556 /* (Out) A pointer set to 0 if different or >0 if equal */
557 /* (Out) A pointer to an OS return code (may be NULL) */
558 /* */
559 /* Returns: kSTAFOk on success */
560 /* other on error */
561 /***********************************************************************/
562
563 STAFRC_t STAFStringIsEqualTo(STAFStringConst_t aFirst,
564 STAFStringConst_t aSecond,
565 STAFStringCaseSensitive_t sensitive,
566 unsigned int *comparison,
567 unsigned int *osRC);
568
569 /***********************************************************************/
570 /* STAFStringCompareTo - Determines whether a STAFString is greater */
571 /* than another STAFString by byte comparison */
572 /* */
573 /* Accepts: (In) A STAFString_t */
574 /* (In) A STAFString_t */
575 /* (Out) A pointer to a int set to 1 if the first string is */
576 /* less than the second string, 0 if they are equal, */
577 /* or 2 if the second string is less than the first */
578 /* (Out) A pointer to an OS return code (may be NULL) */
579 /* */
580 /* Returns: kSTAFOk on success */
581 /* other on error */
582 /***********************************************************************/
583
584 STAFRC_t STAFStringCompareTo(STAFStringConst_t aFirst,
585 STAFStringConst_t aSecond,
586 unsigned int *less,
587 unsigned int *osRC);
588
589 /***********************************************************************/
590 /* STAFStringCompareTo - Determines whether a STAFString is greater */
591 /* than another STAFString by byte comparison */
592 /* */
593 /* Accepts: (In) String to check */
594 /* (In) Starts with string */
595 /* (Out) A pointer to a int set to 1 if the first string */
596 /* starts with the second string, and 0 if the first */
597 /* does not start with the second string */
598 /* (Out) A pointer to an OS return code (may be NULL) */
599 /* */
600 /* Returns: kSTAFOk on success */
601 /* other on error */
602 /***********************************************************************/
603
604 STAFRC_t STAFStringStartsWith(STAFStringConst_t aString,
605 STAFStringConst_t startsWithString,
606 unsigned int *startsWith,
607 unsigned int *osRC);
608
609 /***********************************************************************/
610 /* STAFStringContainsWildcard - Determines whether a STAFString is */
611 /* contains at least one wildcard */
612 /* character */
613 /* */
614 /* Accepts: (In) A STAFString_t */
615 /* (Out) A pointer to a int set to 1 if the string contains */
616 /* at least one wildcard character, 0 if the string */
617 /* does not contain any wildcard characters */
618 /* (Out) A pointer to an OS return code (may be NULL) */
619 /* */
620 /* Returns: kSTAFOk on success */
621 /* other on error */
622 /* */
623 /* Note : Two wildcard characters are understood: '*' and '?' */
624 /***********************************************************************/
625
626 STAFRC_t STAFStringContainsWildcard(STAFStringConst_t aString,
627 unsigned int *hasWildcard,
628 unsigned int *osRC);
629
630 /***********************************************************************/
631 /* STAFStringMatchesWildcards - Determines whether a given STAFString */
632 /* matches a given wildcard STAFString */
633 /* */
634 /* Accepts: (In) String to check */
635 /* (In) String containg wildcards */
636 /* (In) Case sensitivity indicator */
637 /* (Out) Result of comparison (0 = no match, 1 = matches) */
638 /* (Out) A pointer to an OS return code (may be NULL) */
639 /* */
640 /* Returns: kSTAFOk on success */
641 /* other on error */
642 /* */
643 /* Note : Two wildcard characters are understood. '*' matches zero */
644 /* or more characters. '?' matches one single character. */
645 /***********************************************************************/
646
647 STAFRC_t STAFStringMatchesWildcards(STAFStringConst_t stringToCheck,
648 STAFStringConst_t wildcardString,
649 STAFStringCaseSensitive_t caseSensitive,
650 unsigned int *matches,
651 unsigned int *osRC);
652
653 /***********************************************************************/
654 /* STAFStringFind - Finds the first instance of a substring in a STAF- */
655 /* String */
656 /* */
657 /* Accepts: (In) A STAFString_t */
658 /* (In) A STAFString_t to look for */
659 /* (In) The char or byte index from where to start looking */
660 /* (In) 0->char index, 1->byte index */
661 /* (Out) A pointer to a int set to the char or byte index of */
662 /* the entry found or 0xffffffff if not found */
663 /* (Out) A pointer to an OS return code (may be NULL) */
664 /* */
665 /* Returns: kSTAFOk on success */
666 /* other on error */
667 /***********************************************************************/
668
669 STAFRC_t STAFStringFind(STAFStringConst_t aString,
670 STAFStringConst_t aSubStr,
671 unsigned int index, unsigned int corb,
672 unsigned int *pos,
673 unsigned int *osRC);
674
675 /***********************************************************************/
676 /* STAFStringFindFirstOf - Finds the first instance of a UTF-8 char in */
677 /* a set starting from a given char or byte */
678 /* index */
679 /* */
680 /* Accepts: (In) A STAFString_t */
681 /* (In) A STAFString_t which is a set of chars to look for */
682 /* (In) The char or byte index from where to start looking */
683 /* (In) 0->char index, 1->byte index */
684 /* (Out) A pointer to a int set to the char or byte index of */
685 /* the entry found or 0xffffffff if not found */
686 /* (Out) A pointer to an OS return code (may be NULL) */
687 /* */
688 /* Returns: kSTAFOk on success */
689 /* other on error */
690 /***********************************************************************/
691
692 STAFRC_t STAFStringFindFirstOf(STAFStringConst_t aString,
693 STAFStringConst_t aSet,
694 unsigned int index, unsigned int corb,
695 unsigned int *pos,
696 unsigned int *osRC);
697
698 /***********************************************************************/
699 /* STAFStringFindLastOf - Finds the last instance of a UTF-8 char in a */
700 /* set starting from a given char or byte index */
701 /* */
702 /* Accepts: (In) A STAFString_t */
703 /* (In) A STAFString_t which is a set of chars to look for */
704 /* (In) The char or byte index from where to start looking */
705 /* (In) 0->char index, 1->byte index */
706 /* (Out) A pointer to a int set to the char or byte index of */
707 /* the entry found or 0xffffffff if not found */
708 /* (Out) A pointer to an OS return code (may be NULL) */
709 /* */
710 /* Returns: kSTAFOk on success */
711 /* other on error */
712 /***********************************************************************/
713
714 STAFRC_t STAFStringFindLastOf(STAFStringConst_t aString,
715 STAFStringConst_t aSet,
716 unsigned int index, unsigned int corb,
717 unsigned int *pos,
718 unsigned int *osRC);
719
720 /***********************************************************************/
721 /* STAFStringFindFirstNotOf - Finds the first instance of a UTF-8 char */
722 /* not in set starting from a given char or */
723 /* byte index */
724 /* */
725 /* Accepts: (In) A STAFString_t */
726 /* (In) A STAFString_t which is a set of chars to look for */
727 /* (In) The char or byte index from where to start looking */
728 /* (In) 0->char index, 1->byte index */
729 /* (Out) A pointer to a int set to the char or byte index of */
730 /* the entry found or 0xffffffff if not found */
731 /* (Out) A pointer to an OS return code (may be NULL) */
732 /* */
733 /* Returns: kSTAFOk on success */
734 /* other on error */
735 /***********************************************************************/
736
737 STAFRC_t STAFStringFindFirstNotOf(STAFStringConst_t aString,
738 STAFStringConst_t aSet,
739 unsigned int index,
740 unsigned int corb,
741 unsigned int *pos,
742 unsigned int *osRC);
743
744 /***********************************************************************/
745 /* STAFStringFindLastNotOf - Finds the last instance of a UTF-8 char */
746 /* not in a set starting from a given char */
747 /* byte index */
748 /* */
749 /* Accepts: (In) A STAFString_t */
750 /* (In) A STAFString_t which is a set of chars to look for */
751 /* (In) The char or byte index from where to start looking */
752 /* (In) 0->char index, 1->byte index */
753 /* (Out) A pointer to a int set to the char or byte index of */
754 /* the entry found or 0xffffffff if not found */
755 /* (Out) A pointer to an OS return code (may be NULL) */
756 /* */
757 /* Returns: kSTAFOk on success */
758 /* other on error */
759 /***********************************************************************/
760
761 STAFRC_t STAFStringFindLastNotOf(STAFStringConst_t aString,
762 STAFStringConst_t aSet,
763 unsigned int index,
764 unsigned int corb,
765 unsigned int *pos,
766 unsigned int *osRC);
767
768 /***********************************************************************/
769 /* STAFStringDestruct - Destructs a STAFString */
770 /* */
771 /* Accepts: (Out) A pointer to a STAFString_t */
772 /* (Out) A pointer to an OS return code (may be NULL) */
773 /* */
774 /* Returns: kSTAFOk on success */
775 /* other on error */
776 /***********************************************************************/
777
778 STAFRC_t STAFStringDestruct(STAFString_t *pString,
779 unsigned int *osRC);
780
781
782 /***********************************************************************/
783 /* STAFStringFreeBuffer - Deallocates a buffer allocated by a */
784 /* STAFString function call */
785 /* */
786 /* Accepts: (In) A pointer to a STAFString allocated buffer */
787 /* (Out) A pointer to an OS return code (may be NULL) */
788 /* */
789 /* Returns: kSTAFOk on success */
790 /* other on error */
791 /* */
792 /* Note : This function must be used per STAFStringToLocalCodePage */
793 /* in order to free up any allocated memory */
794 /***********************************************************************/
795
796 STAFRC_t STAFStringFreeBuffer(const char *buffer,
797 unsigned int *osRC);
798
799 /* End C language definitions */
800
801 #ifdef __cplusplus
802 }
803
804 /* Begin C++ language definitions */
805
806 #include <cstdio>
807 #include "STAF_iostream.h"
808 #include "STAFRefPtr.h"
809 #include "STAFException.h"
810
811 // Forward declaration for typedef
812 class STAFString;
813 class STAFStringBuffer;
814 typedef STAFRefPtr<STAFString> STAFStringPtr;
815 typedef STAFRefPtr<STAFStringBuffer> STAFStringBufferPtr;
816
817
818 // STAFStringBuffer - This class is a helper class used by the STAFString
819 // class when it needs to return a buffer to the current
820 // codepage representation of the string
821
822 class STAFStringBuffer
823 {
824 public:
825
length()826 unsigned int length() { return fLength; }
buffer()827 const char *buffer() { return fPtr; }
828
829 ~STAFStringBuffer();
830
831 private:
832
833 friend class STAFString;
834
STAFStringBuffer(const char * ptr,unsigned int length)835 STAFStringBuffer(const char *ptr, unsigned int length)
836 : fPtr(ptr), fLength(length)
837 { /* Do Nothing */ }
838
839 unsigned int fLength;
840 const char *fPtr;
841 };
842
843
~STAFStringBuffer()844 inline STAFStringBuffer::~STAFStringBuffer()
845 {
846 unsigned int osRC = 0;
847 STAFStringFreeBuffer(fPtr, &osRC);
848 }
849
850
851 // STAFString - This class provides a C++ wrapper around the STAFString
852 // C APIs.
853
854 class STAFString
855 {
856 public:
857
858 enum IndexRep { kChar = 0, kByte = 1 };
859 enum CodePageType { kCurrent = 0, kUTF8 = 1 };
860 enum InvalidPosition { kNPos = 0xFFFFFFFF };
861 enum DefaultBufferLen { kStrLen = 0xFFFFFFFF };
862 enum StripWhat { kFront = 0, kBack = 1, kBoth = 2 };
863 enum CopyMode { kShallow = 0, kDeep = 1 };
864 enum Remainder { kRemainder = 0xFFFFFFFF };
865
866 // Constructors
867 STAFString(void);
868 STAFString(const char *buffer, unsigned int length = kStrLen,
869 CodePageType cpType = kCurrent);
870 STAFString(unsigned int fromValue, unsigned int base = 10);
871 STAFString(int fromValue, unsigned int base = 10);
872 STAFString(unsigned short fromValue, unsigned int base = 10);
873 STAFString(short fromValue, unsigned int base = 10);
874
875 // On 64-bit Unix machines, an unsigned long is the same as a STAFUInt64_t
876 // and a long is the same as a STAFInt64_t, so can't define STAFString
877 // constructors for both
878
879 #if !defined(STAF_OS_64BIT)
880 STAFString(unsigned long fromValue, unsigned int base = 10);
881 STAFString(long fromValue, unsigned int base = 10);
882 #endif
883
884 STAFString(STAFUInt64_t fromValue, unsigned int base = 10);
885 STAFString(STAFInt64_t fromValue, unsigned int base = 10);
886 STAFString(const STAFString &from);
887 STAFString(STAFStringConst_t from);
888 STAFString(STAFString_t from, CopyMode mode = kDeep);
889 STAFString(STAFUTF8Char_t aChar);
890
891 // Substring functions
892 STAFString subString(unsigned int begin, unsigned int len = kRemainder,
893 IndexRep corb = kByte) const;
894
895 // Word functions
896 unsigned int numWords() const;
897 STAFString subWord(unsigned int begin,
898 unsigned int length = kRemainder) const;
899
900 // Data functions
901 unsigned int count(const STAFString &theSubStr) const;
902 unsigned int length(IndexRep corb = kByte) const;
903 unsigned int sizeOfChar(unsigned int index, IndexRep corb = kByte) const;
904 const char *buffer(unsigned int *bufLength = 0) const;
905 STAFString_t getImpl() const;
906 STAFString_t adoptImpl();
907 void replaceImpl(STAFString_t replacementImpl);
908
909 // Search functions
910 unsigned int byteIndexOfChar(unsigned int charIndex) const;
911 unsigned int find(const STAFString &searchFor, unsigned int begin = 0,
912 IndexRep corb = kByte) const;
913 unsigned int findFirstOf(const STAFString &searchList,
914 unsigned int begin = 0,
915 IndexRep corb = kByte) const;
916 unsigned int findFirstNotOf(const STAFString &searchList,
917 unsigned int begin = 0,
918 IndexRep corb = kByte) const;
919 unsigned int findLastOf(const STAFString &searchList,
920 unsigned int begin = 0,
921 IndexRep corb = kByte) const;
922 unsigned int findLastNotOf(const STAFString &searchList,
923 unsigned int begin = 0,
924 IndexRep corb = kByte) const;
925
926 // Miscellaneous alteration functions
927 STAFString &lowerCase();
928 STAFString &upperCase();
929 STAFString &strip(StripWhat stripWhat = kBoth);
930 STAFString &join(const STAFString stringArray[], unsigned int arraySize);
931
932 // Conversions
933 unsigned int asUInt(unsigned int base = 10) const;
934 unsigned int asUIntWithDefault(unsigned int defaultValue,
935 unsigned int base = 10) const;
936
937 /* XXX: Commented out until get UINT64_MAX working on Solaris
938 STAFUInt64_t asUInt64(unsigned int base = 10) const;
939 STAFUInt64_t asUInt64WithDefault(STAFUInt64_t defaultValue,
940 unsigned int base = 10) const;
941 */
942
943 STAFStringBufferPtr toCurrentCodePage() const;
944 STAFString toLowerCase() const;
945 STAFString toUpperCase() const;
946 STAFString replace(const STAFString oldchar,
947 const STAFString newchar) const;
948
949 // Evaluation
950 bool isWhiteSpace() const;
951 bool isDigits() const;
952 bool isEqualTo(const STAFString &theString,
953 STAFStringCaseSensitive_t caseSensitive =
954 kSTAFStringCaseSensitive) const;
955 bool startsWith(const STAFString &someString) const;
956 bool hasWildcard() const;
957 bool matchesWildcards(const STAFString &wildcardString,
958 STAFStringCaseSensitive_t caseSensitive =
959 kSTAFStringCaseSensitive) const;
960
961 // operators
962 STAFString &operator=(const STAFString &rhs);
963 bool operator==(const STAFString &rhs) const;
964 bool operator!=(const STAFString &rhs) const;
965 bool operator<(const STAFString &rhs) const;
966 bool operator<=(const STAFString &rhs) const;
967 bool operator>(const STAFString &rhs) const;
968 bool operator>=(const STAFString &rhs) const;
969 STAFString &operator+=(const STAFString &rhs);
970
971 friend STAFString operator+(const STAFString &lhs, const STAFString &rhs);
972 friend ostream &operator<<(ostream &os, const STAFString &rhs);
973
974 // Destructor
975 ~STAFString();
976
977 private:
978
979 STAFString_t fStringImpl;
980 };
981
982
983 // Now include inline definitions
984
985 #ifndef STAF_NATIVE_COMPILER
986 #include "STAFStringInlImpl.cpp"
987 #endif
988
989 // End C++ language definitions
990
991 // End #ifdef __cplusplus
992 #endif
993
994 #endif
995