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 INCLUDED_RTL_STRBUF_H
  21 #define INCLUDED_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.  Since LibreOffice 4.4, as a
 105                                 special case, if str is null then the len added
 106                                 characters are left uninitialized.
 107     @param[in]      len         the number of characters to append.
 108  */
 109 SAL_DLLPUBLIC void SAL_CALL rtl_stringbuffer_insert(
 110                                        rtl_String ** This,
 111                                        sal_Int32 * capacity,
 112                                        sal_Int32 offset,
 113                                        const sal_Char * str,
 114                                        sal_Int32 len);
 115
 116 /**
 117     Removes the characters in a substring of this sequence.
 118
 119     The substring begins at the specified <code>start</code> and
 120     is <code>len</code> characters long.
 121
 122     start must be >= 0 && <= This->length
 123
 124     @param[in,out]  This        The String to operate on.
 125     @param[in]      start       The beginning index, inclusive
 126     @param[in]      len         The substring length
 127  */
 128 SAL_DLLPUBLIC void SAL_CALL rtl_stringbuffer_remove(
 129                                        rtl_String ** This,
 130                                        sal_Int32 start,
 131                                        sal_Int32 len );
 132
 133 #ifdef __cplusplus
 134 }
 135 #endif
 136
 137 #endif // INCLUDED_RTL_STRBUF_H
 138
 139 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */