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
32extern "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 */
49SAL_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 */
70SAL_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 */
98SAL_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 */
130SAL_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 */
158SAL_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
182SAL_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 */
204SAL_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 */
234SAL_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 */
269SAL_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 */
295SAL_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 */
324SAL_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 */
357SAL_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 */
389SAL_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 */
416SAL_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 */
447SAL_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 */
481SAL_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 */
518SAL_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 */
533SAL_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 */
551SAL_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 */
568SAL_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 */
587SAL_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 */
605SAL_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 */
625SAL_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 */
643SAL_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 */
668SAL_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*/
695SAL_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 */
714SAL_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 */
739SAL_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*/
766SAL_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 */
784SAL_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 */
804SAL_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 */
816SAL_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 */
831SAL_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 */
843SAL_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 */
858SAL_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 */
873SAL_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 */
892SAL_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 */
913SAL_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 */
930SAL_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 */
953SAL_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 */
978SAL_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 */
1001SAL_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 */
1020SAL_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 */
1039SAL_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 */
1054SAL_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 */
1073SAL_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 */
1094SAL_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 */
1113SAL_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 */
1134SAL_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 */
1149SAL_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 */
1164SAL_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*/
1176typedef 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 */
1195SAL_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 */
1205SAL_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 */
1214SAL_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 */
1238SAL_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 */
1253SAL_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 */
1269SAL_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 */
1285SAL_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 */
1305SAL_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 */
1323SAL_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 */
1344SAL_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*/
1351SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromLiteral(
1352 rtl_uString ** newStr, const sal_Char * value, sal_Int32 len,
1353 sal_Int32 allocExtra ) 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*/
1374SAL_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 */
1390SAL_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 */
1403SAL_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 */
1414SAL_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 */
1434SAL_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 */
1466SAL_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 */
1493SAL_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*/
1517SAL_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*/
1545SAL_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*/
1577SAL_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*/
1599SAL_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*/
1622SAL_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*/
1646SAL_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*/
1673SAL_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 */
1697SAL_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 */
1719SAL_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 */
1741SAL_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 */
1788SAL_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 */
1855SAL_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 */
1880SAL_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 */
1918SAL_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*/
1978SAL_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*/
2015SAL_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 */
2035SAL_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