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_USTRING_H |
21 | #define INCLUDED_RTL_USTRING_H |
22 | |
23 | #include <sal/config.h> |
24 | |
25 | #include <osl/interlck.h> |
26 | #include <rtl/string.h> |
27 | #include <rtl/textenc.h> |
28 | #include <sal/saldllapi.h> |
29 | #include <sal/types.h> |
30 | |
31 | #ifdef __cplusplus |
32 | extern "C" { |
33 | #endif |
34 | |
35 | /* ======================================================================= */ |
36 | |
37 | /** Return the length of a string. |
38 | |
39 | The length is equal to the number of 16-bit Unicode characters in the |
40 | string, without the terminating NUL character. |
41 | |
42 | @param str |
43 | a null-terminated string. |
44 | |
45 | @return |
46 | the length of the sequence of characters represented by this string, |
47 | excluding the terminating NUL character. |
48 | */ |
49 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_getLength( |
50 | const sal_Unicode * str ) SAL_THROW_EXTERN_C(); |
51 | |
52 | /** Compare two strings. |
53 | |
54 | The comparison is based on the numeric value of each character in the |
55 | strings and returns a value indicating their relationship. This function |
56 | cannot be used for language-specific sorting. Both strings must be |
57 | null-terminated. |
58 | |
59 | @param first |
60 | the first null-terminated string to be compared. |
61 | |
62 | @param second |
63 | the second null-terminated string which is compared with the first one. |
64 | |
65 | @return |
66 | 0 if both strings are equal, a value less than 0 if the first string is |
67 | less than the second string, and a value greater than 0 if the first |
68 | string is greater than the second string. |
69 | */ |
70 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_compare( |
71 | const sal_Unicode * first, const sal_Unicode * second ) SAL_THROW_EXTERN_C(); |
72 | |
73 | /** Compare two strings. |
74 | |
75 | The comparison is based on the numeric value of each character in the |
76 | strings and returns a value indicating their relationship. This function |
77 | cannot be used for language-specific sorting. |
78 | |
79 | @param first |
80 | the first string to be compared. Need not be null-terminated, but must be |
81 | at least as long as the specified firstLen. |
82 | |
83 | @param firstLen |
84 | the length of the first string. |
85 | |
86 | @param second |
87 | the second string which is compared with the first one. Need not be |
88 | null-terminated, but must be at least as long as the specified secondLen. |
89 | |
90 | @param secondLen |
91 | the length of the second string. |
92 | |
93 | @return |
94 | 0 if both strings are equal, a value less than 0 if the first string is |
95 | less than the second string, and a value greater than 0 if the first |
96 | string is greater than the second string. |
97 | */ |
98 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_compare_WithLength( |
99 | const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C(); |
100 | |
101 | /** Compare two strings with a maximum count of characters. |
102 | |
103 | The comparison is based on the numeric value of each character in the |
104 | strings and returns a value indicating their relationship. This function |
105 | cannot be used for language-specific sorting. |
106 | |
107 | @param first |
108 | the first string to be compared. Need not be null-terminated, but must be |
109 | at least as long as the specified firstLen. |
110 | |
111 | @param firstLen |
112 | the length of the first string. |
113 | |
114 | @param second |
115 | the second string which is compared with the first one. Need not be |
116 | null-terminated, but must be at least as long as the specified secondLen. |
117 | |
118 | @param secondLen |
119 | the length of the second string. |
120 | |
121 | @param shortenedLen |
122 | the maximum number of characters to compare. This length can be greater |
123 | or smaller than the lengths of the two strings. |
124 | |
125 | @return |
126 | 0 if both substrings are equal, a value less than 0 if the first substring |
127 | is less than the second substring, and a value greater than 0 if the first |
128 | substring is greater than the second substring. |
129 | */ |
130 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_shortenedCompare_WithLength( |
131 | const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C(); |
132 | |
133 | /** Compare two strings from back to front. |
134 | |
135 | The comparison is based on the numeric value of each character in the |
136 | strings and returns a value indicating their relationship. This function |
137 | cannot be used for language-specific sorting. |
138 | |
139 | @param first |
140 | the first string to be compared. Need not be null-terminated, but must be |
141 | at least as long as the specified firstLen. |
142 | |
143 | @param firstLen |
144 | the length of the first string. |
145 | |
146 | @param second |
147 | the second string which is compared with the first one. Need not be |
148 | null-terminated, but must be at least as long as the specified secondLen. |
149 | |
150 | @param secondLen |
151 | the length of the second string. |
152 | |
153 | @return |
154 | 0 if both strings are equal, a value less than 0 if the first string |
155 | compares less than the second string, and a value greater than 0 if the |
156 | first string compares greater than the second string. |
157 | */ |
158 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_reverseCompare_WithLength( |
159 | const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C(); |
160 | |
161 | /** Compare two strings from back to front for equality. |
162 | |
163 | The comparison is based on the numeric value of each character in the |
164 | strings and returns 'true' if, ans only if, both strings are equal. |
165 | This function cannot be used for language-specific sorting. |
166 | |
167 | @param first |
168 | the first string to be compared. Need not be null-terminated, but must be |
169 | at least as long as the specified len. |
170 | |
171 | @param second |
172 | the second string which is compared with the first one. Need not be |
173 | null-terminated, but must be at least as long as the specified len. |
174 | |
175 | @param len |
176 | the length of both strings. |
177 | |
178 | @return |
179 | true if both strings are equal, false if they are not equal. |
180 | */ |
181 | |
182 | SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_ustr_asciil_reverseEquals_WithLength( |
183 | const sal_Unicode * first, const sal_Char * second, sal_Int32 len ) SAL_THROW_EXTERN_C(); |
184 | |
185 | /** Compare two strings, ignoring the case of ASCII characters. |
186 | |
187 | The comparison is based on the numeric value of each character in the |
188 | strings and returns a value indicating their relationship. Character |
189 | values between 65 and 90 (ASCII A--Z) are interpreted as values between 97 |
190 | and 122 (ASCII a--z). This function cannot be used for language-specific |
191 | sorting. Both strings must be null-terminated. |
192 | |
193 | @param first |
194 | the first null-terminated string to be compared. |
195 | |
196 | @param second |
197 | the second null-terminated string which is compared with the first one. |
198 | |
199 | @return |
200 | 0 if both strings are equal, a value less than 0 if the first string is |
201 | less than the second string, and a value greater than 0 if the first |
202 | string is greater than the second string. |
203 | */ |
204 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_compareIgnoreAsciiCase( |
205 | const sal_Unicode * first, const sal_Unicode * second ) SAL_THROW_EXTERN_C(); |
206 | |
207 | /** Compare two strings, ignoring the case of ASCII characters. |
208 | |
209 | The comparison is based on the numeric value of each character in the |
210 | strings and returns a value indicating their relationship. Character |
211 | values between 65 and 90 (ASCII A--Z) are interpreted as values between 97 |
212 | and 122 (ASCII a--z). This function cannot be used for language-specific |
213 | sorting. |
214 | |
215 | @param first |
216 | the first string to be compared. Need not be null-terminated, but must be |
217 | at least as long as the specified firstLen. |
218 | |
219 | @param firstLen |
220 | the length of the first string. |
221 | |
222 | @param second |
223 | the second string which is compared with the first one. Need not be |
224 | null-terminated, but must be at least as long as the specified secondLen. |
225 | |
226 | @param secondLen |
227 | the length of the second string. |
228 | |
229 | @return |
230 | 0 if both strings are equal, a value less than 0 if the first string is |
231 | less than the second string, and a value greater than 0 if the first |
232 | string is greater than the second string. |
233 | */ |
234 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_compareIgnoreAsciiCase_WithLength( |
235 | const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C(); |
236 | |
237 | /** Compare two strings with a maximum count of characters, ignoring the case |
238 | of ASCII characters. |
239 | |
240 | The comparison is based on the numeric value of each character in the |
241 | strings and returns a value indicating their relationship. Character |
242 | values between 65 and 90 (ASCII A--Z) are interpreted as values between 97 |
243 | and 122 (ASCII a--z). This function cannot be used for language-specific |
244 | sorting. |
245 | |
246 | @param first |
247 | the first string to be compared. Need not be null-terminated, but must be |
248 | at least as long as the specified firstLen. |
249 | |
250 | @param firstLen |
251 | the length of the first string. |
252 | |
253 | @param second |
254 | the second string which is compared with the first one. Need not be |
255 | null-terminated, but must be at least as long as the specified secondLen. |
256 | |
257 | @param secondLen |
258 | the length of the second string. |
259 | |
260 | @param shortenedLen |
261 | the maximum number of characters to compare. This length can be greater |
262 | or smaller than the lengths of the two strings. |
263 | |
264 | @return |
265 | 0 if both substrings are equal, a value less than 0 if the first substring |
266 | is less than the second substring, and a value greater than 0 if the first |
267 | substring is greater than the second substring. |
268 | */ |
269 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_shortenedCompareIgnoreAsciiCase_WithLength( |
270 | const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C(); |
271 | |
272 | /** Compare two strings. |
273 | |
274 | The comparison is based on the numeric value of each character in the |
275 | strings and returns a value indicating their relationship. This function |
276 | cannot be used for language-specific sorting. Both strings must be |
277 | null-terminated. |
278 | |
279 | Since this function is optimized for performance, the ASCII character |
280 | values are not converted in any way. The caller has to make sure that |
281 | all ASCII characters are in the allowed range of 0 and 127, inclusive. |
282 | |
283 | @param first |
284 | the first null-terminated string to be compared. |
285 | |
286 | @param second |
287 | the second null-terminated ASCII string which is compared with the first |
288 | one. |
289 | |
290 | @return |
291 | 0 if both substrings are equal, a value less than 0 if the first substring |
292 | is less than the second substring, and a value greater than 0 if the first |
293 | substring is greater than the second substring. |
294 | */ |
295 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_compare( |
296 | const sal_Unicode * first, const sal_Char * second ) SAL_THROW_EXTERN_C(); |
297 | |
298 | /** Compare two strings. |
299 | |
300 | The comparison is based on the numeric value of each character in the |
301 | strings and returns a value indicating their relationship. This function |
302 | cannot be used for language-specific sorting. |
303 | |
304 | Since this function is optimized for performance, the ASCII character |
305 | values are not converted in any way. The caller has to make sure that |
306 | all ASCII characters are in the allowed range of 0 and 127, inclusive. |
307 | |
308 | @param first |
309 | the first string to be compared. Need not be null-terminated, but must be |
310 | at least as long as the specified firstLen. |
311 | |
312 | @param firstLen |
313 | the length of the first string. |
314 | |
315 | @param second |
316 | the second null-terminated ASCII string which is compared with the first |
317 | one. |
318 | |
319 | @return |
320 | 0 if both substrings are equal, a value less than 0 if the first substring |
321 | is less than the second substring, and a value greater than 0 if the first |
322 | substring is greater than the second substring. |
323 | */ |
324 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_compare_WithLength( |
325 | const sal_Unicode * first, sal_Int32 firstLen, const sal_Char * second ) SAL_THROW_EXTERN_C(); |
326 | |
327 | /** Compare two strings with a maximum count of characters. |
328 | |
329 | The comparison is based on the numeric value of each character in the |
330 | strings and returns a value indicating their relationship. This function |
331 | cannot be used for language-specific sorting. |
332 | |
333 | Since this function is optimized for performance, the ASCII character |
334 | values are not converted in any way. The caller has to make sure that |
335 | all ASCII characters are in the allowed range of 0 and 127, inclusive. |
336 | |
337 | @param first |
338 | the first string to be compared. Need not be null-terminated, but must be |
339 | at least as long as the specified firstLen. |
340 | |
341 | @param firstLen |
342 | the length of the first string. |
343 | |
344 | @param second |
345 | the second null-terminated ASCII string which is compared with the first |
346 | one. |
347 | |
348 | @param shortenedLen |
349 | the maximum number of characters to compare. This length can be greater |
350 | or smaller than the lengths of the two strings. |
351 | |
352 | @return |
353 | 0 if both substrings are equal, a value less than 0 if the first substring |
354 | is less than the second substring, and a value greater than 0 if the first |
355 | substring is greater than the second substring. |
356 | */ |
357 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_shortenedCompare_WithLength( |
358 | const sal_Unicode * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C(); |
359 | |
360 | /** Compare two strings from back to front. |
361 | |
362 | The comparison is based on the numeric value of each character in the |
363 | strings and returns a value indicating their relationship. This function |
364 | cannot be used for language-specific sorting. |
365 | |
366 | Since this function is optimized for performance, the ASCII character |
367 | values are not converted in any way. The caller has to make sure that |
368 | all ASCII characters are in the allowed range of 0 and 127, inclusive. |
369 | |
370 | @param first |
371 | the first string to be compared. Need not be null-terminated, but must be |
372 | at least as long as the specified firstLen. |
373 | |
374 | @param firstLen |
375 | the length of the first string. |
376 | |
377 | @param second |
378 | the second ASCII string which is compared with the first one. Need not be |
379 | null-terminated, but must be at least as long as the specified secondLen. |
380 | |
381 | @param secondLen |
382 | the length of the second string. |
383 | |
384 | @return |
385 | 0 if both strings are equal, a value less than 0 if the first string |
386 | compares less than the second string, and a value greater than 0 if the |
387 | first string compares greater than the second string. |
388 | */ |
389 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_asciil_reverseCompare_WithLength( |
390 | const sal_Unicode * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C(); |
391 | |
392 | /** Compare two strings, ignoring the case of ASCII characters. |
393 | |
394 | The comparison is based on the numeric value of each character in the |
395 | strings and returns a value indicating their relationship. Character |
396 | values between 65 and 90 (ASCII A--Z) are interpreted as values between 97 |
397 | and 122 (ASCII a--z). This function cannot be used for language-specific |
398 | sorting. Both strings must be null-terminated. |
399 | |
400 | Since this function is optimized for performance, the ASCII character |
401 | values are not converted in any way. The caller has to make sure that |
402 | all ASCII characters are in the allowed range of 0 and 127, inclusive. |
403 | |
404 | @param first |
405 | the first null-terminated string to be compared. |
406 | |
407 | @param second |
408 | the second null-terminated ASCII string which is compared with the first |
409 | one. |
410 | |
411 | @return |
412 | 0 if both strings are equal, a value less than 0 if the first string is |
413 | less than the second string, and a value greater than 0 if the first |
414 | string is greater than the second string. |
415 | */ |
416 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_compareIgnoreAsciiCase( |
417 | const sal_Unicode * first, const sal_Char * second ) SAL_THROW_EXTERN_C(); |
418 | |
419 | /** Compare two strings, ignoring the case of ASCII characters. |
420 | |
421 | The comparison is based on the numeric value of each character in the |
422 | strings and returns a value indicating their relationship. Character |
423 | values between 65 and 90 (ASCII A--Z) are interpreted as values between 97 |
424 | and 122 (ASCII a--z). This function cannot be used for language-specific |
425 | sorting. |
426 | |
427 | Since this function is optimized for performance, the ASCII character |
428 | values are not converted in any way. The caller has to make sure that |
429 | all ASCII characters are in the allowed range of 0 and 127, inclusive. |
430 | |
431 | @param first |
432 | the first string to be compared. Need not be null-terminated, but must be |
433 | at least as long as the specified firstLen. |
434 | |
435 | @param firstLen |
436 | the length of the first string. |
437 | |
438 | @param second |
439 | the second null-terminated ASCII string which is compared with the first |
440 | one. |
441 | |
442 | @return |
443 | 0 if both strings are equal, a value less than 0 if the first string is |
444 | less than the second string, and a value greater than 0 if the first |
445 | string is greater than the second string. |
446 | */ |
447 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_compareIgnoreAsciiCase_WithLength( |
448 | const sal_Unicode * first, sal_Int32 firstLen, const sal_Char * second ) SAL_THROW_EXTERN_C(); |
449 | |
450 | /** Compare two strings, ignoring the case of ASCII characters. |
451 | |
452 | The comparison is based on the numeric value of each character in the |
453 | strings and returns a value indicating their relationship. Character |
454 | values between 65 and 90 (ASCII A--Z) are interpreted as values between 97 |
455 | and 122 (ASCII a--z). This function cannot be used for language-specific |
456 | sorting. |
457 | |
458 | Since this function is optimized for performance, the ASCII character |
459 | values are not converted in any way. The caller has to make sure that |
460 | all ASCII characters are in the allowed range of 0 and 127, inclusive. |
461 | |
462 | @param first |
463 | the first string to be compared. Need not be null-terminated, but must be |
464 | at least as long as the specified firstLen. |
465 | |
466 | @param firstLen |
467 | the length of the first string. |
468 | |
469 | @param second |
470 | the second string which is compared with the first one. Need not be |
471 | null-terminated, but must be at least as long as the specified secondLen. |
472 | |
473 | @param secondLen |
474 | the length of the second string. |
475 | |
476 | @return |
477 | 0 if both strings are equal, a value less than 0 if the first string is |
478 | less than the second string, and a value greater than 0 if the first |
479 | string is greater than the second string. |
480 | */ |
481 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_compareIgnoreAsciiCase_WithLengths( |
482 | sal_Unicode const * first, sal_Int32 firstLen, |
483 | char const * second, sal_Int32 secondLen) SAL_THROW_EXTERN_C(); |
484 | |
485 | /** Compare two strings with a maximum count of characters, ignoring the case |
486 | of ASCII characters. |
487 | |
488 | The comparison is based on the numeric value of each character in the |
489 | strings and returns a value indicating their relationship. Character |
490 | values between 65 and 90 (ASCII A--Z) are interpreted as values between 97 |
491 | and 122 (ASCII a--z). This function cannot be used for language-specific |
492 | sorting. |
493 | |
494 | Since this function is optimized for performance, the ASCII character |
495 | values are not converted in any way. The caller has to make sure that |
496 | all ASCII characters are in the allowed range of 0 and 127, inclusive. |
497 | |
498 | @param first |
499 | the first string to be compared. Need not be null-terminated, but must be |
500 | at least as long as the specified firstLen. |
501 | |
502 | @param firstLen |
503 | the length of the first string. |
504 | |
505 | @param second |
506 | the second null-terminated ASCII string which is compared with the first |
507 | one. |
508 | |
509 | @param shortenedLen |
510 | the maximum number of characters to compare. This length can be greater |
511 | or smaller than the lengths of the two strings. |
512 | |
513 | @return |
514 | 0 if both substrings are equal, a value less than 0 if the first substring |
515 | is less than the second substring, and a value greater than 0 if the first |
516 | substring is greater than the second substring. |
517 | */ |
518 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_shortenedCompareIgnoreAsciiCase_WithLength( |
519 | const sal_Unicode * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C(); |
520 | |
521 | /** Return a hash code for a string. |
522 | |
523 | It is not allowed to store the hash code persistently, because later |
524 | versions could return other hash codes. The string must be |
525 | null-terminated. |
526 | |
527 | @param str |
528 | a null-terminated string. |
529 | |
530 | @return |
531 | a hash code for the given string. |
532 | */ |
533 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_hashCode( |
534 | const sal_Unicode * str ) SAL_THROW_EXTERN_C(); |
535 | |
536 | /** Return a hash code for a string. |
537 | |
538 | It is not allowed to store the hash code persistently, because later |
539 | versions could return other hash codes. |
540 | |
541 | @param str |
542 | a string. Need not be null-terminated, but must be at least as long as |
543 | the specified len. |
544 | |
545 | @param len |
546 | the length of the string. |
547 | |
548 | @return |
549 | a hash code for the given string. |
550 | */ |
551 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_hashCode_WithLength( |
552 | const sal_Unicode * str, sal_Int32 len ) SAL_THROW_EXTERN_C(); |
553 | |
554 | /** Search for the first occurrence of a character within a string. |
555 | |
556 | The string must be null-terminated. |
557 | |
558 | @param str |
559 | a null-terminated string. |
560 | |
561 | @param ch |
562 | the character to be searched for. |
563 | |
564 | @return |
565 | the index (starting at 0) of the first occurrence of the character in the |
566 | string, or -1 if the character does not occur. |
567 | */ |
568 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_indexOfChar( |
569 | const sal_Unicode * str, sal_Unicode ch ) SAL_THROW_EXTERN_C(); |
570 | |
571 | /** Search for the first occurrence of a character within a string. |
572 | |
573 | @param str |
574 | a string. Need not be null-terminated, but must be at least as long as |
575 | the specified len. |
576 | |
577 | @param len |
578 | the length of the string. |
579 | |
580 | @param ch |
581 | the character to be searched for. |
582 | |
583 | @return |
584 | the index (starting at 0) of the first occurrence of the character in the |
585 | string, or -1 if the character does not occur. |
586 | */ |
587 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_indexOfChar_WithLength( |
588 | const sal_Unicode * str, sal_Int32 len, sal_Unicode ch ) SAL_THROW_EXTERN_C(); |
589 | |
590 | /** Search for the last occurrence of a character within a string. |
591 | |
592 | The string must be null-terminated. |
593 | |
594 | @param str |
595 | a null-terminated string. |
596 | |
597 | @param ch |
598 | the character to be searched for. |
599 | |
600 | @return |
601 | the index (starting at 0) of the last occurrence of the character in the |
602 | string, or -1 if the character does not occur. The returned value is |
603 | always smaller than the string length. |
604 | */ |
605 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_lastIndexOfChar( |
606 | const sal_Unicode * str, sal_Unicode ch ) SAL_THROW_EXTERN_C(); |
607 | |
608 | /** Search for the last occurrence of a character within a string. |
609 | |
610 | @param str |
611 | a string. Need not be null-terminated, but must be at least as long as |
612 | the specified len. |
613 | |
614 | @param len |
615 | the length of the string. |
616 | |
617 | @param ch |
618 | the character to be searched for. |
619 | |
620 | @return |
621 | the index (starting at 0) of the last occurrence of the character in the |
622 | string, or -1 if the character does not occur. The returned value is |
623 | always smaller than the string length. |
624 | */ |
625 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_lastIndexOfChar_WithLength( |
626 | const sal_Unicode * str, sal_Int32 len, sal_Unicode ch ) SAL_THROW_EXTERN_C(); |
627 | |
628 | /** Search for the first occurrence of a substring within a string. |
629 | |
630 | If subStr is empty, or both str and subStr are empty, -1 is returned. |
631 | Both strings must be null-terminated. |
632 | |
633 | @param str |
634 | a null-terminated string. |
635 | |
636 | @param subStr |
637 | the null-terminated substring to be searched for. |
638 | |
639 | @return |
640 | the index (starting at 0) of the first character of the first occurrence |
641 | of the substring within the string, or -1 if the substring does not occur. |
642 | */ |
643 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_indexOfStr( |
644 | const sal_Unicode * str, const sal_Unicode * subStr ) SAL_THROW_EXTERN_C(); |
645 | |
646 | /** Search for the first occurrence of a substring within a string. |
647 | |
648 | If subStr is empty, or both str and subStr are empty, -1 is returned. |
649 | |
650 | @param str |
651 | a string. Need not be null-terminated, but must be at least as long as |
652 | the specified len. |
653 | |
654 | @param len |
655 | the length of the string. |
656 | |
657 | @param subStr |
658 | the substring to be searched for. Need not be null-terminated, but must |
659 | be at least as long as the specified subLen. |
660 | |
661 | @param subLen |
662 | the length of the substring. |
663 | |
664 | @return |
665 | the index (starting at 0) of the first character of the first occurrence |
666 | of the substring within the string, or -1 if the substring does not occur. |
667 | */ |
668 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_indexOfStr_WithLength( |
669 | const sal_Unicode * str, sal_Int32 len, const sal_Unicode * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C(); |
670 | |
671 | /** Search for the first occurrence of an ASCII substring within a string. |
672 | |
673 | @param str |
674 | a string. Need not be null-terminated, but must be at least as long as |
675 | the specified len. |
676 | |
677 | @param len |
678 | the length of the string; must be non-negative. |
679 | |
680 | @param subStr |
681 | the substring to be searched for. Need not be null-terminated, but must |
682 | be at least as long as the specified subLen. Must only contain characters |
683 | in the ASCII range 0x00--7F. |
684 | |
685 | @param subLen |
686 | the length of the substring; must be non-negative. |
687 | |
688 | @return |
689 | the index (starting at 0) of the first character of the first occurrence |
690 | of the substring within the string, or -1 if the substring does not occur. |
691 | If subLen is zero, -1 is returned. |
692 | |
693 | @since UDK 3.2.7 |
694 | */ |
695 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_indexOfAscii_WithLength( |
696 | sal_Unicode const * str, sal_Int32 len, |
697 | char const * subStr, sal_Int32 subLen) SAL_THROW_EXTERN_C(); |
698 | |
699 | /** Search for the last occurrence of a substring within a string. |
700 | |
701 | If subStr is empty, or both str and subStr are empty, -1 is returned. |
702 | Both strings must be null-terminated. |
703 | |
704 | @param str |
705 | a null-terminated string. |
706 | |
707 | @param subStr |
708 | the null-terminated substring to be searched for. |
709 | |
710 | @return |
711 | the index (starting at 0) of the first character of the last occurrence |
712 | of the substring within the string, or -1 if the substring does not occur. |
713 | */ |
714 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_lastIndexOfStr( |
715 | const sal_Unicode * str, const sal_Unicode * subStr ) SAL_THROW_EXTERN_C(); |
716 | |
717 | /** Search for the last occurrence of a substring within a string. |
718 | |
719 | If subStr is empty, or both str and subStr are empty, -1 is returned. |
720 | |
721 | @param str |
722 | a string. Need not be null-terminated, but must be at least as long as |
723 | the specified len. |
724 | |
725 | @param len |
726 | the length of the string. |
727 | |
728 | @param subStr |
729 | the substring to be searched for. Need not be null-terminated, but must |
730 | be at least as long as the specified subLen. |
731 | |
732 | @param subLen |
733 | the length of the substring. |
734 | |
735 | @return |
736 | the index (starting at 0) of the first character of the first occurrence |
737 | of the substring within the string, or -1 if the substring does not occur. |
738 | */ |
739 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_lastIndexOfStr_WithLength( |
740 | const sal_Unicode * str, sal_Int32 len, const sal_Unicode * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C(); |
741 | |
742 | /** Search for the last occurrence of an ASCII substring within a string. |
743 | |
744 | @param str |
745 | a string. Need not be null-terminated, but must be at least as long as |
746 | the specified len. |
747 | |
748 | @param len |
749 | the length of the string; must be non-negative. |
750 | |
751 | @param subStr |
752 | the substring to be searched for. Need not be null-terminated, but must |
753 | be at least as long as the specified subLen. Must only contain characters |
754 | in the ASCII range 0x00--7F. |
755 | |
756 | @param subLen |
757 | the length of the substring; must be non-negative. |
758 | |
759 | @return |
760 | the index (starting at 0) of the first character of the last occurrence |
761 | of the substring within the string, or -1 if the substring does not occur. |
762 | If subLen is zero, -1 is returned. |
763 | |
764 | @since UDK 3.2.7 |
765 | */ |
766 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_lastIndexOfAscii_WithLength( |
767 | sal_Unicode const * str, sal_Int32 len, |
768 | char const * subStr, sal_Int32 subLen) SAL_THROW_EXTERN_C(); |
769 | |
770 | /** Replace all occurrences of a single character within a string. |
771 | |
772 | If oldChar does not occur within str, then the string is not modified. |
773 | The string must be null-terminated. |
774 | |
775 | @param str |
776 | a null-terminated string. |
777 | |
778 | @param oldChar |
779 | the old character. |
780 | |
781 | @param newChar |
782 | the new character. |
783 | */ |
784 | SAL_DLLPUBLIC void SAL_CALL rtl_ustr_replaceChar( |
785 | sal_Unicode * str, sal_Unicode oldChar, sal_Unicode newChar ) SAL_THROW_EXTERN_C(); |
786 | |
787 | /** Replace all occurrences of a single character within a string. |
788 | |
789 | If oldChar does not occur within str, then the string is not modified. |
790 | |
791 | @param str |
792 | a string. Need not be null-terminated, but must be at least as long as |
793 | the specified len. |
794 | |
795 | @param len |
796 | the length of the string. |
797 | |
798 | @param oldChar |
799 | the old character. |
800 | |
801 | @param newChar |
802 | the new character. |
803 | */ |
804 | SAL_DLLPUBLIC void SAL_CALL rtl_ustr_replaceChar_WithLength( |
805 | sal_Unicode * str, sal_Int32 len, sal_Unicode oldChar, sal_Unicode newChar ) SAL_THROW_EXTERN_C(); |
806 | |
807 | /** Convert all ASCII uppercase letters to lowercase within a string. |
808 | |
809 | The characters with values between 65 and 90 (ASCII A--Z) are replaced |
810 | with values between 97 and 122 (ASCII a--z). The string must be |
811 | null-terminated. |
812 | |
813 | @param str |
814 | a null-terminated string. |
815 | */ |
816 | SAL_DLLPUBLIC void SAL_CALL rtl_ustr_toAsciiLowerCase( |
817 | sal_Unicode * str ) SAL_THROW_EXTERN_C(); |
818 | |
819 | /** Convert all ASCII uppercase letters to lowercase within a string. |
820 | |
821 | The characters with values between 65 and 90 (ASCII A--Z) are replaced |
822 | with values between 97 and 122 (ASCII a--z). |
823 | |
824 | @param str |
825 | a string. Need not be null-terminated, but must be at least as long as |
826 | the specified len. |
827 | |
828 | @param len |
829 | the length of the string. |
830 | */ |
831 | SAL_DLLPUBLIC void SAL_CALL rtl_ustr_toAsciiLowerCase_WithLength( |
832 | sal_Unicode * str, sal_Int32 len ) SAL_THROW_EXTERN_C(); |
833 | |
834 | /** Convert all ASCII lowercase letters to uppercase within a string. |
835 | |
836 | The characters with values between 97 and 122 (ASCII a--z) are replaced |
837 | with values between 65 and 90 (ASCII A--Z). The string must be |
838 | null-terminated. |
839 | |
840 | @param str |
841 | a null-terminated string. |
842 | */ |
843 | SAL_DLLPUBLIC void SAL_CALL rtl_ustr_toAsciiUpperCase( |
844 | sal_Unicode * str ) SAL_THROW_EXTERN_C(); |
845 | |
846 | /** Convert all ASCII lowercase letters to uppercase within a string. |
847 | |
848 | The characters with values between 97 and 122 (ASCII a--z) are replaced |
849 | with values between 65 and 90 (ASCII A--Z). |
850 | |
851 | @param str |
852 | a string. Need not be null-terminated, but must be at least as long as |
853 | the specified len. |
854 | |
855 | @param len |
856 | the length of the string. |
857 | */ |
858 | SAL_DLLPUBLIC void SAL_CALL rtl_ustr_toAsciiUpperCase_WithLength( |
859 | sal_Unicode * str, sal_Int32 len ) SAL_THROW_EXTERN_C(); |
860 | |
861 | /** Remove white space from both ends of a string. |
862 | |
863 | All characters with values less than or equal to 32 (the space character) |
864 | are considered to be white space. This function cannot be used for |
865 | language-specific operations. The string must be null-terminated. |
866 | |
867 | @param str |
868 | a null-terminated string. |
869 | |
870 | @return |
871 | the new length of the string. |
872 | */ |
873 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_trim( |
874 | sal_Unicode * str ) SAL_THROW_EXTERN_C(); |
875 | |
876 | /** Remove white space from both ends of the string. |
877 | |
878 | All characters with values less than or equal to 32 (the space character) |
879 | are considered to be white space. This function cannot be used for |
880 | language-specific operations. The string must be null-terminated. |
881 | |
882 | @param str |
883 | a string. Need not be null-terminated, but must be at least as long as |
884 | the specified len. |
885 | |
886 | @param len |
887 | the original length of the string. |
888 | |
889 | @return |
890 | the new length of the string. |
891 | */ |
892 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_trim_WithLength( |
893 | sal_Unicode * str, sal_Int32 len ) SAL_THROW_EXTERN_C(); |
894 | |
895 | /** Create the string representation of a boolean. |
896 | |
897 | If b is true, the buffer is filled with the string "true" and 5 is |
898 | returned. If b is false, the buffer is filled with the string "false" and |
899 | 6 is returned. This function cannot be used for language-specific |
900 | operations. |
901 | |
902 | @param str |
903 | a buffer that is big enough to hold the result and the terminating NUL |
904 | character. You should use the RTL_USTR_MAX_VALUEOFBOOLEAN define to |
905 | create a buffer that is big enough. |
906 | |
907 | @param b |
908 | a boolean value. |
909 | |
910 | @return |
911 | the length of the string. |
912 | */ |
913 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfBoolean( |
914 | sal_Unicode * str, sal_Bool b ) SAL_THROW_EXTERN_C(); |
915 | #define RTL_USTR_MAX_VALUEOFBOOLEAN RTL_STR_MAX_VALUEOFBOOLEAN |
916 | |
917 | /** Create the string representation of a character. |
918 | |
919 | @param str |
920 | a buffer that is big enough to hold the result and the terminating NUL |
921 | character. You should use the RTL_USTR_MAX_VALUEOFCHAR define to create a |
922 | buffer that is big enough. |
923 | |
924 | @param ch |
925 | a character value. |
926 | |
927 | @return |
928 | the length of the string. |
929 | */ |
930 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfChar( |
931 | sal_Unicode * str, sal_Unicode ch ) SAL_THROW_EXTERN_C(); |
932 | #define RTL_USTR_MAX_VALUEOFCHAR RTL_STR_MAX_VALUEOFCHAR |
933 | |
934 | /** Create the string representation of an integer. |
935 | |
936 | This function cannot be used for language-specific operations. |
937 | |
938 | @param str |
939 | a buffer that is big enough to hold the result and the terminating NUL |
940 | character. You should use the RTL_USTR_MAX_VALUEOFINT32 define to create |
941 | a buffer that is big enough. |
942 | |
943 | @param i |
944 | an integer value. |
945 | |
946 | @param radix |
947 | the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX |
948 | (36), inclusive. |
949 | |
950 | @return |
951 | the length of the string. |
952 | */ |
953 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfInt32( |
954 | sal_Unicode * str, sal_Int32 i, sal_Int16 radix ) SAL_THROW_EXTERN_C(); |
955 | #define RTL_USTR_MIN_RADIX RTL_STR_MIN_RADIX |
956 | #define RTL_USTR_MAX_RADIX RTL_STR_MAX_RADIX |
957 | #define RTL_USTR_MAX_VALUEOFINT32 RTL_STR_MAX_VALUEOFINT32 |
958 | |
959 | /** Create the string representation of a long integer. |
960 | |
961 | This function cannot be used for language-specific operations. |
962 | |
963 | @param str |
964 | a buffer that is big enough to hold the result and the terminating NUL |
965 | character. You should use the RTL_USTR_MAX_VALUEOFINT64 define to create |
966 | a buffer that is big enough. |
967 | |
968 | @param l |
969 | a long integer value. |
970 | |
971 | @param radix |
972 | the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX |
973 | (36), inclusive. |
974 | |
975 | @return |
976 | the length of the string. |
977 | */ |
978 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfInt64( |
979 | sal_Unicode * str, sal_Int64 l, sal_Int16 radix ) SAL_THROW_EXTERN_C(); |
980 | #define RTL_USTR_MAX_VALUEOFINT64 RTL_STR_MAX_VALUEOFINT64 |
981 | |
982 | /** Create the string representation of an unsigned long integer. |
983 | |
984 | This function cannot be used for language-specific operations. |
985 | |
986 | @param str |
987 | a buffer that is big enough to hold the result and the terminating NUL |
988 | character. You should use the RTL_USTR_MAX_VALUEOFUINT64 define to create |
989 | a buffer that is big enough. |
990 | |
991 | @param l |
992 | a long integer value. |
993 | |
994 | @param radix |
995 | the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX |
996 | (36), inclusive. |
997 | |
998 | @return |
999 | the length of the string. |
1000 | */ |
1001 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfUInt64( |
1002 | sal_Unicode * str, sal_uInt64 l, sal_Int16 radix ) SAL_THROW_EXTERN_C(); |
1003 | #define RTL_USTR_MAX_VALUEOFINT64 RTL_STR_MAX_VALUEOFINT64 |
1004 | |
1005 | /** Create the string representation of a float. |
1006 | |
1007 | This function cannot be used for language-specific conversion. |
1008 | |
1009 | @param str |
1010 | a buffer that is big enough to hold the result and the terminating NUL |
1011 | character. You should use the RTL_USTR_MAX_VALUEOFFLOAT define to create |
1012 | a buffer that is big enough. |
1013 | |
1014 | @param f |
1015 | a float value. |
1016 | |
1017 | @return |
1018 | the length of the string. |
1019 | */ |
1020 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfFloat( |
1021 | sal_Unicode * str, float f ) SAL_THROW_EXTERN_C(); |
1022 | #define RTL_USTR_MAX_VALUEOFFLOAT RTL_STR_MAX_VALUEOFFLOAT |
1023 | |
1024 | /** Create the string representation of a double. |
1025 | |
1026 | This function cannot be used for language-specific conversion. |
1027 | |
1028 | @param str |
1029 | a buffer that is big enough to hold the result and the terminating NUL |
1030 | character. You should use the RTL_USTR_MAX_VALUEOFDOUBLE define to create |
1031 | a buffer that is big enough. |
1032 | |
1033 | @param d |
1034 | a double value. |
1035 | |
1036 | @return |
1037 | the length of the string. |
1038 | */ |
1039 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfDouble( |
1040 | sal_Unicode * str, double d ) SAL_THROW_EXTERN_C(); |
1041 | #define RTL_USTR_MAX_VALUEOFDOUBLE RTL_STR_MAX_VALUEOFDOUBLE |
1042 | |
1043 | /** Interpret a string as a boolean. |
1044 | |
1045 | This function cannot be used for language-specific conversion. The string |
1046 | must be null-terminated. |
1047 | |
1048 | @param str |
1049 | a null-terminated string. |
1050 | |
1051 | @return |
1052 | true if the string is "1" or "true" in any ASCII case, false otherwise. |
1053 | */ |
1054 | SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_ustr_toBoolean( |
1055 | const sal_Unicode * str ) SAL_THROW_EXTERN_C(); |
1056 | |
1057 | /** Interpret a string as an integer. |
1058 | |
1059 | This function cannot be used for language-specific conversion. The string |
1060 | must be null-terminated. |
1061 | |
1062 | @param str |
1063 | a null-terminated string. |
1064 | |
1065 | @param radix |
1066 | the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX |
1067 | (36), inclusive. |
1068 | |
1069 | @return |
1070 | the integer value represented by the string, or 0 if the string does not |
1071 | represent an integer. |
1072 | */ |
1073 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_toInt32( |
1074 | const sal_Unicode * str, sal_Int16 radix ) SAL_THROW_EXTERN_C(); |
1075 | |
1076 | /** Interpret a string as an unsigned integer. |
1077 | |
1078 | This function cannot be used for language-specific conversion. The string |
1079 | must be null-terminated. |
1080 | |
1081 | @param str |
1082 | a null-terminated string. |
1083 | |
1084 | @param radix |
1085 | the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX |
1086 | (36), inclusive. |
1087 | |
1088 | @return |
1089 | the unsigned integer value represented by the string, or 0 if the string |
1090 | does not represent an unsigned integer. |
1091 | |
1092 | @since LibreOffice 4.2 |
1093 | */ |
1094 | SAL_DLLPUBLIC sal_uInt32 SAL_CALL rtl_ustr_toUInt32( |
1095 | const sal_Unicode * str, sal_Int16 radix ) SAL_THROW_EXTERN_C(); |
1096 | |
1097 | /** Interpret a string as a long integer. |
1098 | |
1099 | This function cannot be used for language-specific conversion. The string |
1100 | must be null-terminated. |
1101 | |
1102 | @param str |
1103 | a null-terminated string. |
1104 | |
1105 | @param radix |
1106 | the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX |
1107 | (36), inclusive. |
1108 | |
1109 | @return |
1110 | the long integer value represented by the string, or 0 if the string does |
1111 | not represent a long integer. |
1112 | */ |
1113 | SAL_DLLPUBLIC sal_Int64 SAL_CALL rtl_ustr_toInt64( |
1114 | const sal_Unicode * str, sal_Int16 radix ) SAL_THROW_EXTERN_C(); |
1115 | |
1116 | /** Interpret a string as an unsigned long integer. |
1117 | |
1118 | This function cannot be used for language-specific conversion. The string |
1119 | must be null-terminated. |
1120 | |
1121 | @param str |
1122 | a null-terminated string. |
1123 | |
1124 | @param radix |
1125 | the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX |
1126 | (36), inclusive. |
1127 | |
1128 | @return |
1129 | the unsigned long integer value represented by the string, or 0 if the |
1130 | string does not represent an unsigned long integer. |
1131 | |
1132 | @since LibreOffice 4.1 |
1133 | */ |
1134 | SAL_DLLPUBLIC sal_uInt64 SAL_CALL rtl_ustr_toUInt64( |
1135 | const sal_Unicode * str, sal_Int16 radix ) SAL_THROW_EXTERN_C(); |
1136 | |
1137 | /** Interpret a string as a float. |
1138 | |
1139 | This function cannot be used for language-specific conversion. The string |
1140 | must be null-terminated. |
1141 | |
1142 | @param str |
1143 | a null-terminated string. |
1144 | |
1145 | @return |
1146 | the float value represented by the string, or 0.0 if the string does not |
1147 | represent a float. |
1148 | */ |
1149 | SAL_DLLPUBLIC float SAL_CALL rtl_ustr_toFloat( |
1150 | const sal_Unicode * str ) SAL_THROW_EXTERN_C(); |
1151 | |
1152 | /** Interpret a string as a double. |
1153 | |
1154 | This function cannot be used for language-specific conversion. The string |
1155 | must be null-terminated. |
1156 | |
1157 | @param str |
1158 | a null-terminated string. |
1159 | |
1160 | @return |
1161 | the float value represented by the string, or 0.0 if the string does not |
1162 | represent a double. |
1163 | */ |
1164 | SAL_DLLPUBLIC double SAL_CALL rtl_ustr_toDouble( |
1165 | const sal_Unicode * str ) SAL_THROW_EXTERN_C(); |
1166 | |
1167 | /* ======================================================================= */ |
1168 | |
1169 | #if defined(SAL_W32) |
1170 | #pragma pack(push, 4) |
1171 | #endif |
1172 | |
1173 | /** @cond INTERNAL */ |
1174 | /** The implementation of a Unicode string. |
1175 | */ |
1176 | typedef struct _rtl_uString |
1177 | { |
1178 | oslInterlockedCount refCount; /* opaque */ |
1179 | sal_Int32 length; |
1180 | sal_Unicode buffer[1]; |
1181 | } rtl_uString; |
1182 | /** @endcond */ |
1183 | |
1184 | #if defined(SAL_W32) |
1185 | #pragma pack(pop) |
1186 | #endif |
1187 | |
1188 | /* ----------------------------------------------------------------------- */ |
1189 | |
1190 | /** Increment the reference count of a string. |
1191 | |
1192 | @param str |
1193 | a string. |
1194 | */ |
1195 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_acquire( |
1196 | rtl_uString * str ) SAL_THROW_EXTERN_C(); |
1197 | |
1198 | /** Decrement the reference count of a string. |
1199 | |
1200 | If the count goes to zero than the string data is deleted. |
1201 | |
1202 | @param str |
1203 | a string. |
1204 | */ |
1205 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_release( |
1206 | rtl_uString * str ) SAL_THROW_EXTERN_C(); |
1207 | |
1208 | /** Allocate a new string containing no characters. |
1209 | |
1210 | @param newStr |
1211 | pointer to the new string. The pointed-to data must be null or a valid |
1212 | string. |
1213 | */ |
1214 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_new( |
1215 | rtl_uString ** newStr ) SAL_THROW_EXTERN_C(); |
1216 | |
1217 | /** Allocate a new string containing space for a given number of characters. |
1218 | |
1219 | The reference count of the new string will be 1. The length of the string |
1220 | will be nLen. This function does not handle out-of-memory conditions. |
1221 | |
1222 | For nLen < 0 or failed allocation this method returns NULL. |
1223 | |
1224 | The characters of the capacity are not cleared, and the length is set to |
1225 | nLen, unlike the similar method of rtl_uString_new_WithLength which |
1226 | zeros out the buffer, and sets the length to 0. So should be somewhat |
1227 | more efficient for allocating a new string. |
1228 | |
1229 | call rtl_uString_release to release the string |
1230 | alternatively pass ownership to an OUString with |
1231 | rtl::OUString(newStr, SAL_NO_ACQUIRE); |
1232 | |
1233 | @param[in] nLen the number of characters. |
1234 | @return pointer to the new string. |
1235 | |
1236 | @since LibreOffice 4.1 |
1237 | */ |
1238 | SAL_DLLPUBLIC rtl_uString * SAL_CALL rtl_uString_alloc(sal_Int32 nLen) SAL_THROW_EXTERN_C(); |
1239 | |
1240 | /** Allocate a new string containing space for a given number of characters. |
1241 | |
1242 | If len is greater than zero, the reference count of the new string will be |
1243 | 1. The values of all characters are set to 0 and the length of the string |
1244 | is 0. This function does not handle out-of-memory conditions. |
1245 | |
1246 | @param newStr |
1247 | pointer to the new string. The pointed-to data must be null or a valid |
1248 | string. |
1249 | |
1250 | @param nLen |
1251 | the number of characters. |
1252 | */ |
1253 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_new_WithLength( |
1254 | rtl_uString ** newStr, sal_Int32 nLen ) SAL_THROW_EXTERN_C(); |
1255 | |
1256 | /** Allocate a new string that contains a copy of another string. |
1257 | |
1258 | If the length of value is greater than zero, the reference count of the |
1259 | new string will be 1. This function does not handle out-of-memory |
1260 | conditions. |
1261 | |
1262 | @param newStr |
1263 | pointer to the new string. The pointed-to data must be null or a valid |
1264 | string. |
1265 | |
1266 | @param value |
1267 | a valid string. |
1268 | */ |
1269 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromString( |
1270 | rtl_uString ** newStr, const rtl_uString * value ) SAL_THROW_EXTERN_C(); |
1271 | |
1272 | /** Allocate a new string that contains a copy of a character array. |
1273 | |
1274 | If the length of value is greater than zero, the reference count of the |
1275 | new string will be 1. This function does not handle out-of-memory |
1276 | conditions. |
1277 | |
1278 | @param newStr |
1279 | pointer to the new string. The pointed-to data must be null or a valid |
1280 | string. |
1281 | |
1282 | @param value |
1283 | a null-terminated character array. |
1284 | */ |
1285 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromStr( |
1286 | rtl_uString ** newStr, const sal_Unicode * value ) SAL_THROW_EXTERN_C(); |
1287 | |
1288 | /** Allocate a new string that contains a copy of a character array. |
1289 | |
1290 | If the length of value is greater than zero, the reference count of the |
1291 | new string will be 1. This function does not handle out-of-memory |
1292 | conditions. |
1293 | |
1294 | @param newStr |
1295 | pointer to the new string. The pointed-to data must be null or a valid |
1296 | string. |
1297 | |
1298 | @param value |
1299 | a character array. Need not be null-terminated, but must be at least as |
1300 | long as the specified len. |
1301 | |
1302 | @param len |
1303 | the length of the character array. |
1304 | */ |
1305 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromStr_WithLength( |
1306 | rtl_uString ** newStr, const sal_Unicode * value, sal_Int32 len ) SAL_THROW_EXTERN_C(); |
1307 | |
1308 | /** Allocate a new string that is a substring of this string. |
1309 | |
1310 | The substring begins at the specified beginIndex and contains count |
1311 | characters. Meaningless combinations such as negative beginIndex, |
1312 | or beginIndex + count greater than the length of the string have |
1313 | undefined behaviour. |
1314 | |
1315 | @param[out] newStr the specified substring. |
1316 | @param[in] from the String to take the substring from. |
1317 | @param[in] beginIndex the beginning index, inclusive. |
1318 | @param[in] count the number of characters. |
1319 | @return the specified substring. |
1320 | |
1321 | @since LibreOffice 4.0 |
1322 | */ |
1323 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromSubString( |
1324 | rtl_uString ** newStr, const rtl_uString * from, |
1325 | sal_Int32 beginIndex, sal_Int32 count ) SAL_THROW_EXTERN_C(); |
1326 | |
1327 | /** Allocate a new string that contains a copy of a character array. |
1328 | |
1329 | If the length of value is greater than zero, the reference count of the |
1330 | new string will be 1. This function does not handle out-of-memory |
1331 | conditions. |
1332 | |
1333 | Since this function is optimized for performance, the ASCII character |
1334 | values are not converted in any way. The caller has to make sure that |
1335 | all ASCII characters are in the allowed range of 0 and 127, inclusive. |
1336 | |
1337 | @param newStr |
1338 | pointer to the new string. The pointed-to data must be null or a valid |
1339 | string. |
1340 | |
1341 | @param value |
1342 | a null-terminated ASCII character array. |
1343 | */ |
1344 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromAscii( |
1345 | rtl_uString ** newStr, const sal_Char * value ) SAL_THROW_EXTERN_C(); |
1346 | |
1347 | /** |
1348 | @internal |
1349 | @since LibreOffice 3.6 |
1350 | */ |
1351 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromLiteral( |
1352 | rtl_uString ** newStr, const sal_Char * value, sal_Int32 len, |
1353 | sal_Int32 ) SAL_THROW_EXTERN_C(); |
1354 | |
1355 | /** Allocate a new string from an array of Unicode code points. |
1356 | |
1357 | @param newString |
1358 | a non-null pointer to a (possibly null) rtl_uString pointer, which (if |
1359 | non-null) will have been passed to rtl_uString_release before the function |
1360 | returns. Upon return, points to the newly allocated string or to null if |
1361 | there was either an out-of-memory condition or the resulting number of |
1362 | UTF-16 code units would have been larger than SAL_MAX_INT32. The newly |
1363 | allocated string (if any) must ultimately be passed to rtl_uString_release. |
1364 | |
1365 | @param codePoints |
1366 | an array of at least codePointCount code points, which each must be in the |
1367 | range from 0 to 0x10FFFF, inclusive. May be null if codePointCount is zero. |
1368 | |
1369 | @param codePointCount |
1370 | the non-negative number of code points. |
1371 | |
1372 | @since UDK 3.2.7 |
1373 | */ |
1374 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromCodePoints( |
1375 | rtl_uString ** newString, sal_uInt32 const * codePoints, |
1376 | sal_Int32 codePointCount) SAL_THROW_EXTERN_C(); |
1377 | |
1378 | /** Assign a new value to a string. |
1379 | |
1380 | First releases any value str might currently hold, then acquires |
1381 | rightValue. |
1382 | |
1383 | @param str |
1384 | pointer to the string. The pointed-to data must be null or a valid |
1385 | string. |
1386 | |
1387 | @param rightValue |
1388 | a valid string. |
1389 | */ |
1390 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_assign( |
1391 | rtl_uString ** str, rtl_uString * rightValue ) SAL_THROW_EXTERN_C(); |
1392 | |
1393 | /** Return the length of a string. |
1394 | |
1395 | The length is equal to the number of characters in the string. |
1396 | |
1397 | @param str |
1398 | a valid string. |
1399 | |
1400 | @return |
1401 | the length of the string. |
1402 | */ |
1403 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_uString_getLength( |
1404 | const rtl_uString * str ) SAL_THROW_EXTERN_C(); |
1405 | |
1406 | /** Return a pointer to the underlying character array of a string. |
1407 | |
1408 | @param str |
1409 | a valid string. |
1410 | |
1411 | @return |
1412 | a pointer to the null-terminated character array. |
1413 | */ |
1414 | SAL_DLLPUBLIC sal_Unicode * SAL_CALL rtl_uString_getStr( |
1415 | rtl_uString * str ) SAL_THROW_EXTERN_C(); |
1416 | |
1417 | /** Create a new string that is the concatenation of two other strings. |
1418 | |
1419 | The new string does not necessarily have a reference count of 1 (in cases |
1420 | where one of the two other strings is empty), so it must not be modified |
1421 | without checking the reference count. This function does not handle |
1422 | out-of-memory conditions. |
1423 | |
1424 | @param newStr |
1425 | pointer to the new string. The pointed-to data must be null or a valid |
1426 | string. |
1427 | |
1428 | @param left |
1429 | a valid string. |
1430 | |
1431 | @param right |
1432 | a valid string. |
1433 | */ |
1434 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_newConcat( |
1435 | rtl_uString ** newStr, rtl_uString * left, rtl_uString * right ) SAL_THROW_EXTERN_C(); |
1436 | |
1437 | /** Create a new string by replacing a substring of another string. |
1438 | |
1439 | The new string results from replacing a number of characters (count), |
1440 | starting at the specified position (index) in the original string (str), |
1441 | with some new substring (subStr). If subStr is null, than only a number |
1442 | of characters is deleted. |
1443 | |
1444 | The new string does not necessarily have a reference count of 1, so it |
1445 | must not be modified without checking the reference count. This function |
1446 | does not handle out-of-memory conditions. |
1447 | |
1448 | @param newStr |
1449 | pointer to the new string. The pointed-to data must be null or a valid |
1450 | string. |
1451 | |
1452 | @param str |
1453 | a valid string. |
1454 | |
1455 | @param idx |
1456 | the index into str at which to start replacement. Must be between 0 and |
1457 | the length of str, inclusive. |
1458 | |
1459 | @param count |
1460 | the number of characters to remove. Must not be negative, and the sum of |
1461 | index and count must not exceed the length of str. |
1462 | |
1463 | @param subStr |
1464 | either null or a valid string to be inserted. |
1465 | */ |
1466 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceStrAt( |
1467 | rtl_uString ** newStr, rtl_uString * str, sal_Int32 idx, sal_Int32 count, rtl_uString * subStr ) SAL_THROW_EXTERN_C(); |
1468 | |
1469 | /** Create a new string by replacing all occurrences of a single character |
1470 | within another string. |
1471 | |
1472 | The new string results from replacing all occurrences of oldChar in str |
1473 | with newChar. |
1474 | |
1475 | The new string does not necessarily have a reference count of 1 (in cases |
1476 | where oldChar does not occur in str), so it must not be modified without |
1477 | checking the reference count. This function does not handle out-of-memory |
1478 | conditions. |
1479 | |
1480 | @param newStr |
1481 | pointer to the new string. The pointed-to data must be null or a valid |
1482 | string. |
1483 | |
1484 | @param str |
1485 | a valid string. |
1486 | |
1487 | @param oldChar |
1488 | the old character. |
1489 | |
1490 | @param newChar |
1491 | the new character. |
1492 | */ |
1493 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplace( |
1494 | rtl_uString ** newStr, rtl_uString * str, sal_Unicode oldChar, sal_Unicode newChar ) SAL_THROW_EXTERN_C(); |
1495 | |
1496 | /** Create a new string by replacing the first occurrence of a given substring |
1497 | with another substring. |
1498 | |
1499 | @param[in, out] newStr pointer to the new string; must not be null; must |
1500 | point to null or a valid rtl_uString |
1501 | |
1502 | @param str pointer to the original string; must not be null |
1503 | |
1504 | @param from pointer to the substring to be replaced; must not be null |
1505 | |
1506 | @param to pointer to the replacing substring; must not be null |
1507 | |
1508 | @param[in,out] index pointer to a start index, must not be null; upon entry |
1509 | to the function its value is the index into the original string at which to |
1510 | start searching for the \p from substring, the value must be non-negative |
1511 | and not greater than the original string's length; upon exit from the |
1512 | function its value is the index into the original string at which the |
1513 | replacement took place or -1 if no replacement took place |
1514 | |
1515 | @since LibreOffice 3.6 |
1516 | */ |
1517 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceFirst( |
1518 | rtl_uString ** newStr, rtl_uString * str, rtl_uString const * from, |
1519 | rtl_uString const * to, sal_Int32 * index) SAL_THROW_EXTERN_C(); |
1520 | |
1521 | /** Create a new string by replacing the first occurrence of a given substring |
1522 | with another substring. |
1523 | |
1524 | @param[in, out] newStr pointer to the new string; must not be null; must |
1525 | point to null or a valid rtl_uString |
1526 | |
1527 | @param str pointer to the original string; must not be null |
1528 | |
1529 | @param from pointer to the substring to be replaced; must not be null and |
1530 | must point to memory of at least \p fromLength ASCII bytes |
1531 | |
1532 | @param fromLength the length of the \p from substring; must be non-negative |
1533 | |
1534 | @param to pointer to the replacing substring; must not be null |
1535 | |
1536 | @param[in,out] index pointer to a start index, must not be null; upon entry |
1537 | to the function its value is the index into the original string at which to |
1538 | start searching for the \p from substring, the value must be non-negative |
1539 | and not greater than the original string's length; upon exit from the |
1540 | function its value is the index into the original string at which the |
1541 | replacement took place or -1 if no replacement took place |
1542 | |
1543 | @since LibreOffice 3.6 |
1544 | */ |
1545 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceFirstAsciiL( |
1546 | rtl_uString ** newStr, rtl_uString * str, char const * from, |
1547 | sal_Int32 fromLength, rtl_uString const * to, sal_Int32 * index) |
1548 | SAL_THROW_EXTERN_C(); |
1549 | |
1550 | /** Create a new string by replacing the first occurrence of a given substring |
1551 | with another substring. |
1552 | |
1553 | @param[in, out] newStr pointer to the new string; must not be null; must |
1554 | point to null or a valid rtl_uString |
1555 | |
1556 | @param str pointer to the original string; must not be null |
1557 | |
1558 | @param from pointer to the substring to be replaced; must not be null and |
1559 | must point to memory of at least \p fromLength ASCII bytes |
1560 | |
1561 | @param fromLength the length of the \p from substring; must be non-negative |
1562 | |
1563 | @param to pointer to the substring to be replaced; must not be null and |
1564 | must point to memory of at least \p toLength ASCII bytes |
1565 | |
1566 | @param toLength the length of the \p to substring; must be non-negative |
1567 | |
1568 | @param[in,out] index pointer to a start index, must not be null; upon entry |
1569 | to the function its value is the index into the original string at which to |
1570 | start searching for the \p from substring, the value must be non-negative |
1571 | and not greater than the original string's length; upon exit from the |
1572 | function its value is the index into the original string at which the |
1573 | replacement took place or -1 if no replacement took place |
1574 | |
1575 | @since LibreOffice 3.6 |
1576 | */ |
1577 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceFirstAsciiLAsciiL( |
1578 | rtl_uString ** newStr, rtl_uString * str, char const * from, |
1579 | sal_Int32 fromLength, char const * to, sal_Int32 toLength, |
1580 | sal_Int32 * index) SAL_THROW_EXTERN_C(); |
1581 | |
1582 | /** Create a new string by replacing all occurrences of a given substring with |
1583 | another substring. |
1584 | |
1585 | Replacing subsequent occurrences picks up only after a given replacement. |
1586 | That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx". |
1587 | |
1588 | @param[in, out] newStr pointer to the new string; must not be null; must |
1589 | point to null or a valid rtl_uString |
1590 | |
1591 | @param str pointer to the original string; must not be null |
1592 | |
1593 | @param from pointer to the substring to be replaced; must not be null |
1594 | |
1595 | @param to pointer to the replacing substring; must not be null |
1596 | |
1597 | @since LibreOffice 3.6 |
1598 | */ |
1599 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceAll( |
1600 | rtl_uString ** newStr, rtl_uString * str, rtl_uString const * from, |
1601 | rtl_uString const * to) SAL_THROW_EXTERN_C(); |
1602 | |
1603 | /** Create a new string by replacing all occurrences of a given substring with |
1604 | another substring. |
1605 | |
1606 | Replacing subsequent occurrences picks up only after a given replacement. |
1607 | That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx". |
1608 | |
1609 | @param[in, out] newStr pointer to the new string; must not be null; must |
1610 | point to null or a valid rtl_uString |
1611 | |
1612 | @param str pointer to the original string; must not be null |
1613 | |
1614 | @param from pointer to the substring to be replaced; must not be null |
1615 | |
1616 | @param to pointer to the replacing substring; must not be null |
1617 | |
1618 | @param fromIndex the position in the string where we will begin searching |
1619 | |
1620 | @since LibreOffice 4.0 |
1621 | */ |
1622 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceAllFromIndex( |
1623 | rtl_uString ** newStr, rtl_uString * str, rtl_uString const * from, |
1624 | rtl_uString const * to, sal_Int32 fromIndex) SAL_THROW_EXTERN_C(); |
1625 | |
1626 | /** Create a new string by replacing all occurrences of a given substring with |
1627 | another substring. |
1628 | |
1629 | Replacing subsequent occurrences picks up only after a given replacement. |
1630 | That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx". |
1631 | |
1632 | @param[in, out] newStr pointer to the new string; must not be null; must |
1633 | point to null or a valid rtl_uString |
1634 | |
1635 | @param str pointer to the original string; must not be null |
1636 | |
1637 | @param from pointer to the substring to be replaced; must not be null and |
1638 | must point to memory of at least \p fromLength ASCII bytes |
1639 | |
1640 | @param fromLength the length of the \p from substring; must be non-negative |
1641 | |
1642 | @param to pointer to the replacing substring; must not be null |
1643 | |
1644 | @since LibreOffice 3.6 |
1645 | */ |
1646 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceAllAsciiL( |
1647 | rtl_uString ** newStr, rtl_uString * str, char const * from, |
1648 | sal_Int32 fromLength, rtl_uString const * to) SAL_THROW_EXTERN_C(); |
1649 | |
1650 | /** Create a new string by replacing all occurrences of a given substring with |
1651 | another substring. |
1652 | |
1653 | Replacing subsequent occurrences picks up only after a given replacement. |
1654 | That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx". |
1655 | |
1656 | @param[in, out] newStr pointer to the new string; must not be null; must |
1657 | point to null or a valid rtl_uString |
1658 | |
1659 | @param str pointer to the original string; must not be null |
1660 | |
1661 | @param from pointer to the substring to be replaced; must not be null and |
1662 | must point to memory of at least \p fromLength ASCII bytes |
1663 | |
1664 | @param fromLength the length of the \p from substring; must be non-negative |
1665 | |
1666 | @param to pointer to the substring to be replaced; must not be null and |
1667 | must point to memory of at least \p toLength ASCII bytes |
1668 | |
1669 | @param toLength the length of the \p to substring; must be non-negative |
1670 | |
1671 | @since LibreOffice 3.6 |
1672 | */ |
1673 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceAllAsciiLAsciiL( |
1674 | rtl_uString ** newStr, rtl_uString * str, char const * from, |
1675 | sal_Int32 fromLength, char const * to, sal_Int32 toLength) |
1676 | SAL_THROW_EXTERN_C(); |
1677 | |
1678 | /** Create a new string by converting all ASCII uppercase letters to lowercase |
1679 | within another string. |
1680 | |
1681 | The new string results from replacing all characters with values between |
1682 | 65 and 90 (ASCII A--Z) by values between 97 and 122 (ASCII a--z). |
1683 | |
1684 | This function cannot be used for language-specific conversion. The new |
1685 | string does not necessarily have a reference count of 1 (in cases where |
1686 | no characters need to be converted), so it must not be modified without |
1687 | checking the reference count. This function does not handle out-of-memory |
1688 | conditions. |
1689 | |
1690 | @param newStr |
1691 | pointer to the new string. The pointed-to data must be null or a valid |
1692 | string. |
1693 | |
1694 | @param str |
1695 | a valid string. |
1696 | */ |
1697 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_newToAsciiLowerCase( |
1698 | rtl_uString ** newStr, rtl_uString * str ) SAL_THROW_EXTERN_C(); |
1699 | |
1700 | /** Create a new string by converting all ASCII lowercase letters to uppercase |
1701 | within another string. |
1702 | |
1703 | The new string results from replacing all characters with values between |
1704 | 97 and 122 (ASCII a--z) by values between 65 and 90 (ASCII A--Z). |
1705 | |
1706 | This function cannot be used for language-specific conversion. The new |
1707 | string does not necessarily have a reference count of 1 (in cases where |
1708 | no characters need to be converted), so it must not be modified without |
1709 | checking the reference count. This function does not handle out-of-memory |
1710 | conditions. |
1711 | |
1712 | @param newStr |
1713 | pointer to the new string. The pointed-to data must be null or a valid |
1714 | string. |
1715 | |
1716 | @param str |
1717 | a valid string. |
1718 | */ |
1719 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_newToAsciiUpperCase( |
1720 | rtl_uString ** newStr, rtl_uString * str ) SAL_THROW_EXTERN_C(); |
1721 | |
1722 | /** Create a new string by removing white space from both ends of another |
1723 | string. |
1724 | |
1725 | The new string results from removing all characters with values less than |
1726 | or equal to 32 (the space character) form both ends of str. |
1727 | |
1728 | This function cannot be used for language-specific conversion. The new |
1729 | string does not necessarily have a reference count of 1 (in cases where |
1730 | no characters need to be removed), so it must not be modified without |
1731 | checking the reference count. This function does not handle out-of-memory |
1732 | conditions. |
1733 | |
1734 | @param newStr |
1735 | pointer to the new string. The pointed-to data must be null or a valid |
1736 | string. |
1737 | |
1738 | @param str |
1739 | a valid string. |
1740 | */ |
1741 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_newTrim( |
1742 | rtl_uString ** newStr, rtl_uString * str ) SAL_THROW_EXTERN_C(); |
1743 | |
1744 | /** Create a new string by extracting a single token from another string. |
1745 | |
1746 | Starting at index, the token's next token is searched for. If there is no |
1747 | such token, the result is an empty string. Otherwise, all characters from |
1748 | the start of that token and up to, but not including the next occurrence |
1749 | of cTok make up the resulting token. The return value is the position of |
1750 | the next token, or -1 if no more tokens follow. |
1751 | |
1752 | Example code could look like |
1753 | rtl_uString * pToken = NULL; |
1754 | sal_Int32 nIndex = 0; |
1755 | do |
1756 | { |
1757 | ... |
1758 | nIndex = rtl_uString_getToken(&pToken, pStr, 0, ';', nIndex); |
1759 | ... |
1760 | } |
1761 | while (nIndex >= 0); |
1762 | |
1763 | The new string does not necessarily have a reference count of 1, so it |
1764 | must not be modified without checking the reference count. This function |
1765 | does not handle out-of-memory conditions. |
1766 | |
1767 | @param newStr |
1768 | pointer to the new string. The pointed-to data must be null or a valid |
1769 | string. If either token or index is negative, an empty token is stored in |
1770 | newStr (and -1 is returned). |
1771 | |
1772 | @param str |
1773 | a valid string. |
1774 | |
1775 | @param token |
1776 | the number of the token to return, starting at index. |
1777 | |
1778 | @param cTok |
1779 | the character that separates the tokens. |
1780 | |
1781 | @param idx |
1782 | the position at which searching for the token starts. Must not be greater |
1783 | than the length of str. |
1784 | |
1785 | @return |
1786 | the index of the next token, or -1 if no more tokens follow. |
1787 | */ |
1788 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_uString_getToken( |
1789 | rtl_uString ** newStr , rtl_uString * str, sal_Int32 token, sal_Unicode cTok, sal_Int32 idx ) SAL_THROW_EXTERN_C(); |
1790 | |
1791 | /* ======================================================================= */ |
1792 | |
1793 | /** Supply an ASCII string literal together with its length and text encoding. |
1794 | |
1795 | This macro can be used to compute (some of) the arguments in function calls |
1796 | like rtl::OUString(RTL_CONSTASCII_USTRINGPARAM("foo")). |
1797 | |
1798 | @param constAsciiStr |
1799 | must be an expression of type "(possibly cv-qualified reference to) array of |
1800 | (possibly cv-qualified) char." Each element of the referenced array must |
1801 | represent an ASCII value in the range 0x00--0x7F. The last element of the |
1802 | referenced array is not considered part of the represented ASCII string, and |
1803 | its value should be 0x00. Depending on where this macro is used, the nature |
1804 | of the supplied expression might be further restricted. |
1805 | */ |
1806 | // The &foo[0] trick is intentional, it makes sure the type is char* or const char* |
1807 | // (plain cast to const char* would not work with non-const char foo[]="a", which seems to be allowed). |
1808 | // This is to avoid mistaken use with functions that accept string literals |
1809 | // (i.e. const char (&)[N]) where usage of this macro otherwise could match |
1810 | // the argument and a following int argument with a default value (e.g. OUString::match()). |
1811 | #define RTL_CONSTASCII_USTRINGPARAM( constAsciiStr ) (&(constAsciiStr)[0]), \ |
1812 | ((sal_Int32)(SAL_N_ELEMENTS(constAsciiStr)-1)), RTL_TEXTENCODING_ASCII_US |
1813 | |
1814 | /* ======================================================================= */ |
1815 | |
1816 | /* predefined constants for String-Conversion */ |
1817 | #define OSTRING_TO_OUSTRING_CVTFLAGS (RTL_TEXTTOUNICODE_FLAGS_UNDEFINED_MAPTOPRIVATE |\ |
1818 | RTL_TEXTTOUNICODE_FLAGS_MBUNDEFINED_DEFAULT |\ |
1819 | RTL_TEXTTOUNICODE_FLAGS_INVALID_DEFAULT) |
1820 | |
1821 | /* ----------------------------------------------------------------------- */ |
1822 | |
1823 | /** Create a new Unicode string by converting a byte string, using a specific |
1824 | text encoding. |
1825 | |
1826 | The lengths of the byte string and the Unicode string may differ (e.g., |
1827 | for double-byte encodings, UTF-7, UTF-8). |
1828 | |
1829 | If the length of the byte string is greater than zero, the reference count |
1830 | of the new string will be 1. |
1831 | |
1832 | If an out-of-memory condition occurs, newStr will point to a null pointer |
1833 | upon return. |
1834 | |
1835 | @param newStr |
1836 | pointer to the new string. The pointed-to data must be null or a valid |
1837 | string. |
1838 | |
1839 | @param str |
1840 | a byte character array. Need not be null-terminated, but must be at |
1841 | least as long as the specified len. |
1842 | |
1843 | @param len |
1844 | the length of the byte character array. |
1845 | |
1846 | @param encoding |
1847 | the text encoding to use for conversion. |
1848 | |
1849 | @param convertFlags |
1850 | flags which control the conversion. Either use |
1851 | OSTRING_TO_OUSTRING_CVTFLAGS, or see |
1852 | <http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more |
1853 | details. |
1854 | */ |
1855 | SAL_DLLPUBLIC void SAL_CALL rtl_string2UString( |
1856 | rtl_uString ** newStr, const sal_Char * str, sal_Int32 len, rtl_TextEncoding encoding, sal_uInt32 convertFlags ) SAL_THROW_EXTERN_C(); |
1857 | |
1858 | /* ======================================================================= */ |
1859 | /* Interning methods */ |
1860 | |
1861 | /** Return a canonical representation for a string. |
1862 | |
1863 | A pool of strings, initially empty is maintained privately |
1864 | by the string class. On invocation, if present in the pool |
1865 | the original string will be returned. Otherwise this string, |
1866 | or a copy thereof will be added to the pool and returned. |
1867 | |
1868 | @param newStr |
1869 | pointer to the new string. The pointed-to data must be null or a valid |
1870 | string. |
1871 | |
1872 | If an out-of-memory condition occurs, newStr will point to a null pointer |
1873 | upon return. |
1874 | |
1875 | @param str |
1876 | pointer to the string to be interned. |
1877 | |
1878 | @since UDK 3.2.7 |
1879 | */ |
1880 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_intern( |
1881 | rtl_uString ** newStr, rtl_uString * str) SAL_THROW_EXTERN_C(); |
1882 | |
1883 | /** Return a canonical representation for a string. |
1884 | |
1885 | A pool of strings, initially empty is maintained privately |
1886 | by the string class. On invocation, if present in the pool |
1887 | the original string will be returned. Otherwise this string, |
1888 | or a copy thereof will be added to the pool and returned. |
1889 | |
1890 | @param newStr |
1891 | pointer to the new string. The pointed-to data must be null or a valid |
1892 | string. |
1893 | |
1894 | If an out-of-memory condition occurs, newStr will point to a null pointer |
1895 | upon return. |
1896 | |
1897 | @param str |
1898 | a byte character array. Need not be null-terminated, but must be at |
1899 | least as long as the specified len. |
1900 | |
1901 | @param len |
1902 | the length of the byte character array. |
1903 | |
1904 | @param encoding |
1905 | the text encoding to use for conversion. |
1906 | |
1907 | @param convertFlags |
1908 | flags which control the conversion. Either use |
1909 | OSTRING_TO_OUSTRING_CVTFLAGS, or see |
1910 | <http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more |
1911 | details. |
1912 | |
1913 | @param pInfo |
1914 | pointer to return conversion status in, or NULL. |
1915 | |
1916 | @since UDK 3.2.7 |
1917 | */ |
1918 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_internConvert( |
1919 | rtl_uString ** newStr, |
1920 | const sal_Char * str, |
1921 | sal_Int32 len, |
1922 | rtl_TextEncoding encoding, |
1923 | sal_uInt32 convertFlags, |
1924 | sal_uInt32 *pInfo) SAL_THROW_EXTERN_C(); |
1925 | |
1926 | /** Iterate through a string based on code points instead of UTF-16 code units. |
1927 | |
1928 | See Chapter 3 of The Unicode Standard 5.0 (Addison--Wesley, 2006) for |
1929 | definitions of the various terms used in this description. |
1930 | |
1931 | The given string is interpreted as a sequence of zero or more UTF-16 code |
1932 | units. For each index into this sequence (from zero to one less than the |
1933 | length of the sequence, inclusive), a code point represented starting at the |
1934 | given index is computed as follows: |
1935 | |
1936 | - If the UTF-16 code unit addressed by the index constitutes a well-formed |
1937 | UTF-16 code unit sequence, the computed code point is the scalar value |
1938 | encoded by that UTF-16 code unit sequence. |
1939 | |
1940 | - Otherwise, if the index is at least two UTF-16 code units away from the |
1941 | end of the sequence, and the sequence of two UTF-16 code units addressed by |
1942 | the index constitutes a well-formed UTF-16 code unit sequence, the computed |
1943 | code point is the scalar value encoded by that UTF-16 code unit sequence. |
1944 | |
1945 | - Otherwise, the computed code point is the UTF-16 code unit addressed by |
1946 | the index. (This last case catches unmatched surrogates as well as indices |
1947 | pointing into the middle of surrogate pairs.) |
1948 | |
1949 | @param string |
1950 | pointer to a valid string; must not be null. |
1951 | |
1952 | @param indexUtf16 |
1953 | pointer to a UTF-16 based index into the given string; must not be null. On |
1954 | entry, the index must be in the range from zero to the length of the string |
1955 | (in UTF-16 code units), inclusive. Upon successful return, the index will |
1956 | be updated to address the UTF-16 code unit that is the given |
1957 | incrementCodePoints away from the initial index. |
1958 | |
1959 | @param incrementCodePoints |
1960 | the number of code points to move the given *indexUtf16. If non-negative, |
1961 | moving is done after determining the code point at the index. If negative, |
1962 | moving is done before determining the code point at the (then updated) |
1963 | index. The value must be such that the resulting UTF-16 based index is in |
1964 | the range from zero to the length of the string (in UTF-16 code units), |
1965 | inclusive. |
1966 | |
1967 | @return |
1968 | the code point (an integer in the range from 0 to 0x10FFFF, inclusive) that |
1969 | is represented within the string starting at the index computed as follows: |
1970 | If incrementCodePoints is non-negative, the index is the initial value of |
1971 | *indexUtf16; if incrementCodePoints is negative, the index is the updated |
1972 | value of *indexUtf16. In either case, the computed index must be in the |
1973 | range from zero to one less than the length of the string (in UTF-16 code |
1974 | units), inclusive. |
1975 | |
1976 | @since UDK 3.2.7 |
1977 | */ |
1978 | SAL_DLLPUBLIC sal_uInt32 SAL_CALL rtl_uString_iterateCodePoints( |
1979 | rtl_uString const * string, sal_Int32 * indexUtf16, |
1980 | sal_Int32 incrementCodePoints); |
1981 | |
1982 | /** Converts a byte string to a Unicode string, signalling failure. |
1983 | |
1984 | @param target |
1985 | An out parameter receiving the converted string. Must not be null itself, |
1986 | and must contain either null or a pointer to a valid rtl_uString; the |
1987 | contents are unspecified if conversion fails (rtl_convertStringToUString |
1988 | returns false). |
1989 | |
1990 | @param source |
1991 | The byte string. May only be null if length is zero. |
1992 | |
1993 | @param length |
1994 | The length of the byte string. Must be non-negative. |
1995 | |
1996 | @param encoding |
1997 | The text encoding to convert from. Must be an octet encoding (i.e., |
1998 | rtl_isOctetTextEncoding(encoding) must return true). |
1999 | |
2000 | @param flags |
2001 | A combination of RTL_TEXTTOUNICODE_FLAGS that detail how to do the |
2002 | conversion (see rtl_convertTextToUnicode). RTL_TEXTTOUNICODE_FLAGS_FLUSH |
2003 | need not be included, it is implicitly assumed. Typical uses are either |
2004 | RTL_TEXTTOUNICODE_FLAGS_UNDEFINED_ERROR | |
2005 | RTL_TEXTTOUNICODE_FLAGS_MBUNDEFINED_ERROR | |
2006 | RTL_TEXTTOUNICODE_FLAGS_INVALID_ERROR (fail if a byte or multi-byte sequence |
2007 | cannot be converted from the source encoding) or |
2008 | OSTRING_TO_OUSTRING_CVTFLAGS (make a best efforts conversion). |
2009 | |
2010 | @return |
2011 | True if the conversion succeeded, false otherwise. |
2012 | |
2013 | @since UDK 3.2.9 |
2014 | */ |
2015 | SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_convertStringToUString( |
2016 | rtl_uString ** target, char const * source, sal_Int32 length, |
2017 | rtl_TextEncoding encoding, sal_uInt32 flags) SAL_THROW_EXTERN_C(); |
2018 | |
2019 | /** Ensure a string has enough space for a given number of characters. |
2020 | |
2021 | If the given string is large enough and has refcount of 1, it is not altered in any way. |
2022 | Otherwise it is replaced by a copy that has enough space for the given number of characters, |
2023 | data from the source string is copied to the beginning of it, the content of the remaining |
2024 | capacity undefined, the string has refcount of 1, and refcount of the original string is decreased. |
2025 | |
2026 | @param str |
2027 | pointer to the string. The pointed-to data must be a valid string. |
2028 | |
2029 | @param size |
2030 | the number of characters |
2031 | |
2032 | @since LibreOffice 4.1 |
2033 | @internal |
2034 | */ |
2035 | SAL_DLLPUBLIC void SAL_CALL rtl_uString_ensureCapacity( rtl_uString ** str, sal_Int32 size ) SAL_THROW_EXTERN_C(); |
2036 | |
2037 | #ifdef __cplusplus |
2038 | } |
2039 | #endif |
2040 | |
2041 | #endif // INCLUDED_RTL_USTRING_H |
2042 | |
2043 | /* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |
2044 | |