LibreOffice LibreOffice 6.2 SDK C/C++ API Reference

Functions
ustrbuf.h File Reference
`#include "sal/config.h"`
`#include "rtl/ustring.h"`
`#include "sal/saldllapi.h"`

Go to the source code of this file.

## Functions
SAL_DLLPUBLIC void | rtl_uStringbuffer_newFromStr_WithLength (rtl_uString **newStr, const sal_Unicode *value, sal_Int32 count)
| Allocates a new `String` that contains characters from the character array argument. More...
SAL_DLLPUBLIC sal_Int32 | rtl_uStringbuffer_newFromStringBuffer (rtl_uString **newStr, sal_Int32 capacity, rtl_uString *oldStr)
| Allocates a new `String` that contains the same sequence of characters as the string argument. More...
SAL_DLLPUBLIC void | rtl_uStringbuffer_ensureCapacity (rtl_uString **This, sal_Int32 *capacity, sal_Int32 minimumCapacity)
| Ensures that the capacity of the buffer is at least equal to the specified minimum. More...
SAL_DLLPUBLIC void | rtl_uStringbuffer_insert (rtl_uString **This, sal_Int32 *capacity, sal_Int32 offset, const sal_Unicode *str, sal_Int32 len)
| Inserts the string representation of the `str` array argument into this string buffer. More...
SAL_DLLPUBLIC void | rtl_uStringbuffer_insertUtf32 (rtl_uString **pThis, sal_Int32 *capacity, sal_Int32 offset, sal_uInt32 c) SAL_THROW_EXTERN_C()
| Inserts a single UTF-32 character into this string buffer. More...
SAL_DLLPUBLIC void | rtl_uStringbuffer_insert_ascii (rtl_uString **This, sal_Int32 *capacity, sal_Int32 offset, const sal_Char *str, sal_Int32 len)
| Inserts the 8-Bit ASCII string representation of the `str` array argument into this string buffer. More...
SAL_DLLPUBLIC void | rtl_uStringbuffer_remove (rtl_uString **This, sal_Int32 start, sal_Int32 len)
| Removes the characters in a substring of this sequence. More...
SAL_DLLPUBLIC rtl_uString * | rtl_uStringBuffer_makeStringAndClear (rtl_uString **ppThis, sal_Int32 *nCapacity) SAL_RETURNS_NONNULL
| Returns an immutable rtl_uString object, while clearing the string buffer. More...
SAL_DLLPUBLIC rtl_uString * | rtl_uStringBuffer_refReturn (rtl_uString *pThis)
| References and returns an immutable rtl_uString object, from a mutable string-buffer object. More...

## Function Documentation

## ◆ rtl_uStringbuffer_ensureCapacity()

SAL_DLLPUBLIC void rtl_uStringbuffer_ensureCapacity | ( | rtl_uString ** | This,
|  | sal_Int32 * | capacity,
|  | sal_Int32 | minimumCapacity
| ) |  |

Ensures that the capacity of the buffer is at least equal to the specified minimum.

If the current capacity of this string buffer is less than the argument, then a new internal buffer is allocated with greater capacity. The new capacity is the larger of:

- The `minimumCapacity` argument.
- Twice the old capacity, plus `2`.

If the `minimumCapacity` argument is nonpositive, this method takes no action and simply returns.

Parameters

  [in,out] | This | the String to operate on.
  [in,out] | capacity | in: old capacity, out: new capacity.
  [in] | minimumCapacity | the minimum desired capacity.

## ◆ rtl_uStringbuffer_insert()

SAL_DLLPUBLIC void rtl_uStringbuffer_insert | ( | rtl_uString ** | This,
|  | sal_Int32 * | capacity,
|  | sal_Int32 | offset,
|  | const sal_Unicode * | str,
|  | sal_Int32 | len
| ) |  |

Inserts the string representation of the `str` array argument into this string buffer.

The characters of the array argument are inserted into the contents of this string buffer at the position indicated by `offset`. The length of this string buffer increases by the length of the argument.

Parameters

  This | The string, on that the operation should take place
  capacity | the capacity of the string buffer
  offset | the offset.
  str | a character array. Since LibreOffice 4.4, as a special case, if str is null then the len added characters are left uninitialized.
  len | the number of characters to append.

## ◆ rtl_uStringbuffer_insert_ascii()

