include/rtl/stringutils.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
  10 /*
  11  * This file is part of LibreOffice published API.
  12  */
  13
  14 #ifndef INCLUDED_RTL_STRINGUTILS_HXX
  15 #define INCLUDED_RTL_STRINGUTILS_HXX
  16
  17 #include "sal/config.h"
  18
  19 #include <cassert>
  20 #include <cstddef>
  21
  22 #include "sal/types.h"
  23
  24 // The unittest uses slightly different code to help check that the proper
  25 // calls are made. The class is put into a different namespace to make
  26 // sure the compiler generates a different (if generating also non-inline)
  27 // copy of the function and does not merge them together. The class
  28 // is "brought" into the proper rtl namespace by a typedef below.
  29 #ifdef RTL_STRING_UNITTEST
  30 #define rtl rtlunittest
  31 #endif
  32
  33 namespace rtl
  34 {
  35
  36 #ifdef RTL_STRING_UNITTEST
  37 #undef rtl
  38 #endif
  39
  40 #if defined LIBO_INTERNAL_ONLY
  41 /// @cond INTERNAL
  42
  43 // A simple wrapper around a single char.  Can be useful in string concatenation contexts, like in
  44 //
  45 //  OString s = ...;
  46 //  char c = ...;
  47 //  s += OStringChar(c);
  48 //
  49 struct SAL_WARN_UNUSED OStringChar {
  50     constexpr OStringChar(char theC): c(theC) {}
  51     template<typename T> OStringChar(T &&) = delete;
  52     constexpr operator std::string_view() const { return {&c, 1}; }
  53     char const c;
  54 };
  55
  56 /** A simple wrapper around a single sal_Unicode character.
  57
  58     Can be useful to pass a sal_Unicode constant into an OUString-related
  59     function that is optimized for UTF-16 string literal arguments.  That is,
  60     instead of
  61
  62       sal_Unicode const WILDCARD = '%';
  63       ...
  64       if (s[i] == WILDCARD) ...
  65       ...
  66       if (s.endsWith(OUString(WILDCARD))) ...
  67
  68     use
  69
  70       sal_Unicode const WILDCARD = '%';
  71       ...
  72       if (s[i] == WILDCARD) ...
  73       ...
  74       if (s.endsWith(OUStringChar(WILDCARD))) ...
  75
  76     to avoid creating a temporary OUString instance, and instead pick the
  77     endsWith overload actually designed to take an argument of type
  78     sal_Unicode const[N].
  79
  80     (Because of the above use case,
  81     instances of OUStringChar need to be const, as those literal-optimized
  82     functions take the literal argument by non-const lvalue reference, for
  83     technical reasons.
  84
  85     For actual arrays, it is important to distinguish string literals from other char or sal_Unicode
  86     arrays, which may contain junk after the first NUL character or may be non-ASCII in the case of
  87     char arrays.  This is not so much a concern for single char and sal_Unicode values, where NUL is
  88     assumed to always be meant as an actual character.)
  89
  90     Can also be useful in string concatenation contexts, like in
  91
  92       sal_Unicode const * s = ...;
  93       sal_Unicode c = ...;
  94       OUString t = s + OUStringChar(c);
  95
  96     @since LibreOffice 5.0
  97 */
  98 struct SAL_WARN_UNUSED OUStringChar_ {
  99     constexpr OUStringChar_(sal_Unicode theC): c(theC) {}
 100     constexpr OUStringChar_(char theC): c(theC) { assert(c <= 0x7F); }
 101     template<typename T> OUStringChar_(T &&) = delete;
 102     constexpr operator std::u16string_view() const { return {&c, 1}; }
 103     sal_Unicode const c;
 104 };
 105 using OUStringChar = OUStringChar_ const;
 106
 107 /// @endcond
 108 #endif
 109
 110 namespace libreoffice_internal
 111 {
 112 /*
 113 These templates use SFINAE (Substitution failure is not an error) to help distinguish the various
 114 plain C string types: char*, const char*, char[N], const char[N], char[] and const char[].
 115 There are 2 cases:
 116 1) Only string literal (i.e. const char[N]) is wanted, not any of the others.
 117     In this case it is necessary to distinguish between const char[N] and char[N], as the latter
 118     would be automatically converted to the const variant, which is not wanted (not a string literal
 119     with known size of the content). In this case ConstCharArrayDetector is used to ensure the function
 120     is called only with const char[N] arguments. There's no other plain C string type overload.
 121     (Note that OUStringChar is also covered by ConstCharArrayDetector's TypeUtf16 check, but
 122     provides a pointer to a string that is not NUL-terminated, unlike the char16_t const[N] arrays
 123     normally covered by that check, and which are assumed to represent NUL-terminated string
 124     literals.)
 125 2) All plain C string types are wanted, and const char[N] needs to be handled differently.
 126     In this case const char[N] would match const char* argument type (not exactly sure why, but it's
 127     consistent in all of gcc, clang and msvc). Using a template with a reference to const of the type
 128     avoids this problem, and CharPtrDetector ensures that the function is called only with char pointer
 129     arguments. The const in the argument is necessary to handle the case when something is explicitly
 130     cast to const char*. Additionally (non-const) char[N] needs to be handled, but with the reference
 131     being const, it would also match const char[N], so another overload with a reference to non-const
 132     and NonConstCharArrayDetector are used to ensure the function is called only with (non-const) char[N].
 133 Additionally, char[] and const char[] (i.e. size unknown) are rather tricky. Their usage with 'T&' would
 134 mean it would be 'char(&)[]', which seems to be invalid. But gcc and clang somehow manage when it is
 135 a template. while msvc complains about no conversion from char[] to char[1]. And the reference cannot
 136 be avoided, because 'const char[]' as argument type would match also 'const char[N]'
 137 So char[] and const char[] should always be used with their contents specified (which automatically
 138 turns them into char[N] or const char[N]), or char* and const char* should be used.
 139 */
 140 struct Dummy {};
 141 template< typename T1, typename T2 = void >
 142 struct CharPtrDetector
 143 {
 144     static const bool ok = false;
 145 };
 146 template< typename T >
 147 struct CharPtrDetector< const char*, T >
 148 {
 149     typedef T Type;
 150     static const bool ok = true;
 151 };
 152 template< typename T >
 153 struct CharPtrDetector< char*, T >
 154 {
 155     typedef T Type;
 156     static const bool ok = true;
 157 };
 158 #if defined LIBO_INTERNAL_ONLY
 159 template<typename T> struct CharPtrDetector<sal_Unicode *, T> { using TypeUtf16 = T; };
 160 template<typename T> struct CharPtrDetector<sal_Unicode const *, T> { using TypeUtf16 = T; };
 161 template<typename T> struct CharPtrDetector<sal_Unicode[], T> { using TypeUtf16 = T; };
 162 template<typename T> struct CharPtrDetector<sal_Unicode const[], T> { using TypeUtf16 = T; };
 163 #endif
 164
 165 template< typename T1, typename T2 >
 166 struct NonConstCharArrayDetector
 167 {
 168 };
 169 template< typename T, int N >
 170 struct NonConstCharArrayDetector< char[ N ], T >
 171 {
 172     typedef T Type;
 173 };
 174 #ifdef RTL_STRING_UNITTEST
 175 // never use, until all compilers handle this
 176 template< typename T >
 177 struct NonConstCharArrayDetector< char[], T >
 178 {
 179     typedef T Type;
 180 };
 181 template< typename T >
 182 struct NonConstCharArrayDetector< const char[], T >
 183 {
 184     typedef T Type;
 185 };
 186 #endif
 187 #if defined LIBO_INTERNAL_ONLY
 188 template<typename T, std::size_t N> struct NonConstCharArrayDetector<sal_Unicode[N], T> {
 189     using TypeUtf16 = T;
 190 };
 191 #endif
 192
 193 template< typename T1, typename T2 = void >
 194 struct ConstCharArrayDetector
 195 {
 196     static const bool ok = false;
 197 };
 198 template< std::size_t N, typename T >
 199 struct ConstCharArrayDetector< const char[ N ], T >
 200 {
 201     typedef T Type;
 202     static const std::size_t length = N - 1;
 203     static const bool ok = true;
 204 #if defined LIBO_INTERNAL_ONLY
 205     constexpr
 206 #endif
 207     static bool isValid(char const (& literal)[N]) {
 208         for (std::size_t i = 0; i != N - 1; ++i) {
 209             if (literal[i] == '\0') {
 210                 return false;
 211             }
 212         }
 213         return literal[N - 1] == '\0';
 214     }
 215 #if defined LIBO_INTERNAL_ONLY
 216     constexpr
 217 #endif
 218     static char const * toPointer(char const (& literal)[N]) { return literal; }
 219 };
 220
 221 #if defined(__COVERITY__)
 222 //to silence over zealous warnings that the loop is logically dead
 223 //for the single char case
 224 template< typename T >
 225 struct ConstCharArrayDetector< const char[ 1 ], T >
 226 {
 227     typedef T Type;
 228     static const std::size_t length = 0;
 229     static const bool ok = true;
 230 #if defined LIBO_INTERNAL_ONLY
 231     constexpr
 232 #endif
 233     static bool isValid(char const (& literal)[1]) {
 234         return literal[0] == '\0';
 235     }
 236 #if defined LIBO_INTERNAL_ONLY
 237     constexpr
 238 #endif
 239     static char const * toPointer(char const (& literal)[1]) { return literal; }
 240 };
 241 #endif
 242
 243 #if defined LIBO_INTERNAL_ONLY && defined __cpp_char8_t
 244 template<std::size_t N, typename T>
 245 struct ConstCharArrayDetector<char8_t const [N], T> {
 246     using Type = T;
 247     static constexpr bool const ok = true;
 248     static constexpr std::size_t const length = N - 1;
 249     static constexpr bool isValid(char8_t const (& literal)[N]) {
 250         for (std::size_t i = 0; i != N - 1; ++i) {
 251             if (literal[i] == u8'\0') {
 252                 return false;
 253             }
 254         }
 255         return literal[N - 1] == u8'\0';
 256     }
 257     static constexpr char const * toPointer(char8_t const (& literal)[N])
 258     { return reinterpret_cast<char const *>(literal); }
 259 };
 260 #endif
 261
 262 #if defined LIBO_INTERNAL_ONLY
 263 template<std::size_t N, typename T>
 264 struct ConstCharArrayDetector<sal_Unicode const [N], T> {
 265     using TypeUtf16 = T;
 266     static constexpr bool const ok = true;
 267     static constexpr std::size_t const length = N - 1;
 268     static constexpr bool isValid(sal_Unicode const (& literal)[N]) {
 269         for (std::size_t i = 0; i != N - 1; ++i) {
 270             if (literal[i] == '\0') {
 271                 return false;
 272             }
 273         }
 274         return literal[N - 1] == '\0';
 275     }
 276     static constexpr sal_Unicode const * toPointer(
 277         sal_Unicode const (& literal)[N])
 278     { return literal; }
 279 };
 280
 281 #if defined(__COVERITY__)
 282 //to silence over zealous warnings that the loop is logically dead
 283 //for the single char case
 284 template<typename T>
 285 struct ConstCharArrayDetector<sal_Unicode const [1], T> {
 286     using TypeUtf16 = T;
 287     static constexpr bool const ok = true;
 288     static constexpr std::size_t const length = 0;
 289     static constexpr bool isValid(sal_Unicode const (& literal)[1]) {
 290         return literal[0] == '\0';
 291     }
 292     static constexpr sal_Unicode const * toPointer(
 293         sal_Unicode const (& literal)[1])
 294     { return literal; }
 295 };
 296 #endif
 297
 298 template<typename T> struct ConstCharArrayDetector<
 299     OUStringChar,
 300     T>
 301 {
 302     using TypeUtf16 = T;
 303     static constexpr bool const ok = true;
 304     static constexpr std::size_t const length = 1;
 305     static constexpr bool isValid(OUStringChar) { return true; }
 306     static constexpr sal_Unicode const * toPointer(
 307         OUStringChar_ const & literal)
 308     { return &literal.c; }
 309 };
 310 #endif
 311
 312 #if defined LIBO_INTERNAL_ONLY && defined RTL_STRING_UNITTEST
 313
 314 // this one is used to rule out only const char[N]
 315 template< typename T >
 316 struct ExceptConstCharArrayDetector
 317 {
 318     typedef Dummy Type;
 319 };
 320 template< int N >
 321 struct ExceptConstCharArrayDetector< const char[ N ] >
 322 {
 323 };
 324 template<std::size_t N>
 325 struct ExceptConstCharArrayDetector<sal_Unicode const[N]> {};
 326 template<> struct ExceptConstCharArrayDetector<
 327     OUStringChar
 328     >
 329 {};
 330
 331 // this one is used to rule out only const char[N]
 332 // (const will be brought in by 'const T&' in the function call)
 333 // msvc needs const char[N] here (not sure whether gcc or msvc
 334 // are right, it doesn't matter).
 335 template< typename T >
 336 struct ExceptCharArrayDetector
 337 {
 338     typedef Dummy Type;
 339 };
 340 template< int N >
 341 struct ExceptCharArrayDetector< char[ N ] >
 342 {
 343 };
 344 template< int N >
 345 struct ExceptCharArrayDetector< const char[ N ] >
 346 {
 347 };
 348 template<std::size_t N> struct ExceptCharArrayDetector<sal_Unicode[N]> {};
 349 template<std::size_t N> struct ExceptCharArrayDetector<sal_Unicode const[N]> {};
 350 template<> struct ExceptCharArrayDetector<OUStringChar_> {};
 351
 352 #endif
 353
 354 template< typename T1, typename T2 = void >
 355 struct SalUnicodePtrDetector
 356 {
 357     static const bool ok = false;
 358 };
 359 template< typename T >
 360 struct SalUnicodePtrDetector< const sal_Unicode*, T >
 361 {
 362     typedef T Type;
 363     static const bool ok = true;
 364 };
 365 template< typename T >
 366 struct SalUnicodePtrDetector< sal_Unicode*, T >
 367 {
 368     typedef T Type;
 369     static const bool ok = true;
 370 };
 371
 372 // SFINAE helper class
 373 template< typename T, bool >
 374 struct Enable
 375     {
 376     };
 377
 378 template< typename T >
 379 struct Enable< T, true >
 380     {
 381     typedef T Type;
 382     };
 383
 384
 385 } /* Namespace */
 386
 387 } /* Namespace */
 388
 389 #endif // INCLUDED_RTL_STRINGUTILS_HXX
 390
 391 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */