sal/inc/rtl/ustrbuf.h

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: ustrbuf.h,v $
  10  * $Revision: 1.6 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  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.
  17  *
  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).
  23  *
  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.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef _RTL_USTRBUF_H_
  32 #define _RTL_USTRBUF_H_
  33
  34 #include <rtl/ustring.h>
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 /** @HTML
  41     Allocates a new <code>String</code> that contains characters from
  42     the character array argument.
  43
  44     The <code>count</code> argument specifies
  45     the length of the array. The initial capacity of the string buffer is
  46     <code>16</code> plus the length of the string argument.
  47
  48     @param  newStr   out parameter, contains the new string. The reference count is 1.
  49     @param  value   the initial value of the string.
  50     @param  count    the length of value.
  51  */
  52 void SAL_CALL rtl_uStringbuffer_newFromStr_WithLength( rtl_uString ** newStr,
  53                                                       const sal_Unicode * value,
  54                                                       sal_Int32 count );
  55
  56 /**
  57     Allocates a new <code>String</code> that contains the same sequence of
  58     characters as the string argument.
  59
  60     The initial capacity is the larger of:
  61     <ul>
  62     <li> The <code>bufferLen</code> argument.
  63     <li> The <code>length</code> of the string argument.
  64     </ul>
  65
  66     @param  newStr       out parameter, contains the new string. The reference count is 1.
  67     @param  capacity     the initial len of the string buffer.
  68     @param  oldStr       the initial value of the string.
  69     @return the new capacity of the string buffer
  70  */
  71 sal_Int32 SAL_CALL rtl_uStringbuffer_newFromStringBuffer( rtl_uString ** newStr,
  72                                                           sal_Int32 capacity,
  73                                                           rtl_uString * olsStr );
  74
  75 /**
  76     Ensures that the capacity of the buffer is at least equal to the
  77     specified minimum.
  78
  79     If the current capacity of this string buffer is less than the
  80     argument, then a new internal buffer is allocated with greater
  81     capacity. The new capacity is the larger of:
  82     <ul>
  83     <li>The <code>minimumCapacity</code> argument.
  84     <li>Twice the old capacity, plus <code>2</code>.
  85     </ul>
  86     If the <code>minimumCapacity</code> argument is nonpositive, this
  87     method takes no action and simply returns.
  88
  89     @param   capacity          in: old capicity, out: new capacity.
  90     @param   minimumCapacity   the minimum desired capacity.
  91  */
  92 void SAL_CALL rtl_uStringbuffer_ensureCapacity( /*inout*/rtl_uString ** This,
  93                                                 /*inout*/sal_Int32* capacity,
  94                                                 sal_Int32 minimumCapacity);
  95
  96 /**
  97     Inserts the string representation of the <code>str</code> array
  98     argument into this string buffer.
  99
 100     The characters of the array argument are inserted into the
 101     contents of this string buffer at the position indicated by
 102     <code>offset</code>. The length of this string buffer increases by
 103     the length of the argument.
 104
 105     @param   This        The string, on that the operation should take place
 106     @param   capacity    the capacity of the string buffer
 107     @param   offset      the offset.
 108     @param   str         a character array.
 109     @param   len         the number of characters to append.
 110  */
 111 void SAL_CALL rtl_uStringbuffer_insert( /*inout*/rtl_uString ** This,
 112                                         /*inout*/sal_Int32 * capacity,
 113                                         sal_Int32 offset,
 114                                         const sal_Unicode * str,
 115                                         sal_Int32 len);
 116
 117 /**
 118    Inserts a single UTF-32 character into this string buffer.
 119
 120    <p>The single UTF-32 character will be represented within the string buffer
 121    as either one or two UTF-16 code units.</p>
 122
 123    @param pThis the string buffer on which the operation is performed
 124
 125    @param capacity the capacity of the string buffer
 126
 127    @param offset the offset into this string buffer (from zero to the length
 128    of this string buffer, inclusive)
 129
 130    @param c a well-formed UTF-32 code unit (that is, a value in the range
 131    <code>0</code>&ndash;<code>0x10FFFF</code>, but excluding
 132    <code>0xD800</code>&ndash;<code>0xDFFF</code>)
 133  */
 134 void SAL_CALL rtl_uStringbuffer_insertUtf32(
 135     rtl_uString ** pThis, sal_Int32 * capacity, sal_Int32 offset, sal_uInt32 c)
 136     SAL_THROW_EXTERN_C();
 137
 138 /**
 139     Inserts the 8-Bit ASCII string representation of the <code>str</code>
 140     array argument into this string buffer.
 141
 142     Since this function is optimized
 143     for performance, the ASCII character values are not converted in any way.
 144     The caller has to make sure that all ASCII characters are in the allowed
 145     range between 0 and 127.
 146     <p>
 147     The characters of the array argument are inserted into the
 148     contents of this string buffer at the position indicated by
 149     <code>offset</code>. The length of this string buffer increases by
 150     the length of the argument.
 151
 152     @param   This        The string, on that the operation should take place
 153     @param   capacity    the capacity of the string buffer
 154     @param   offset      the offset.
 155     @param   str         a character array.
 156     @param   len         the number of characters to append.
 157  */
 158 void SAL_CALL rtl_uStringbuffer_insert_ascii(   /*inout*/rtl_uString ** This,
 159                                                 /*inout*/sal_Int32 * capacity,
 160                                                 sal_Int32 offset,
 161                                                 const sal_Char * str,
 162                                                 sal_Int32 len);
 163
 164 #ifdef __cplusplus
 165 }
 166 #endif
 167
 168 #endif  /* _RTL_USTRBUF_H_ */