rtl_(u)String_ensureCapacity

Ensure there will be enough extra space in a string, to be used for string
appending. A bit like rtl_(u)String_newConcat(), but without the function
actually appending anything. Unlike the stringbuffer variant this does
not allocate any extra.

Change-Id: Ic6f84bf014a713f9912c81d8f1405c593978822d

2 files changed, 36 insertions, 0 deletions

diff --git a/sal/inc/rtl/string.h b/sal/inc/rtl/string.h
index 9f3c69a0bcc4..13c622d4e8b3 100644
--- a/sal/inc/rtl/string.h
+++ b/sal/inc/rtl/string.h
@@ -1313,6 +1313,24 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_convertUStringToString(
                                              sal_uInt32 nFlags)
     SAL_THROW_EXTERN_C();
 
+/** Ensure a string has enough space for a given number of characters.
+
+ If the given string is large enough and has refcount of 1, it is not altered in any way.
+ Otherwise it is replaced by a copy that has enough space for the given number of characters,
+ data from the source string is copied to the beginning of it, the content of the remaining
+ capacity undefined, the string has refcount of 1, and refcount of the original string is decreased.
+
+ @param str
+ pointer to the string.  The pointed-to data must be a valid string.
+
+ @param size
+ the number of characters
+
+ @since LibreOffice 4.1
+ @internal
+ */
+SAL_DLLPUBLIC void SAL_CALL rtl_string_ensureCapacity( rtl_String ** str, sal_Int32 size ) SAL_THROW_EXTERN_C();
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/sal/inc/rtl/ustring.h b/sal/inc/rtl/ustring.h
index 0352e59b0e33..0548033f732c 100644
--- a/sal/inc/rtl/ustring.h
+++ b/sal/inc/rtl/ustring.h
@@ -1926,6 +1926,24 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_convertStringToUString(
     rtl_uString ** target, char const * source, sal_Int32 length,
     rtl_TextEncoding encoding, sal_uInt32 flags) SAL_THROW_EXTERN_C();
 
+/** Ensure a string has enough space for a given number of characters.
+
+ If the given string is large enough and has refcount of 1, it is not altered in any way.
+ Otherwise it is replaced by a copy that has enough space for the given number of characters,
+ data from the source string is copied to the beginning of it, the content of the remaining
+ capacity undefined, the string has refcount of 1, and refcount of the original string is decreased.
+
+ @param str
+ pointer to the string.  The pointed-to data must be a valid string.
+
+ @param size
+ the number of characters
+
+ @since LibreOffice 4.1
+ @internal
+ */
+SAL_DLLPUBLIC void SAL_CALL rtl_uString_ensureCapacity( rtl_uString ** str, sal_Int32 size ) SAL_THROW_EXTERN_C();
+
 #ifdef __cplusplus
 }
 #endif