SAL_DLLPUBLIC void rtl_uStringbuffer_insert_ascii | ( | rtl_uString ** | This,
|  | sal_Int32 * | capacity,
|  | sal_Int32 | offset,
|  | const sal_Char * | str,
|  | sal_Int32 | len
| ) |  |

Inserts the 8-Bit ASCII string representation of the `str` array argument into this string buffer.

Since this function is optimized for performance, the ASCII character values are not converted in any way. The caller has to make sure that all ASCII characters are in the allowed range between 0 and 127.

The characters of the array argument are inserted into the contents of this string buffer at the position indicated by `offset`. The length of this string buffer increases by the length of the argument.

Parameters

  This | The string, on that the operation should take place
  capacity | the capacity of the string buffer
  offset | the offset.
  str | a character array.
  len | the number of characters to append.

## ◆ rtl_uStringbuffer_insertUtf32()

SAL_DLLPUBLIC void rtl_uStringbuffer_insertUtf32 | ( | rtl_uString ** | pThis,
|  | sal_Int32 * | capacity,
|  | sal_Int32 | offset,
|  | sal_uInt32 | c
| ) |  |

Inserts a single UTF-32 character into this string buffer.

The single UTF-32 character will be represented within the string buffer as either one or two UTF-16 code units.

Parameters

  pThis | the string buffer on which the operation is performed
  capacity | the capacity of the string buffer
  offset | the offset into this string buffer (from zero to the length of this string buffer, inclusive)
  c | a well-formed UTF-32 code unit (that is, a value in the range `0`–`0x10FFFF`, but excluding `0xD800`–`0xDFFF`)

## ◆ rtl_uStringBuffer_makeStringAndClear()

SAL_DLLPUBLIC rtl_uString* rtl_uStringBuffer_makeStringAndClear | ( | rtl_uString ** | ppThis,
|  | sal_Int32 * | nCapacity
| ) |  |

Returns an immutable rtl_uString object, while clearing the string buffer.

This method is primarily used to allow these completed string allocation events to be traced.

Parameters

  ppThis | The string, on that the operation should take place
  nCapacity | pointer to the capacity of the string buffer

Since
  LibreOffice 3.6

## ◆ rtl_uStringbuffer_newFromStr_WithLength()

SAL_DLLPUBLIC void rtl_uStringbuffer_newFromStr_WithLength | ( | rtl_uString ** | newStr,
|  | const sal_Unicode * | value,
|  | sal_Int32 | count
| ) |  |

Allocates a new `String` that contains characters from the character array argument.

The `count` argument specifies the length of the array. The initial capacity of the string buffer is `16` plus the length of the string argument.

Parameters

  newStr | out parameter, contains the new string. The reference count is 1.
  value | the initial value of the string.
  count | the length of value.

## ◆ rtl_uStringbuffer_newFromStringBuffer()

SAL_DLLPUBLIC sal_Int32 rtl_uStringbuffer_newFromStringBuffer | ( | rtl_uString ** | newStr,
|  | sal_Int32 | capacity,
|  | rtl_uString * | oldStr
| ) |  |

Allocates a new `String` that contains the same sequence of characters as the string argument.

The initial capacity is the larger of:

- The `bufferLen` argument.
- The `length` of the string argument.

Parameters

  newStr | out parameter, contains the new string. The reference count is 1.
  capacity | the initial len of the string buffer.
  oldStr | the initial value of the string.

Returns
  the new capacity of the string buffer

## ◆ rtl_uStringBuffer_refReturn()

SAL_DLLPUBLIC rtl_uString* rtl_uStringBuffer_refReturn | ( | rtl_uString * | pThis | ) |

References and returns an immutable rtl_uString object, from a mutable string-buffer object.

This method is primarily used to allow legacy 'String' class conversions to OUString to be accurately traced.

Parameters

  pThis | The string, on that the operation should take place

Since
  LibreOffice 3.6

## ◆ rtl_uStringbuffer_remove()

SAL_DLLPUBLIC void rtl_uStringbuffer_remove | ( | rtl_uString ** | This,
|  | sal_Int32 | start,
|  | sal_Int32 | len
| ) |  |

Removes the characters in a substring of this sequence.

The substring begins at the specified `start` and is `len` characters long.

start must be >= 0 && <= This->length

Parameters

  [in,out] | This | The String to operate on.
  [in] | start | The beginning index, inclusive
  [in] | len | The substring length