include/comphelper/string.hxx

   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_COMPHELPER_STRING_HXX
  21 #define INCLUDED_COMPHELPER_STRING_HXX
  22
  23 #include <sal/config.h>
  24
  25 #include <vector>
  26 #include <comphelper/comphelperdllapi.h>
  27 #include <sal/types.h>
  28 #include <rtl/strbuf.hxx>
  29 #include <rtl/ustrbuf.hxx>
  30 #include <com/sun/star/uno/Sequence.h>
  31 #include <com/sun/star/uno/Reference.hxx>
  32
  33 #include <com/sun/star/lang/Locale.hpp>
  34
  35 namespace com::sun::star::i18n { class XBreakIterator; }
  36 namespace com::sun::star::i18n { class XCollator; }
  37 namespace com::sun::star::uno { class XComponentContext; }
  38
  39 // OUString helper functions that are not widespread or mature enough to
  40 // go into the stable URE API:
  41 namespace comphelper::string {
  42
  43 /** Compare an OUString to a single char
  44
  45     @param rIn      The input OUString
  46     @param c        The character to compare against
  47
  48     @return         true if rIn has one char and its equal to c
  49  */
  50 inline bool equals(const OUString& rIn, sal_Unicode c)
  51 { return rIn.getLength() == 1 && rIn[0] == c; }
  52
  53 /** Removes all occurrences of a character from within the source string
  54
  55     @param rIn      The input OUStringBuffer
  56     @param c        The character to be removed
  57
  58     @return         The resulting OUStringBuffer
  59  */
  60 inline OUStringBuffer& remove(OUStringBuffer &rIn,
  61     sal_Unicode c)
  62 {
  63     sal_Int32 index = 0;
  64     while (true)
  65     {
  66         if (index >= rIn.getLength())
  67             break;
  68         index = rIn.indexOf(c, index);
  69         if (index == -1)
  70             break;
  71         rIn.remove(index, 1);
  72     }
  73     return rIn;
  74 }
  75
  76 /** Strips occurrences of a character from the start of the source string
  77
  78     @param rIn      The input OString
  79     @param c        The character to be stripped from the start
  80
  81     @return         The resulting OString
  82  */
  83 COMPHELPER_DLLPUBLIC OString stripStart(const OString &rIn,
  84     char c);
  85
  86 /** Strips occurrences of a character from the start of the source string
  87
  88     @param rIn      The input OUString
  89     @param c        The character to be stripped from the start
  90
  91     @return         The resulting OUString
  92  */
  93 COMPHELPER_DLLPUBLIC OUString stripStart(const OUString &rIn,
  94     sal_Unicode c);
  95
  96 /** Strips occurrences of a character from the end of the source string
  97
  98     @param rIn      The input OString
  99     @param c        The character to be stripped from the end
 100
 101     @return         The resulting OString
 102  */
 103 COMPHELPER_DLLPUBLIC OString stripEnd(const OString &rIn,
 104     char c);
 105
 106 /** Strips occurrences of a character from the end of the source string
 107
 108     @param rIn      The input OUString
 109     @param c        The character to be stripped from the end
 110
 111     @return         The resulting OUString
 112  */
 113 COMPHELPER_DLLPUBLIC OUString stripEnd(const OUString &rIn,
 114     sal_Unicode c);
 115
 116 /** Strips occurrences of a character from the start and end of the source string
 117
 118     @param rIn      The input OString
 119     @param c        The character to be stripped from the start and end
 120
 121     @return         The resulting OString
 122  */
 123 COMPHELPER_DLLPUBLIC OString strip(const OString &rIn,
 124     char c);
 125
 126 /** Strips occurrences of a character from the start and end of the source string
 127
 128     @param rIn      The input OUString
 129     @param c        The character to be stripped from the start and end
 130
 131     @return         The resulting OUString
 132  */
 133 COMPHELPER_DLLPUBLIC OUString strip(const OUString &rIn,
 134     sal_Unicode c);
 135
 136 /** Returns number of tokens in an OUString
 137
 138   @param    rIn     the input OString
 139   @param    cTok    the character which separate the tokens.
 140   @return   the number of tokens
 141 */
 142 COMPHELPER_DLLPUBLIC sal_Int32 getTokenCount(const OString &rIn, char cTok);
 143
 144 /** Returns number of tokens in an OUString
 145
 146   @param    rIn     the input OUString
 147   @param    cTok    the character which separate the tokens.
 148   @return   the number of tokens
 149 */
 150 COMPHELPER_DLLPUBLIC sal_Int32 getTokenCount(const OUString &rIn, sal_Unicode cTok);
 151
 152 /** Reverse an OUString
 153
 154   @param    rIn     the input OUString
 155   @return   the reversed input
 156 */
 157 COMPHELPER_DLLPUBLIC OUString reverseString(const OUString &rStr);
 158
 159 /** Reverse an OString
 160
 161   @param    rIn     the input OString
 162   @return   the reversed input
 163 */
 164 COMPHELPER_DLLPUBLIC OString reverseString(const OString &rStr);
 165
 166
 167 namespace detail
 168 {
 169     template<typename B> B& truncateToLength(B& rBuffer, sal_Int32 nLen)
 170     {
 171         if (nLen < rBuffer.getLength())
 172             rBuffer.remove(nLen, rBuffer.getLength()-nLen);
 173         return rBuffer;
 174     }
 175 }
 176
 177 /** Truncate a buffer to a given length.
 178
 179     If the StringBuffer has more characters than nLength it will be truncated
 180     on the right to nLength characters.
 181
 182     Has no effect if the StringBuffer is <= nLength
 183
 184     @param rBuf   StringBuffer to operate on
 185     @param nLength   Length to truncate the buffer to
 186
 187     @return         rBuf;
 188  */
 189 inline OUStringBuffer& truncateToLength(
 190     OUStringBuffer& rBuffer, sal_Int32 nLength)
 191 {
 192     return detail::truncateToLength(rBuffer, nLength);
 193 }
 194
 195 namespace detail
 196 {
 197     template<typename B, typename U> B& padToLength(B& rBuffer, sal_Int32 nLen,
 198         U cFill = '\0')
 199     {
 200         sal_Int32 nOrigLen = rBuffer.getLength();
 201         if (nLen > nOrigLen)
 202         {
 203             rBuffer.setLength(nLen);
 204             for (sal_Int32 i = nOrigLen; i < nLen; ++i)
 205                 rBuffer[i] = cFill;
 206         }
 207         return rBuffer;
 208     }
 209 }
 210
 211 /** Pad a buffer to a given length using a given char.
 212
 213     If the StringBuffer has less characters than nLength it will be expanded on
 214     the right to nLength characters, with the expansion filled using cFill.
 215
 216     Has no effect if the StringBuffer is >= nLength
 217
 218     @param rBuf   StringBuffer to operate on
 219     @param nLength   Length to pad the buffer to
 220     @param cFill  character to fill expansion with
 221
 222     @return         rBuf;
 223  */
 224 inline OStringBuffer& padToLength(
 225     OStringBuffer& rBuffer, sal_Int32 nLength,
 226     char cFill = '\0')
 227 {
 228     return detail::padToLength(rBuffer, nLength, cFill);
 229 }
 230
 231 inline OUStringBuffer& padToLength(
 232     OUStringBuffer& rBuffer, sal_Int32 nLength,
 233     sal_Unicode cFill = '\0')
 234 {
 235     return detail::padToLength(rBuffer, nLength, cFill);
 236 }
 237
 238 /** Replace a token in a string
 239     @param rIn       OUString in which the token is to be replaced
 240     @param nToken    which nToken to replace
 241     @param cTok      token delimiter
 242     @param rNewToken replacement token
 243
 244     @return original string with token nToken replaced by rNewToken
 245  */
 246 COMPHELPER_DLLPUBLIC OUString setToken(const OUString& rIn, sal_Int32 nToken, sal_Unicode cTok,
 247     const OUString& rNewToken);
 248
 249 /** Find any of a list of code units in the string.
 250     @param rIn      OUString to search
 251     @param pChars   0-terminated array of sal_Unicode code units to search for
 252     @param nPos     start position
 253
 254     @return position of first occurrence of any of the elements of pChars
 255             or -1 if none of the code units occur in the string
 256  */
 257 COMPHELPER_DLLPUBLIC sal_Int32 indexOfAny(OUString const& rIn,
 258         sal_Unicode const*const pChars, sal_Int32 const nPos);
 259
 260 /** Remove any of a list of code units in the string.
 261     @param rIn      OUString to search
 262     @param pChars   0-terminated array of sal_Unicode code units to search for
 263
 264     @return OUString that has all of the pChars code units removed
 265  */
 266 COMPHELPER_DLLPUBLIC OUString removeAny(OUString const& rIn,
 267         sal_Unicode const*const pChars);
 268
 269 /** Convert a sequence of strings to a single comma separated string.
 270
 271     Note that no escaping of commas or anything fancy is done.
 272
 273     @param i_rSeq   A list of strings to be concatenated.
 274
 275     @return         A single string containing the concatenation of the given
 276                     list, interspersed with the string ", ".
 277  */
 278 COMPHELPER_DLLPUBLIC OUString convertCommaSeparated(
 279     css::uno::Sequence< OUString > const & i_rSeq);
 280
 281 /// Return a string which is the concatenation of the strings in the sequence.
 282 COMPHELPER_DLLPUBLIC OString join(const OString& rSeparator, const std::vector<OString>& rSequence);
 283
 284 /** Convert a decimal string to a number.
 285
 286     The string must be base-10, no sign but can contain any
 287     codepoint listed in the "Number, Decimal Digit" Unicode
 288     category.
 289
 290     No verification is made about the validity of the string,
 291     passing string not containing decimal digit code points
 292     gives unspecified results
 293
 294     If your string is guaranteed to contain only ASCII digit
 295     use OUString::toInt32 instead.
 296
 297     @param str  The string to convert containing only decimal
 298                 digit codepoints.
 299
 300     @return     The value of the string as an int32.
 301  */
 302 COMPHELPER_DLLPUBLIC sal_uInt32 decimalStringToNumber(
 303     OUString const & str );
 304
 305 COMPHELPER_DLLPUBLIC std::vector<OUString>
 306     split(const OUString& rString, const sal_Unicode cSeparator);
 307
 308 /** Convert a single comma separated string to a sequence of strings.
 309
 310     Note that no escaping of commas or anything fancy is done.
 311
 312     @param i_rString    A string containing comma-separated words.
 313
 314     @return         A sequence of strings resulting from splitting the given
 315                     string at ',' tokens and stripping whitespace.
 316  */
 317 COMPHELPER_DLLPUBLIC css::uno::Sequence< OUString >
 318     convertCommaSeparated( OUString const & i_rString );
 319
 320 /**
 321   Compares two strings using natural order.
 322
 323   For non digit characters, the comparison use the same algorithm as
 324   rtl_str_compare. When a number is encountered during the comparison,
 325   natural order is used. Thus, Heading 10 will be considered as greater
 326   than Heading 2. Numerical comparison is done using decimal representation.
 327
 328   Beware that "MyString 001" and "MyString 1" will be considered as equal
 329   since leading 0 are meaningless.
 330
 331   @param    str         the object to be compared.
 332   @return   0 - if both strings are equal
 333             < 0 - if this string is less than the string argument
 334             > 0 - if this string is greater than the string argument
 335 */
 336 COMPHELPER_DLLPUBLIC sal_Int32 compareNatural( const OUString &rLHS, const OUString &rRHS,
 337     const css::uno::Reference< css::i18n::XCollator > &rCollator,
 338     const css::uno::Reference< css::i18n::XBreakIterator > &rBI,
 339     const css::lang::Locale &rLocale );
 340
 341 class COMPHELPER_DLLPUBLIC NaturalStringSorter
 342 {
 343 private:
 344     css::lang::Locale const                          m_aLocale;
 345     css::uno::Reference< css::i18n::XCollator >      m_xCollator;
 346     css::uno::Reference< css::i18n::XBreakIterator > m_xBI;
 347 public:
 348     NaturalStringSorter(
 349         const css::uno::Reference< css::uno::XComponentContext > &rContext,
 350         const css::lang::Locale &rLocale);
 351     sal_Int32 compare(const OUString &rLHS, const OUString &rRHS) const
 352     {
 353         return compareNatural(rLHS, rRHS, m_xCollator, m_xBI, m_aLocale);
 354     }
 355     const css::lang::Locale& getLocale() const { return m_aLocale; }
 356 };
 357
 358 /** Determine if an OString contains solely ASCII numeric digits
 359
 360     @param rString  An OString
 361
 362     @return         false if string contains any characters outside
 363                     the ASCII '0'-'9' range
 364                     true otherwise, including for empty string
 365  */
 366 COMPHELPER_DLLPUBLIC bool isdigitAsciiString(const OString &rString);
 367
 368 /** Determine if an OUString contains solely ASCII numeric digits
 369
 370     @param rString  An OUString
 371
 372     @return         false if string contains any characters outside
 373                     the ASCII '0'-'9' range
 374                     true otherwise, including for empty string
 375  */
 376 COMPHELPER_DLLPUBLIC bool isdigitAsciiString(const OUString &rString);
 377
 378 }
 379
 380 #endif
 381
 382 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */