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