include/rtl/strbuf.h

   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 _RTL_STRBUF_H_
  21 #define _RTL_STRBUF_H_
  22
  23 #include "sal/config.h"
  24
  25 #include "rtl/string.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_stringbuffer_newFromStr_WithLength(
  44                                                       rtl_String ** newStr,
  45                                                       const sal_Char * 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_stringbuffer_newFromStringBuffer(
  64                                                          rtl_String ** newStr,
  65                                                          sal_Int32 capacity,
  66                                                          rtl_String * 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_stringbuffer_ensureCapacity(
  87                                                 rtl_String ** This,
  88                                                 sal_Int32* capacity,
  89                                                 sal_Int32 minimumCapacity);
  90
  91
  92 /**
  93     Inserts the string representation of the <code>char</code> array
  94     argument into this string buffer.
  95
  96     The characters of the array argument are inserted into the
  97     contents of this string buffer at the position indicated by
  98     <code>offset</code>. The length of this string buffer increases by
  99     the length of the argument.
 100
 101     @param[in,out]  This        the String to operate on.
 102     @param[in,out]  capacity    the capacity of the string buffer
 103     @param[in]      offset      the offset.
 104     @param[in]      str         a character array.
 105     @param[in]      len         the number of characters to append.
 106  */
 107 SAL_DLLPUBLIC void SAL_CALL rtl_stringbuffer_insert(
 108                                        rtl_String ** This,
 109                                        sal_Int32 * capacity,
 110                                        sal_Int32 offset,
 111                                        const sal_Char * str,
 112                                        sal_Int32 len);
 113
 114 /**
 115     Removes the characters in a substring of this sequence.
 116
 117     The substring begins at the specified <code>start</code> and
 118     is <code>len</code> characters long.
 119
 120     start must be >= 0 && <= This->length
 121
 122     @param[in,out]  This        The String to operate on.
 123     @param[in]      start       The beginning index, inclusive
 124     @param[in]      len         The substring length
 125  */
 126 SAL_DLLPUBLIC void SAL_CALL rtl_stringbuffer_remove(
 127                                        rtl_String ** This,
 128                                        sal_Int32 start,
 129                                        sal_Int32 len );
 130
 131 #ifdef __cplusplus
 132 }
 133 #endif
 134
 135 #endif  /* _RTL_STRBUF_H_ */
 136
 137 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */