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_USTRBUF_H |
21 | #define INCLUDED_RTL_USTRBUF_H |
22 | |
23 | #include <sal/config.h> |
24 | |
25 | #include <rtl/ustring.h> |
26 | #include <sal/saldllapi.h> |
27 | |
28 | #ifdef __cplusplus |
29 | extern "C" { |
30 | #endif |
31 | |
32 | /** Allocates a new <code>String</code> that contains characters from |
33 | the character array argument. |
34 | |
35 | The <code>count</code> argument specifies |
36 | the length of the array. The initial capacity of the string buffer is |
37 | <code>16</code> plus the length of the string argument. |
38 | |
39 | @param newStr out parameter, contains the new string. The reference count is 1. |
40 | @param value the initial value of the string. |
41 | @param count the length of value. |
42 | */ |
43 | SAL_DLLPUBLIC void SAL_CALL rtl_uStringbuffer_newFromStr_WithLength( |
44 | rtl_uString ** newStr, |
45 | const sal_Unicode * value, |
46 | sal_Int32 count ); |
47 | |
48 | /** |
49 | Allocates a new <code>String</code> that contains the same sequence of |
50 | characters as the string argument. |
51 | |
52 | The initial capacity is the larger of: |
53 | <ul> |
54 | <li> The <code>bufferLen</code> argument. |
55 | <li> The <code>length</code> of the string argument. |
56 | </ul> |
57 | |
58 | @param newStr out parameter, contains the new string. The reference count is 1. |
59 | @param capacity the initial len of the string buffer. |
60 | @param oldStr the initial value of the string. |
61 | @return the new capacity of the string buffer |
62 | */ |
63 | SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_uStringbuffer_newFromStringBuffer( |
64 | rtl_uString ** newStr, |
65 | sal_Int32 capacity, |
66 | rtl_uString * oldStr ); |
67 | |
68 | /** |
69 | Ensures that the capacity of the buffer is at least equal to the |
70 | specified minimum. |
71 | |
72 | If the current capacity of this string buffer is less than the |
73 | argument, then a new internal buffer is allocated with greater |
74 | capacity. The new capacity is the larger of: |
75 | <ul> |
76 | <li>The <code>minimumCapacity</code> argument. |
77 | <li>Twice the old capacity, plus <code>2</code>. |
78 | </ul> |
79 | If the <code>minimumCapacity</code> argument is nonpositive, this |
80 | method takes no action and simply returns. |
81 | |
82 | @param[in,out] This the String to operate on. |
83 | @param[in,out] capacity in: old capacity, out: new capacity. |
84 | @param[in] minimumCapacity the minimum desired capacity. |
85 | */ |
86 | SAL_DLLPUBLIC void SAL_CALL rtl_uStringbuffer_ensureCapacity( |
87 | rtl_uString ** This, |
88 | sal_Int32* capacity, |
89 | sal_Int32 minimumCapacity); |
90 | |
91 | /** |
92 | Inserts the string representation of the <code>str</code> array |
93 | argument into this string buffer. |
94 | |
95 | The characters of the array argument are inserted into the |
96 | contents of this string buffer at the position indicated by |
97 | <code>offset</code>. The length of this string buffer increases by |
98 | the length of the argument. |
99 | |
100 | @param This The string, on that the operation should take place |
101 | @param capacity the capacity of the string buffer |
102 | @param offset the offset. |
103 | @param str a character array. |
104 | @param len the number of characters to append. |
105 | */ |
106 | SAL_DLLPUBLIC void SAL_CALL rtl_uStringbuffer_insert( |
107 | /*inout*/rtl_uString ** This, |
108 | /*inout*/sal_Int32 * capacity, |
109 | sal_Int32 offset, |
110 | const sal_Unicode * str, |
111 | sal_Int32 len); |
112 | |
113 | /** |
114 | Inserts a single UTF-32 character into this string buffer. |
115 | |
116 | <p>The single UTF-32 character will be represented within the string buffer |
117 | as either one or two UTF-16 code units.</p> |
118 | |
119 | @param pThis the string buffer on which the operation is performed |
120 | |
121 | @param capacity the capacity of the string buffer |
122 | |
123 | @param offset the offset into this string buffer (from zero to the length |
124 | of this string buffer, inclusive) |
125 | |
126 | @param c a well-formed UTF-32 code unit (that is, a value in the range |
127 | <code>0</code>–<code>0x10FFFF</code>, but excluding |
128 | <code>0xD800</code>–<code>0xDFFF</code>) |
129 | */ |
130 | SAL_DLLPUBLIC void SAL_CALL rtl_uStringbuffer_insertUtf32( |
131 | rtl_uString ** pThis, sal_Int32 * capacity, sal_Int32 offset, sal_uInt32 c) |
132 | SAL_THROW_EXTERN_C(); |
133 | |
134 | /** |
135 | Inserts the 8-Bit ASCII string representation of the <code>str</code> |
136 | array argument into this string buffer. |
137 | |
138 | Since this function is optimized |
139 | for performance, the ASCII character values are not converted in any way. |
140 | The caller has to make sure that all ASCII characters are in the allowed |
141 | range between 0 and 127. |
142 | <p> |
143 | The characters of the array argument are inserted into the |
144 | contents of this string buffer at the position indicated by |
145 | <code>offset</code>. The length of this string buffer increases by |
146 | the length of the argument. |
147 | |
148 | @param This The string, on that the operation should take place |
149 | @param capacity the capacity of the string buffer |
150 | @param offset the offset. |
151 | @param str a character array. |
152 | @param len the number of characters to append. |
153 | */ |
154 | SAL_DLLPUBLIC void SAL_CALL rtl_uStringbuffer_insert_ascii( |
155 | /*inout*/rtl_uString ** This, |
156 | /*inout*/sal_Int32 * capacity, |
157 | sal_Int32 offset, |
158 | const sal_Char * str, |
159 | sal_Int32 len); |
160 | |
161 | /** |
162 | Removes the characters in a substring of this sequence. |
163 | |
164 | The substring begins at the specified <code>start</code> and |
165 | is <code>len</code> characters long. |
166 | |
167 | start must be >= 0 && <= This->length |
168 | |
169 | @param[in,out] This The String to operate on. |
170 | @param[in] start The beginning index, inclusive |
171 | @param[in] len The substring length |
172 | */ |
173 | SAL_DLLPUBLIC void SAL_CALL rtl_uStringbuffer_remove( |
174 | rtl_uString ** This, |
175 | sal_Int32 start, |
176 | sal_Int32 len ); |
177 | |
178 | /** |
179 | Returns an immutable rtl_uString object, while clearing the string buffer. |
180 | |
181 | This method is primarily used to allow these completed |
182 | string allocation events to be traced. |
183 | |
184 | @param ppThis The string, on that the operation should take place |
185 | @param nCapacity pointer to the capacity of the string buffer |
186 | |
187 | @since LibreOffice 3.6 |
188 | */ |
189 | SAL_DLLPUBLIC rtl_uString * SAL_CALL rtl_uStringBuffer_makeStringAndClear( |
190 | /*inout*/ rtl_uString ** ppThis, |
191 | sal_Int32 *nCapacity ); |
192 | |
193 | /** |
194 | References and returns an immutable rtl_uString object, from a mutable |
195 | string-buffer object. |
196 | |
197 | This method is primarily used to allow legacy 'String' class |
198 | conversions to OUString to be accurately traced. |
199 | |
200 | @param pThis The string, on that the operation should take place |
201 | |
202 | @since LibreOffice 3.6 |
203 | */ |
204 | SAL_DLLPUBLIC rtl_uString * SAL_CALL rtl_uStringBuffer_refReturn( rtl_uString *pThis ); |
205 | |
206 | #ifdef __cplusplus |
207 | } |
208 | #endif |
209 | |
210 | #endif // INCLUDED_RTL_USTRBUF_H |
211 | |
212 | /* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |
213 | |