1 | /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ |
2 | /* |
3 | * This file is part of the LibreOffice project. |
4 | * |
5 | * This Source Code Form is subject to the terms of the Mozilla Public |
6 | * License, v. 2.0. If a copy of the MPL was not distributed with this |
7 | * file, You can obtain one at http://mozilla.org/MPL/2.0/. |
8 | * |
9 | * This file incorporates work covered by the following license notice: |
10 | * |
11 | * Licensed to the Apache Software Foundation (ASF) under one or more |
12 | * contributor license agreements. See the NOTICE file distributed |
13 | * with this work for additional information regarding copyright |
14 | * ownership. The ASF licenses this file to you under the Apache |
15 | * License, Version 2.0 (the "License"); you may not use this file |
16 | * except in compliance with the License. You may obtain a copy of |
17 | * the License at http://www.apache.org/licenses/LICENSE-2.0 . |
18 | */ |
19 | |
20 | #ifndef INCLUDED_RTL_STRING_H |
21 | #define INCLUDED_RTL_STRING_H |
22 | |
23 | #include <sal/config.h> |
24 | |
25 | #include <osl/interlck.h> |
26 | #include <rtl/textcvt.h> |
27 | #include <sal/saldllapi.h> |
28 | #include <sal/types.h> |
29 | |
30 | #ifdef __cplusplus |
31 | extern "C" { |
32 | #endif |
33 | |
34 | /* ======================================================================= */ |
35 | |
36 | /** Return the length of a string. |
37 | |
38 | The length is equal to the number of 8-bit characters in the string, |
39 | without the terminating NUL character. |
40 | |
41 | @param str |
42 | a null-terminated string. |
43 | |
44 | @return |
45 | the length of the sequence of characters represented by this string, |
46 | excluding the terminating NUL character. |
47 | */ |
48 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_getLength( |
49 | const sal_Char * str ) SAL_THROW_EXTERN_C(); |
50 | |
51 | /** Compare two strings. |
52 | |
53 | The comparison is based on the numeric value of each character in the |
54 | strings and returns a value indicating their relationship. This function |
55 | cannot be used for language-specific sorting. Both strings must be |
56 | null-terminated. |
57 | |
58 | @param first |
59 | the first null-terminated string to be compared. |
60 | |
61 | @param second |
62 | the second null-terminated string which is compared with the first one. |
63 | |
64 | @return |
65 | 0 if both strings are equal, a value less than 0 if the first string is |
66 | less than the second string, and a value greater than 0 if the first |
67 | string is greater than the second string. |
68 | */ |
69 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_compare( |
70 | const sal_Char * first, const sal_Char * second ) SAL_THROW_EXTERN_C(); |
71 | |
72 | /** Compare two strings. |
73 | |
74 | The comparison is based on the numeric value of each character in the |
75 | strings and returns a value indicating their relationship. This function |
76 | cannot be used for language-specific sorting. |
77 | |
78 | @param first |
79 | the first string to be compared. Need not be null-terminated, but must be |
80 | at least as long as the specified firstLen. |
81 | |
82 | @param firstLen |
83 | the length of the first string. |
84 | |
85 | @param second |
86 | the second string which is compared with the first one. Need not be |
87 | null-terminated, but must be at least as long as the specified secondLen. |
88 | |
89 | @param secondLen |
90 | the length of the second string. |
91 | |
92 | @return |
93 | 0 if both strings are equal, a value less than 0 if the first string is |
94 | less than the second string, and a value greater than 0 if the first |
95 | string is greater than the second string. |
96 | */ |
97 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_compare_WithLength( |
98 | const sal_Char * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C(); |
99 | |
100 | /** Compare two strings with a maximum count of characters. |
101 | |
102 | The comparison is based on the numeric value of each character in the |
103 | strings and returns a value indicating their relationship. This function |
104 | cannot be used for language-specific sorting. |
105 | |
106 | @param first |
107 | the first string to be compared. Need not be null-terminated, but must be |
108 | at least as long as the specified firstLen. |
109 | |
110 | @param firstLen |
111 | the length of the first string. |
112 | |
113 | @param second |
114 | the second string which is compared with the first one. Need not be |
115 | null-terminated, but must be at least as long as the specified secondLen. |
116 | |
117 | @param secondLen |
118 | the length of the second string. |
119 | |
120 | @param shortenedLen |
121 | the maximum number of characters to compare. This length can be greater |
122 | or smaller than the lengths of the two strings. |
123 | |
124 | @return |
125 | 0 if both substrings are equal, a value less than 0 if the first substring |
126 | is less than the second substring, and a value greater than 0 if the first |
127 | substring is greater than the second substring. |
128 | */ |
129 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_shortenedCompare_WithLength( |
130 | const sal_Char * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C(); |
131 | |
132 | /** Compare two strings from back to front. |
133 | |
134 | The comparison is based on the numeric value of each character in the |
135 | strings and returns a value indicating their relationship. This function |
136 | cannot be used for language-specific sorting. |
137 | |
138 | @param first |
139 | the first string to be compared. Need not be null-terminated, but must be |
140 | at least as long as the specified firstLen. |
141 | |
142 | @param firstLen |
143 | the length of the first string. |
144 | |
145 | @param second |
146 | the second string which is compared with the first one. Need not be |
147 | null-terminated, but must be at least as long as the specified secondLen. |
148 | |
149 | @param secondLen |
150 | the length of the second string. |
151 | |
152 | @return |
153 | 0 if both strings are equal, a value less than 0 if the first string |
154 | compares less than the second string, and a value greater than 0 if the |
155 | first string compares greater than the second string. |
156 | */ |
157 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_reverseCompare_WithLength( |
158 | const sal_Char * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C(); |
159 | |
160 | /** Compare two strings, ignoring the case of ASCII characters. |
161 | |
162 | The comparison is based on the numeric value of each character in the |
163 | strings and returns a value indicating their relationship. Character |
164 | values between 65 and 90 (ASCII A--Z) are interpreted as values between 97 |
165 | and 122 (ASCII a--z). This function cannot be used for language-specific |
166 | sorting. Both strings must be null-terminated. |
167 | |
168 | @param first |
169 | the first null-terminated string to be compared. |
170 | |
171 | @param second |
172 | the second null-terminated string which is compared with the first one. |
173 | |
174 | @return |
175 | 0 if both strings are equal, a value less than 0 if the first string is |
176 | less than the second string, and a value greater than 0 if the first |
177 | string is greater than the second string. |
178 | */ |
179 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_compareIgnoreAsciiCase( |
180 | const sal_Char * first, const sal_Char * second ) SAL_THROW_EXTERN_C(); |
181 | |
182 | /** Compare two strings, ignoring the case of ASCII characters. |
183 | |
184 | The comparison is based on the numeric value of each character in the |
185 | strings and returns a value indicating their relationship. Character |
186 | values between 65 and 90 (ASCII A--Z) are interpreted as values between 97 |
187 | and 122 (ASCII a--z). This function cannot be used for language-specific |
188 | sorting. |
189 | |
190 | @param first |
191 | the first string to be compared. Need not be null-terminated, but must be |
192 | at least as long as the specified firstLen. |
193 | |
194 | @param firstLen |
195 | the length of the first string. |
196 | |
197 | @param second |
198 | the second string which is compared with the first one. Need not be |
199 | null-terminated, but must be at least as long as the specified secondLen. |
200 | |
201 | @param secondLen |
202 | the length of the second string. |
203 | |
204 | @return |
205 | 0 if both strings are equal, a value less than 0 if the first string is |
206 | less than the second string, and a value greater than 0 if the first |
207 | string is greater than the second string. |
208 | */ |
209 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_compareIgnoreAsciiCase_WithLength( |
210 | const sal_Char * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C(); |
211 | |
212 | /** Compare two strings with a maximum count of characters, ignoring the case |
213 | of ASCII characters. |
214 | |
215 | The comparison is based on the numeric value of each character in the |
216 | strings and returns a value indicating their relationship. Character |
217 | values between 65 and 90 (ASCII A--Z) are interpreted as values between 97 |
218 | and 122 (ASCII a--z). This function cannot be used for language-specific |
219 | sorting. |
220 | |
221 | @param first |
222 | the first string to be compared. Need not be null-terminated, but must be |
223 | at least as long as the specified firstLen. |
224 | |
225 | @param firstLen |
226 | the length of the first string. |
227 | |
228 | @param second |
229 | the second string which is compared with the first one. Need not be |
230 | null-terminated, but must be at least as long as the specified secondLen. |
231 | |
232 | @param secondLen |
233 | the length of the second string. |
234 | |
235 | @param shortenedLen |
236 | the maximum number of characters to compare. This length can be greater |
237 | or smaller than the lengths of the two strings. |
238 | |
239 | @return |
240 | 0 if both substrings are equal, a value less than 0 if the first substring |
241 | is less than the second substring, and a value greater than 0 if the first |
242 | substring is greater than the second substring. |
243 | */ |
244 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_shortenedCompareIgnoreAsciiCase_WithLength( |
245 | const sal_Char * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C(); |
246 | |
247 | /** Return a hash code for a string. |
248 | |
249 | It is not allowed to store the hash code persistently, because later |
250 | versions could return other hash codes. The string must be |
251 | null-terminated. |
252 | |
253 | @param str |
254 | a null-terminated string. |
255 | |
256 | @return |
257 | a hash code for the given string. |
258 | */ |
259 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_hashCode( |
260 | const sal_Char * str ) SAL_THROW_EXTERN_C(); |
261 | |
262 | /** Return a hash code for a string. |
263 | |
264 | It is not allowed to store the hash code persistently, because later |
265 | versions could return other hash codes. |
266 | |
267 | @param str |
268 | a string. Need not be null-terminated, but must be at least as long as |
269 | the specified len. |
270 | |
271 | @param len |
272 | the length of the string. |
273 | |
274 | @return |
275 | a hash code for the given string. |
276 | */ |
277 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_hashCode_WithLength( |
278 | const sal_Char * str, sal_Int32 len ) SAL_THROW_EXTERN_C(); |
279 | |
280 | /** Search for the first occurrence of a character within a string. |
281 | |
282 | The string must be null-terminated. |
283 | |
284 | @param str |
285 | a null-terminated string. |
286 | |
287 | @param ch |
288 | the character to be searched for. |
289 | |
290 | @return |
291 | the index (starting at 0) of the first occurrence of the character in the |
292 | string, or -1 if the character does not occur. |
293 | */ |
294 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_indexOfChar( |
295 | const sal_Char * str, sal_Char ch ) SAL_THROW_EXTERN_C(); |
296 | |
297 | /** Search for the first occurrence of a character within a string. |
298 | |
299 | @param str |
300 | a string. Need not be null-terminated, but must be at least as long as |
301 | the specified len. |
302 | |
303 | @param len |
304 | the length of the string. |
305 | |
306 | @param ch |
307 | the character to be searched for. |
308 | |
309 | @return |
310 | the index (starting at 0) of the first occurrence of the character in the |
311 | string, or -1 if the character does not occur. |
312 | */ |
313 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_indexOfChar_WithLength( |
314 | const sal_Char * str, sal_Int32 len, sal_Char ch ) SAL_THROW_EXTERN_C(); |
315 | |
316 | /** Search for the last occurrence of a character within a string. |
317 | |
318 | The string must be null-terminated. |
319 | |
320 | @param str |
321 | a null-terminated string. |
322 | |
323 | @param ch |
324 | the character to be searched for. |
325 | |
326 | @return |
327 | the index (starting at 0) of the last occurrence of the character in the |
328 | string, or -1 if the character does not occur. The returned value is |
329 | always smaller than the string length. |
330 | */ |
331 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_lastIndexOfChar( |
332 | const sal_Char * str, sal_Char ch ) SAL_THROW_EXTERN_C(); |
333 | |
334 | /** Search for the last occurrence of a character within a string. |
335 | |
336 | @param str |
337 | a string. Need not be null-terminated, but must be at least as long as |
338 | the specified len. |
339 | |
340 | @param len |
341 | the length of the string. |
342 | |
343 | @param ch |
344 | the character to be searched for. |
345 | |
346 | @return |
347 | the index (starting at 0) of the last occurrence of the character in the |
348 | string, or -1 if the character does not occur. The returned value is |
349 | always smaller than the string length. |
350 | */ |
351 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_lastIndexOfChar_WithLength( |
352 | const sal_Char * str, sal_Int32 len, sal_Char ch ) SAL_THROW_EXTERN_C(); |
353 | |
354 | /** Search for the first occurrence of a substring within a string. |
355 | |
356 | If subStr is empty, or both str and subStr are empty, -1 is returned. |
357 | Both strings must be null-terminated. |
358 | |
359 | @param str |
360 | a null-terminated string. |
361 | |
362 | @param subStr |
363 | the null-terminated substring to be searched for. |
364 | |
365 | @return |
366 | the index (starting at 0) of the first character of the first occurrence |
367 | of the substring within the string, or -1 if the substring does not occur. |
368 | */ |
369 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_indexOfStr( |
370 | const sal_Char * str, const sal_Char * subStr ) SAL_THROW_EXTERN_C(); |
371 | |
372 | /** Search for the first occurrence of a substring within a string. |
373 | |
374 | If subStr is empty, or both str and subStr are empty, -1 is returned. |
375 | |
376 | @param str |
377 | a string. Need not be null-terminated, but must be at least as long as |
378 | the specified len. |
379 | |
380 | @param len |
381 | the length of the string. |
382 | |
383 | @param subStr |
384 | the substring to be searched for. Need not be null-terminated, but must |
385 | be at least as long as the specified subLen. |
386 | |
387 | @param subLen |
388 | the length of the substring. |
389 | |
390 | @return |
391 | the index (starting at 0) of the first character of the first occurrence |
392 | of the substring within the string, or -1 if the substring does not occur. |
393 | */ |
394 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_indexOfStr_WithLength( |
395 | const sal_Char * str, sal_Int32 len, const sal_Char * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C(); |
396 | |
397 | /** Search for the last occurrence of a substring within a string. |
398 | |
399 | If subStr is empty, or both str and subStr are empty, -1 is returned. |
400 | Both strings must be null-terminated. |
401 | |
402 | @param str |
403 | a null-terminated string. |
404 | |
405 | @param subStr |
406 | the null-terminated substring to be searched for. |
407 | |
408 | @return |
409 | the index (starting at 0) of the first character of the last occurrence |
410 | of the substring within the string, or -1 if the substring does not occur. |
411 | */ |
412 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_lastIndexOfStr( |
413 | const sal_Char * str, const sal_Char * subStr ) SAL_THROW_EXTERN_C(); |
414 | |
415 | /** Search for the last occurrence of a substring within a string. |
416 | |
417 | If subStr is empty, or both str and subStr are empty, -1 is returned. |
418 | |
419 | @param str |
420 | a string. Need not be null-terminated, but must be at least as long as |
421 | the specified len. |
422 | |
423 | @param len |
424 | the length of the string. |
425 | |
426 | @param subStr |
427 | the substring to be searched for. Need not be null-terminated, but must |
428 | be at least as long as the specified subLen. |
429 | |
430 | @param subLen |
431 | the length of the substring. |
432 | |
433 | @return |
434 | the index (starting at 0) of the first character of the first occurrence |
435 | of the substring within the string, or -1 if the substring does not occur. |
436 | */ |
437 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_lastIndexOfStr_WithLength( |
438 | const sal_Char * str, sal_Int32 len, const sal_Char * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C(); |
439 | |
440 | /** Replace all occurrences of a single character within a string. |
441 | |
442 | If oldChar does not occur within str, then the string is not modified. |
443 | The string must be null-terminated. |
444 | |
445 | @param str |
446 | a null-terminated string. |
447 | |
448 | @param oldChar |
449 | the old character. |
450 | |
451 | @param newChar |
452 | the new character. |
453 | */ |
454 | SAL_DLLPUBLIC void SAL_CALL rtl_str_replaceChar( |
455 | sal_Char * str, sal_Char oldChar, sal_Char newChar ) SAL_THROW_EXTERN_C(); |
456 | |
457 | /** Replace all occurrences of a single character within a string. |
458 | |
459 | If oldChar does not occur within str, then the string is not modified. |
460 | |
461 | @param str |
462 | a string. Need not be null-terminated, but must be at least as long as |
463 | the specified len. |
464 | |
465 | @param len |
466 | the length of the string. |
467 | |
468 | @param oldChar |
469 | the old character. |
470 | |
471 | @param newChar |
472 | the new character. |
473 | */ |
474 | SAL_DLLPUBLIC void SAL_CALL rtl_str_replaceChar_WithLength( |
475 | sal_Char * str, sal_Int32 len, sal_Char oldChar, sal_Char newChar ) SAL_THROW_EXTERN_C(); |
476 | |
477 | /** Convert all ASCII uppercase letters to lowercase within a string. |
478 | |
479 | The characters with values between 65 and 90 (ASCII A--Z) are replaced |
480 | with values between 97 and 122 (ASCII a--z). The string must be |
481 | null-terminated. |
482 | |
483 | @param str |
484 | a null-terminated string. |
485 | */ |
486 | SAL_DLLPUBLIC void SAL_CALL rtl_str_toAsciiLowerCase( |
487 | sal_Char * str ) SAL_THROW_EXTERN_C(); |
488 | |
489 | /** Convert all ASCII uppercase letters to lowercase within a string. |
490 | |
491 | The characters with values between 65 and 90 (ASCII A--Z) are replaced |
492 | with values between 97 and 122 (ASCII a--z). |
493 | |
494 | @param str |
495 | a string. Need not be null-terminated, but must be at least as long as |
496 | the specified len. |
497 | |
498 | @param len |
499 | the length of the string. |
500 | */ |
501 | SAL_DLLPUBLIC void SAL_CALL rtl_str_toAsciiLowerCase_WithLength( |
502 | sal_Char * str, sal_Int32 len ) SAL_THROW_EXTERN_C(); |
503 | |
504 | /** Convert all ASCII lowercase letters to uppercase within a string. |
505 | |
506 | The characters with values between 97 and 122 (ASCII a--z) are replaced |
507 | with values between 65 and 90 (ASCII A--Z). The string must be |
508 | null-terminated. |
509 | |
510 | @param str |
511 | a null-terminated string. |
512 | */ |
513 | SAL_DLLPUBLIC void SAL_CALL rtl_str_toAsciiUpperCase( |
514 | sal_Char * str ) SAL_THROW_EXTERN_C(); |
515 | |
516 | /** Convert all ASCII lowercase letters to uppercase within a string. |
517 | |
518 | The characters with values between 97 and 122 (ASCII a--z) are replaced |
519 | with values between 65 and 90 (ASCII A--Z). |
520 | |
521 | @param str |
522 | a string. Need not be null-terminated, but must be at least as long as |
523 | the specified len. |
524 | |
525 | @param len |
526 | the length of the string. |
527 | */ |
528 | SAL_DLLPUBLIC void SAL_CALL rtl_str_toAsciiUpperCase_WithLength( |
529 | sal_Char * str, sal_Int32 len ) SAL_THROW_EXTERN_C(); |
530 | |
531 | /** Remove white space from both ends of a string. |
532 | |
533 | All characters with values less than or equal to 32 (the space character) |
534 | are considered to be white space. This function cannot be used for |
535 | language-specific operations. The string must be null-terminated. |
536 | |
537 | @param str |
538 | a null-terminated string. |
539 | |
540 | @return |
541 | the new length of the string. |
542 | */ |
543 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_trim( |
544 | sal_Char * str ) SAL_THROW_EXTERN_C(); |
545 | |
546 | /** Remove white space from both ends of the string. |
547 | |
548 | All characters with values less than or equal to 32 (the space character) |
549 | are considered to be white space. This function cannot be used for |
550 | language-specific operations. The string must be null-terminated. |
551 | |
552 | @param str |
553 | a string. Need not be null-terminated, but must be at least as long as |
554 | the specified len. |
555 | |
556 | @param len |
557 | the original length of the string. |
558 | |
559 | @return |
560 | the new length of the string. |
561 | */ |
562 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_trim_WithLength( |
563 | sal_Char * str, sal_Int32 len ) SAL_THROW_EXTERN_C(); |
564 | |
565 | /** Create the string representation of a boolean. |
566 | |
567 | If b is true, the buffer is filled with the string "true" and 5 is |
568 | returned. If b is false, the buffer is filled with the string "false" and |
569 | 6 is returned. This function cannot be used for language-specific |
570 | operations. |
571 | |
572 | @param str |
573 | a buffer that is big enough to hold the result and the terminating NUL |
574 | character. You should use the RTL_STR_MAX_VALUEOFBOOLEAN define to create |
575 | a buffer that is big enough. |
576 | |
577 | @param b |
578 | a boolean value. |
579 | |
580 | @return |
581 | the length of the string. |
582 | */ |
583 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfBoolean( |
584 | sal_Char * str, sal_Bool b ) SAL_THROW_EXTERN_C(); |
585 | #define RTL_STR_MAX_VALUEOFBOOLEAN 6 |
586 | |
587 | /** Create the string representation of a character. |
588 | |
589 | @param str |
590 | a buffer that is big enough to hold the result and the terminating NUL |
591 | character. You should use the RTL_STR_MAX_VALUEOFCHAR define to create a |
592 | buffer that is big enough. |
593 | |
594 | @param ch |
595 | a character value. |
596 | |
597 | @return |
598 | the length of the string. |
599 | */ |
600 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfChar( |
601 | sal_Char * str, sal_Char ch ) SAL_THROW_EXTERN_C(); |
602 | #define RTL_STR_MAX_VALUEOFCHAR 2 |
603 | |
604 | /** Create the string representation of an integer. |
605 | |
606 | This function cannot be used for language-specific operations. |
607 | |
608 | @param str |
609 | a buffer that is big enough to hold the result and the terminating NUL |
610 | character. You should use the RTL_STR_MAX_VALUEOFINT32 define to create a |
611 | buffer that is big enough. |
612 | |
613 | @param i |
614 | an integer value. |
615 | |
616 | @param radix |
617 | the radix. Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX |
618 | (36), inclusive. |
619 | |
620 | @return |
621 | the length of the string. |
622 | */ |
623 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfInt32( |
624 | sal_Char * str, sal_Int32 i, sal_Int16 radix ) SAL_THROW_EXTERN_C(); |
625 | #define RTL_STR_MIN_RADIX 2 |
626 | #define RTL_STR_MAX_RADIX 36 |
627 | #define RTL_STR_MAX_VALUEOFINT32 33 |
628 | |
629 | /** Create the string representation of a long integer. |
630 | |
631 | This function cannot be used for language-specific operations. |
632 | |
633 | @param str |
634 | a buffer that is big enough to hold the result and the terminating NUL |
635 | character. You should use the RTL_STR_MAX_VALUEOFINT64 define to create a |
636 | buffer that is big enough. |
637 | |
638 | @param l |
639 | a long integer value. |
640 | |
641 | @param radix |
642 | the radix. Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX |
643 | (36), inclusive. |
644 | |
645 | @return |
646 | the length of the string. |
647 | */ |
648 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfInt64( |
649 | sal_Char * str, sal_Int64 l, sal_Int16 radix ) SAL_THROW_EXTERN_C(); |
650 | #define RTL_STR_MAX_VALUEOFINT64 65 |
651 | |
652 | /** Create the string representation of an unsigned long integer. |
653 | |
654 | This function cannot be used for language-specific operations. |
655 | |
656 | @param str |
657 | a buffer that is big enough to hold the result and the terminating NUL |
658 | character. You should use the RTL_STR_MAX_VALUEOFUINT64 define to create a |
659 | buffer that is big enough. |
660 | |
661 | @param l |
662 | a long integer value. |
663 | |
664 | @param radix |
665 | the radix. Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX |
666 | (36), inclusive. |
667 | |
668 | @return |
669 | the length of the string. |
670 | */ |
671 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfUInt64( |
672 | sal_Char * str, sal_uInt64 l, sal_Int16 radix ) SAL_THROW_EXTERN_C(); |
673 | #define RTL_STR_MAX_VALUEOFUINT64 65 |
674 | |
675 | /** Create the string representation of a float. |
676 | |
677 | This function cannot be used for language-specific conversion. |
678 | |
679 | @param str |
680 | a buffer that is big enough to hold the result and the terminating NUL |
681 | character. You should use the RTL_STR_MAX_VALUEOFFLOAT define to create a |
682 | buffer that is big enough. |
683 | |
684 | @param f |
685 | a float value. |
686 | |
687 | @return |
688 | the length of the string. |
689 | */ |
690 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfFloat( |
691 | sal_Char * str, float f ) SAL_THROW_EXTERN_C(); |
692 | #define RTL_STR_MAX_VALUEOFFLOAT 15 |
693 | |
694 | /** Create the string representation of a double. |
695 | |
696 | This function cannot be used for language-specific conversion. |
697 | |
698 | @param str |
699 | a buffer that is big enough to hold the result and the terminating NUL |
700 | character. You should use the RTL_STR_MAX_VALUEOFDOUBLE define to create |
701 | a buffer that is big enough. |
702 | |
703 | @param d |
704 | a double value. |
705 | |
706 | @return |
707 | the length of the string. |
708 | */ |
709 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfDouble( |
710 | sal_Char * str, double d ) SAL_THROW_EXTERN_C(); |
711 | #define RTL_STR_MAX_VALUEOFDOUBLE 25 |
712 | |
713 | /** Interpret a string as a boolean. |
714 | |
715 | This function cannot be used for language-specific conversion. The string |
716 | must be null-terminated. |
717 | |
718 | @param str |
719 | a null-terminated string. |
720 | |
721 | @return |
722 | true if the string is "1" or "true" in any ASCII case, false otherwise. |
723 | */ |
724 | SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_str_toBoolean( |
725 | const sal_Char * str ) SAL_THROW_EXTERN_C(); |
726 | |
727 | /** Interpret a string as an integer. |
728 | |
729 | This function cannot be used for language-specific conversion. The string |
730 | must be null-terminated. |
731 | |
732 | @param str |
733 | a null-terminated string. |
734 | |
735 | @param radix |
736 | the radix. Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX |
737 | (36), inclusive. |
738 | |
739 | @return |
740 | the integer value represented by the string, or 0 if the string does not |
741 | represent an integer. |
742 | */ |
743 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_toInt32( |
744 | const sal_Char * str, sal_Int16 radix ) SAL_THROW_EXTERN_C(); |
745 | |
746 | /** Interpret a string as an unsigned integer. |
747 | |
748 | This function cannot be used for language-specific conversion. The string |
749 | must be null-terminated. |
750 | |
751 | @param str |
752 | a null-terminated string. |
753 | |
754 | @param radix |
755 | the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX |
756 | (36), inclusive. |
757 | |
758 | @return |
759 | the unsigned integer value represented by the string, or 0 if the string |
760 | does not represent an unsigned integer. |
761 | |
762 | @since LibreOffice 4.2 |
763 | */ |
764 | SAL_DLLPUBLIC sal_uInt32 SAL_CALL rtl_str_toUInt32( |
765 | const sal_Char * str, sal_Int16 radix ) SAL_THROW_EXTERN_C(); |
766 | |
767 | /** Interpret a string as a long integer. |
768 | |
769 | This function cannot be used for language-specific conversion. The string |
770 | must be null-terminated. |
771 | |
772 | @param str |
773 | a null-terminated string. |
774 | |
775 | @param radix |
776 | the radix. Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX |
777 | (36), inclusive. |
778 | |
779 | @return |
780 | the long integer value represented by the string, or 0 if the string does |
781 | not represent a long integer. |
782 | */ |
783 | SAL_DLLPUBLIC sal_Int64 SAL_CALL rtl_str_toInt64( |
784 | const sal_Char * str, sal_Int16 radix ) SAL_THROW_EXTERN_C(); |
785 | |
786 | /** Interpret a string as an unsigned long integer. |
787 | |
788 | This function cannot be used for language-specific conversion. The string |
789 | must be null-terminated. |
790 | |
791 | @param str |
792 | a null-terminated string. |
793 | |
794 | @param radix |
795 | the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX |
796 | (36), inclusive. |
797 | |
798 | @return |
799 | the unsigned long integer value represented by the string, or 0 if the |
800 | string does not represent an unsigned long integer. |
801 | |
802 | @since LibreOffice 4.1 |
803 | */ |
804 | SAL_DLLPUBLIC sal_uInt64 SAL_CALL rtl_str_toUInt64( |
805 | const sal_Char * str, sal_Int16 radix ) SAL_THROW_EXTERN_C(); |
806 | |
807 | /** Interpret a string as a float. |
808 | |
809 | This function cannot be used for language-specific conversion. The string |
810 | must be null-terminated. |
811 | |
812 | @param str |
813 | a null-terminated string. |
814 | |
815 | @return |
816 | the float value represented by the string, or 0.0 if the string does not |
817 | represent a float. |
818 | */ |
819 | SAL_DLLPUBLIC float SAL_CALL rtl_str_toFloat( |
820 | const sal_Char * str ) SAL_THROW_EXTERN_C(); |
821 | |
822 | /** Interpret a string as a double. |
823 | |
824 | This function cannot be used for language-specific conversion. The string |
825 | must be null-terminated. |
826 | |
827 | @param str |
828 | a null-terminated string. |
829 | |
830 | @return |
831 | the float value represented by the string, or 0.0 if the string does not |
832 | represent a double. |
833 | */ |
834 | SAL_DLLPUBLIC double SAL_CALL rtl_str_toDouble( |
835 | const sal_Char * str ) SAL_THROW_EXTERN_C(); |
836 | |
837 | /* ======================================================================= */ |
838 | |
839 | #ifdef SAL_W32 |
840 | # pragma pack(push, 8) |
841 | #endif |
842 | |
843 | /** @cond INTERNAL */ |
844 | /** The implementation of a byte string. |
845 | */ |
846 | typedef struct _rtl_String |
847 | { |
848 | oslInterlockedCount refCount; /* opaque */ |
849 | sal_Int32 length; |
850 | sal_Char buffer[1]; |
851 | } rtl_String; |
852 | /** @endcond */ |
853 | |
854 | #if defined(SAL_W32) |
855 | #pragma pack(pop) |
856 | #endif |
857 | |
858 | /* ----------------------------------------------------------------------- */ |
859 | |
860 | /** Increment the reference count of a string. |
861 | |
862 | @param str |
863 | a string. |
864 | */ |
865 | SAL_DLLPUBLIC void SAL_CALL rtl_string_acquire( rtl_String * str ) SAL_THROW_EXTERN_C(); |
866 | |
867 | /** Decrement the reference count of a string. |
868 | |
869 | If the count goes to zero than the string data is deleted. |
870 | |
871 | @param str |
872 | a string. |
873 | */ |
874 | SAL_DLLPUBLIC void SAL_CALL rtl_string_release( rtl_String * str ) SAL_THROW_EXTERN_C(); |
875 | |
876 | /** Allocate a new string containing no characters. |
877 | |
878 | @param newStr |
879 | pointer to the new string. The pointed-to data must be null or a valid |
880 | string. |
881 | */ |
882 | SAL_DLLPUBLIC void SAL_CALL rtl_string_new( rtl_String ** newStr ) SAL_THROW_EXTERN_C(); |
883 | |
884 | /** Allocate a new string containing space for a given number of characters. |
885 | |
886 | The reference count of the new string will be 1. The length of the string |
887 | will be nLen. This function does not handle out-of-memory conditions. |
888 | |
889 | For nLen < 0 or failed allocation this method returns NULL. |
890 | |
891 | The characters of the capacity are not cleared, and the length is set to |
892 | nLen, unlike the similar method of rtl_String_new_WithLength which |
893 | zeros out the buffer, and sets the length to 0. So should be somewhat |
894 | more efficient for allocating a new string. |
895 | |
896 | call rtl_String_release to release the string |
897 | alternatively pass ownership to an OUString with |
898 | rtl::OUString(newStr, SAL_NO_ACQUIRE); |
899 | |
900 | @param[out] nLen the number of characters. |
901 | @return pointer to the new string. |
902 | |
903 | @since LibreOffice 4.1 |
904 | */ |
905 | SAL_DLLPUBLIC rtl_String * SAL_CALL rtl_string_alloc(sal_Int32 nLen) SAL_THROW_EXTERN_C(); |
906 | |
907 | /** Allocate a new string containing space for a given number of characters. |
908 | |
909 | If len is greater than zero, the reference count of the new string will be |
910 | 1. The values of all characters are set to 0 and the length of the string |
911 | is 0. This function does not handle out-of-memory conditions. |
912 | |
913 | @param newStr |
914 | pointer to the new string. The pointed-to data must be null or a valid |
915 | string. |
916 | |
917 | @param len |
918 | the number of characters. |
919 | */ |
920 | SAL_DLLPUBLIC void SAL_CALL rtl_string_new_WithLength( rtl_String ** newStr, sal_Int32 len ) SAL_THROW_EXTERN_C(); |
921 | |
922 | /** Allocate a new string that contains a copy of another string. |
923 | |
924 | If the length of value is greater than zero, the reference count of the |
925 | new string will be 1. This function does not handle out-of-memory |
926 | conditions. |
927 | |
928 | @param newStr |
929 | pointer to the new string. The pointed-to data must be null or a valid |
930 | string. |
931 | |
932 | @param value |
933 | a valid string. |
934 | */ |
935 | SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromString( rtl_String ** newStr, const rtl_String * value ) SAL_THROW_EXTERN_C(); |
936 | |
937 | /** Allocate a new string that contains a copy of a character array. |
938 | |
939 | If the length of value is greater than zero, the reference count of the |
940 | new string will be 1. This function does not handle out-of-memory |
941 | conditions. |
942 | |
943 | @param newStr |
944 | pointer to the new string. The pointed-to data must be null or a valid |
945 | string. |
946 | |
947 | @param value |
948 | a null-terminated character array. |
949 | */ |
950 | SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromStr( rtl_String ** newStr, const sal_Char * value ) SAL_THROW_EXTERN_C(); |
951 | |
952 | /** Allocate a new string that contains a copy of a character array. |
953 | |
954 | If the length of value is greater than zero, the reference count of the |
955 | new string will be 1. This function does not handle out-of-memory |
956 | conditions. |
957 | |
958 | @param newStr |
959 | pointer to the new string. The pointed-to data must be null or a valid |
960 | string. |
961 | |
962 | @param value |
963 | a character array. Need not be null-terminated, but must be at least as |
964 | long as the specified len. |
965 | |
966 | @param len |
967 | the length of the character array. |
968 | */ |
969 | SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromStr_WithLength( rtl_String ** newStr, const sal_Char * value, sal_Int32 len ) SAL_THROW_EXTERN_C(); |
970 | |
971 | /** Allocate a new string that is a substring of this string. |
972 | |
973 | The substring begins at the specified beginIndex and contains count |
974 | characters. Meaningless combinations such as negative beginIndex, |
975 | or beginIndex + count greater than the length of the string have |
976 | undefined behaviour. |
977 | |
978 | @param[out] newStr the specified substring. |
979 | @param[in] from the String to take the substring from. |
980 | @param[in] beginIndex the beginning index, inclusive. |
981 | @param[in] count the number of characters. |
982 | |
983 | @since LibreOffice 4.0 |
984 | */ |
985 | SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromSubString( |
986 | rtl_String ** newStr, const rtl_String * from, |
987 | sal_Int32 beginIndex, sal_Int32 count ) SAL_THROW_EXTERN_C(); |
988 | |
989 | /** |
990 | @internal |
991 | @since LibreOffice 3.6 |
992 | */ |
993 | SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromLiteral( rtl_String ** newStr, const sal_Char * value, sal_Int32 len, sal_Int32 ) SAL_THROW_EXTERN_C(); |
994 | |
995 | /** Assign a new value to a string. |
996 | |
997 | First releases any value str might currently hold, then acquires |
998 | rightValue. |
999 | |
1000 | @param str |
1001 | pointer to the string. The pointed-to data must be null or a valid |
1002 | string. |
1003 | |
1004 | @param rightValue |
1005 | a valid string. |
1006 | */ |
1007 | SAL_DLLPUBLIC void SAL_CALL rtl_string_assign( rtl_String ** str, rtl_String * rightValue ) SAL_THROW_EXTERN_C(); |
1008 | |
1009 | /** Return the length of a string. |
1010 | |
1011 | The length is equal to the number of characters in the string. |
1012 | |
1013 | @param str |
1014 | a valid string. |
1015 | |
1016 | @return |
1017 | the length of the string. |
1018 | */ |
1019 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_string_getLength( const rtl_String * str ) SAL_THROW_EXTERN_C(); |
1020 | |
1021 | /** Return a pointer to the underlying character array of a string. |
1022 | |
1023 | @param str |
1024 | a valid string. |
1025 | |
1026 | @return |
1027 | a pointer to the null-terminated character array. |
1028 | */ |
1029 | SAL_DLLPUBLIC sal_Char * SAL_CALL rtl_string_getStr( rtl_String * str ) SAL_THROW_EXTERN_C(); |
1030 | |
1031 | /** Create a new string that is the concatenation of two other strings. |
1032 | |
1033 | The new string does not necessarily have a reference count of 1 (in cases |
1034 | where one of the two other strings is empty), so it must not be modified |
1035 | without checking the reference count. This function does not handle |
1036 | out-of-memory conditions. |
1037 | |
1038 | @param newStr |
1039 | pointer to the new string. The pointed-to data must be null or a valid |
1040 | string. |
1041 | |
1042 | @param left |
1043 | a valid string. |
1044 | |
1045 | @param right |
1046 | a valid string. |
1047 | */ |
1048 | SAL_DLLPUBLIC void SAL_CALL rtl_string_newConcat( rtl_String ** newStr, rtl_String * left, rtl_String * right ) SAL_THROW_EXTERN_C(); |
1049 | |
1050 | /** Create a new string by replacing a substring of another string. |
1051 | |
1052 | The new string results from replacing a number of characters (count), |
1053 | starting at the specified position (index) in the original string (str), |
1054 | with some new substring (subStr). If subStr is null, than only a number |
1055 | of characters is deleted. |
1056 | |
1057 | The new string does not necessarily have a reference count of 1, so it |
1058 | must not be modified without checking the reference count. This function |
1059 | does not handle out-of-memory conditions. |
1060 | |
1061 | @param newStr |
1062 | pointer to the new string. The pointed-to data must be null or a valid |
1063 | string. |
1064 | |
1065 | @param str |
1066 | a valid string. |
1067 | |
1068 | @param idx |
1069 | the index into str at which to start replacement. Must be between 0 and |
1070 | the length of str, inclusive. |
1071 | |
1072 | @param count |
1073 | the number of characters to remove. Must not be negative, and the sum of |
1074 | index and count must not exceed the length of str. |
1075 | |
1076 | @param subStr |
1077 | either null or a valid string to be inserted. |
1078 | */ |
1079 | SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplaceStrAt( |
1080 | rtl_String ** newStr, rtl_String * str, sal_Int32 idx, sal_Int32 count, rtl_String * subStr ) SAL_THROW_EXTERN_C(); |
1081 | |
1082 | /** Create a new string by replacing all occurrences of a single character |
1083 | within another string. |
1084 | |
1085 | The new string results from replacing all occurrences of oldChar in str |
1086 | with newChar. |
1087 | |
1088 | The new string does not necessarily have a reference count of 1 (in cases |
1089 | where oldChar does not occur in str), so it must not be modified without |
1090 | checking the reference count. This function does not handle out-of-memory |
1091 | conditions. |
1092 | |
1093 | @param newStr |
1094 | pointer to the new string. The pointed-to data must be null or a valid |
1095 | string. |
1096 | |
1097 | @param str |
1098 | a valid string. |
1099 | |
1100 | @param oldChar |
1101 | the old character. |
1102 | |
1103 | @param newChar |
1104 | the new character. |
1105 | */ |
1106 | SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplace( |
1107 | rtl_String ** newStr, rtl_String * str, sal_Char oldChar, sal_Char newChar ) SAL_THROW_EXTERN_C(); |
1108 | |
1109 | /** Create a new string by replacing the first occurrence of a given substring |
1110 | with another substring. |
1111 | |
1112 | @param[in, out] newStr pointer to the new string; must not be null; must |
1113 | point to null or a valid rtl_String |
1114 | |
1115 | @param str pointer to the original string; must not be null |
1116 | |
1117 | @param from pointer to the substring to be replaced; must not be null and |
1118 | must point to memory of at least \p fromLength bytes |
1119 | |
1120 | @param fromLength the length of the \p from substring; must be non-negative |
1121 | |
1122 | @param to pointer to the replacing substring; must not be null and must |
1123 | point to memory of at least \p toLength bytes |
1124 | |
1125 | @param toLength the length of the \p to substring; must be non-negative |
1126 | |
1127 | @param[in,out] index pointer to a start index, must not be null; upon entry |
1128 | to the function its value is the index into the original string at which to |
1129 | start searching for the \p from substring, the value must be non-negative |
1130 | and not greater than the original string's length; upon exit from the |
1131 | function its value is the index into the original string at which the |
1132 | replacement took place or -1 if no replacement took place |
1133 | |
1134 | @since LibreOffice 3.6 |
1135 | */ |
1136 | SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplaceFirst( |
1137 | rtl_String ** newStr, rtl_String * str, char const * from, |
1138 | sal_Int32 fromLength, char const * to, sal_Int32 toLength, |
1139 | sal_Int32 * index) SAL_THROW_EXTERN_C(); |
1140 | |
1141 | /** Create a new string by replacing all occurrences of a given substring with |
1142 | another substring. |
1143 | |
1144 | Replacing subsequent occurrences picks up only after a given replacement. |
1145 | That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx". |
1146 | |
1147 | @param[in, out] newStr pointer to the new string; must not be null; must |
1148 | point to null or a valid rtl_String |
1149 | |
1150 | @param str pointer to the original string; must not be null |
1151 | |
1152 | @param from pointer to the substring to be replaced; must not be null and |
1153 | must point to memory of at least \p fromLength bytes |
1154 | |
1155 | @param fromLength the length of the \p from substring; must be non-negative |
1156 | |
1157 | @param to pointer to the replacing substring; must not be null and must |
1158 | point to memory of at least \p toLength bytes |
1159 | |
1160 | @param toLength the length of the \p to substring; must be non-negative |
1161 | |
1162 | @since LibreOffice 3.6 |
1163 | */ |
1164 | SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplaceAll( |
1165 | rtl_String ** newStr, rtl_String * str, char const * from, |
1166 | sal_Int32 fromLength, char const * to, sal_Int32 toLength) |
1167 | SAL_THROW_EXTERN_C(); |
1168 | |
1169 | /** Create a new string by converting all ASCII uppercase letters to lowercase |
1170 | within another string. |
1171 | |
1172 | The new string results from replacing all characters with values between |
1173 | 65 and 90 (ASCII A--Z) by values between 97 and 122 (ASCII a--z). |
1174 | |
1175 | This function cannot be used for language-specific conversion. The new |
1176 | string does not necessarily have a reference count of 1 (in cases where |
1177 | no characters need to be converted), so it must not be modified without |
1178 | checking the reference count. This function does not handle out-of-memory |
1179 | conditions. |
1180 | |
1181 | @param newStr |
1182 | pointer to the new string. The pointed-to data must be null or a valid |
1183 | string. |
1184 | |
1185 | @param str |
1186 | a valid string. |
1187 | */ |
1188 | SAL_DLLPUBLIC void SAL_CALL rtl_string_newToAsciiLowerCase( |
1189 | rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C(); |
1190 | |
1191 | /** Create a new string by converting all ASCII lowercase letters to uppercase |
1192 | within another string. |
1193 | |
1194 | The new string results from replacing all characters with values between |
1195 | 97 and 122 (ASCII a--z) by values between 65 and 90 (ASCII A--Z). |
1196 | |
1197 | This function cannot be used for language-specific conversion. The new |
1198 | string does not necessarily have a reference count of 1 (in cases where |
1199 | no characters need to be converted), so it must not be modified without |
1200 | checking the reference count. This function does not handle out-of-memory |
1201 | conditions. |
1202 | |
1203 | @param newStr |
1204 | pointer to the new string. The pointed-to data must be null or a valid |
1205 | string. |
1206 | |
1207 | @param str |
1208 | a valid string. |
1209 | */ |
1210 | SAL_DLLPUBLIC void SAL_CALL rtl_string_newToAsciiUpperCase( |
1211 | rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C(); |
1212 | |
1213 | /** Create a new string by removing white space from both ends of another |
1214 | string. |
1215 | |
1216 | The new string results from removing all characters with values less than |
1217 | or equal to 32 (the space character) form both ends of str. |
1218 | |
1219 | This function cannot be used for language-specific conversion. The new |
1220 | string does not necessarily have a reference count of 1 (in cases where |
1221 | no characters need to be removed), so it must not be modified without |
1222 | checking the reference count. This function does not handle out-of-memory |
1223 | conditions. |
1224 | |
1225 | @param newStr |
1226 | pointer to the new string. The pointed-to data must be null or a valid |
1227 | string. |
1228 | |
1229 | @param str |
1230 | a valid string. |
1231 | */ |
1232 | SAL_DLLPUBLIC void SAL_CALL rtl_string_newTrim( |
1233 | rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C(); |
1234 | |
1235 | /** Create a new string by extracting a single token from another string. |
1236 | |
1237 | Starting at index, the token's next token is searched for. If there is no |
1238 | such token, the result is an empty string. Otherwise, all characters from |
1239 | the start of that token and up to, but not including the next occurrence |
1240 | of cTok make up the resulting token. The return value is the position of |
1241 | the next token, or -1 if no more tokens follow. |
1242 | |
1243 | Example code could look like |
1244 | rtl_String * pToken = NULL; |
1245 | sal_Int32 nIndex = 0; |
1246 | do |
1247 | { |
1248 | ... |
1249 | nIndex = rtl_string_getToken(&pToken, pStr, 0, ';', nIndex); |
1250 | ... |
1251 | } |
1252 | while (nIndex >= 0); |
1253 | |
1254 | The new string does not necessarily have a reference count of 1, so it |
1255 | must not be modified without checking the reference count. This function |
1256 | does not handle out-of-memory conditions. |
1257 | |
1258 | @param newStr |
1259 | pointer to the new string. The pointed-to data must be null or a valid |
1260 | string. If either token or index is negative, an empty token is stored in |
1261 | newStr (and -1 is returned). |
1262 | |
1263 | @param str |
1264 | a valid string. |
1265 | |
1266 | @param token |
1267 | the number of the token to return, starting at index. |
1268 | |
1269 | @param cTok |
1270 | the character that separates the tokens. |
1271 | |
1272 | @param idx |
1273 | the position at which searching for the token starts. Must not be greater |
1274 | than the length of str. |
1275 | |
1276 | @return |
1277 | the index of the next token, or -1 if no more tokens follow. |
1278 | */ |
1279 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_string_getToken( |
1280 | rtl_String ** newStr , rtl_String * str, sal_Int32 token, sal_Char cTok, sal_Int32 idx ) SAL_THROW_EXTERN_C(); |
1281 | |
1282 | /* ======================================================================= */ |
1283 | |
1284 | /** Supply an ASCII string literal together with its length. |
1285 | |
1286 | This macro can be used to compute (some of) the arguments in function calls |
1287 | like rtl::OString(RTL_CONSTASCII_STRINGPARAM("foo")) or |
1288 | rtl::OUString::equalsAsciiL(RTL_CONSTASCII_STRINGPARAM("foo")). |
1289 | |
1290 | @param constAsciiStr |
1291 | must be an expression of type "(possibly cv-qualified reference to) array of |
1292 | (possibly cv-qualified) char." Each element of the referenced array must |
1293 | represent an ASCII value in the range 0x00--0x7F. The last element of the |
1294 | referenced array is not considered part of the represented ASCII string, and |
1295 | its value should be 0x00. Depending on where this macro is used, the nature |
1296 | of the supplied expression might be further restricted. |
1297 | */ |
1298 | // The &foo[0] trick is intentional, it makes sure the type is char* or const char* |
1299 | // (plain cast to const char* would not work with non-const char foo[]="a", which seems to be allowed). |
1300 | // This is to avoid mistaken use with functions that accept string literals |
1301 | // (i.e. const char (&)[N]) where usage of this macro otherwise could match |
1302 | // the argument and a following int argument with a default value (e.g. OString::match()). |
1303 | #define RTL_CONSTASCII_STRINGPARAM( constAsciiStr ) (&(constAsciiStr)[0]), \ |
1304 | ((sal_Int32)SAL_N_ELEMENTS(constAsciiStr)-1) |
1305 | |
1306 | /** Supply the length of an ASCII string literal. |
1307 | |
1308 | This macro can be used to compute arguments in function calls like |
1309 | rtl::OUString::match(other, RTL_CONSTASCII_LENGTH("prefix")). |
1310 | |
1311 | @param constAsciiStr |
1312 | must be an expression of type "(possibly cv-qualified reference to) array of |
1313 | (possibly cv-qualified) char." Each element of the referenced array must |
1314 | represent an ASCII value in the range 0x00--0x7F. The last element of the |
1315 | referenced array is not considered part of the represented ASCII string, and |
1316 | its value should be 0x00. Depending on where this macro is used, the nature |
1317 | of the supplied expression might be further restricted. |
1318 | */ |
1319 | #define RTL_CONSTASCII_LENGTH( constAsciiStr ) ((sal_Int32)(SAL_N_ELEMENTS(constAsciiStr)-1)) |
1320 | |
1321 | /* ======================================================================= */ |
1322 | |
1323 | /* predefined constants for String-Conversion */ |
1324 | #define OUSTRING_TO_OSTRING_CVTFLAGS (RTL_UNICODETOTEXT_FLAGS_UNDEFINED_DEFAULT |\ |
1325 | RTL_UNICODETOTEXT_FLAGS_INVALID_DEFAULT |\ |
1326 | RTL_UNICODETOTEXT_FLAGS_UNDEFINED_REPLACE |\ |
1327 | RTL_UNICODETOTEXT_FLAGS_PRIVATE_MAPTO0 |\ |
1328 | RTL_UNICODETOTEXT_FLAGS_NOCOMPOSITE) |
1329 | |
1330 | /* ----------------------------------------------------------------------- */ |
1331 | |
1332 | /** Create a new byte string by converting a Unicode string, using a specific |
1333 | text encoding. |
1334 | |
1335 | The lengths of the byte string and the Unicode string may differ (e.g., |
1336 | for double-byte encodings, UTF-7, UTF-8). |
1337 | |
1338 | If the length of the Unicode string is greater than zero, the reference |
1339 | count of the new string will be 1. |
1340 | |
1341 | If an out-of-memory condition occurs, newStr will point to a null pointer |
1342 | upon return. |
1343 | |
1344 | @param newStr |
1345 | pointer to the new string. The pointed-to data must be null or a valid |
1346 | string. |
1347 | |
1348 | @param str |
1349 | a Unicode character array. Need not be null-terminated, but must be at |
1350 | least as long as the specified len. |
1351 | |
1352 | @param len |
1353 | the length of the Unicode character array. |
1354 | |
1355 | @param encoding |
1356 | the text encoding to use for conversion. |
1357 | |
1358 | @param convertFlags |
1359 | flags which control the conversion. Either use |
1360 | OUSTRING_TO_OSTRING_CVTFLAGS, or see |
1361 | <http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more |
1362 | details. |
1363 | */ |
1364 | SAL_DLLPUBLIC void SAL_CALL rtl_uString2String( |
1365 | rtl_String ** newStr, const sal_Unicode * str, sal_Int32 len, rtl_TextEncoding encoding, sal_uInt32 convertFlags ) SAL_THROW_EXTERN_C(); |
1366 | |
1367 | /** |
1368 | Converts a Unicode string to a byte string, signalling failure. |
1369 | |
1370 | @param pTarget |
1371 | An out parameter receiving the converted string. Must not be null itself, and |
1372 | must contain either null or a pointer to a valid rtl_String; the contents are |
1373 | not modified if conversion fails (rtl_convertUStringToString returns false). |
1374 | |
1375 | @param pSource |
1376 | The Unicode string. May only be null if nLength is zero. |
1377 | |
1378 | @param nLength |
1379 | The length of the Unicode string. Must be non-negative. |
1380 | |
1381 | @param nEncoding |
1382 | The text encoding to convert into. Must be an octet encoding (i.e., |
1383 | rtl_isOctetTextEncoding(nEncoding) must return true). |
1384 | |
1385 | @param nFlags |
1386 | A combination of RTL_UNICODETOTEXT_FLAGS that detail how to do the conversion |
1387 | (see rtl_convertUnicodeToText). RTL_UNICODETOTEXT_FLAGS_FLUSH need not be |
1388 | included, it is implicitly assumed. Typical uses are either |
1389 | RTL_UNICODETOTEXT_FLAGS_UNDEFINED_ERROR | |
1390 | RTL_UNICODETOTEXT_FLAGS_INVALID_ERROR (fail if a Unicode character cannot be |
1391 | converted to the target nEncoding) or OUSTRING_TO_OSTRING_CVTFLAGS (make a |
1392 | best efforts conversion). |
1393 | |
1394 | @return |
1395 | True if the conversion succeeded, false otherwise. |
1396 | */ |
1397 | SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_convertUStringToString( |
1398 | rtl_String ** pTarget, |
1399 | sal_Unicode const * pSource, |
1400 | sal_Int32 nLength, |
1401 | rtl_TextEncoding nEncoding, |
1402 | sal_uInt32 nFlags) |
1403 | SAL_THROW_EXTERN_C(); |
1404 | |
1405 | /** Ensure a string has enough space for a given number of characters. |
1406 | |
1407 | If the given string is large enough and has refcount of 1, it is not altered in any way. |
1408 | Otherwise it is replaced by a copy that has enough space for the given number of characters, |
1409 | data from the source string is copied to the beginning of it, the content of the remaining |
1410 | capacity undefined, the string has refcount of 1, and refcount of the original string is decreased. |
1411 | |
1412 | @param str |
1413 | pointer to the string. The pointed-to data must be a valid string. |
1414 | |
1415 | @param size |
1416 | the number of characters |
1417 | |
1418 | @since LibreOffice 4.1 |
1419 | @internal |
1420 | */ |
1421 | SAL_DLLPUBLIC void SAL_CALL rtl_string_ensureCapacity( rtl_String ** str, sal_Int32 size ) SAL_THROW_EXTERN_C(); |
1422 | |
1423 | #ifdef __cplusplus |
1424 | } |
1425 | #endif |
1426 | |
1427 | #endif // INCLUDED_RTL_STRING_H |
1428 | |
1429 | /* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |
1430 | |