update dev300-m58
[ooovba.git] / sal / inc / rtl / strbuf.hxx
blob3210f43b1fe6c02166d85fe61bc43e7aa6da690f
1 /*************************************************************************
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * Copyright 2008 by Sun Microsystems, Inc.
7 * OpenOffice.org - a multi-platform office productivity suite
9 * $RCSfile: strbuf.hxx,v $
10 * $Revision: 1.11 $
12 * This file is part of OpenOffice.org.
14 * OpenOffice.org is free software: you can redistribute it and/or modify
15 * it under the terms of the GNU Lesser General Public License version 3
16 * only, as published by the Free Software Foundation.
18 * OpenOffice.org is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU Lesser General Public License version 3 for more details
22 * (a copy is included in the LICENSE file that accompanied this code).
24 * You should have received a copy of the GNU Lesser General Public License
25 * version 3 along with OpenOffice.org. If not, see
26 * <http://www.openoffice.org/license.html>
27 * for a copy of the LGPLv3 License.
29 ************************************************************************/
31 #ifndef _RTL_STRBUF_HXX_
32 #define _RTL_STRBUF_HXX_
34 #include "osl/diagnose.h"
35 #include <rtl/strbuf.h>
36 #include <rtl/string.hxx>
38 #ifdef __cplusplus
40 namespace rtl
43 /** @HTML
45 A string buffer implements a mutable sequence of characters.
46 <p>
47 String buffers are safe for use by multiple threads. The methods
48 are synchronized where necessary so that all the operations on any
49 particular instance behave as if they occur in some serial order.
50 <p>
51 String buffers are used by the compiler to implement the binary
52 string concatenation operator <code>+</code>. For example, the code:
53 <p><blockquote><pre>
54 x = "a" + 4 + "c"
55 </pre></blockquote><p>
56 is compiled to the equivalent of:
57 <p><blockquote><pre>
58 x = new OStringBuffer().append("a").append(4).append("c")
59 .toString()
60 </pre></blockquote><p>
61 The principal operations on a <code>OStringBuffer</code> are the
62 <code>append</code> and <code>insert</code> methods, which are
63 overloaded so as to accept data of any type. Each effectively
64 converts a given datum to a string and then appends or inserts the
65 characters of that string to the string buffer. The
66 <code>append</code> method always adds these characters at the end
67 of the buffer; the <code>insert</code> method adds the characters at
68 a specified point.
69 <p>
70 For example, if <code>z</code> refers to a string buffer object
71 whose current contents are "<code>start</code>", then
72 the method call <code>z.append("le")</code> would cause the string
73 buffer to contain "<code>startle</code>", whereas
74 <code>z.insert(4, "le")</code> would alter the string buffer to
75 contain "<code>starlet</code>".
76 <p>
77 Every string buffer has a capacity. As long as the length of the
78 character sequence contained in the string buffer does not exceed
79 the capacity, it is not necessary to allocate a new internal
80 buffer array. If the internal buffer overflows, it is
81 automatically made larger.
83 class OStringBuffer
85 public:
86 /**
87 Constructs a string buffer with no characters in it and an
88 initial capacity of 16 characters.
90 OStringBuffer()
91 : pData(NULL)
92 , nCapacity( 16 )
94 rtl_string_new_WithLength( &pData, nCapacity );
97 /**
98 Allocates a new string buffer that contains the same sequence of
99 characters as the string buffer argument.
101 @param value a <code>OStringBuffer</code>.
103 OStringBuffer( const OStringBuffer & value )
104 : pData(NULL)
105 , nCapacity( value.nCapacity )
107 rtl_stringbuffer_newFromStringBuffer( &pData, value.nCapacity, value.pData );
111 Constructs a string buffer with no characters in it and an
112 initial capacity specified by the <code>length</code> argument.
114 @param length the initial capacity.
116 OStringBuffer(sal_Int32 length)
117 : pData(NULL)
118 , nCapacity( length )
120 rtl_string_new_WithLength( &pData, length );
124 Constructs a string buffer so that it represents the same
125 sequence of characters as the string argument.
127 The initial
128 capacity of the string buffer is <code>16</code> plus the length
129 of the string argument.
131 @param value the initial string value.
133 OStringBuffer(OString value)
134 : pData(NULL)
135 , nCapacity( value.getLength() + 16 )
137 rtl_stringbuffer_newFromStr_WithLength( &pData, value.getStr(), value.getLength() );
140 /** Assign to this a copy of value.
142 OStringBuffer& operator = ( const OStringBuffer& value )
144 if (this != &value)
146 rtl_stringbuffer_newFromStringBuffer(&pData,
147 value.nCapacity,
148 value.pData);
149 nCapacity = value.nCapacity;
151 return *this;
155 Release the string data.
157 ~OStringBuffer()
159 rtl_string_release( pData );
163 Fill the string data in the new string and clear the buffer.
165 This method is more efficient than the contructor of the string. It does
166 not copy the buffer.
168 @return the string previously contained in the buffer.
170 OString makeStringAndClear()
172 OString aRet( pData );
173 rtl_string_new(&pData);
174 nCapacity = 0;
175 return aRet;
179 Returns the length (character count) of this string buffer.
181 @return the number of characters in this string buffer.
183 sal_Int32 getLength() const
185 return pData->length;
189 Returns the current capacity of the String buffer.
191 The capacity
192 is the amount of storage available for newly inserted
193 characters. The real buffer size is 2 bytes longer, because
194 all strings are 0 terminated.
196 @return the current capacity of this string buffer.
198 sal_Int32 getCapacity() const
200 return nCapacity;
204 Ensures that the capacity of the buffer is at least equal to the
205 specified minimum.
207 The new capacity will be at least as large as the maximum of the current
208 length (so that no contents of the buffer is destroyed) and the given
209 minimumCapacity. If the given minimumCapacity is negative, nothing is
210 changed.
212 @param minimumCapacity the minimum desired capacity.
214 void ensureCapacity(sal_Int32 minimumCapacity)
216 rtl_stringbuffer_ensureCapacity( &pData, &nCapacity, minimumCapacity );
220 Sets the length of this String buffer.
222 If the <code>newLength</code> argument is less than the current
223 length of the string buffer, the string buffer is truncated to
224 contain exactly the number of characters given by the
225 <code>newLength</code> argument.
227 If the <code>newLength</code> argument is greater than or equal
228 to the current length, sufficient null characters
229 (<code>'&#92;u0000'</code>) are appended to the string buffer so that
230 length becomes the <code>newLength</code> argument.
232 The <code>newLength</code> argument must be greater than or equal
233 to <code>0</code>.
235 @param newLength the new length of the buffer.
237 void setLength(sal_Int32 newLength)
239 OSL_ASSERT(newLength >= 0);
240 // Avoid modifications if pData points to const empty string:
241 if( newLength != pData->length )
243 if( newLength > nCapacity )
244 rtl_stringbuffer_ensureCapacity(&pData, &nCapacity, newLength);
245 else
246 pData->buffer[newLength] = '\0';
247 pData->length = newLength;
252 Returns the character at a specific index in this string buffer.
254 The first character of a string buffer is at index
255 <code>0</code>, the next at index <code>1</code>, and so on, for
256 array indexing.
258 The index argument must be greater than or equal to
259 <code>0</code>, and less than the length of this string buffer.
261 @param index the index of the desired character.
262 @return the character at the specified index of this string buffer.
264 sal_Char charAt( sal_Int32 index )
266 OSL_ASSERT(index >= 0 && index < pData->length);
267 return pData->buffer[ index ];
271 Return a null terminated character array.
273 operator const sal_Char *() const { return pData->buffer; }
276 Return a null terminated character array.
278 const sal_Char* getStr() const { return pData->buffer; }
282 The character at the specified index of this string buffer is set
283 to <code>ch</code>.
285 The index argument must be greater than or equal to
286 <code>0</code>, and less than the length of this string buffer.
288 @param index the index of the character to modify.
289 @param ch the new character.
291 OStringBuffer & setCharAt(sal_Int32 index, sal_Char ch)
293 OSL_ASSERT(index >= 0 && index < pData->length);
294 pData->buffer[ index ] = ch;
295 return *this;
299 Appends the string to this string buffer.
301 The characters of the <code>String</code> argument are appended, in
302 order, to the contents of this string buffer, increasing the
303 length of this string buffer by the length of the argument.
305 @param str a string.
306 @return this string buffer.
308 OStringBuffer & append(const OString &str)
310 return append( str.getStr(), str.getLength() );
314 Appends the string representation of the <code>char</code> array
315 argument to this string buffer.
317 The characters of the array argument are appended, in order, to
318 the contents of this string buffer. The length of this string
319 buffer increases by the length of the argument.
321 @param str the characters to be appended.
322 @return this string buffer.
324 OStringBuffer & append( const sal_Char * str )
326 return append( str, rtl_str_getLength( str ) );
330 Appends the string representation of the <code>char</code> array
331 argument to this string buffer.
333 Characters of the character array <code>str</code> are appended,
334 in order, to the contents of this string buffer. The length of this
335 string buffer increases by the value of <code>len</code>.
337 @param str the characters to be appended; must be non-null, and must
338 point to at least len characters
339 @param len the number of characters to append; must be non-negative
340 @return this string buffer.
342 OStringBuffer & append( const sal_Char * str, sal_Int32 len)
344 // insert behind the last character
345 rtl_stringbuffer_insert( &pData, &nCapacity, getLength(), str, len );
346 return *this;
350 Appends the string representation of the <code>sal_Bool</code>
351 argument to the string buffer.
353 The argument is converted to a string as if by the method
354 <code>String.valueOf</code>, and the characters of that
355 string are then appended to this string buffer.
357 @param b a <code>sal_Bool</code>.
358 @return this string buffer.
360 OStringBuffer & append(sal_Bool b)
362 sal_Char sz[RTL_STR_MAX_VALUEOFBOOLEAN];
363 return append( sz, rtl_str_valueOfBoolean( sz, b ) );
367 Appends the string representation of the <code>char</code>
368 argument to this string buffer.
370 The argument is appended to the contents of this string buffer.
371 The length of this string buffer increases by <code>1</code>.
373 @param ch a <code>char</code>.
374 @return this string buffer.
376 OStringBuffer & append(sal_Char c)
378 return append( &c, 1 );
382 Appends the string representation of the <code>sal_Int32</code>
383 argument to this string buffer.
385 The argument is converted to a string as if by the method
386 <code>String.valueOf</code>, and the characters of that
387 string are then appended to this string buffer.
389 @param i an <code>sal_Int32</code>.
390 @return this string buffer.
392 OStringBuffer & append(sal_Int32 i, sal_Int16 radix = 10 )
394 sal_Char sz[RTL_STR_MAX_VALUEOFINT32];
395 return append( sz, rtl_str_valueOfInt32( sz, i, radix ) );
399 Appends the string representation of the <code>long</code>
400 argument to this string buffer.
402 The argument is converted to a string as if by the method
403 <code>String.valueOf</code>, and the characters of that
404 string are then appended to this string buffer.
406 @param l a <code>long</code>.
407 @return this string buffer.
409 OStringBuffer & append(sal_Int64 l, sal_Int16 radix = 10 )
411 sal_Char sz[RTL_STR_MAX_VALUEOFINT64];
412 return append( sz, rtl_str_valueOfInt64( sz, l, radix ) );
416 Appends the string representation of the <code>float</code>
417 argument to this string buffer.
419 The argument is converted to a string as if by the method
420 <code>String.valueOf</code>, and the characters of that
421 string are then appended to this string buffer.
423 @param f a <code>float</code>.
424 @return this string buffer.
426 OStringBuffer & append(float f)
428 sal_Char sz[RTL_STR_MAX_VALUEOFFLOAT];
429 return append( sz, rtl_str_valueOfFloat( sz, f ) );
433 Appends the string representation of the <code>double</code>
434 argument to this string buffer.
436 The argument is converted to a string as if by the method
437 <code>String.valueOf</code>, and the characters of that
438 string are then appended to this string buffer.
440 @param d a <code>double</code>.
441 @return this string buffer.
443 OStringBuffer & append(double d)
445 sal_Char sz[RTL_STR_MAX_VALUEOFDOUBLE];
446 return append( sz, rtl_str_valueOfDouble( sz, d ) );
450 Inserts the string into this string buffer.
452 The characters of the <code>String</code> argument are inserted, in
453 order, into this string buffer at the indicated offset. The length
454 of this string buffer is increased by the length of the argument.
456 The offset argument must be greater than or equal to
457 <code>0</code>, and less than or equal to the length of this
458 string buffer.
460 @param offset the offset.
461 @param str a string.
462 @return this string buffer.
464 OStringBuffer & insert(sal_Int32 offset, const OString & str)
466 return insert( offset, str.getStr(), str.getLength() );
470 Inserts the string representation of the <code>char</code> array
471 argument into this string buffer.
473 The characters of the array argument are inserted into the
474 contents of this string buffer at the position indicated by
475 <code>offset</code>. The length of this string buffer increases by
476 the length of the argument.
478 The offset argument must be greater than or equal to
479 <code>0</code>, and less than or equal to the length of this
480 string buffer.
482 @param offset the offset.
483 @param ch a character array.
484 @return this string buffer.
486 OStringBuffer & insert( sal_Int32 offset, const sal_Char * str )
488 return insert( offset, str, rtl_str_getLength( str ) );
492 Inserts the string representation of the <code>char</code> array
493 argument into this string buffer.
495 The characters of the array argument are inserted into the
496 contents of this string buffer at the position indicated by
497 <code>offset</code>. The length of this string buffer increases by
498 the length of the argument.
500 The offset argument must be greater than or equal to
501 <code>0</code>, and less than or equal to the length of this
502 string buffer.
504 @param offset the offset.
505 @param ch a character array.
506 @param len the number of characters to append.
507 @return this string buffer.
509 OStringBuffer & insert( sal_Int32 offset, const sal_Char * str, sal_Int32 len)
511 // insert behind the last character
512 rtl_stringbuffer_insert( &pData, &nCapacity, offset, str, len );
513 return *this;
517 Inserts the string representation of the <code>sal_Bool</code>
518 argument into this string buffer.
520 The second argument is converted to a string as if by the method
521 <code>String.valueOf</code>, and the characters of that
522 string are then inserted into this string buffer at the indicated
523 offset.
525 The offset argument must be greater than or equal to
526 <code>0</code>, and less than or equal to the length of this
527 string buffer.
529 @param offset the offset.
530 @param b a <code>sal_Bool</code>.
531 @return this string buffer.
533 OStringBuffer & insert(sal_Int32 offset, sal_Bool b)
535 sal_Char sz[RTL_STR_MAX_VALUEOFBOOLEAN];
536 return insert( offset, sz, rtl_str_valueOfBoolean( sz, b ) );
540 Inserts the string representation of the <code>char</code>
541 argument into this string buffer.
543 The second argument is inserted into the contents of this string
544 buffer at the position indicated by <code>offset</code>. The length
545 of this string buffer increases by one.
547 The offset argument must be greater than or equal to
548 <code>0</code>, and less than or equal to the length of this
549 string buffer.
551 @param offset the offset.
552 @param ch a <code>char</code>.
553 @return this string buffer.
555 OStringBuffer & insert(sal_Int32 offset, sal_Char c)
557 return insert( offset, &c, 1 );
561 Inserts the string representation of the second <code>sal_Int32</code>
562 argument into this string buffer.
564 The second argument is converted to a string as if by the method
565 <code>String.valueOf</code>, and the characters of that
566 string are then inserted into this string buffer at the indicated
567 offset.
569 The offset argument must be greater than or equal to
570 <code>0</code>, and less than or equal to the length of this
571 string buffer.
573 @param offset the offset.
574 @param b an <code>sal_Int32</code>.
575 @return this string buffer.
577 OStringBuffer & insert(sal_Int32 offset, sal_Int32 i, sal_Int16 radix = 10 )
579 sal_Char sz[RTL_STR_MAX_VALUEOFINT32];
580 return insert( offset, sz, rtl_str_valueOfInt32( sz, i, radix ) );
584 Inserts the string representation of the <code>long</code>
585 argument into this string buffer.
587 The second argument is converted to a string as if by the method
588 <code>String.valueOf</code>, and the characters of that
589 string are then inserted into this string buffer at the indicated
590 offset.
592 The offset argument must be greater than or equal to
593 <code>0</code>, and less than or equal to the length of this
594 string buffer.
596 @param offset the offset.
597 @param b a <code>long</code>.
598 @return this string buffer.
600 OStringBuffer & insert(sal_Int32 offset, sal_Int64 l, sal_Int16 radix = 10 )
602 sal_Char sz[RTL_STR_MAX_VALUEOFINT64];
603 return insert( offset, sz, rtl_str_valueOfInt64( sz, l, radix ) );
607 Inserts the string representation of the <code>float</code>
608 argument into this string buffer.
610 The second argument is converted to a string as if by the method
611 <code>String.valueOf</code>, and the characters of that
612 string are then inserted into this string buffer at the indicated
613 offset.
615 The offset argument must be greater than or equal to
616 <code>0</code>, and less than or equal to the length of this
617 string buffer.
619 @param offset the offset.
620 @param b a <code>float</code>.
621 @return this string buffer.
623 OStringBuffer insert(sal_Int32 offset, float f)
625 sal_Char sz[RTL_STR_MAX_VALUEOFFLOAT];
626 return insert( offset, sz, rtl_str_valueOfFloat( sz, f ) );
630 Inserts the string representation of the <code>double</code>
631 argument into this string buffer.
633 The second argument is converted to a string as if by the method
634 <code>String.valueOf</code>, and the characters of that
635 string are then inserted into this string buffer at the indicated
636 offset.
638 The offset argument must be greater than or equal to
639 <code>0</code>, and less than or equal to the length of this
640 string buffer.
642 @param offset the offset.
643 @param b a <code>double</code>.
644 @return this string buffer.
646 OStringBuffer & insert(sal_Int32 offset, double d)
648 sal_Char sz[RTL_STR_MAX_VALUEOFDOUBLE];
649 return insert( offset, sz, rtl_str_valueOfDouble( sz, d ) );
651 private:
653 A pointer to the data structur which contains the data.
655 rtl_String * pData;
658 The len of the pData->buffer.
660 sal_Int32 nCapacity;
665 #endif /* __cplusplus */
666 #endif /* _RTL_STRBUF_HXX_ */