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 /*
  21  * This file is part of LibreOffice published API.
  22  */
  23
  24 #ifndef INCLUDED_RTL_STRBUF_H
  25 #define INCLUDED_RTL_STRBUF_H
  26
  27 #include "sal/config.h"
  28
  29 #include "rtl/string.h"
  30 #include "sal/saldllapi.h"
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /** Allocates a new <code>String</code> that contains characters from
  37     the character array argument.
  38
  39     The <code>count</code> argument specifies
  40     the length of the array. The initial capacity of the string buffer is
  41     <code>16</code> plus the length of the string argument.
  42
  43     @param  newStr   out parameter, contains the new string. The reference count is 1.
  44     @param  value    the initial value of the string.
  45     @param  count    the length of value.
  46  */
  47 SAL_DLLPUBLIC void SAL_CALL rtl_stringbuffer_newFromStr_WithLength(
  48                                                       rtl_String ** newStr,
  49                                                       const char * value,
  50                                                       sal_Int32 count);
  51
  52 /**
  53     Allocates a new <code>String</code> that contains the same sequence of
  54     characters as the string argument.
  55
  56     The initial capacity is the larger of:
  57     <ul>
  58     <li> The <code>bufferLen</code> argument.
  59     <li> The <code>length</code> of the string argument.
  60     </ul>
  61
  62     @param  newStr      out parameter, contains the new string. The reference count is 1.
  63     @param  capacity    the initial len of the string buffer.
  64     @param  oldStr      the initial value of the string.
  65     @return the new capacity of the string buffer
  66  */
  67 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_stringbuffer_newFromStringBuffer(
  68                                                          rtl_String ** newStr,
  69                                                          sal_Int32 capacity,
  70                                                          rtl_String * oldStr );
  71
  72 /**
  73     Ensures that the capacity of the buffer is at least equal to the
  74     specified minimum.
  75
  76     If the current capacity of this string buffer is less than the
  77     argument, then a new internal buffer is allocated with greater
  78     capacity. The new capacity is the larger of:
  79     <ul>
  80     <li>The <code>minimumCapacity</code> argument.
  81     <li>Twice the old capacity, plus <code>2</code>.
  82     </ul>
  83     If the <code>minimumCapacity</code> argument is nonpositive, this
  84     method takes no action and simply returns.
  85
  86     @param[in,out]   This              the String to operate on.
  87     @param[in,out]   capacity          in: old capacity, out: new capacity.
  88     @param[in]       minimumCapacity   the minimum desired capacity.
  89  */
  90 SAL_DLLPUBLIC void SAL_CALL rtl_stringbuffer_ensureCapacity(
  91                                                 rtl_String ** This,
  92                                                 sal_Int32* capacity,
  93                                                 sal_Int32 minimumCapacity);
  94
  95
  96 /**
  97     Inserts the string representation of the <code>char</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[in,out]  This        the String to operate on.
 106     @param[in,out]  capacity    the capacity of the string buffer
 107     @param[in]      offset      the offset.
 108     @param[in]      str         a character array.  Since LibreOffice 4.4, as a
 109                                 special case, if str is null then the len added
 110                                 characters are left uninitialized.
 111     @param[in]      len         the number of characters to append.
 112  */
 113 SAL_DLLPUBLIC void SAL_CALL rtl_stringbuffer_insert(
 114                                        rtl_String ** This,
 115                                        sal_Int32 * capacity,
 116                                        sal_Int32 offset,
 117                                        const char * str,
 118                                        sal_Int32 len);
 119
 120 /**
 121     Removes the characters in a substring of this sequence.
 122
 123     The substring begins at the specified <code>start</code> and
 124     is <code>len</code> characters long.
 125
 126     start must be >= 0 && <= This->length
 127
 128     @param[in,out]  This        The String to operate on.
 129     @param[in]      start       The beginning index, inclusive
 130     @param[in]      len         The substring length
 131  */
 132 SAL_DLLPUBLIC void SAL_CALL rtl_stringbuffer_remove(
 133                                        rtl_String ** This,
 134                                        sal_Int32 start,
 135                                        sal_Int32 len );
 136
 137 #ifdef __cplusplus
 138 }
 139 #endif
 140
 141 #endif // INCLUDED_RTL_STRBUF_H
 142
 143 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */