xref: /aoo41x/main/sal/inc/rtl/ustrbuf.h (revision 9eab2a37)
1 /**************************************************************
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one
4  * or more contributor license agreements.  See the NOTICE file
5  * distributed with this work for additional information
6  * regarding copyright ownership.  The ASF licenses this file
7  * to you under the Apache License, Version 2.0 (the
8  * "License"); you may not use this file except in compliance
9  * with the License.  You may obtain a copy of the License at
10  *
11  *   http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing,
14  * software distributed under the License is distributed on an
15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16  * KIND, either express or implied.  See the License for the
17  * specific language governing permissions and limitations
18  * under the License.
19  *
20  *************************************************************/
21 
22 
23 
24 #ifndef _RTL_USTRBUF_H_
25 #define _RTL_USTRBUF_H_
26 
27 #include <rtl/ustring.h>
28 
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32 
33 /** @HTML
34 	Allocates a new <code>String</code> that contains characters from
35 	the character array argument.
36 
37     The <code>count</code> argument specifies
38 	the length of the array. The initial capacity of the string buffer is
39 	<code>16</code> plus the length of the string argument.
40 
41 	@param  newStr   out parameter, contains the new string. The reference count is 1.
42 	@param  value   the initial value of the string.
43 	@param  count    the length of value.
44  */
45 void SAL_CALL rtl_uStringbuffer_newFromStr_WithLength( rtl_uString ** newStr,
46                                                       const sal_Unicode * value,
47                                                       sal_Int32 count );
48 
49 /**
50 	Allocates a new <code>String</code> that contains the same sequence of
51 	characters as the string argument.
52 
53     The initial capacity is the larger of:
54 	<ul>
55 	<li> The <code>bufferLen</code> argument.
56 	<li> The <code>length</code> of the string argument.
57 	</ul>
58 
59 	@param  newStr       out parameter, contains the new string. The reference count is 1.
60 	@param  capacity     the initial len of the string buffer.
61 	@param  oldStr       the initial value of the string.
62 	@return the new capacity of the string buffer
63  */
64 sal_Int32 SAL_CALL rtl_uStringbuffer_newFromStringBuffer( rtl_uString ** newStr,
65                                                           sal_Int32 capacity,
66                                                           rtl_uString * olsStr );
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   capacity          in: old capicity, out: new capacity.
83 	@param   minimumCapacity   the minimum desired capacity.
84  */
85 void SAL_CALL rtl_uStringbuffer_ensureCapacity( /*inout*/rtl_uString ** This,
86                                                 /*inout*/sal_Int32* capacity,
87                                                 sal_Int32 minimumCapacity);
88 
89 /**
90 	Inserts the string representation of the <code>str</code> array
91 	argument into this string buffer.
92 
93 	The characters of the array argument are inserted into the
94 	contents of this string buffer at the position indicated by
95 	<code>offset</code>. The length of this string buffer increases by
96 	the length of the argument.
97 
98 	@param   This        The string, on that the operation should take place
99 	@param   capacity    the capacity of the string buffer
100 	@param   offset      the offset.
101 	@param   str         a character array.
102 	@param   len         the number of characters to append.
103  */
104 void SAL_CALL rtl_uStringbuffer_insert( /*inout*/rtl_uString ** This,
105                                         /*inout*/sal_Int32 * capacity,
106                                         sal_Int32 offset,
107                                         const sal_Unicode * str,
108                                         sal_Int32 len);
109 
110 /**
111    Inserts a single UTF-32 character into this string buffer.
112 
113    <p>The single UTF-32 character will be represented within the string buffer
114    as either one or two UTF-16 code units.</p>
115 
116    @param pThis the string buffer on which the operation is performed
117 
118    @param capacity the capacity of the string buffer
119 
120    @param offset the offset into this string buffer (from zero to the length
121    of this string buffer, inclusive)
122 
123    @param c a well-formed UTF-32 code unit (that is, a value in the range
124    <code>0</code>&ndash;<code>0x10FFFF</code>, but excluding
125    <code>0xD800</code>&ndash;<code>0xDFFF</code>)
126  */
127 void SAL_CALL rtl_uStringbuffer_insertUtf32(
128     rtl_uString ** pThis, sal_Int32 * capacity, sal_Int32 offset, sal_uInt32 c)
129     SAL_THROW_EXTERN_C();
130 
131 /**
132 	Inserts the 8-Bit ASCII string representation of the <code>str</code>
133 	array argument into this string buffer.
134 
135     Since this function is optimized
136 	for performance, the ASCII character values are not converted in any way.
137 	The caller has to make sure that all ASCII characters are in the allowed
138 	range between 0 and 127.
139 	<p>
140 	The characters of the array argument are inserted into the
141 	contents of this string buffer at the position indicated by
142 	<code>offset</code>. The length of this string buffer increases by
143 	the length of the argument.
144 
145 	@param   This        The string, on that the operation should take place
146 	@param   capacity    the capacity of the string buffer
147 	@param   offset      the offset.
148 	@param   str         a character array.
149 	@param   len         the number of characters to append.
150  */
151 void SAL_CALL rtl_uStringbuffer_insert_ascii(   /*inout*/rtl_uString ** This,
152                                                 /*inout*/sal_Int32 * capacity,
153                                                 sal_Int32 offset,
154                                                 const sal_Char * str,
155                                                 sal_Int32 len);
156 
157 #ifdef __cplusplus
158 }
159 #endif
160 
161 #endif  /* _RTL_USTRBUF_H_ */
162