NCBI C++ ToolKit
ncbistr.hpp
Go to the documentation of this file.

Go to the repository for this file.

1 #ifndef CORELIB___NCBISTR__HPP
2 #define CORELIB___NCBISTR__HPP
3 
4 /* $Id: ncbistr.hpp 107542 2026-09-28 14:19:59Z ivanov $
5  * ===========================================================================
6  *
7  * PUBLIC DOMAIN NOTICE
8  * National Center for Biotechnology Information
9  *
10  * This software/database is a "United States Government Work" under the
11  * terms of the United States Copyright Act. It was written as part of
12  * the author's official duties as a United States Government employee and
13  * thus cannot be copyrighted. This software/database is freely available
14  * to the public for use. The National Library of Medicine and the U.S.
15  * Government have not placed any restriction on its use or reproduction.
16  *
17  * Although all reasonable efforts have been taken to ensure the accuracy
18  * and reliability of the software and data, the NLM and the U.S.
19  * Government do not and cannot warrant the performance or results that
20  * may be obtained by using this software or data. The NLM and the U.S.
21  * Government disclaim all warranties, express or implied, including
22  * warranties of performance, merchantability or fitness for any particular
23  * purpose.
24  *
25  * Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Authors: Eugene Vasilchenko, Denis Vakatov
30  *
31  *
32  */
33 
34 /// @file ncbistr.hpp
35 /// The NCBI C++ standard methods for dealing with std::string
36 
37 
38 #include <corelib/ncbi_limits.hpp>
39 #include <corelib/tempstr.hpp>
40 #include <corelib/ncbierror.hpp>
41 #ifdef NCBI_OS_OSF1
42 # include <strings.h>
43 #endif
44 #include <stdarg.h>
45 #include <time.h>
46 #include <set>
47 #include <functional>
48 
49 
51 
52 /** @addtogroup String
53  *
54  * @{
55  */
56 
57 /// Empty "C" string (points to a '\0').
58 NCBI_XNCBI_EXPORT extern const char *const kEmptyCStr;
59 #define NcbiEmptyCStr ncbi::kEmptyCStr
60 
61 #if defined(HAVE_WSTRING)
62 NCBI_XNCBI_EXPORT extern const wchar_t *const kEmptyWCStr;
63 #define NcbiEmptyWCStr ncbi::kEmptyWCStr
64 #endif
65 
66 /// Empty "C++" string.
68 {
69 public:
70  /// Get string.
71  inline
72  static const string& Get(void)
73  {
74  static string empty_str;
75  return empty_str;
76  }
77 };
78 #if defined(HAVE_WSTRING)
80 {
81 public:
82  /// Get string.
83  static const wstring& Get(void)
84  {
85  static wstring empty_str;
86  return empty_str;
87  }
88 };
89 #endif
90 
91 
92 #define NcbiEmptyString ncbi::CNcbiEmptyString::Get()
93 #define kEmptyStr NcbiEmptyString
94 
95 #if defined(HAVE_WSTRING)
96 # define NcbiEmptyWString ncbi::CNcbiEmptyWString::Get()
97 # define kEmptyWStr NcbiEmptyWString
98 #endif
99 
100 // SIZE_TYPE and NPOS
101 
102 typedef std::string::size_type SIZE_TYPE;
103 #define NPOS std::string::npos
104 
105 
106 
107 /////////////////////////////////////////////////////////////////////////////
108 // Unicode-related definitions and conversions
109 
110 /// Unicode character
111 typedef char32_t TUnicodeSymbol;
112 /// Unicode string
113 typedef basic_string<TUnicodeSymbol> TStringUnicode;
114 
115 #if defined(NCBI_OS_MSWIN) && defined(_UNICODE)
116 
117 typedef wchar_t TXChar;
118 typedef wstring TXString;
119 
120 # if !defined(_TX)
121 # define _TX(x) L ## x
122 # endif
123 
124 # if defined(_DEBUG)
125 # define _T_XSTRING(x) \
126  ncbi::CUtf8::AsBasicString<ncbi::TXChar>(x, NULL, ncbi::CUtf8::eValidate)
127 # else
128 # define _T_XSTRING(x) \
129  ncbi::CUtf8::AsBasicString<ncbi::TXChar>(x, NULL, ncbi::CUtf8::eNoValidate)
130 # endif
131 # define _T_STDSTRING(x) ncbi::CUtf8::AsUTF8(x)
132 # define _T_XCSTRING(x) _T_XSTRING(x).c_str()
133 # define _T_CSTRING(x) _T_STDSTRING(x).c_str()
134 
135 # define NcbiEmptyXCStr NcbiEmptyWCStr
136 # define NcbiEmptyXString NcbiEmptyWString
137 # define kEmptyXStr kEmptyWStr
138 # define kEmptyXCStr kEmptyWCStr
139 
140 #else
141 
142 typedef char TXChar;
143 typedef string TXString;
144 
145 # if !defined(_TX)
146 # define _TX(x) x
147 # endif
148 
149 # define _T_XSTRING(x) (x)
150 # define _T_STDSTRING(x) (x)
151 # define _T_XCSTRING(x) ncbi::impl_ToCString(x)
152 # define _T_CSTRING(x) (x)
153 
154 # define NcbiEmptyXCStr NcbiEmptyCStr
155 # define NcbiEmptyXString NcbiEmptyString
156 # define kEmptyXStr kEmptyStr
157 # define kEmptyXCStr kEmptyCStr
158 
159 inline const char* impl_ToCString(const char* s) { return s; }
160 inline const char* impl_ToCString(const string& s) { return s.c_str(); }
161 
162 #endif
163 
164 
165 /////////////////////////////////////////////////////////////////////////////
166 ///
167 
168 #if defined(NCBI_CUTF8_ENCODING_CLASSIC) || !defined(HAVE_ENUM_CLASS)
169 enum EEncoding {
173  eEncoding_ISO8859_1, ///< Note: From the point of view of the C++
174  ///< Toolkit, the ISO 8859-1 character set includes
175  ///< symbols 0x00 through 0xFF except 0x80 through
176  ///< 0x9F.
179 };
180 #else
181 // Temporary safeguard to protect against implicit conversion of EEncoding
182 // to size_t, etc
183 // @attention Do not use "EEncoding::Xxx" values directly, as they will go
184 // away eventually! Use the "eEncoding_Xxx" values instead.
185 enum class EEncoding {
186  Unknown, ///< Do not use this directly! It will go away eventually!
187  UTF8, ///< Do not use this directly! It will go away eventually!
188  Ascii, ///< Do not use this directly! It will go away eventually!
189  ISO8859_1, ///< Do not use this directly! It will go away eventually!
190  Windows_1252, ///< Do not use this directly! It will go away eventually!
191  // CESU-8 spec https://www.unicode.org/reports/tr26/tr26-4.html
192  // It is not intended nor recommended for open information exchange.
193  // but since it may appear in incoming data, we want to be able to detect it
194  // and convert into 'normal' UTF-8
195  CESU8
196 };
197 #define eEncoding_Unknown EEncoding::Unknown
198 #define eEncoding_UTF8 EEncoding::UTF8
199 #define eEncoding_Ascii EEncoding::Ascii
200 #define eEncoding_ISO8859_1 EEncoding::ISO8859_1
201 #define eEncoding_Windows_1252 EEncoding::Windows_1252
202 #define eEncoding_CESU8 EEncoding::CESU8
203 #endif
204 
205 
206 /////////////////////////////////////////////////////////////////////////////
207 ///
208 /// NStr --
209 ///
210 /// Encapsulates class-wide string processing functions.
211 
213 {
214 public:
215  /// Number to string conversion flags.
216  ///
217  /// NOTE:
218  /// If specified base in the *ToString() methods is not default 10,
219  /// that some flags like fWithSign and fWithCommas will be ignored.
221  fUseLowercase = (1 << 4), ///< Use lowercase letters for string representation for bases above 10
222  fWithRadix = (1 << 5), ///< Prefix the output value with radix for "well-known" bases like 8 ("0") and 16 ("0x")
223  fWithSign = (1 << 6), ///< Prefix the output value with a sign ('+'/'-')
224  fWithCommas = (1 << 7), ///< Use commas as thousands separator
225  fDoubleFixed = (1 << 8), ///< DoubleToString*(): Use n.nnnn format for double conversions
226  fDoubleScientific = (1 << 9), ///< DoubleToString*(): Use scientific format for double conversions
227  fDoublePosix = (1 << 10), ///< DoubleToString*(): Use C locale for double conversions
228  fDoubleGeneral = fDoubleFixed | fDoubleScientific,
229  // Additional flags to convert "software" qualifiers (see UInt8ToString_DataSize)
230  fDS_Binary = (1 << 11), ///< UInt8ToString_DataSize(): Use 1024 as a kilobyte factor, not 1000.
231  fDS_NoDecimalPoint = (1 << 12), ///< UInt8ToString_DataSize(): Do not add a decimal point ("10KB" vs "10.0KB")
232  fDS_PutSpaceBeforeSuffix = (1 << 13), ///< UInt8ToString_DataSize(): Add space between value and qualifiers, like "10.0 KB"
233  fDS_ShortSuffix = (1 << 14), ///< UInt8ToString_DataSize(): Use short suffix, like "10.0K"
234  fDS_PutBSuffixToo = (1 << 15) ///< UInt8ToString_DataSize(): Use "B" suffix for small bytes values.
235  };
236  typedef int TNumToStringFlags; ///< Bitwise OR of "ENumToStringFlags"
237 
238  /// String to number conversion flags.
240  /// Do not throw an exception on error.
241  /// Could be used with methods throwing an exception by default, ignored otherwise.
242  /// Just return zero and set errno to non-zero instead of throwing an exception.
243  /// We recommend the following technique to check against errors
244  /// with minimum overhead when this flag is used:
245  /// @code
246  /// if (!retval && errno != 0)
247  /// ERROR;
248  /// @endcode
249  /// And for StringToDouble*() variants:
250  /// @code
251  /// if (retval == HUGE_VAL || retval == -HUGE_VAL ||
252  /// !retval && errno != 0)
253  /// ERROR;
254  /// @endcode
255  fConvErr_NoThrow = (1 << 0),
256  /*
257  fConvErr_NoErrno = (1 << 1), ///< Do not set errno at all.
258  ///< If used together with fConvErr_NoThrow flag
259  ///< returns 0 on error (-1 for StringToNonNegativeInt).
260  */
261  fConvErr_NoErrMessage = (1 << 2), ///< Set errno, but do not set CNcbiError message on error
262  fMandatorySign = (1 << 17), ///< Check on mandatory sign. See 'ENumToStringFlags::fWithSign'.
263  fAllowCommas = (1 << 18), ///< Allow commas. See 'ENumToStringFlags::fWithCommas'.
264  fAllowLeadingSpaces = (1 << 19), ///< Ignore leading whitespace characters in converted string.
265  fAllowLeadingSymbols = (1 << 20) | fAllowLeadingSpaces,
266  ///< Ignore leading non-numeric characters.
267  fAllowTrailingSpaces = (1 << 21), ///< Ignore trailing whitespace characters.
268  fAllowTrailingSymbols = (1 << 22) | fAllowTrailingSpaces,
269  ///< Ignore trailing non-numerics characters.
270  fDecimalPosix = (1 << 23), ///< StringToDouble*(): For decimal point, use C locale.
271  fDecimalPosixOrLocal = (1 << 24), ///< StringToDouble*(): For decimal point, try both C and current locale.
272  fDecimalPosixFinite = (1 << 25), ///< StringToDouble*(): Keep result finite and normalized:
273  ///< if DBL_MAX < result < INF, result becomes DBL_MAX
274  ///< if 0 < result < DBL_MIN, result becomes DBL_MIN
275  // Additional flags to convert "software" qualifiers (see StringToUInt8_DataSize)
276  fDS_ForceBinary = (1 << 26), ///< StringToUInt8_DataSize(): Use 1024 as a kilobyte factor regardless of suffix, like "KB" or "KiB".
277  fDS_ProhibitFractions = (1 << 27), ///< StringToUInt8_DataSize(): Ignore any fraction part of a value, "1.2K" ~ "1K"
278  fDS_ProhibitSpaceBeforeSuffix = (1 << 28) ///< StringToUInt8_DataSize(): Do not allow spaces between value and suffix, like "10 K".
279  };
280  typedef EStringToNumFlags EConvErrFlags; ///< Formerly split out
281  typedef int TStringToNumFlags; ///< Bitwise OR of "EStringToNumFlags"
282  typedef TStringToNumFlags TConvErrFlags; ///< Formerly split out
283 
284  /// Convert string to a numeric value.
285  ///
286  /// @param str
287  /// String to be converted.
288  /// @param flags
289  /// Optional flags to tune up how the string is converted to value.
290  /// @param base
291  /// Radix base. Allowed values are 0, 2..36. Zero means to use the
292  /// first characters to determine the base - a leading "0x" or "0X"
293  /// means base 16; otherwise a leading 0 means base 8; otherwise base 10.
294  /// @return
295  /// - If conversion succeeds, set errno to zero and return the
296  /// converted value.
297  /// - Otherwise, if fConvErr_NoThrow is not set, throw an exception.
298  /// - Otherwise, set errno to non-zero and return zero.
299  template <typename TNumeric>
300  static TNumeric StringToNumeric(const CTempString str,
302  int base = 10)
303  {
304  return x_StringToNumeric<TNumeric>(str, flags, base);
305  }
306 
307  /// Convert string to a numeric value.
308  ///
309  /// @param str [in]
310  /// String to be converted.
311  /// @param value [out]
312  /// The numeric value represented by "str". Zero on any error.
313  /// @param flags [in]
314  /// Optional flags to tune up how the string is converted to value.
315  /// @param base [in]
316  /// Radix base. Allowed values are 0, 2..36. Zero means to use the
317  /// first characters to determine the base - a leading "0x" or "0X"
318  /// means base 16; otherwise a leading 0 means base 8; otherwise base 10.
319  /// @return
320  /// - If conversion succeeds, set errno to zero, set the value, and
321  /// return true.
322  /// - Otherwise, if fConvErr_NoThrow is not set, throw an exception.
323  /// - Otherwise, set errno to non-zero, set the value to zero, and
324  /// return false.
325  template <typename TNumeric>
326  static bool StringToNumeric(const CTempString str,
327  TNumeric* value, /*[out]*/
329  int base = 10)
330  {
331  return x_StringToNumeric(str, value, flags, base);
332  }
333 
334  /// Convert string to non-negative integer value.
335  ///
336  /// @param str
337  /// String containing only digits, representing non-negative
338  /// decimal value in the int range: [0..kMax_Int].
339  /// @param flags
340  /// How to convert string to value.
341  /// Only fConvErr_NoErrMessage flag is supported here.
342  /// @return
343  /// - If conversion succeeds, set errno to zero and return the converted value.
344  /// - Otherwise, set errno to non-zero and return -1.
345  static int StringToNonNegativeInt(const CTempString str, TStringToNumFlags flags = 0);
346 
347  /// @deprecated
348  /// Use template-based StringToNumeric<> or StringToNonNegativeInt() instead.
350  static int StringToNumeric(const string& str)
351  {
352  return StringToNonNegativeInt(str);
353  }
354 
355  /// Convert string to int.
356  ///
357  /// @param str
358  /// String to be converted.
359  /// @param flags
360  /// How to convert string to value.
361  /// @param base
362  /// Radix base. Allowed values are 0, 2..36. Zero means to use the
363  /// first characters to determine the base - a leading "0x" or "0X"
364  /// means base 16; otherwise a leading 0 means base 8; otherwise base 10.
365  /// @return
366  /// - If conversion succeeds, set errno to zero and return the
367  /// converted value.
368  /// - Otherwise, if fConvErr_NoThrow is not set, throw an exception.
369  /// - Otherwise, set errno to non-zero and return zero.
370  static int StringToInt(const CTempString str,
371  TStringToNumFlags flags = 0,
372  int base = 10);
373 
374  /// Convert string to unsigned int.
375  ///
376  /// @param str
377  /// String to be converted.
378  /// @param flags
379  /// How to convert string to value.
380  /// @param base
381  /// Radix base. Allowed values are 0, 2..36. Zero means to use the
382  /// first characters to determine the base - a leading "0x" or "0X"
383  /// means base 16; otherwise a leading 0 means base 8; otherwise base 10.
384  /// @return
385  /// - If conversion succeeds, set errno to zero and return the
386  /// converted value.
387  /// - Otherwise, if fConvErr_NoThrow is not set, throw an exception.
388  /// - Otherwise, set errno to non-zero and return zero.
389  static unsigned int StringToUInt(const CTempString str,
390  TStringToNumFlags flags = 0,
391  int base = 10);
392 
393  /// Convert string to long.
394  ///
395  /// @param str
396  /// String to be converted.
397  /// @param flags
398  /// How to convert string to value.
399  /// @param base
400  /// Radix base. Allowed values are 0, 2..36. Zero means to use the
401  /// first characters to determine the base - a leading "0x" or "0X"
402  /// means base 16; otherwise a leading 0 means base 8; otherwise base 10.
403  /// @return
404  /// - If conversion succeeds, set errno to zero and return the
405  /// converted value.
406  /// - Otherwise, if fConvErr_NoThrow is not set, throw an exception.
407  /// - Otherwise, set errno to non-zero and return zero.
408  static long StringToLong(const CTempString str,
409  TStringToNumFlags flags = 0,
410  int base = 10);
411 
412  /// Convert string to unsigned long.
413  ///
414  /// @param str
415  /// String to be converted.
416  /// @param flags
417  /// How to convert string to value.
418  /// @param base
419  /// Radix base. Allowed values are 0, 2..36. Zero means to use the
420  /// first characters to determine the base - a leading "0x" or "0X"
421  /// means base 16; otherwise a leading 0 means base 8; otherwise base 10.
422  /// @return
423  /// - If conversion succeeds, set errno to zero and return the
424  /// converted value.
425  /// - Otherwise, if fConvErr_NoThrow is not set, throw an exception.
426  /// - Otherwise, set errno to non-zero and return zero.
427  static unsigned long StringToULong(const CTempString str,
428  TStringToNumFlags flags = 0,
429  int base = 10);
430 
431  /// Convert string to double-precision value (analog of strtod function)
432  ///
433  /// @param str
434  /// String to be converted.
435  /// @param endptr
436  /// Pointer to character that stops scan.
437  /// @return
438  /// Double-precision value.
439  /// This function always uses dot as decimal separator.
440  /// - on overflow, it returns HUGE_VAL and sets errno to ERANGE;
441  /// - on underflow, it returns 0 and sets errno to ERANGE;
442  /// - if conversion was impossible, it returns 0 and sets errno.
443  /// Also, when input string equals (case-insensitive) to
444  /// - "NAN", the function returns NaN;
445  /// - "INF" or "INFINITY", the function returns HUGE_VAL;
446  /// - "-INF" or "-INFINITY", the function returns -HUGE_VAL;
447  /// @note
448  /// - If conversion succeeds, set errno to zero and return the
449  /// converted value.
450  /// - Otherwise, set errno to non-zero and return zero.
451  /// - Denormal or infinite results are considered successful conversion.
452  /// - To enforce finite and normalized result, use fDecimalPosixFinite flag.
453  /// - This function is meant to be more "low-level" than other
454  /// StringToXxx functions - for example, it allows trailing characters
455  /// (and doesn't include a flags parameter for tweaking such behavior).
456  /// This could result in strings like "nanosecond" being converted to
457  /// NaN, "-inf=input_file" being converted to -INF, or other unexpected
458  /// behavior. Therefore, please consider using StringToDouble unless
459  /// you specifically need this functionality.
460  static double StringToDoublePosix(const char* str, char** endptr=0,
461  TStringToNumFlags flags=0);
462 
463 
464  /// Convert string to double.
465  ///
466  /// @param str
467  /// String to be converted.
468  /// @param flags
469  /// How to convert string to value.
470  /// Do not support fAllowCommas flag.
471  /// @return
472  /// - If invalid flags are passed, throw an exception.
473  /// - If conversion succeeds, set errno to zero and return the
474  /// converted value.
475  /// - Otherwise, if fConvErr_NoThrow is not set, throw an exception.
476  /// - Otherwise, set errno to non-zero and return zero.
477  /// @note
478  /// - Denormal or infinite results are considered successful conversion.
479  /// - To enforce finite and normalized result, use fDecimalPosixFinite flag.
480  static double StringToDouble(const CTempStringEx str,
481  TStringToNumFlags flags = 0);
482 
483  /// This version accepts zero-terminated string
484  /// @deprecated
485  /// It is unsafe to use this method directly, please use StringToDouble()
486  /// instead.
488  static double StringToDoubleEx(const char* str, size_t size,
489  TStringToNumFlags flags = 0);
490 
491  /// Convert string to Int8.
492  ///
493  /// @param str
494  /// String to be converted.
495  /// @param flags
496  /// How to convert string to value.
497  /// @param base
498  /// Radix base. Allowed values are 0, 2..36. Zero means to use the
499  /// first characters to determine the base - a leading "0x" or "0X"
500  /// means base 16; otherwise a leading 0 means base 8; otherwise base 10.
501  /// @return
502  /// - If conversion succeeds, set errno to zero and return the
503  /// converted value.
504  /// - Otherwise, if fConvErr_NoThrow is not set, throw an exception.
505  /// - Otherwise, set errno to non-zero and return zero.
506  static Int8 StringToInt8(const CTempString str,
507  TStringToNumFlags flags = 0,
508  int base = 10);
509 
510  /// Convert string to Uint8.
511  ///
512  /// @param str
513  /// String to be converted.
514  /// @param flags
515  /// How to convert string to value.
516  /// @param base
517  /// Radix base. Allowed values are 0, 2..36. Zero means to use the
518  /// first characters to determine the base - a leading "0x" or "0X"
519  /// means base 16; otherwise a leading 0 means base 8; otherwise base 10.
520  /// @return
521  /// - If conversion succeeds, set errno to zero and return the
522  /// converted value.
523  /// - Otherwise, if fConvErr_NoThrow is not set, throw an exception.
524  /// - Otherwise, set errno to non-zero and return zero.
525  static Uint8 StringToUInt8(const CTempString str,
526  TStringToNumFlags flags = 0,
527  int base = 10);
528 
529  /// Convert string that can contain "software" qualifiers to Uint8.
530  ///
531  /// String can contain "software" qualifiers: G(giga-), MB(mega-),
532  /// KiB (kibi-) etc.
533  /// Example: 100MB, 1024KiB, 5.7G.
534  /// Meaning of qualifiers depends on flags and by default is 1000-based
535  /// (i.e. K=1000, M=10^6 etc.) except in cases when qualifiers with "iB"
536  /// are used, i.e. KiB=1024, MiB=1024^2 etc. When flags parameter contains
537  /// fDS_ForceBinary then qualifiers without "iB" (i.e. "K" or "MB") will
538  /// also be 1024-based.
539  /// String can contain a decimal fraction (except when fDS_ProhibitFractions
540  /// flag is used), in this case the resultant Uint8 number will be rounded
541  /// to fit into integer value.
542  ///
543  /// @param str
544  /// String to be converted.
545  /// @param flags
546  /// How to convert string to value.
547  /// @return
548  /// - If invalid flags are passed, throw an exception.
549  /// - If conversion succeeds, return the converted value.
550  /// - Otherwise, if fConvErr_NoThrow is not set, throw an exception.
551  /// - Otherwise, set errno to non-zero and return zero.
552  static Uint8 StringToUInt8_DataSize(const CTempString str,
553  TStringToNumFlags flags = 0);
554 
555  /// Convert string to number of bytes.
556  ///
557  /// String can contain "software" qualifiers: MB(megabyte), KB (kilobyte).
558  /// Example: 100MB, 1024KB
559  /// Note the qualifiers are power-of-2 based, aka kibi-, mebi- etc, so that
560  /// 1KB = 1024B (not 1000B), 1MB = 1024KB = 1048576B, etc.
561  ///
562  /// @param str
563  /// String to be converted.
564  /// @param flags
565  /// How to convert string to value.
566  /// @param base
567  /// Numeric base of the number (before the qualifier). Allowed values
568  /// are 0, 2..20. Zero means to use the first characters to determine
569  /// the base - a leading "0x" or "0X" means base 16; otherwise a
570  /// leading 0 means base 8; otherwise base 10.
571  /// The base is limited to 20 to prevent 'K' from being interpreted as
572  /// a digit in the number.
573  /// @return
574  /// - If conversion succeeds, set errno to zero and return the
575  /// converted value.
576  /// - Otherwise, if fConvErr_NoThrow is not set, throw an exception.
577  /// - Otherwise, set errno to non-zero and return zero.
578  /// @deprecated Use StringToUInt8_DataSize(str, flags) instead.
580  static Uint8 StringToUInt8_DataSize(const CTempString str,
581  TStringToNumFlags flags,
582  int base);
583 
584  /// Convert string to size_t.
585  ///
586  /// @param str
587  /// String to be converted.
588  /// @param flags
589  /// How to convert string to value.
590  /// @param base
591  /// Radix base. Allowed values are 0, 2..36. Zero means to use the
592  /// first characters to determine the base - a leading "0x" or "0X"
593  /// means base 16; otherwise a leading 0 means base 8; otherwise base 10.
594  /// @return
595  /// - If conversion succeeds, set errno to zero and return the
596  /// converted value.
597  /// - Otherwise, if fConvErr_NoThrow is not set, throw an exception.
598  /// - Otherwise, set errno to non-zero and return zero.
599  static size_t StringToSizet(const CTempString str,
600  TStringToNumFlags flags = 0,
601  int base = 10);
602 
603  /// Convert string to pointer.
604  ///
605  /// @param str
606  /// String to be converted.
607  /// @param flags
608  /// How to convert string to value.
609  /// Only fConvErr_NoErrMessage flag is supported here.
610  /// @return
611  /// Pointer value corresponding to its string representation.
612  /// - If conversion succeeds, set errno to zero and return the
613  /// converted value.
614  /// - Otherwise, set errno to non-zero and return NULL.
615  static const void* StringToPtr(const CTempStringEx str, TStringToNumFlags flags = 0);
616 
617  /// Convert character to integer.
618  ///
619  /// @param ch
620  /// Character to be converted.
621  /// @return
622  /// Integer (0..15) corresponding to the "ch" as a hex digit.
623  /// Return -1 on error.
624  static int HexChar(char ch);
625 
626  /// Convert numeric value to string.
627  ///
628  /// @param value
629  /// Numeric value to be converted.
630  /// @param flags
631  /// How to convert value to string.
632  /// @param base
633  /// Radix base. Default is 10. Allowed values are 2..36.
634  /// Bases 8 and 16 do not add leading '0' and '0x' accordingly.
635  /// If necessary you should add it yourself.
636  /// If value is float or double type, the parameter is ignored.
637  /// @return
638  /// - If conversion succeeds, set errno to zero and return the
639  /// converted string value.
640  /// - Otherwise, set errno to non-zero and return empty string.
641  template<typename TNumeric>
642  requires std::integral<TNumeric> || std::floating_point<TNumeric> || std::convertible_to<TNumeric, Int8>
643  static string
644  NumericToString(TNumeric value, TNumToStringFlags flags = 0, int base = 10)
645  {
646  string ret;
647  x_NumericToString(ret, value, flags, base);
648  return ret;
649  }
650  template <typename TStrictId>
651  static typename enable_if< is_integral<typename TStrictId::TId>::value && is_member_function_pointer<decltype(&TStrictId::Get)>::value, string>::type
652  NumericToString(TStrictId value, TNumToStringFlags flags = 0, int base = 10)
653  {
654  return NumericToString(value.Get(), flags, base);
655  }
656 
657  /// Convert numeric value to string.
658  ///
659  /// @param out_str
660  /// Output string variable.
661  /// @param value
662  /// Numeric value to be converted.
663  /// @param flags
664  /// How to convert value to string.
665  /// @param base
666  /// Radix base. Default is 10. Allowed values are 2..36.
667  /// Bases 8 and 16 do not add leading '0' and '0x' accordingly.
668  /// If necessary you should add it yourself.
669  /// If value is float or double type, the parameter is ignored.
670  /// @note
671  /// - If conversion succeeds, set errno to zero and return the
672  /// converted string value in 'out_str'.
673  /// - Otherwise, set errno to non-zero, value of 'out_str' is undefined.
674  template<typename TNumeric>
675  static void NumericToString(string& out_str, TNumeric value,
676  TNumToStringFlags flags = 0, int base = 10)
677  {
678  x_NumericToString(out_str, value, flags, base);
679  }
680 
681  /// Convert int to string.
682  ///
683  /// @param value
684  /// Integer value to be converted.
685  /// @param flags
686  /// How to convert value to string.
687  /// @param base
688  /// Radix base. Default is 10. Allowed values are 2..36.
689  /// Bases 8 and 16 do not add leading '0' and '0x' accordingly.
690  /// If necessary you should add it yourself.
691  /// @return
692  /// - If conversion succeeds, set errno to zero and return the
693  /// converted string value.
694  /// - Otherwise, set errno to non-zero and return empty string.
695  static string IntToString(int value, TNumToStringFlags flags = 0,
696  int base = 10);
697 
698  static string IntToString(unsigned int value, TNumToStringFlags flags = 0,
699  int base = 10);
700 
701  /// Convert int to string.
702  ///
703  /// @param out_str
704  /// Output string variable.
705  /// @param value
706  /// Integer value to be converted.
707  /// @param flags
708  /// How to convert value to string.
709  /// @param base
710  /// Radix base. Default is 10. Allowed values are 2..36.
711  /// Bases 8 and 16 do not add leading '0' and '0x' accordingly.
712  /// If necessary you should add it yourself.
713  /// @note
714  /// - If conversion succeeds, set errno to zero and return the
715  /// converted string value in 'out_str'.
716  /// - Otherwise, set errno to non-zero, value of 'out_str' is undefined.
717  static void IntToString(string& out_str, int value,
718  TNumToStringFlags flags = 0,
719  int base = 10);
720 
721  static void IntToString(string& out_str, unsigned int value,
722  TNumToStringFlags flags = 0,
723  int base = 10);
724 
725  /// Convert UInt to string.
726  ///
727  /// @param value
728  /// Integer value (unsigned long) to be converted.
729  /// @param flags
730  /// How to convert value to string.
731  /// @param base
732  /// Radix base. Default is 10. Allowed values are 2..36.
733  /// Bases 8 and 16 do not add leading '0' and '0x' accordingly.
734  /// If necessary you should add it yourself.
735  /// @return
736  /// - If conversion succeeds, set errno to zero and return the
737  /// converted string value.
738  /// - Otherwise, set errno to non-zero and return empty string.
739  static string UIntToString(unsigned int value,
740  TNumToStringFlags flags = 0,
741  int base = 10);
742 
743  static string UIntToString(int value,
744  TNumToStringFlags flags = 0,
745  int base = 10);
746 
747  /// Convert UInt to string.
748  ///
749  /// @param out_str
750  /// Output string variable
751  /// @param value
752  /// Integer value (unsigned long) to be converted.
753  /// @param flags
754  /// How to convert value to string.
755  /// @param base
756  /// Radix base. Default is 10. Allowed values are 2..36.
757  /// Bases 8 and 16 do not add leading '0' and '0x' accordingly.
758  /// If necessary you should add it yourself.
759  /// @note
760  /// - If conversion succeeds, set errno to zero and return the
761  /// converted string value in 'out_str'.
762  /// - Otherwise, set errno to non-zero, value of 'out_str' is undefined.
763  static void UIntToString(string& out_str, unsigned int value,
764  TNumToStringFlags flags = 0,
765  int base = 10);
766 
767  static void UIntToString(string& out_str, int value,
768  TNumToStringFlags flags = 0,
769  int base = 10);
770 
771  /// Convert Int to string.
772  ///
773  /// @param value
774  /// Integer value (long) to be converted.
775  /// @param flags
776  /// How to convert value to string.
777  /// @param base
778  /// Radix base. Default is 10. Allowed values are 2..36.
779  /// Bases 8 and 16 do not add leading '0' and '0x' accordingly.
780  /// If necessary you should add it yourself.
781  /// @return
782  /// - If conversion succeeds, set errno to zero and return the
783  /// converted string value.
784  /// - Otherwise, set errno to non-zero and return empty string.
785  static string LongToString(long value, TNumToStringFlags flags = 0,
786  int base = 10);
787 
788  /// Convert Int to string.
789  ///
790  /// @param out_str
791  /// Output string variable.
792  /// @param value
793  /// Integer value (long) to be converted.
794  /// @param flags
795  /// How to convert value to string.
796  /// @param base
797  /// Radix base. Default is 10. Allowed values are 2..36.
798  /// Bases 8 and 16 do not add leading '0' and '0x' accordingly.
799  /// If necessary you should add it yourself.
800  /// @note
801  /// - If conversion succeeds, set errno to zero and return the
802  /// converted string value in 'out_str'.
803  /// - Otherwise, set errno to non-zero, value of 'out_str' is undefined.
804  static void LongToString(string& out_str, long value,
805  TNumToStringFlags flags = 0,
806  int base = 10);
807 
808  /// Convert unsigned long to string.
809  ///
810  /// @param value
811  /// Integer value (unsigned long) to be converted.
812  /// @param flags
813  /// How to convert value to string.
814  /// @param base
815  /// Radix base. Default is 10. Allowed values are 2..36.
816  /// Bases 8 and 16 do not add leading '0' and '0x' accordingly.
817  /// If necessary you should add it yourself.
818  /// @return
819  /// - If conversion succeeds, set errno to zero and return the
820  /// converted string value.
821  /// - Otherwise, set errno to non-zero and return empty string.
822  static string ULongToString(unsigned long value,
823  TNumToStringFlags flags = 0,
824  int base = 10);
825 
826  /// Convert unsigned long to string.
827  ///
828  /// @param out_str
829  /// Output string variable
830  /// @param value
831  /// Integer value (unsigned long) to be converted.
832  /// @param flags
833  /// How to convert value to string.
834  /// @param base
835  /// Radix base. Default is 10. Allowed values are 2..36.
836  /// Bases 8 and 16 do not add leading '0' and '0x' accordingly.
837  /// If necessary you should add it yourself.
838  /// @note
839  /// - If conversion succeeds, set errno to zero and return the
840  /// converted string value in 'out_str'.
841  /// - Otherwise, set errno to non-zero, value of 'out_str' is undefined.
842  static void ULongToString(string& out_str, unsigned long value,
843  TNumToStringFlags flags = 0,
844  int base = 10);
845 
846  /// Convert Int8 to string.
847  ///
848  /// @param value
849  /// Integer value (Int8) to be converted.
850  /// @param flags
851  /// How to convert value to string.
852  /// @param base
853  /// Radix base. Default is 10. Allowed values are 2..36.
854  /// Bases 8 and 16 do not add leading '0' and '0x' accordingly.
855  /// If necessary you should add it yourself.
856  /// @return
857  /// - If conversion succeeds, set errno to zero and return the
858  /// converted string value.
859  /// - Otherwise, set errno to non-zero and return empty string.
860  static string Int8ToString(Int8 value,
861  TNumToStringFlags flags = 0,
862  int base = 10);
863 
864  /// Convert Int8 to string.
865  ///
866  /// @param out_str
867  /// Output string variable
868  /// @param value
869  /// Integer value (Int8) to be converted.
870  /// @param flags
871  /// How to convert value to string.
872  /// @param base
873  /// Radix base. Default is 10. Allowed values are 2..36.
874  /// Bases 8 and 16 do not add leading '0' and '0x' accordingly.
875  /// If necessary you should add it yourself.
876  /// @note
877  /// - If conversion succeeds, set errno to zero and return the
878  /// converted string value in 'out_str'.
879  /// - Otherwise, set errno to non-zero, value of 'out_str' is undefined.
880  static void Int8ToString(string& out_str, Int8 value,
881  TNumToStringFlags flags = 0,
882  int base = 10);
883 
884  /// Convert UInt8 to string.
885  ///
886  /// @param value
887  /// Integer value (UInt8) to be converted.
888  /// @param flags
889  /// How to convert value to string.
890  /// @param base
891  /// Radix base. Default is 10. Allowed values are 2..36.
892  /// Bases 8 and 16 do not add leading '0' and '0x' accordingly.
893  /// If necessary you should add it yourself.
894  /// @return
895  /// - If conversion succeeds, set errno to zero and return the
896  /// converted string value.
897  /// - Otherwise, set errno to non-zero and return empty string.
898  static string UInt8ToString(Uint8 value,
899  TNumToStringFlags flags = 0,
900  int base = 10);
901 
902  /// Convert UInt8 to string.
903  ///
904  /// @param out_str
905  /// Output string variable
906  /// @param value
907  /// Integer value (UInt8) to be converted.
908  /// @param flags
909  /// How to convert value to string.
910  /// @param base
911  /// Radix base. Default is 10. Allowed values are 2..36.
912  /// Bases 8 and 16 do not add leading '0' and '0x' accordingly.
913  /// If necessary you should add it yourself.
914  /// @note
915  /// - If conversion succeeds, set errno to zero and return the
916  /// converted string value in 'out_str'.
917  /// - Otherwise, set errno to non-zero, value of 'out_str' is undefined.
918  static void UInt8ToString(string& out_str, Uint8 value,
919  TNumToStringFlags flags = 0,
920  int base = 10);
921 
922  /// Convert UInt8 to string using "software" qualifiers.
923  ///
924  /// Result of conversion will be limited to max_digits digits so that e.g.
925  /// 1024 will be converted to 1.02KB. Conversion will be made using
926  /// rounding so that 1025 will be converted to 1.03KB. By default function
927  /// uses 1000-based qualifiers (as in examples above) but with fDS_Binary
928  /// flag it will use 1024-based qualifiers, e.g. 1100 will be converted to
929  /// 1.07KiB. With fDS_ShortSuffix flag function will omit "B" in 1000-based
930  /// and "iB" in 1024-based qualifiers. When the result of conversion doesn't
931  /// need any qualifiers then the result of this function will be equivalent
932  /// to result of UInt8ToString() above except if fDS_PutBSuffixToo flag
933  /// is passed. In the latter case "B" will be added to the number.
934  ///
935  /// Function will always try to use a maximum possible qualifier and
936  /// a number with decimal point except if fDS_NoDecimalPoint flag is passed.
937  /// In that case function will return only whole number and try to use a
938  /// minimum possible qualifier (which makes difference only if
939  /// max_digits > 3).
940  ///
941  /// @param value
942  /// Integer value (UInt8) to be converted.
943  /// @param flags
944  /// How to convert value to string.
945  /// @param max_digits
946  /// Maximum number of digits to use (cannot be less than 3)
947  /// @return
948  /// - If invalid flags are passed, throw an exception.
949  /// - If conversion succeeds, return the converted value.
950  static string UInt8ToString_DataSize(Uint8 value,
951  TNumToStringFlags flags = 0,
952  unsigned int max_digits = 3);
953 
954  /// Convert UInt8 to string using "software" qualifiers.
955  ///
956  /// See notes and details of how function works in the comments to
957  /// UInt8ToString_DataSize() above.
958  ///
959  /// @param out_str
960  /// Output string variable
961  /// @param value
962  /// Integer value (UInt8) to be converted.
963  /// @param flags
964  /// How to convert value to string.
965  /// @param max_digits
966  /// Maximum number of digits to use (cannot be less than 3)
967  static void UInt8ToString_DataSize(string& out_str,
968  Uint8 value,
969  TNumToStringFlags flags = 0,
970  unsigned int max_digits = 3);
971  /// Convert double to string.
972  ///
973  /// @param value
974  /// Double value to be converted.
975  /// @param precision
976  /// Precision value for conversion. If precision is more that maximum
977  /// for current platform, then it will be truncated to this maximum.
978  /// If it is negative, that double will be converted to number in
979  /// scientific notation.
980  /// @param flags
981  /// How to convert value to string.
982  /// If double format flags are not specified, that next output format
983  /// will be used by default:
984  /// - fDoubleFixed, if 'precision' >= 0.
985  /// - fDoubleGeneral, if 'precision' < 0.
986  /// @return
987  /// - If conversion succeeds, set errno to zero and return the
988  /// converted string value.
989  /// - Otherwise, set errno to non-zero and return empty string.
990  static string DoubleToString(double value, int precision = -1,
991  TNumToStringFlags flags = 0);
992 
993  /// Convert double to string.
994  ///
995  /// @param out_str
996  /// Output string variable
997  /// @param value
998  /// Double value to be converted.
999  /// @param precision
1000  /// Precision value for conversion. If precision is more that maximum
1001  /// for current platform, then it will be truncated to this maximum.
1002  /// If it is negative, that double will be converted to number in
1003  /// scientific notation.
1004  /// @param flags
1005  /// How to convert value to string.
1006  /// If double format flags are not specified, that next output format
1007  /// will be used by default:
1008  /// - fDoubleFixed, if 'precision' >= 0.
1009  /// - fDoubleGeneral, if 'precision' < 0.
1010  /// @note
1011  /// - If conversion succeeds, set errno to zero and return the
1012  /// converted string value in 'out_str'.
1013  /// - Otherwise, set errno to non-zero, value of 'out_str' is undefined.
1014  static void DoubleToString(string& out_str, double value,
1015  int precision = -1,
1016  TNumToStringFlags flags = 0);
1017 
1018  /// Convert double to string with specified precision and place the result
1019  /// in the specified buffer.
1020  ///
1021  /// @param value
1022  /// Double value to be converted.
1023  /// @param precision
1024  /// Precision value for conversion. If precision is more that maximum
1025  /// for current platform, then it will be truncated to this maximum.
1026  /// @param buf
1027  /// Put result of the conversion into this buffer.
1028  /// @param buf_size
1029  /// Size of buffer, "buf".
1030  /// @param flags
1031  /// How to convert value to string.
1032  /// Default output format is fDoubleFixed.
1033  /// @return
1034  /// - If conversion succeeds, set errno to zero and return the
1035  /// number of bytes stored in "buf", not counting the
1036  /// terminating '\0'.
1037  /// - Otherwise, set errno to non-zero, value of 'out_str' is undefined.
1038  static SIZE_TYPE DoubleToString(double value, unsigned int precision,
1039  char* buf, SIZE_TYPE buf_size,
1040  TNumToStringFlags flags = 0);
1041 
1042  /// Convert double to string with specified precision and put the result
1043  /// into a character buffer, in scientific format.
1044  ///
1045  /// NOTE:
1046  /// The output character buffer is NOT zero-terminated.
1047  /// The decimal separator is dot, always.
1048  /// This function DOES NOT check 'value' for being finite or not-a-number;
1049  /// if it is, the result is unpredictable.
1050  /// This function is less precise for a small fraction of values
1051  /// (the difference is in the last significant digit) than its
1052  /// 'DoubleToString' siblings, but it is much faster.
1053  ///
1054  /// @param value
1055  /// Double value to be converted.
1056  /// @param precision
1057  /// Maximum number of significant digits to preserve. If precision is greater than
1058  /// maximum for the current platform, it will be truncated to this maximum.
1059  /// @param buf
1060  /// Put result of the conversion into this buffer.
1061  /// @param buf_size
1062  /// Size of buffer, "buf".
1063  /// @return
1064  /// The number of bytes written into "buf".
1065  static SIZE_TYPE DoubleToStringPosix(double value, unsigned int precision,
1066  char* buf, SIZE_TYPE buf_size);
1067 
1068 
1069  /// Convert double to string with specified precision.
1070  ///
1071  /// The result consists of three parts: significant digits, exponent and sign.
1072  /// For example, input value -12345.67 will produce
1073  /// buf = "1234567", *dec = 4, and *sign = -1.
1074  /// NOTE:
1075  /// The output character buffer is NOT zero-terminated.
1076  /// The buffer is NOT padded with zeros.
1077  /// This function DOES NOT check 'value' for being finite or not-a-number;
1078  /// if it is, the result is unpredictable.
1079  /// This function is less precise for a small fraction of values
1080  /// (the difference is in the last significant digit) than its
1081  /// 'DoubleToString' siblings, but it is much faster.
1082  ///
1083  /// @param value
1084  /// Double value to be converted.
1085  /// @param precision
1086  /// Maximum number of significant digits to preserve. If precision is greater than
1087  /// maximum for the current platform, it will be truncated to this maximum.
1088  /// @param buf
1089  /// Put result of the conversion into this buffer.
1090  /// @param buf_size
1091  /// Size of buffer, "buf".
1092  /// @param dec
1093  /// Exponent
1094  /// @param sign
1095  /// Sign of the value
1096  /// @return
1097  /// The number of bytes written into "buf".
1098  static SIZE_TYPE DoubleToString_Ecvt(double value, unsigned int precision,
1099  char* buf, SIZE_TYPE buf_size,
1100  int* dec, int* sign);
1101 
1102  /// Convert size_t to string.
1103  ///
1104  /// @param value
1105  /// Value to be converted.
1106  /// @param flags
1107  /// How to convert value to string.
1108  /// @param base
1109  /// Radix base. Default is 10. Allowed values are 2..36.
1110  /// Bases 8 and 16 do not add leading '0' and '0x' accordingly.
1111  /// If necessary you should add it yourself.
1112  /// @return
1113  /// - If conversion succeeds, set errno to zero and return the
1114  /// converted string value.
1115  /// - Otherwise, set errno to non-zero and return empty string.
1116  static string SizetToString(size_t value,
1117  TNumToStringFlags flags = 0,
1118  int base = 10);
1119 
1120  /// Convert pointer to string.
1121  ///
1122  /// @param out_str
1123  /// Output string variable.
1124  /// @param str
1125  /// Pointer to be converted.
1126  /// @note
1127  /// - If conversion succeeds, set errno to zero and return the
1128  /// converted string value in 'out_str'.
1129  /// - Otherwise, set errno to non-zero, value of 'out_str' is undefined.
1130  static void PtrToString(string& out_str, const void* ptr);
1131 
1132  /// Convert pointer to string.
1133  ///
1134  /// @param str
1135  /// Pointer to be converted.
1136  /// @return
1137  /// - If conversion succeeds, set errno to zero and return the
1138  /// converted string value representing the pointer.
1139  /// - Otherwise, set errno to non-zero and return empty string.
1140  static string PtrToString(const void* ptr);
1141 
1142  /// Convert bool to string.
1143  ///
1144  /// @param value
1145  /// Boolean value to be converted.
1146  /// @return
1147  /// One of: 'true, 'false'
1148  /// @note
1149  /// Don't change errno.
1150  static const string BoolToString(bool value);
1151 
1152  /// Convert string to bool.
1153  ///
1154  /// @param str
1155  /// Boolean string value to be converted. Can recognize
1156  /// case-insensitive version as one of:
1157  /// TRUE - 'true, 't', 'yes', 'y', '1', 'on';
1158  /// FALSE - 'false', 'f', 'no', 'n', '0', 'off'.
1159  /// @return
1160  /// - If conversion succeeds, set errno to zero and return TRUE or FALSE.
1161  /// - Otherwise, set errno to non-zero and throw an exception.
1162  static bool StringToBool(const CTempString str);
1163 
1164 
1165  /// Handle an arbitrary printf-style format string.
1166  ///
1167  /// This method exists only to support third-party code that insists on
1168  /// representing messages in this format; please stick to type-checked
1169  /// means of formatting such as the above ToString methods and I/O
1170  /// streams whenever possible.
1171  static string FormatVarargs(const char* format, va_list args) NCBI_ATTRIBUTE_PRINTF(1, 0);
1172 
1173 
1174  /// Which type of string comparison.
1175  enum ECase {
1176  eCase, ///< Case sensitive compare
1177  eNocase ///< Case insensitive compare
1178  };
1179 
1180  // ATTENTION. Be aware that:
1181  //
1182  // 1) "Compare***(..., SIZE_TYPE pos, SIZE_TYPE n, ...)" functions
1183  // follow the ANSI C++ comparison rules a la "basic_string::compare()":
1184  // s1[pos:pos+n) == s2 --> return 0
1185  // s1[pos:pos+n) < s2 --> return negative value
1186  // s1[pos:pos+n) > s2 --> return positive value
1187  //
1188  // 2) "strn[case]cmp()" functions follow the ANSI C comparison rules:
1189  // s1[0:n) == s2[0:n) --> return 0
1190  // s1[0:n) < s2[0:n) --> return negative value
1191  // s1[0:n) > s2[0:n) --> return positive value
1192 
1193 
1194  /// Case-sensitive compare of a substring with another string.
1195  ///
1196  /// @param s1
1197  /// String containing the substring to be compared.
1198  /// @param pos
1199  /// Start position of substring to be compared.
1200  /// @param n
1201  /// Number of characters in substring to be compared.
1202  /// @param s2
1203  /// String (char*) to be compared with substring.
1204  /// @return
1205  /// - 0, if s1[pos:pos+n) == s2;
1206  /// - Negative integer, if s1[pos:pos+n) < s2;
1207  /// - Positive integer, if s1[pos:pos+n) > s2.
1208  /// @sa
1209  /// Other forms of overloaded CompareCase() with differences in argument
1210  /// types: char* vs. CTempString[Ex]
1211  static int CompareCase(const CTempString s1, SIZE_TYPE pos, SIZE_TYPE n,
1212  const char* s2);
1213 
1214  /// Case-sensitive compare of a substring with another string.
1215  ///
1216  /// @param s1
1217  /// String containing the substring to be compared.
1218  /// @param pos
1219  /// Start position of substring to be compared.
1220  /// @param n
1221  /// Number of characters in substring to be compared.
1222  /// @param s2
1223  /// String to be compared with substring.
1224  /// @return
1225  /// - 0, if s1[pos:pos+n) == s2;
1226  /// - Negative integer, if s1[pos:pos+n) < s2;
1227  /// - Positive integer, if s1[pos:pos+n) > s2.
1228  /// @sa
1229  /// Other forms of overloaded CompareCase() with differences in argument
1230  /// types: char* vs. CTempString[Ex]
1231  static int CompareCase(const CTempString s1, SIZE_TYPE pos, SIZE_TYPE n,
1232  const CTempString s2);
1233 
1234  /// Case-sensitive compare of two strings -- char* version.
1235  ///
1236  /// @param s1
1237  /// String to be compared -- operand 1.
1238  /// @param s2
1239  /// String to be compared -- operand 2.
1240  /// @return
1241  /// - 0, if s1 == s2;
1242  /// - Negative integer, if s1 < s2;
1243  /// - Positive integer, if s1 > s2.
1244  /// @sa
1245  /// CompareNocase(), Compare() versions with same argument types.
1246  static int CompareCase(const char* s1, const char* s2);
1247 
1248  /// Case-sensitive compare of two strings -- CTempStringEx version.
1249  ///
1250  /// @param s1
1251  /// String to be compared -- operand 1.
1252  /// @param s2
1253  /// String to be compared -- operand 2.
1254  /// @return
1255  /// - 0, if s1 == s2;
1256  /// - Negative integer, if s1 < s2;
1257  /// - Positive integer, if s1 > s2.
1258  /// @sa
1259  /// CompareNocase(), Compare() versions with same argument types.
1260  static int CompareCase(const CTempStringEx s1, const CTempStringEx s2);
1261 
1262  /// Case-insensitive compare of a substring with another string.
1263  ///
1264  /// @param s1
1265  /// String containing the substring to be compared.
1266  /// @param pos
1267  /// Start position of substring to be compared.
1268  /// @param n
1269  /// Number of characters in substring to be compared.
1270  /// @param s2
1271  /// String (char*) to be compared with substring.
1272  /// @return
1273  /// - 0, if s1[pos:pos+n) == s2 (case-insensitive compare);
1274  /// - Negative integer, if s1[pos:pos+n) < s2 (case-insensitive compare);
1275  /// - Positive integer, if s1[pos:pos+n) > s2 (case-insensitive compare).
1276  /// @sa
1277  /// Other forms of overloaded CompareNocase() with differences in
1278  /// argument types: char* vs. CTempString[Ex]
1279  static int CompareNocase(const CTempString s1, SIZE_TYPE pos, SIZE_TYPE n,
1280  const char* s2);
1281 
1282  /// Case-insensitive compare of a substring with another string.
1283  ///
1284  /// @param s1
1285  /// String containing the substring to be compared.
1286  /// @param pos
1287  /// Start position of substring to be compared.
1288  /// @param n
1289  /// Number of characters in substring to be compared.
1290  /// @param s2
1291  /// String to be compared with substring.
1292  /// @return
1293  /// - 0, if s1[pos:pos+n) == s2 (case-insensitive compare);
1294  /// - Negative integer, if s1[pos:pos+n) < s2 (case-insensitive compare);
1295  /// - Positive integer, if s1[pos:pos+n) > s2 (case-insensitive compare).
1296  /// @sa
1297  /// Other forms of overloaded CompareNocase() with differences in
1298  /// argument types: char* vs. CTempString[Ex]
1299  static int CompareNocase(const CTempString s1, SIZE_TYPE pos, SIZE_TYPE n,
1300  const CTempString s2);
1301 
1302  /// Case-insensitive compare of two strings -- char* version.
1303  ///
1304  /// @param s1
1305  /// String to be compared -- operand 1.
1306  /// @param s2
1307  /// String to be compared -- operand 2.
1308  /// @return
1309  /// - 0, if s1 == s2 (case-insensitive compare);
1310  /// - Negative integer, if s1 < s2 (case-insensitive compare);
1311  /// - Positive integer, if s1 > s2 (case-insensitive compare).
1312  /// @sa
1313  /// CompareCase(), Compare() versions with same argument types.
1314  static int CompareNocase(const char* s1, const char* s2);
1315 
1316  /// Case-insensitive compare of two strings -- CTempStringEx version.
1317  ///
1318  /// @param s1
1319  /// String to be compared -- operand 1.
1320  /// @param s2
1321  /// String to be compared -- operand 2.
1322  /// @return
1323  /// - 0, if s1 == s2 (case-insensitive compare);
1324  /// - Negative integer, if s1 < s2 (case-insensitive compare);
1325  /// - Positive integer, if s1 > s2 (case-insensitive compare).
1326  /// @sa
1327  /// CompareCase(), Compare() versions with same argument types.
1328  static int CompareNocase(const CTempStringEx s1, const CTempStringEx s2);
1329 
1330  /// Compare of a substring with another string.
1331  ///
1332  /// @param s1
1333  /// String containing the substring to be compared.
1334  /// @param pos
1335  /// Start position of substring to be compared.
1336  /// @param n
1337  /// Number of characters in substring to be compared.
1338  /// @param s2
1339  /// String (char*) to be compared with substring.
1340  /// @param use_case
1341  /// Whether to do a case sensitive compare(eCase -- default), or a
1342  /// case-insensitive compare (eNocase).
1343  /// @return
1344  /// - 0, if s1[pos:pos+n) == s2;
1345  /// - Negative integer, if s1[pos:pos+n) < s2;
1346  /// - Positive integer, if s1[pos:pos+n) > s2.
1347  /// @sa
1348  /// Other forms of overloaded Compare() with differences in argument
1349  /// types: char* vs. CTempString[Ex]
1350  static int Compare(const CTempString s1, SIZE_TYPE pos, SIZE_TYPE n,
1351  const char* s2, ECase use_case = eCase);
1352 
1353  /// Compare of a substring with another string.
1354  ///
1355  /// @param s1
1356  /// String containing the substring to be compared.
1357  /// @param pos
1358  /// Start position of substring to be compared.
1359  /// @param n
1360  /// Number of characters in substring to be compared.
1361  /// @param s2
1362  /// String to be compared with substring.
1363  /// @param use_case
1364  /// Whether to do a case sensitive compare(default is eCase), or a
1365  /// case-insensitive compare (eNocase).
1366  /// @return
1367  /// - 0, if s1[pos:pos+n) == s2;
1368  /// - Negative integer, if s1pos:pos+n) < s2;
1369  /// - Positive integer, if s1[pos:pos+n) > s2.
1370  /// @sa
1371  /// Other forms of overloaded Compare() with differences in argument
1372  /// types: char* vs. CTempString[Ex]
1373  static int Compare(const CTempString s1, SIZE_TYPE pos, SIZE_TYPE n,
1374  const CTempString s2, ECase use_case = eCase);
1375 
1376  /// Compare two strings -- char* version.
1377  ///
1378  /// @param s1
1379  /// String to be compared -- operand 1.
1380  /// @param s2
1381  /// String to be compared -- operand 2.
1382  /// @param use_case
1383  /// Whether to do a case sensitive compare(default is eCase), or a
1384  /// case-insensitive compare (eNocase).
1385  /// @return
1386  /// - 0, if s1 == s2.
1387  /// - Negative integer, if s1 < s2.
1388  /// - Positive integer, if s1 > s2.
1389  /// @sa
1390  /// Other forms of overloaded Compare() with differences in argument
1391  /// types: char* vs. CTempString[Ex]
1392  static int Compare(const char* s1, const char* s2,
1393  ECase use_case = eCase);
1394 
1395  /// Compare two strings -- CTempStringEx version.
1396  ///
1397  /// @param s1
1398  /// String to be compared -- operand 1.
1399  /// @param s2
1400  /// String to be compared -- operand 2.
1401  /// @param use_case
1402  /// Whether to do a case sensitive compare(default is eCase), or a
1403  /// case-insensitive compare (eNocase).
1404  /// @return
1405  /// - 0, if s1 == s2;
1406  /// - Negative integer, if s1 < s2;
1407  /// - Positive integer, if s1 > s2.
1408  /// @sa
1409  /// Other forms of overloaded Compare() with differences in argument
1410  /// types: char* vs. CTempString[Ex]
1411  static int Compare(const CTempStringEx s1, const CTempStringEx s2,
1412  ECase use_case = eCase);
1413 
1414  /// Case-sensitive equality of a substring with another string.
1415  ///
1416  /// @param s1
1417  /// String containing the substring to be compared.
1418  /// @param pos
1419  /// Start position of substring to be compared.
1420  /// @param n
1421  /// Number of characters in substring to be compared.
1422  /// @param s2
1423  /// String (char*) to be compared with substring.
1424  /// @return
1425  /// - true, if s1[pos:pos+n) equals s2;
1426  /// - false, otherwise
1427  /// @sa
1428  /// Other forms of overloaded EqualCase() with differences in argument
1429  /// types: char* vs. CTempString[Ex]
1430  static bool EqualCase(const CTempString s1, SIZE_TYPE pos, SIZE_TYPE n,
1431  const char* s2);
1432 
1433  /// Case-sensitive equality of a substring with another string.
1434  ///
1435  /// @param s1
1436  /// String containing the substring to be compared.
1437  /// @param pos
1438  /// Start position of substring to be compared.
1439  /// @param n
1440  /// Number of characters in substring to be compared.
1441  /// @param s2
1442  /// String to be compared with substring.
1443  /// @return
1444  /// - true, if s1[pos:pos+n) equals s2;
1445  /// - false, otherwise
1446  /// @sa
1447  /// Other forms of overloaded EqualCase() with differences in argument
1448  /// types: char* vs. CTempString[Ex]
1449  static bool EqualCase(const CTempString s1, SIZE_TYPE pos, SIZE_TYPE n,
1450  const CTempString s2);
1451 
1452  /// Case-sensitive equality of two strings -- char* version.
1453  ///
1454  /// @param s1
1455  /// String to be compared -- operand 1.
1456  /// @param s2
1457  /// String to be compared -- operand 2.
1458  /// @return
1459  /// - true, if s1 equals s2
1460  /// - false, otherwise
1461  /// @sa
1462  /// EqualCase(), Equal() versions with same argument types.
1463  static bool EqualCase(const char* s1, const char* s2);
1464 
1465  /// Case-sensitive equality of two strings.
1466  ///
1467  /// @param s1
1468  /// String to be compared -- operand 1.
1469  /// @param s2
1470  /// String to be compared -- operand 2.
1471  /// @return
1472  /// - true, if s1 equals s2
1473  /// - false, otherwise
1474  /// @sa
1475  /// EqualCase(), Equal() versions with same argument types.
1476  static bool EqualCase(const CTempStringEx s1, const CTempStringEx s2);
1477 
1478  /// Case-insensitive equality of a substring with another string.
1479  ///
1480  /// @param s1
1481  /// String containing the substring to be compared.
1482  /// @param pos
1483  /// Start position of substring to be compared.
1484  /// @param n
1485  /// Number of characters in substring to be compared.
1486  /// @param s2
1487  /// String (char*) to be compared with substring.
1488  /// @return
1489  /// - true, if s1[pos:pos+n) equals s2 (case-insensitive compare);
1490  /// - false, otherwise.
1491  /// @sa
1492  /// Other forms of overloaded EqualNocase() with differences in
1493  /// argument types: char* vs. CTempString[Ex]
1494  static bool EqualNocase(const CTempString s1, SIZE_TYPE pos, SIZE_TYPE n,
1495  const char* s2);
1496 
1497  /// Case-insensitive equality of a substring with another string.
1498  ///
1499  /// @param s1
1500  /// String containing the substring to be compared.
1501  /// @param pos
1502  /// Start position of substring to be compared.
1503  /// @param n
1504  /// Number of characters in substring to be compared.
1505  /// @param s2
1506  /// String to be compared with substring.
1507  /// @return
1508  /// - true, if s1[pos:pos+n) equals s2 (case-insensitive compare);
1509  /// - false, otherwise.
1510  /// @sa
1511  /// Other forms of overloaded EqualNocase() with differences in
1512  /// argument types: char* vs. CTempString[Ex]
1513  static bool EqualNocase(const CTempString s1, SIZE_TYPE pos, SIZE_TYPE n,
1514  const CTempString s2);
1515 
1516  /// Case-insensitive equality of two strings -- char* version.
1517  ///
1518  /// @param s1
1519  /// String to be compared -- operand 1.
1520  /// @param s2
1521  /// String to be compared -- operand 2.
1522  /// @return
1523  /// - true, if s1 equals s2 (case-insensitive compare);
1524  /// - false, otherwise.
1525  /// @sa
1526  /// EqualCase(), Equal() versions with same argument types.
1527  static bool EqualNocase(const char* s1, const char* s2);
1528 
1529  /// Case-insensitive equality of two strings.
1530  ///
1531  /// @param s1
1532  /// String to be compared -- operand 1.
1533  /// @param s2
1534  /// String to be compared -- operand 2.
1535  /// @return
1536  /// - true, if s1 equals s2 (case-insensitive compare);
1537  /// - false, otherwise.
1538  /// @sa
1539  /// EqualCase(), Equal() versions with same argument types.
1540  static bool EqualNocase(const CTempStringEx s1, const CTempStringEx s2);
1541 
1542  /// Test for equality of a substring with another string.
1543  ///
1544  /// @param s1
1545  /// String containing the substring to be compared.
1546  /// @param pos
1547  /// Start position of substring to be compared.
1548  /// @param n
1549  /// Number of characters in substring to be compared.
1550  /// @param s2
1551  /// String (char*) to be compared with substring.
1552  /// @param use_case
1553  /// Whether to do a case sensitive compare(eCase -- default), or a
1554  /// case-insensitive compare (eNocase).
1555  /// @return
1556  /// - true, if s1[pos:pos+n) equals s2;
1557  /// - false, otherwise.
1558  /// @sa
1559  /// Other forms of overloaded Equal() with differences in argument
1560  /// types: char* vs. CTempString[Ex]
1561  static bool Equal(const CTempString s1, SIZE_TYPE pos, SIZE_TYPE n,
1562  const char* s2, ECase use_case = eCase);
1563 
1564  /// Test for equality of a substring with another string.
1565  ///
1566  /// @param s1
1567  /// String containing the substring to be compared.
1568  /// @param pos
1569  /// Start position of substring to be compared.
1570  /// @param n
1571  /// Number of characters in substring to be compared.
1572  /// @param s2
1573  /// String to be compared with substring.
1574  /// @param use_case
1575  /// Whether to do a case sensitive compare (default is eCase), or a
1576  /// case-insensitive compare (eNocase).
1577  /// @return
1578  /// - 0, if s1[pos:pos+n) == s2;
1579  /// - Negative integer, if s1[pos:pos+n) < s2;
1580  /// - Positive integer, if s1[pos:pos+n) > s2.
1581  /// @sa
1582  /// Other forms of overloaded Equal() with differences in argument
1583  /// types: char* vs. CTempString[Ex]
1584  static bool Equal(const CTempString s1, SIZE_TYPE pos, SIZE_TYPE n,
1585  const CTempString s2, ECase use_case = eCase);
1586 
1587  /// Test for equality of two strings -- char* version.
1588  ///
1589  /// @param s1
1590  /// String to be compared -- operand 1.
1591  /// @param s2
1592  /// String to be compared -- operand 2.
1593  /// @param use_case
1594  /// Whether to do a case sensitive compare (default is eCase), or a
1595  /// case-insensitive compare (eNocase).
1596  /// @return
1597  /// - 0, if s1 == s2;
1598  /// - Negative integer, if s1 < s2;
1599  /// - Positive integer, if s1 > s2.
1600  /// @sa
1601  /// EqualNocase(), Equal() versions with similar argument types.
1602  static bool Equal(const char* s1, const char* s2,
1603  ECase use_case = eCase);
1604 
1605  /// Test for equality of two strings.
1606  ///
1607  /// @param s1
1608  /// String to be compared -- operand 1.
1609  /// @param s2
1610  /// String to be compared -- operand 2.
1611  /// @param use_case
1612  /// Whether to do a case sensitive compare (default is eCase), or a
1613  /// case-insensitive compare (eNocase).
1614  /// @return
1615  /// - true, if s1 equals s2;
1616  /// - false, otherwise.
1617  /// @sa
1618  /// EqualNocase(), Equal() versions with similar argument types.
1619  static bool Equal(const CTempStringEx s1, const CTempStringEx s2,
1620  ECase use_case = eCase);
1621 
1622  // NOTE. On some platforms, "strn[case]cmp()" can work faster than their
1623  // "Compare***()" counterparts.
1624 
1625  /// String compare.
1626  ///
1627  /// @param s1
1628  /// String to be compared -- operand 1.
1629  /// @param s2
1630  /// String to be compared -- operand 2.
1631  /// @return
1632  /// - 0, if s1 == s2;
1633  /// - Negative integer, if s1 < s2;
1634  /// - Positive integer, if s1 > s2.
1635  /// @sa
1636  /// strncmp(), strcasecmp(), strncasecmp()
1637  static int strcmp(const char* s1, const char* s2);
1638 
1639  /// String compare up to specified number of characters.
1640  ///
1641  /// @param s1
1642  /// String to be compared -- operand 1.
1643  /// @param s2
1644  /// String to be compared -- operand 2.
1645  /// @param n
1646  /// Number of characters in string
1647  /// @return
1648  /// - 0, if s1 == s2;
1649  /// - Negative integer, if s1 < s2;
1650  /// - Positive integer, if s1 > s2.
1651  /// @sa
1652  /// strcmp(), strcasecmp(), strncasecmp()
1653  static int strncmp(const char* s1, const char* s2, size_t n);
1654 
1655  /// Case-insensitive comparison of two zero-terminated strings.
1656  ///
1657  /// @param s1
1658  /// String to be compared -- operand 1.
1659  /// @param s2
1660  /// String to be compared -- operand 2.
1661  /// @return
1662  /// - 0, if s1 == s2;
1663  /// - Negative integer, if s1 < s2;
1664  /// - Positive integer, if s1 > s2.
1665  /// @sa
1666  /// strcmp(), strncmp(), strncasecmp()
1667  static int strcasecmp(const char* s1, const char* s2);
1668 
1669  /// Case-insensitive comparison of two zero-terminated strings,
1670  /// narrowed to the specified number of characters.
1671  ///
1672  /// @param s1
1673  /// String to be compared -- operand 1.
1674  /// @param s2
1675  /// String to be compared -- operand 2.
1676  /// @return
1677  /// - 0, if s1 == s2;
1678  /// - Negative integer, if s1 < s2.
1679  /// - Positive integer, if s1 > s2.
1680  /// @sa
1681  /// strcmp(), strcasecmp(), strcasecmp()
1682  static int strncasecmp(const char* s1, const char* s2, size_t n);
1683 
1684  /// Wrapper for the function strftime() that corrects handling %D and %T
1685  /// time formats on MS Windows.
1686  static size_t strftime(char* s, size_t maxsize, const char* format,
1687  const struct tm* timeptr);
1688 
1689  /// Match "str" against the "mask".
1690  ///
1691  /// This function does not use regular expressions.
1692  /// Very similar to fnmatch(3), but there are differences (see also glob(7)).
1693  /// There's no special treatment for a slash character '/' in this call.
1694  ///
1695  /// @param str
1696  /// String to match.
1697  /// @param mask
1698  /// Mask used to match string "str".
1699  /// This is a text pattern, which, along ordinary characters that must match
1700  /// literally corresponding symbols in the string "str", can contains also
1701  /// mext wildcard characters: \n
1702  /// ? - matches to any single character in the string. \n
1703  /// * - matches to any number of characters in the string (including none). \n
1704  ///
1705  /// Mask also support POSIX character classes in the forms of "[...]" or "[!...]"
1706  /// that must MATCH or NOT MATCH, respectively, a single character in "str".
1707  /// To cancel the special meaning of '*', '?' or '[', they can be prepended with
1708  /// a backslash '\\' (the backslash in front of other characters does not change
1709  /// their meaning, so "\\\\" matches one graphical backslash in the "str").
1710  /// Within a character class, to have its literal meaning a closing square bracket ']'
1711  /// must be used at the first position, whereas '?', '*', '[, and '\\' stand
1712  /// just for themselves. Two characters separated by a minus sign '-' denote
1713  /// a range that can be used for contraction to include all characters in
1714  /// between: "[A-F]" is equivalent to "[ABCDEF]".
1715  /// For its literal meaning, the minus sign '-' can be used either at the very
1716  /// first position, or the last position before the closing bracket ']'.
1717  /// To have a range that begins with an exclamation point, one has to use
1718  /// a dummy empty range followed by that range with '!'.
1719  ///
1720  /// Examples:
1721  /// "!" matches a single '!' (note that just "[!]" is invalid);
1722  /// "[!!]" matches any character, which is not an exclamation point '!';
1723  /// "[][!]" matches ']', '[', and '!';
1724  /// "[!][-]" matches any character except for ']', '[', and '-';
1725  /// "[-]" matches a minus sign '-' (same as '-' just by itself);
1726  /// "[?*\\]" matches either '?', or '*', or a backslash '\\';
1727  /// "[]-\\]" matches nothing as it defines an empty range (from ']' to '\\');
1728  /// "\\[a]\\*" matches a literal substring "[a]*";
1729  /// "[![a-]" matches any char but '[', 'a' or '-' (same as "[!-[a]"; but not
1730  /// "[![-a]", which defines an empty range, thus matches any char!);
1731  /// "[]A]" matches either ']' or 'A' (NB: "[A]]" matches a substring "A]");
1732  /// "[0-9-]" matches any decimal digit or a minus sign '-' (same: "[-0-9]");
1733  /// "[9-0!-$]" matches '!', '"', '#', and '$' (as first range matches nothing).
1734  ///
1735  /// @note
1736  /// In the above, each double backslash denotes a single graphical backslash
1737  /// character (C string notation is used).
1738  /// @note
1739  /// Unlike shell globbing, "[--0]" *does* match the slash character '/'
1740  /// (along with '-', '.', and '0' that all fall within the range).
1741  /// @param use_case
1742  /// Whether to do a case sensitive compare for letters (eCase -- default),
1743  /// or a case-insensitive compare (eNocase).
1744  /// @return
1745  /// Return TRUE if "str" matches "mask", and FALSE otherwise
1746  /// (including patter errors).
1747  /// @sa
1748  /// CRegexp, CRegexpUtil
1749  ///
1750  static bool MatchesMask(CTempString str, CTempString mask, ECase use_case = eCase);
1751 
1752  /// Check if a string is blank (has no text).
1753  ///
1754  /// @param str
1755  /// String to check.
1756  /// @param pos
1757  /// starting position (default 0)
1758  static bool IsBlank(const CTempString str, SIZE_TYPE pos = 0);
1759 
1760  /// Checks if all letters in the given string have a lower case.
1761  ///
1762  /// @param str
1763  /// String to be checked.
1764  /// @return
1765  /// TRUE if all letter characters in the string are lowercase
1766  /// according to the current C locale (std::islower()).
1767  /// All non-letter characters will be ignored.
1768  /// TRUE if empty or no letters.
1769  static bool IsLower(const CTempString str);
1770 
1771  /// Checks if all letters in the given string have a upper case.
1772  ///
1773  /// @param str
1774  /// String to be checked.
1775  /// @return
1776  /// TRUE if all letter characters in the string are uppercase
1777  /// according to the current C locale (std::isupper()).
1778  /// All non-letter characters will be skipped.
1779  /// TRUE if empty or no letters.
1780  static bool IsUpper(const CTempString str);
1781 
1782 
1783  // The following 4 methods change the passed string, then return it
1784 
1785  /// Convert string to lower case -- string& version.
1786  ///
1787  /// @param str
1788  /// String to be converted.
1789  /// @return
1790  /// Lower cased string.
1791  static string& ToLower(string& str);
1792 
1793  /// Convert string to lower case -- char* version.
1794  ///
1795  /// @param str
1796  /// String to be converted.
1797  /// @return
1798  /// Lower cased string.
1799  static char* ToLower(char* str);
1800 
1801  /// Convert string to upper case -- string& version.
1802  ///
1803  /// @param str
1804  /// String to be converted.
1805  /// @return
1806  /// Upper cased string.
1807  static string& ToUpper(string& str);
1808 
1809  /// Convert string to upper case -- char* version.
1810  ///
1811  /// @param str
1812  /// String to be converted.
1813  /// @return
1814  /// Upper cased string.
1815  static char* ToUpper(char* str);
1816 
1817 private:
1818  /// Privatized ToLower() with const char* parameter to prevent passing of
1819  /// constant strings.
1820  static void/*dummy*/ ToLower(const char* /*dummy*/);
1821 
1822  /// Privatized ToUpper() with const char* parameter to prevent passing of
1823  /// constant strings.
1824  static void/*dummy*/ ToUpper(const char* /*dummy*/);
1825 
1826 public:
1827 
1828  /// Check if a string starts with a specified prefix value.
1829  ///
1830  /// @param str
1831  /// String to check.
1832  /// @param start
1833  /// Prefix value to check for.
1834  /// @param use_case
1835  /// Whether to do a case sensitive compare(default is eCase), or a
1836  /// case-insensitive compare (eNocase) while checking.
1837  static bool StartsWith(const CTempString str, const CTempString start,
1838  ECase use_case = eCase);
1839 
1840  /// Check if a string starts with a specified character value.
1841  ///
1842  /// @param str
1843  /// String to check.
1844  /// @param start
1845  /// Character value to check for.
1846  /// @param use_case
1847  /// Whether to do a case sensitive compare(default is eCase), or a
1848  /// case-insensitive compare (eNocase) while checking.
1849  static bool StartsWith(const CTempString str, char start,
1850  ECase use_case = eCase);
1851 
1852  /// Check if a string ends with a specified suffix value.
1853  ///
1854  /// @param str
1855  /// String to check.
1856  /// @param end
1857  /// Suffix value to check for.
1858  /// @param use_case
1859  /// Whether to do a case sensitive compare(default is eCase), or a
1860  /// case-insensitive compare (eNocase) while checking.
1861  static bool EndsWith(const CTempString str, const CTempString end,
1862  ECase use_case = eCase);
1863 
1864  /// Check if a string ends with a specified character value.
1865  ///
1866  /// @param str
1867  /// String to check.
1868  /// @param end
1869  /// Character value to check for.
1870  /// @param use_case
1871  /// Whether to do a case sensitive compare(default is eCase), or a
1872  /// case-insensitive compare (eNocase) while checking.
1873  static bool EndsWith(const CTempString str, char end,
1874  ECase use_case = eCase);
1875 
1876  /// Determine the common prefix of two strings.
1877  ///
1878  /// @param s1
1879  /// String to be compared -- operand 1.
1880  /// @param s2
1881  /// String to be compared -- operand 2.
1882  /// @return
1883  /// The number of characters common to the start of each string.
1884  static SIZE_TYPE CommonPrefixSize(const CTempString s1, const CTempString s2);
1885 
1886  /// Determine the common suffix of two strings.
1887  ///
1888  /// @param s1
1889  /// String to be compared -- operand 1.
1890  /// @param s2
1891  /// String to be compared -- operand 2.
1892  /// @return
1893  /// The number of characters common to the end of each string.
1894  static SIZE_TYPE CommonSuffixSize(const CTempString s1, const CTempString s2);
1895 
1896  /// Determine if the suffix of one string is the prefix of another.
1897  ///
1898  /// @param s1
1899  /// String to be compared -- operand 1.
1900  /// @param s2
1901  /// String to be compared -- operand 2.
1902  /// @return
1903  /// The number of characters common to the end of the first string
1904  /// and the start of the second string.
1905  static SIZE_TYPE CommonOverlapSize(const CTempString s1, const CTempString s2);
1906 
1907 
1908  /// Whether it is the first or last occurrence.
1909  /// @deprecated
1911  eFirst, ///< First occurrence
1912  eLast ///< Last occurrence
1913  };
1914 
1915  /// Search direction for Find() methods.
1916  enum EDirection {
1917  eForwardSearch = 0, ///< Search in a forward direction
1918  eReverseSearch ///< Search in a backward direction
1919  };
1920 
1921 
1922  /// Find the pattern in the string.
1923  ///
1924  /// @param str
1925  /// String to search.
1926  /// @param pattern
1927  /// Pattern to search for in "str".
1928  /// @param use_case
1929  /// Whether to do a case sensitive compare (default is eCase), or a
1930  /// case-insensitive compare (eNocase) while searching for the pattern.
1931  /// @param direction
1932  /// Define a search direction of the requested "occurrence"
1933  /// of "pattern" in "str".
1934  /// @param occurrence
1935  /// Which occurrence of the pattern in the string to use (zero-based).
1936  /// NOTE: When an occurrence is found the next occurrence will be
1937  /// searched for starting right *after* the found pattern.
1938  /// @return
1939  /// Start of the found pattern in the string.
1940  /// Or NPOS if there is no occurrence of the pattern in the string.
1941  static SIZE_TYPE Find(const CTempString str,
1942  const CTempString pattern,
1943  ECase use_case = eCase,
1944  EDirection direction = eForwardSearch,
1945  SIZE_TYPE occurrence = 0);
1946 
1947  /// Find the pattern in the specified range of a string.
1948  ///
1949  /// @param str
1950  /// String to search.
1951  /// @param pattern
1952  /// Pattern to search for in "str".
1953  /// @param start
1954  /// Position in "str" to start search from.
1955  /// 0 means start the search from the beginning of the string.
1956  /// @param end
1957  /// Position in "str" to perform search up to.
1958  /// NPOS means to search to the end of the string.
1959  /// @param which
1960  /// When set to eFirst, this means to find the first occurrence of
1961  /// "pattern" in "str". When set to eLast, this means to find the last
1962  /// occurrence of "pattern" in "str".
1963  /// @param use_case
1964  /// Whether to do a case sensitive compare (default is eCase), or a
1965  /// case-insensitive compare (eNocase) while searching for the pattern.
1966  /// @return
1967  /// - The start of the first or last (depending on "which" parameter)
1968  /// occurrence of "pattern" in "str", within the string interval
1969  /// ["start", "end"], or
1970  /// - NPOS if there is no occurrence of the pattern.
1971  /// @sa FindCase, FindNoCase, FindWord
1972  ///
1973  /// @deprecated
1974  /// Use
1975  /// @code
1976  /// Find(str, pattern, [use_case], [direction], [occurrence])
1977  /// @endcode
1978  /// method instead.
1979  /// For example:
1980  /// @code
1981  /// Find(str, pattern, 0, NPOS, eLast, eCase)
1982  /// @endcode
1983  /// can be replaced by
1984  /// @code
1985  /// Find(str, pattern, eCase, eReverseSearch, /* 0 */)
1986  /// @endcode
1987  /// If you doing a search on a substring of the 'str' and ["start", "end"] search
1988  /// interval is not a default [0, NPOS], that mean a whole 'str' string, you may
1989  /// need to pass a substring instead of 'str', like
1990  /// @code
1991  /// Find(CTempString(str, start, len), pattern, ....)
1992  /// @endcode
1993  /// and after checking search result on NPOS, adjust it by 'start' yourself.
1995  static SIZE_TYPE Find(const CTempString str,
1996  const CTempString pattern,
1997  SIZE_TYPE start, SIZE_TYPE end,
1998  EOccurrence which = eFirst,
1999  ECase use_case = eCase);
2000 
2001  /// Wrapper for backward-compatibility
2002  inline
2003  static SIZE_TYPE Find(const CTempString str, const CTempString pattern, SIZE_TYPE start)
2004  { return FindCase(str, pattern, start); }
2005 
2006 
2007  /// Find the pattern in the specified range of a string using a case
2008  /// sensitive search.
2009  ///
2010  /// @param str
2011  /// String to search.
2012  /// @param pattern
2013  /// Pattern to search for in "str".
2014  /// @param start
2015  /// Position in "str" to start search from -- default of 0 means start
2016  /// the search from the beginning of the string.
2017  /// @param end
2018  /// Position in "str" to perform search up to -- default of NPOS means
2019  /// to search to the end of the string.
2020  /// @param which
2021  /// When set to eFirst, this means to find the first occurrence of
2022  /// "pattern" in "str". When set to eLast, this means to find the last
2023  /// occurrence of "pattern" in "str".
2024  /// @return
2025  /// - The start of the first or last (depending on "which" parameter)
2026  /// occurrence of "pattern" in "str", within the string interval
2027  /// ["start", "end"], or
2028  /// - NPOS if there is no occurrence of the pattern.
2029  /// @sa Find
2030  ///
2031  /// @deprecated
2032  /// Use Find() method without [start:end] range.
2033  /// @deprecated
2034  /// Use one of the next methods instead:
2035  /// @code
2036  /// Find(str, pattern, [use_case], [direction], [occurrence])
2037  /// FindCase(str, pattern, [start])
2038  /// @endcode
2039  /// For example:
2040  /// @code
2041  /// FindCase(str, pattern, 0, NPOS, eLast)
2042  /// @endcode
2043  /// can be replaced by
2044  /// @code
2045  /// Find(str, pattern, eCase, eReverseSearch, /* 0 */)
2046  /// @endcode
2047  /// For simpler cases without range, or with default [0, NPOS] please use
2048  /// @code
2049  /// FindCase(str, pattern, [start])
2050  /// @endcode
2051  /// But if you doing a search on a substring of the 'str' and ["start", "end"] search
2052  /// interval is not a default [0, NPOS], that mean a whole 'str' string, you may
2053  /// need to pass a substring instead of 'str', like
2054  /// @code
2055  /// FindCase(CTempString(str, start, len), pattern, ....)
2056  /// @endcode
2057  /// and after checking search result on NPOS, adjust it by 'start' yourself.
2059  static SIZE_TYPE FindCase(const CTempString str,
2060  const CTempString pattern,
2061  SIZE_TYPE start, SIZE_TYPE end,
2062  EOccurrence which = eFirst);
2063 
2064  /// Wrappers for backward-compatibility
2065  static SIZE_TYPE FindCase(const CTempString str, const CTempString pattern);
2066  static SIZE_TYPE FindCase(const CTempString str, const CTempString pattern, SIZE_TYPE start);
2067 
2068  /// Find the pattern in the specified range of a string using a case
2069  /// insensitive search.
2070  ///
2071  /// @param str
2072  /// String to search.
2073  /// @param pattern
2074  /// Pattern to search for in "str".
2075  /// @param start
2076  /// Position in "str" to start search from -- default of 0 means start
2077  /// the search from the beginning of the string.
2078  /// @param end
2079  /// Position in "str" to perform search up to -- default of NPOS means
2080  /// to search to the end of the string.
2081  /// @param which
2082  /// When set to eFirst, this means to find the first occurrence of
2083  /// "pattern" in "str". When set to eLast, this means to find the last
2084  /// occurrence of "pattern" in "str".
2085  /// @return
2086  /// - The start of the first or last (depending on "which" parameter)
2087  /// occurrence of "pattern" in "str", within the string interval
2088  /// ["start", "end"], or
2089  /// - NPOS if there is no occurrence of the pattern.
2090  /// @sa Find
2091  ///
2092  /// @deprecated
2093  /// Use one of the next methods instead:
2094  /// @code
2095  /// Find(str, pattern, [use_case], [direction], [occurrence])
2096  /// FindNoCase(str, pattern, [start])
2097  /// @endcode
2098  /// For example:
2099  /// @code
2100  /// FindNoCase(str, pattern, 0, NPOS, eLast)
2101  /// @endcode
2102  /// can be replaced by
2103  /// @code
2104  /// Find(str, pattern, eNocase, eReverseSearch, /* 0 */)
2105  /// @endcode
2106  /// For simpler cases without range, or with default [0, NPOS] please use
2107  /// @code
2108  /// FindNoCase(str, pattern, [start])
2109  /// @endcode
2110  /// But if you doing a search on a substring of the 'str' and ["start", "end"] search
2111  /// interval is not a default [0, NPOS], that mean a whole 'str' string, you may
2112  /// need to pass a substring instead of 'str', like
2113  /// @code
2114  /// FindNoCase(CTempString(str, start, len), pattern, ....)
2115  /// @endcode
2116  /// and after checking search result on NPOS, adjust it by 'start' yourself.
2118  static SIZE_TYPE FindNoCase(const CTempString str,
2119  const CTempString pattern,
2120  SIZE_TYPE start, SIZE_TYPE end,
2121  EOccurrence which = eFirst);
2122 
2123  /// Wrapper for backward-compatibility
2124  static SIZE_TYPE FindNoCase(const CTempString str, const CTempString pattern);
2125  static SIZE_TYPE FindNoCase(const CTempString str, const CTempString pattern, SIZE_TYPE start);
2126 
2127  /// Test for presence of a given string in a list or vector of strings
2128 
2129  static const string* Find (const list<string>& lst,
2130  const CTempString val,
2131  ECase use_case = eCase);
2132 
2133  static const string* FindCase (const list<string>& lst,
2134  const CTempString val);
2135 
2136  static const string* FindNoCase(const list<string>& lst,
2137  const CTempString val);
2138 
2139  static const string* Find (const vector<string>& vec,
2140  const CTempString val,
2141  ECase use_case = eCase);
2142 
2143  static const string* FindCase (const vector<string>& vec,
2144  const CTempString val);
2145 
2146  static const string* FindNoCase(const vector<string>& vec,
2147  const CTempString val);
2148 
2149  /// Find given word in the string.
2150  ///
2151  /// @param str
2152  /// String to search.
2153  /// @param word
2154  /// Word to search for in "str". The "word" can have any symbols,
2155  /// not letters only. Function treat it as a pattern, even it have
2156  /// any non-word characters.
2157  /// @param use_case
2158  /// Whether to do a case sensitive compare (default is eCase), or a
2159  /// case-insensitive compare (eNocase) while searching for the word.
2160  /// @param direction
2161  /// Define a search direction of the occurrence of "word" in "str".
2162  /// @return
2163  /// - Start of the found word in the string.
2164  /// - NPOS if there is no occurrence of the word in the string.
2165  static SIZE_TYPE FindWord(const CTempString str,
2166  const CTempString word,
2167  ECase use_case = eCase,
2168  EDirection direction = eForwardSearch);
2169 
2170  /// Find given word in the string.
2171  ///
2172  /// This function honors word boundaries:
2173  /// - starting or ending of the string,
2174  /// - any non-word character, all except [a-zA-Z0-9_].
2175  ///
2176  /// @param str
2177  /// String to search.
2178  /// @param word
2179  /// Word to search for in "str". The "word" can have any symbols,
2180  /// not letters only. Function treat it as a pattern, even it have
2181  /// any non-word characters.
2182  /// @param which
2183  /// When set to eFirst, this means to find the first occurrence of
2184  /// "word" in "str". When set to eLast, this means to find the last
2185  /// occurrence of "word" in "str".
2186  /// @param use_case
2187  /// Whether to do a case sensitive compare (default is eCase), or a
2188  /// case-insensitive compare (eNocase) while searching for the word.
2189  /// @return
2190  /// - The start of the first or last (depending on "which" parameter)
2191  /// occurrence of "word" in "str", or
2192  /// - NPOS if there is no occurrence of the word.
2193  /// @sa Find
2194  /// @deprecated
2195  /// Use FindWord() variant with EDirection parameter:
2196  /// @code
2197  /// FindWord(str, word, [use_case], [direction])
2198  /// @endcode
2199  inline
2202  const CTempString word,
2203  EOccurrence which,
2204  ECase use_case = eCase) {
2205  return FindWord(str, word, use_case, which == eFirst ? eForwardSearch : eReverseSearch);
2206  }
2207 
2208 
2209  /// Which end to truncate a string.
2210  enum ETrunc {
2211  eTrunc_Begin, ///< Truncate leading whitespace only
2212  eTrunc_End, ///< Truncate trailing whitespace only
2213  eTrunc_Both ///< Truncate whitespace at both begin and end of string
2214  };
2215 
2216  /// Truncate whitespace in a string.
2217  ///
2218  /// @param str
2219  /// String to truncate white-spaces from.
2220  /// @param where
2221  /// Which end of the string to truncate whitespace from.
2222  /// Default is to truncate whitespace from both ends (eTrunc_Both).
2223  /// @sa
2224  /// TruncateSpaces_Unsafe
2225  static string TruncateSpaces(const string& str,
2226  ETrunc where = eTrunc_Both);
2227 
2228  /// Truncate whitespace in a string.
2229  /// It can be faster but it is also more dangerous than TruncateSpaces()
2230  ///
2231  /// @param str
2232  /// String to truncate whitespace from.
2233  /// @param where
2234  /// Which end of the string to truncate whitespace from.
2235  /// Default is to truncate whitespace from both ends (eTrunc_Both).
2236  /// @attention
2237  /// The lifespan of the result string is the same as one of the source.
2238  /// So, for example, if the source is temporary string, or it changes somehow,
2239  /// then the result will be invalid right away (will point to already released
2240  /// or wrong range in the memory).
2241  /// @sa
2242  /// TruncateSpaces
2243  static CTempString TruncateSpaces_Unsafe(const CTempString str,
2244  ETrunc where = eTrunc_Both);
2245 
2246  /// @deprecated Use TruncateSpaces_Unsafe() instead -- AND, do make sure
2247  /// that you indeed use that in a safe manner!
2248  inline
2251  ETrunc where = eTrunc_Both) {
2252  return TruncateSpaces_Unsafe(str, where);
2253  }
2254 
2255  /// @deprecated Use TruncateSpaces_Unsafe() instead -- AND, do make sure
2256  /// that you indeed use that in a safe manner!
2257  inline
2259  static CTempString TruncateSpaces(const char* str,
2260  ETrunc where = eTrunc_Both) {
2261  return TruncateSpaces_Unsafe(str, where);
2262  }
2263 
2264  /// Truncate whitespace in a string (in-place)
2265  ///
2266  /// @param str
2267  /// String to truncate whitespace from.
2268  /// @param where
2269  /// Which end of the string to truncate whitespace from.
2270  /// Default is to truncate whitespace from both ends (eTrunc_Both).
2271  ///
2272  static void TruncateSpacesInPlace(string& str, ETrunc where = eTrunc_Both);
2273  static void TruncateSpacesInPlace(CTempString&, ETrunc where = eTrunc_Both);
2274 
2275 
2276  /// Trim prefix from a string (in-place)
2277  ///
2278  /// @param str
2279  /// String to trim from.
2280  /// @param prefix
2281  /// Prefix to remove.
2282  /// If string doesn't have specified prefix, it doesn't changes.
2283  /// @param use_case
2284  /// Whether to do a case sensitive compare (default is eCase), or a
2285  /// case-insensitive compare (eNocase) while checking for a prefix.
2286  ///
2287  static void TrimPrefixInPlace(string& str, const CTempString prefix,
2288  ECase use_case = eCase);
2289  static void TrimPrefixInPlace(CTempString& str, const CTempString prefix,
2290  ECase use_case = eCase);
2291 
2292  /// Trim prefix from a string.
2293  ///
2294  /// "Unsafe" counterpart to TrimPrefixInPlace().
2295  /// @param str
2296  /// String to trim from.
2297  /// @param prefix
2298  /// Prefix to remove.
2299  /// If string doesn't have specified prefix, it doesn't changes.
2300  /// @param use_case
2301  /// Whether to do a case sensitive compare (default is eCase), or a
2302  /// case-insensitive compare (eNocase) while checking for a prefix.
2303  /// @attention
2304  /// The lifespan of the result string is the same as one of the source.
2305  /// So, for example, if the source is temporary string, or it changes somehow,
2306  /// then the result will be invalid right away (will point to already released
2307  /// or wrong range in the memory).
2308  /// @sa
2309  /// TrimPrefixInPlace
2310  static CTempString TrimPrefix_Unsafe(const CTempString str,
2311  const CTempString prefix,
2312  ECase use_case = eCase);
2313 
2314  /// Trim suffix from a string (in-place)
2315  ///
2316  /// @param str
2317  /// String to trim from.
2318  /// @param suffix
2319  /// Suffix to remove.
2320  /// If string doesn't have specified suffix, it doesn't changes.
2321  /// @param use_case
2322  /// Whether to do a case sensitive compare (default is eCase), or a
2323  /// case-insensitive compare (eNocase) while checking for a suffix.
2324  static void TrimSuffixInPlace(string& str, const CTempString suffix,
2325  ECase use_case = eCase);
2326  static void TrimSuffixInPlace(CTempString& str, const CTempString suffix,
2327  ECase use_case = eCase);
2328 
2329  /// Trim suffix from a string.
2330  ///
2331  /// "Unsafe" counterpart to TrimSuffixInPlace().
2332  /// @param str
2333  /// String to trim from.
2334  /// @param suffix
2335  /// Suffix to remove.
2336  /// If string doesn't have specified suffix, it doesn't changes.
2337  /// @param use_case
2338  /// Whether to do a case sensitive compare (default is eCase), or a
2339  /// case-insensitive compare (eNocase) while checking for a suffix.
2340  /// @attention
2341  /// The lifespan of the result string is the same as one of the source.
2342  /// So, for example, if the source is temporary string, or it changes somehow,
2343  /// then the result will be invalid right away (will point to already released
2344  /// or wrong range in the memory).
2345  /// @sa
2346  /// TrimSuffixInPlace
2347  static CTempString TrimSuffix_Unsafe(const CTempString str,
2348  const CTempString suffix,
2349  ECase use_case = eCase);
2350 
2351  /// Replace occurrences of a substring within a string.
2352  ///
2353  /// @param src
2354  /// Source string from which specified substring occurrences are replaced.
2355  /// @param search
2356  /// Substring value in "src" that is replaced.
2357  /// @param replace
2358  /// Replace "search" substring with this value.
2359  /// @param dst
2360  /// Result of replacing the "search" string with "replace" in "src".
2361  /// This value is also returned by the function.
2362  /// @param start_pos
2363  /// Position to start search from.
2364  /// @param max_replace
2365  /// Replace no more than "max_replace" occurrences of substring "search"
2366  /// If "max_replace" is zero(default), then replace all occurrences with
2367  /// "replace".
2368  /// @param num_replace
2369  /// Optional pointer to a value which receives number of replacements occurred.
2370  /// @return
2371  /// Result of replacing the "search" string with "replace" in "src". This
2372  /// value is placed in "dst" as well.
2373  /// @note
2374  /// After replacing each occurence of the "search" string with "replace"
2375  /// this function move current search position behind a new replacement
2376  /// in the resulting string, so it doesn't search over any part of the
2377  /// inserted "replace".
2378  /// @sa
2379  /// Version of Replace() that returns a new string.
2380  static string& Replace(const string& src,
2381  const string& search,
2382  const string& replace,
2383  string& dst,
2384  SIZE_TYPE start_pos = 0,
2385  SIZE_TYPE max_replace = 0,
2386  SIZE_TYPE* num_replace = 0);
2387 
2388  /// Replace occurrences of a substring within a string and returns the
2389  /// result as a new string.
2390  ///
2391  /// @param src
2392  /// Source string from which specified substring occurrences are
2393  /// replaced.
2394  /// @param search
2395  /// Substring value in "src" that is replaced.
2396  /// @param replace
2397  /// Replace "search" substring with this value.
2398  /// @param start_pos
2399  /// Position to start search from.
2400  /// @param max_replace
2401  /// Replace no more than "max_replace" occurrences of substring "search"
2402  /// If "max_replace" is zero(default), then replace all occurrences with
2403  /// "replace".
2404  /// @param num_replace
2405  /// Optional pointer to a value which receives number of replacements occurred.
2406  /// @return
2407  /// A new string containing the result of replacing the "search" string
2408  /// with "replace" in "src"
2409  /// @note
2410  /// After replacing each occurence of the "search" string with "replace"
2411  /// this function move current search position behind a new replacement
2412  /// in the resulting string, so it doesn't search over any part of the
2413  /// inserted "replace".
2414  /// @sa
2415  /// Version of Replace() that has a destination parameter to accept
2416  /// result.
2417  static string Replace(const string& src,
2418  const string& search,
2419  const string& replace,
2420  SIZE_TYPE start_pos = 0,
2421  SIZE_TYPE max_replace = 0,
2422  SIZE_TYPE* num_replace = 0);
2423 
2424  /// Replace occurrences of a substring within a string.
2425  ///
2426  /// On some platforms this function is much faster than Replace()
2427  /// if sizes of "search" and "replace" strings are equal.
2428  /// Otherwise, the performance is mainly the same.
2429  /// @param src
2430  /// String where the specified substring occurrences are replaced.
2431  /// This value is also returned by the function.
2432  /// @param search
2433  /// Substring value in "src" that is replaced.
2434  /// @param replace
2435  /// Replace "search" substring with this value.
2436  /// @param start_pos
2437  /// Position to start search from.
2438  /// @param max_replace
2439  /// Replace no more than "max_replace" occurrences of substring "search"
2440  /// If "max_replace" is zero(default), then replace all occurrences with
2441  /// "replace".
2442  /// @note
2443  /// After replacing each occurence of the "search" string with "replace"
2444  /// this function move current search position behind a new replacement
2445  /// in the resulting string, so it doesn't search over any part of the
2446  /// inserted "replace".
2447  /// @param num_replace
2448  /// Optional pointer to a value which receives number of replacements occurred.
2449  /// @return
2450  /// Result of replacing the "search" string with "replace" in "src".
2451  /// @sa
2452  /// Replace
2453  static string& ReplaceInPlace(string& src,
2454  const string& search,
2455  const string& replace,
2456  SIZE_TYPE start_pos = 0,
2457  SIZE_TYPE max_replace = 0,
2458  SIZE_TYPE* num_replace = 0);
2459 
2460  /// Flags for Split*() methods.
2461  ///
2462  /// @note
2463  /// With quote support enabled, doubling a quote character suppresses
2464  /// its special meaning, as does escaping it if that's enabled too;
2465  /// unescaped trailing backslashes and unbalanced quotes result in
2466  /// exceptions.
2467  /// @note
2468  /// All escape symbols, single or double quotes became removed
2469  /// if a corresponding fSplit_Can* flag is used.
2471  fSplit_MergeDelimiters = 1 << 0, ///< Merge adjacent delimiters
2472  fSplit_Truncate_Begin = 1 << 1, ///< Truncate leading delimiters
2473  fSplit_Truncate_End = 1 << 2, ///< Truncate trailing delimiters
2474  fSplit_Truncate = fSplit_Truncate_Begin | fSplit_Truncate_End,
2475  fSplit_ByPattern = 1 << 3, ///< Require full delimiter strings
2476  fSplit_CanEscape = 1 << 4, ///< Allow \\... escaping
2477  fSplit_CanSingleQuote = 1 << 5, ///< Allow '...' quoting
2478  fSplit_CanDoubleQuote = 1 << 6, ///< Allow "..." quoting
2479  fSplit_CanQuote = fSplit_CanSingleQuote | fSplit_CanDoubleQuote,
2480  /// All delimiters are merged and trimmed, to get non-empty tokens only
2481  fSplit_Tokenize = fSplit_MergeDelimiters | fSplit_Truncate
2482  };
2483  typedef int TSplitFlags; ///< Bitwise OR of ESplitFlags
2484 
2485  /// Whether to merge adjacent delimiters.
2486  /// Used by some methods that don't need full functionality of ESplitFlags.
2488  eMergeDelims = fSplit_MergeDelimiters | fSplit_Truncate,
2489  eNoMergeDelims = 0
2490  };
2491 
2492  /// Split a string using specified delimiters.
2493  ///
2494  /// @param str
2495  /// String to be split.
2496  /// @param delim
2497  /// Delimiter(s) used to split string "str". The interpretation of
2498  /// multi-character values depends on flags: by default, any of those
2499  /// characters marks a split point (when unquoted), but with
2500  /// fSplit_ByPattern, the entire string must occur. (Meanwhile,
2501  /// an empty value disables splitting.)
2502  /// @param arr
2503  /// The split tokens are added to the list "arr" and also returned
2504  /// by the function.
2505  /// @param flags
2506  /// Flags directing splitting, characterized under ESplitFlags.
2507  /// @param token_pos
2508  /// Optional array for the tokens' positions in "str".
2509  /// @attention
2510  /// Modifying source CTempString object or destroying it,
2511  /// will invalidate results.
2512  /// @return
2513  /// The list "arr" is also returned.
2514  /// @sa
2515  /// ESplitFlags, SplitInTwo, SplitByPattern
2516  static list<string>& Split( const CTempString str,
2517  const CTempString delim,
2518  list<string>& arr,
2519  TSplitFlags flags = 0,
2520  vector<SIZE_TYPE>* token_pos = NULL);
2521 
2522  static vector<string>& Split(
2523  const CTempString str,
2524  const CTempString delim,
2525  vector<string>& arr,
2526  TSplitFlags flags = 0,
2527  vector<SIZE_TYPE>* token_pos = NULL);
2528 
2529  static list<CTempString>& Split(
2530  const CTempString str,
2531  const CTempString delim,
2532  list<CTempString>& arr,
2533  TSplitFlags flags = 0,
2534  vector<SIZE_TYPE>* token_pos = NULL,
2535  CTempString_Storage* storage = NULL);
2536 
2537  static vector<CTempString>& Split(
2538  const CTempString str,
2539  const CTempString delim,
2540  vector<CTempString>& arr,
2541  TSplitFlags flags = 0,
2542  vector<SIZE_TYPE>* token_pos = NULL,
2543  CTempString_Storage* storage = NULL);
2544 
2545  static list<CTempStringEx>& Split(
2546  const CTempString str,
2547  const CTempString delim,
2548  list<CTempStringEx>& arr,
2549  TSplitFlags flags = 0,
2550  vector<SIZE_TYPE>* token_pos = NULL,
2551  CTempString_Storage* storage = NULL);
2552 
2553  static vector<CTempStringEx>& Split(
2554  const CTempString str,
2555  const CTempString delim,
2556  vector<CTempStringEx>& arr,
2557  TSplitFlags flags = 0,
2558  vector<SIZE_TYPE>* token_pos = NULL,
2559  CTempString_Storage* storage = NULL);
2560 
2561  /// Split a string into two pieces using the specified delimiters
2562  ///
2563  /// @param str
2564  /// String to be split.
2565  /// @param delim
2566  /// Delimiters used to split string "str".
2567  /// @param str1
2568  /// The sub-string of "str" before the first character of "delim".
2569  /// It will not contain any characters in "delim".
2570  /// Will be empty if "str" begin with a delimiter.
2571  /// @param str2
2572  /// The sub-string of "str" after the first character of "delim" found.
2573  /// May contain "delim" characters.
2574  /// Will be empty if "str" had no "delim" characters or ended
2575  /// with the "delim" character.
2576  /// @param flags
2577  /// Flags directing splitting, characterized under ESplitFlags.
2578  /// Note, that fSplit_Truncate_End don't have any effect due nature
2579  /// of this method.
2580  /// @attention
2581  /// Modifying source CTempString object or destroying it,
2582  /// will invalidate results.
2583  /// @return
2584  /// true if a symbol from "delim" was found in "str", false if not.
2585  /// This lets you distinguish when there were no delimiters and when
2586  /// the very last character was the first delimiter.
2587  /// @sa
2588  /// ESplitFlags, Split
2589  static bool SplitInTwo(const CTempString str,
2590  const CTempString delim,
2591  string& str1,
2592  string& str2,
2593  TSplitFlags flags = 0);
2594 
2595  static bool SplitInTwo(const CTempString str,
2596  const CTempString delim,
2597  CTempString& str1,
2598  CTempString& str2,
2599  TSplitFlags flags = 0,
2600  CTempString_Storage* storage = NULL);
2601 
2602  static bool SplitInTwo(const CTempString str,
2603  const CTempString delim,
2604  CTempStringEx& str1,
2605  CTempStringEx& str2,
2606  TSplitFlags flags = 0,
2607  CTempString_Storage* storage = NULL);
2608 
2609 
2610  /// Variation of Split() with fSplit_ByPattern flag applied by default
2611 
2612  static list<string>& SplitByPattern(
2613  const CTempString str,
2614  const CTempString delim,
2615  list<string>& arr,
2616  TSplitFlags flags = 0,
2617  vector<SIZE_TYPE>* token_pos = NULL);
2618 
2619  static vector<string>& SplitByPattern(
2620  const CTempString str,
2621  const CTempString delim,
2622  vector<string>& arr,
2623  TSplitFlags flags = 0,
2624  vector<SIZE_TYPE>* token_pos = NULL);
2625 
2626  static list<CTempString>& SplitByPattern(
2627  const CTempString str,
2628  const CTempString delim,
2629  list<CTempString>& arr,
2630  TSplitFlags flags = 0,
2631  vector<SIZE_TYPE>* token_pos = NULL,
2632  CTempString_Storage* storage = NULL);
2633 
2634  static vector<CTempString>& SplitByPattern(
2635  const CTempString str,
2636  const CTempString delim,
2637  vector<CTempString>& arr,
2638  TSplitFlags flags = 0,
2639  vector<SIZE_TYPE>* token_pos = NULL,
2640  CTempString_Storage* storage = NULL);
2641 
2642  static list<CTempStringEx>& SplitByPattern(
2643  const CTempString str,
2644  const CTempString delim,
2645  list<CTempStringEx>& arr,
2646  TSplitFlags flags = 0,
2647  vector<SIZE_TYPE>* token_pos = NULL,
2648  CTempString_Storage* storage = NULL);
2649 
2650  static vector<CTempStringEx>& SplitByPattern(
2651  const CTempString str,
2652  const CTempString delim,
2653  vector<CTempStringEx>& arr,
2654  TSplitFlags flags = 0,
2655  vector<SIZE_TYPE>* token_pos = NULL,
2656  CTempString_Storage* storage = NULL);
2657 
2658  /// Join strings using the specified delimiter.
2659  ///
2660  /// @param arr
2661  /// Array of strings to be joined.
2662  /// @param delim
2663  /// Delimiter used to join the string.
2664  /// @return
2665  /// The strings in "arr" are joined into a single string, separated
2666  /// with "delim".
2667  /// @sa Split
2668  template<typename TContainer>
2669  static string
2670  Join(const TContainer& arr, const CTempString& delim)
2671  {
2672  return x_Join(begin(arr), end(arr), delim);
2673  }
2674  template<typename TValue>
2675  static string
2676  Join(const initializer_list<TValue>& arr, const CTempString& delim)
2677  {
2678  return x_Join(begin(arr), end(arr), delim);
2679  }
2680  template<typename TInputIterator>
2681  static string
2682  Join( TInputIterator from, TInputIterator to, const CTempString& delim)
2683  {
2684  return x_Join(from, to, delim);
2685  }
2686  template<typename TInputIterator>
2687  static string
2688  JoinNumeric( TInputIterator from, TInputIterator to, const CTempString& delim)
2689  {
2690  return x_Join( from, to, delim);
2691  }
2692  template<typename TIterator, typename FTransform>
2693  static string
2694  TransformJoin( TIterator from, TIterator to, const CTempString& delim, FTransform fnTransform);
2695 
2696 
2697  /// How to display printable strings.
2698  ///
2699  /// Assists in making a printable version of "str".
2701  fNewLine_Quote = 0, ///< Display "\n" instead of actual linebreak
2702  eNewLine_Quote = fNewLine_Quote,
2703  fNewLine_Passthru = 1, ///< Break the line at every "\n" occurrence
2704  eNewLine_Passthru = fNewLine_Passthru,
2705  fNonAscii_Passthru = 0, ///< Allow non-ASCII but printable characters
2706  fNonAscii_Quote = 2, ///< Octal for all non-ASCII characters
2707  fPrintable_Full = 64 ///< Show all octal digits at all times
2708  };
2709  typedef int TPrintableMode; ///< Bitwise OR of EPrintableMode flags
2710 
2711  /// Get a printable version of the specified string.
2712  ///
2713  /// All non-printable characters will be represented as "\a", "\b", "\f",
2714  /// "\n", "\r", "\t", "\v", "\'", "\"", "\\\\", etc. or "\\ooo" where 'ooo'
2715  /// is an octal code of the character. The resultant string is a well-
2716  /// formed C string literal, which, without alterations, can be compiled by
2717  /// a C/C++ compiler. Potential tri-graphs are taken care of, too.
2718  /// In many instances, octal representations of non-printable characters
2719  /// can be reduced to take less than all 3 digits, if there is no ambiguity
2720  /// in the interpretation. fPrintable_Full cancels the reduction, and
2721  /// forces to produce the full 3-digit octal codes throughout.
2722  ///
2723  /// @param str
2724  /// The string whose printable version is wanted.
2725  /// @param mode
2726  /// How to display the string. The default setting of fNewLine_Quote
2727  /// displays the new lines as "\n", and uses the octal code reduction.
2728  /// When set to fNewLine_Passthru, the line breaks are actually produced
2729  /// after each "\n" but preceded with trailing backslashes.
2730  /// @return
2731  /// Return a printable version of "str".
2732  /// @sa
2733  /// ParseEscapes, Escape, CEncode, CParse, Sanitize
2734  static string PrintableString(const CTempString str,
2735  TPrintableMode mode = fNewLine_Quote | fNonAscii_Passthru);
2736 
2737  /// Escape string (generic version).
2738  ///
2739  /// Prefix any occurrences of the metacharacters with the escape character.
2740  /// @param str
2741  /// The string to be escaped.
2742  /// @metacharacters
2743  /// List of characters that need to be escaped.
2744  /// Use NStr::Join() if you have metacharacters in list<>, vector<> or set<>.
2745  /// @param escape_char
2746  /// Character used for escaping metacharacters.
2747  /// Each metacharacter will be replaced with pair "escape_char + metacharacter".
2748  /// Each escape character will be replaced with pair "escape_char + escape_char".
2749  /// @return
2750  /// Escaped string.
2751  /// @sa
2752  /// Unescape, PrintableString, Join
2753  static string Escape(const CTempString str, const CTempString metacharacters,
2754  char escape_char = '\\');
2755 
2756  /// Unescape string (generic version).
2757  ///
2758  /// Remove escape characters added by Escape().
2759  /// @param str
2760  /// The string to be processed.
2761  /// @param escape_char
2762  /// Character used for escaping.
2763  /// @return
2764  /// Unescaped string.
2765  /// @sa
2766  /// Escape
2767  static string Unescape(const CTempString str, char escape_char = '\\');
2768 
2769 
2770  /// Quote string (generic version).
2771  ///
2772  /// Prepend and append a specified quote character, but escaping any occurrence
2773  /// of the quote character using either a specified escape character (default '\')
2774  /// or as option, by doubling the quoting character if escape character is the same
2775  /// (e.g. like the single quote in SQL, double-quote in CSV).
2776  ///
2777  /// @param str
2778  /// The string to be quoted.
2779  /// @param quote_char
2780  /// Character used for quoting, default to double quote '"'.
2781  /// @param escape_char
2782  /// Character used for escaping other quote characters inside string (default '\').
2783  /// Each <quote_char> in the string will be replaced with pair "escape_char + quote_char".
2784  /// Each <escape_char> in the string will be replaced with pair "escape_char + escape_char".
2785  /// @return
2786  /// Quoted string.
2787  /// @sa
2788  /// Unquote, ParseQuoted, CEncode
2789  static string Quote(const CTempString str, char quote_char = '"', char escape_char = '\\');
2790 
2791  /// Unquote string (generic version).
2792  ///
2793  /// Remove quotation added by Quote(). Uses first character as quoting character.
2794  /// @param str
2795  /// The string to be processed.
2796  /// @param escape_char
2797  /// Character used for escaping.
2798  /// @return
2799  /// Unquoted string.
2800  /// @sa
2801  /// Quote, ParseQuoted, CEncode
2802  static string Unquote(const CTempString str, char escape_char = '\\');
2803 
2804 
2805  /// Flags for Sanitize().
2806  enum ESS_Flags {
2807  // Character filters
2808  fSS_alpha = 1 << 0, ///< Check on ::isalpha()
2809  fSS_digit = 1 << 1, ///< Check on ::isdigit()
2810  fSS_alnum = 1 << 2, ///< Check on ::isalnum()
2811  fSS_print = 1 << 3, ///< Check on ::isprint()
2812  fSS_cntrl = 1 << 4, ///< Check on ::iscntrl()
2813  fSS_punct = 1 << 5, ///< Check on ::ispunct()
2814 
2815  // Filter: in or out?
2816  fSS_Reject = 1 << 11, ///< Reject specified characters, allow all other.
2817  ///< Revert default behavior, that allow specified
2818  ///< characters and reject all other.
2819  // Utility flags
2820  fSS_Remove = 1 << 12, ///< Remove (rather than replace) rejected chars
2821  fSS_NoMerge = 1 << 13, ///< Do not merge adjacent spaces (rejected chars)
2822  fSS_NoTruncate_Begin = 1 << 14, ///< Do not truncate leading spaces
2823  fSS_NoTruncate_End = 1 << 15, ///< Do not truncate trailing spaces
2824  fSS_NoTruncate = fSS_NoTruncate_Begin | fSS_NoTruncate_End
2825  };
2826  typedef int TSS_Flags; ///< Bitwise OR of ESS_Flags
2827 
2828  /// Sanitize a string, allowing only specified classes of characters.
2829  ///
2830  /// By default:
2831  /// - replace all non-printable characters with spaces;
2832  /// - merge coalescent spaces;
2833  /// - truncate leading and trailing spaces.
2834  /// @note
2835  /// - All coalescent leading/trailing spaces also will be merged
2836  /// by default if fSS_NoMerge has not specified.
2837  /// - The truncation of leading/trailing spaces is doing after
2838  /// allowing/rejecting characters. Depending on the specified flags,
2839  /// all rejected characters adjacent to it can be treat as part
2840  /// of leading/trailing spaces.
2841  /// @param str
2842  /// String to sanitize
2843  /// @param flags
2844  /// Alternative sanitation options
2845  /// @return
2846  /// Sanitized string
2847  /// @sa
2848  /// PrintableString
2849  static string Sanitize(CTempString str, TSS_Flags flags = fSS_print)
2850  {
2851  return Sanitize(str, CTempString(), CTempString(), ' ', flags);
2852  }
2853 
2854 
2855  /// Sanitize a string, allowing only specified characters or character classes.
2856  ///
2857  /// More customizable version of Sanitize():
2858  /// - allow to specify custom sets of allowed and rejected characters,
2859  /// in addition to predefined classes if specified, see TSS_Flags;
2860  /// - allow to specify replacement character for rejected symbols;
2861  /// By default:
2862  /// - replace all rejected characters with <reject_replacement>;
2863  /// - merge coalescent spaces and <reject_replacement>s (separately if differ);
2864  /// - truncate leading and trailing spaces.
2865  /// Filters check order:
2866  /// - character classes via flags.
2867  /// Note, that if no character classes are set, and no custom <allow_chars>
2868  /// or <reject_chars>, fSS_print will be used;
2869  /// - <allow_chars> if not empty, have priority over flags.
2870  /// - <reject_chars> if not empty, have priority over flags and <allow_chars> if have intersections.
2871  /// @note
2872  /// - All coalescent leading/trailing spaces also will be merged
2873  /// by default if fSS_NoMerge has not specified.
2874  /// - The truncation of leading/trailing spaces is doing after
2875  /// allowing/rejecting characters.
2876  /// @note
2877  /// Spaces processes after checks on allowance, so if it isn't allowed
2878  /// it will be threatened as regular rejected character.
2879  /// @param str
2880  /// String to sanitize.
2881  /// @param allow_chars
2882  /// Additional list of allowed characters, in addition to character classes in <flags>.
2883  /// Have priority over character classes.
2884  /// Use NStr::Join() if you have it in list<>, vector<> or set<>.
2885  /// @param reject_chars
2886  /// Additional list of rejected characters, in addition to character classes in <flags>.
2887  /// Have priority over character classes and <allow_chars>.
2888  /// Use NStr::Join() if you have it in list<>, vector<> or set<>.
2889  /// @param reject_replacement
2890  /// Replacement character for all rejected characters.
2891  /// @param flags
2892  /// Alternative sanitation options.
2893  /// If no custom <allow_chars> or <reject_chars>, and no character classes are set, then use fSS_print by default.
2894  /// If <reject_chars>, no class, and no fSS_Reject flag, then all characters allowed except <reject_chars>.
2895  /// If <allow_chars>, no class, and fSS_Reject flag, then no any character allowed except <allow_chars>.
2896  /// @return
2897  /// Sanitized string
2898  /// @sa
2899  /// PrintableString, Join
2900  static string Sanitize(CTempString str,
2901  CTempString allow_chars,
2902  CTempString reject_chars,
2903  char reject_replacement = ' ',
2904  TSS_Flags flags = 0);
2905 
2906  /// C-style escape sequences parsing mode.
2907  /// For escape sequences with a value outside the range of [0-255]
2908  /// the behavior of ParseEscapes() depends from this mode.
2909  /// By default all escape sequences within a out or range
2910  /// will be converted to the least significant byte, with no warning.
2912  eEscSeqRange_Standard, ///< Set char to the last (least significant
2913  ///< byte) of the escape sequence (default).
2914  eEscSeqRange_FirstByte, ///< Set char to the first byte of the escape
2915  ///< sequence.
2916  eEscSeqRange_Throw, ///< Throw an exception.
2917  eEscSeqRange_Errno, ///< Set errno to ERANGE, return empty string.
2918  eEscSeqRange_User ///< Set char to the user value
2919  ///< passed in another parameter.
2920  };
2921 
2922  /// Parse C-style escape sequences in the specified string.
2923  ///
2924  /// Parse escape sequences including all those produced by PrintableString.
2925  /// @param str
2926  /// The string to be parsed.
2927  /// @param mode
2928  /// Parsing mode.
2929  /// By default all escape sequences with a value outside the range of [0-255]
2930  /// will be converted to the least significant byte, with no warning.
2931  /// @param user_char
2932  /// If 'mode' have eEscSeqRange_User, replace all out of range
2933  /// escape sequences with this char.
2934  /// @return
2935  /// String with parsed C-style escape sequences.
2936  /// - If string have wrong format throw an CStringException exception.
2937  /// - If parsing succeeds, return the converted value.
2938  /// Set errno to zero only if eEscSeqRange_Errno is set.
2939  /// - Otherwise, if escape sequence is out of range [0-255],
2940  /// see eEscSeqRange* modes for behavior.
2941  /// @sa
2942  /// EEscSeqFlags, PrintableString, CEncode, CParse
2943  static string ParseEscapes(const CTempString str,
2944  EEscSeqRange mode = eEscSeqRange_Standard,
2945  char user_char = '?');
2946 
2947  /// Discard C-style backslash escapes and extract a quoted string.
2948  ///
2949  /// @param[in] str
2950  /// The original string to extract a quoted string from.
2951  /// It must start with a double quote.
2952  /// @param[out] n_read
2953  /// How many symbols the quoted string occupied in the original string.
2954  /// @return
2955  /// The extracted string, un-escaped and with the quotes removed.
2956  /// Throw an exception on format error.
2957  static string ParseQuoted(const CTempString str, size_t* n_read = NULL);
2958 
2959  /// Define that string is quoted or not.
2960  enum EQuoted {
2961  eQuoted, ///< String is quoted
2962  eNotQuoted ///< String is not quoted
2963  };
2964 
2965  /// Encode a string for C/C++.
2966  ///
2967  /// @param str
2968  /// The string to be parsed.
2969  /// @param quoted
2970  /// Define, to
2971  /// @sa
2972  /// CParse, PrintableString
2973  static string CEncode(const CTempString str, EQuoted quoted = eQuoted);
2974 
2975  /// Discard C-style backslash escapes.
2976  ///
2977  /// @param str
2978  /// The original string to parse.
2979  /// @param quoted
2980  /// Define that parsing string is quoted or not.
2981  /// If parameter "quoted" equal eQuoted and string is not started and
2982  /// finished with a double-quote, the exception will be thrown,
2983  /// otherwise quotes will be removed in result.
2984  /// @return
2985  /// String with parsed C-style escape sequences.
2986  /// @sa
2987  /// CEncode
2988  static string CParse(const CTempString str, EQuoted quoted = eQuoted);
2989 
2990  /// Encode a string for JavaScript.
2991  ///
2992  /// Replace relevant characters by predefined entities.
2993  /// Like to PrintableString(), but process some symbols in different way.
2994  /// @sa PrintableString
2995  static string JavaScriptEncode(const CTempString str);
2996 
2997  /// XML-encode flags
2998  enum EXmlEncode {
2999  /// Encode predefined entities only
3000  eXmlEnc_Contents = 0,
3001  /// Encode double hyphen and ending hyphen,
3002  /// making the result safe to put into XML comments.
3003  eXmlEnc_CommentSafe = 1 << 0,
3004  /// Check each character to conform XML 1.1 standards,
3005  /// skip any not allowed character or throw an CStringException.
3006  /// https://www.w3.org/TR/xml11/#NT-Char
3007  eXmlEnc_Unsafe_Skip = 1 << 1,
3008  eXmlEnc_Unsafe_Throw = 1 << 2
3009  };
3010  typedef int TXmlEncode; //< bitwise OR of "EXmlEncode"
3011 
3012  /// Encode a string for XML.
3013  ///
3014  /// Replace relevant characters by predefined entities.
3015  static string XmlEncode(const CTempString str,
3016  TXmlEncode flags = eXmlEnc_Contents);
3017 
3018 
3019  /// HTML-decode flags
3021  fHtmlEnc_EncodeAll = 0, ///< Encode all symbols
3022  fHtmlEnc_SkipLiteralEntities = 1 << 1, ///< Skip "&entity;"
3023  fHtmlEnc_SkipNumericEntities = 1 << 2, ///< Skip "&#NNNN;"
3024  fHtmlEnc_SkipEntities = fHtmlEnc_SkipLiteralEntities | fHtmlEnc_SkipNumericEntities,
3025  fHtmlEnc_CheckPreencoded = 1 << 3 ///< Print warning if some pre-encoded
3026  ///< entity found in the string
3027  };
3028  typedef int THtmlEncode; //< bitwise OR of "EHtmlEncode"
3029 
3030  /// Encode a string for HTML.
3031  ///
3032  /// Replace relevant characters by predefined entities.
3033  /// @param str
3034  /// Original string in UTF8 encoding.
3035  static string HtmlEncode(const CTempString str,
3036  THtmlEncode flags = fHtmlEnc_EncodeAll);
3037 
3038  /// HTML-decode flags
3040  fHtmlDec_CharRef_Entity = 1, ///< Character entity reference(s) was found
3041  fHtmlDec_CharRef_Numeric = 1 << 1, ///< Numeric character reference(s) was found
3042  fHtmlDec_Encoding_Changed = 1 << 2 ///< Character encoding changed
3043  };
3044  typedef int THtmlDecode; //< bitwise OR of "EHtmlDecode"
3045 
3046  /// Decode HTML entities and character references.
3047  ///
3048  /// @param str
3049  /// String to be decoded, which contains characters or numeric HTML entities
3050  /// @param encoding
3051  /// Encoding of the input string
3052  /// @return
3053  /// UTF8 encoded string
3054  static string HtmlDecode(const CTempString str,
3055  EEncoding encoding = eEncoding_Unknown,
3056  THtmlDecode* result_flags = NULL);
3057 
3058  /// Returns HTML entity name for this symbol if one exists
3059  /// (without leading ampersand and trailing semicolon);
3060  /// or empty string if suitable HTML entity was not found
3061  static string HtmlEntity(TUnicodeSymbol uch);
3062 
3063  /// Json-encode flags
3065  eJsonEnc_UTF8, ///< Encode all characters above 0x80 to \uXXXX form.
3066  ///< https://tools.ietf.org/html/rfc7159#section-8.1
3067  eJsonEnc_Quoted ///< Quote resulting string. Keep all Unicode symbols as is.
3068  ///< https://tools.ietf.org/html/rfc7159#section-7
3069  };
3070  /// Encode a string for JSON.
3071  ///
3072  /// @param str
3073  /// The string to encode.
3074  /// @param encoding
3075  /// Specifies how to encode string.
3076  /// There are 2 approaches, with representing whole string as UTF-8 encoded string,
3077  /// or leave all Unicode symbols "as is", but the resulting string will be put in double quotes.
3078  /// @warning
3079  /// This method is not intended to work with strings that already have UTF-8 encoding,
3080  /// except simple eJsonEnc_Quoted mode, that just quote a string, without any real encoding.
3081  /// Passed string have no information on encoding and JsonEncode() cannot detect it.
3082  /// So, with default eJsonEnc_UTF8 mode such strings will be re-encoded again, so you will
3083  /// have double UTF-8 encoded string as result, that is not what you may expect. Be aware.
3084  /// @return
3085  /// JSON encoded string
3086  static string JsonEncode(const CTempString str, EJsonEncode encoding = eJsonEnc_UTF8);
3087 
3088  /// Decode a string encoded by JsonEncode.
3089  ///
3090  /// @param str
3091  /// The string to encode.
3092  /// It must be in double quotes.
3093  /// @param[out] n_read
3094  /// How many symbols the quoted string occupied in the original string.
3095  /// @sa
3096  /// JsonEncode
3097  /// @warning
3098  /// This method only supports strings encoded by JsonEncode-specific encodings.
3099  static string JsonDecode(const CTempString str, size_t* n_read = NULL);
3100 
3101  /// Quotes a string in Bourne Again Shell (BASH) syntax, in a way
3102  /// that disallows non-printable characters in the result.
3103  /// This function does NOT implement aesthetically optimal quoting,
3104  /// but does try to avoid redundant quoting in simpler cases.
3105  /// Also, since it implements BASH syntax, the result may be
3106  /// incompatible with Bourne syntax, and may be non-obvious to
3107  /// people who are not familiar with the extended quoting syntax.
3108  /// @note The BASH shell has extensions beyond Bourne Shell quoting.
3109  /// Also, this is very different from C Shell quoting, and
3110  /// MS Windows Command Prompt quoting rules.
3111  static string ShellEncode(const string& str);
3112 
3113  /// URL-encode flags
3114  enum EUrlEncode {
3115  eUrlEnc_SkipMarkChars, ///< Do not convert chars like '!', '(' etc.
3116  eUrlEnc_ProcessMarkChars, ///< Convert all non-alphanumeric chars, spaces are converted to '+'
3117  eUrlEnc_PercentOnly, ///< Convert all non-alphanumeric chars including space and '%' to %## format
3118  eUrlEnc_Path, ///< Same as ProcessMarkChars but preserves valid path characters ('/', '.')
3119  eUrlEnc_URIScheme, ///< Encode scheme part of an URI.
3120  eUrlEnc_URIUserinfo, ///< Encode userinfo part of an URI.
3121  eUrlEnc_URIHost, ///< Encode host part of an URI.
3122  eUrlEnc_URIPath, ///< Encode path part of an URI.
3123  eUrlEnc_URIQueryName, ///< Encode query part of an URI, arg name.
3124  eUrlEnc_URIQueryValue, ///< Encode query part of an URI, arg value.
3125  eUrlEnc_URIFragment, ///< Encode fragment part of an URI.
3126  eUrlEnc_Cookie, ///< Same as SkipMarkChars with encoded ','
3127  eUrlEnc_None ///< Do not encode
3128  };
3129  /// URL decode flags
3130  enum EUrlDecode {
3131  eUrlDec_All, ///< Decode '+' to space
3132  eUrlDec_Percent ///< Decode only %XX
3133  };
3134  /// URL-encode string
3135  static string URLEncode(const CTempString str,
3136  EUrlEncode flag = eUrlEnc_SkipMarkChars);
3137 
3138  /// SQL encode flags
3139  enum ESqlEncode {
3140  eSqlEnc_Plain, ///< Always produce '...', with no tag.
3141  eSqlEnc_TagNonASCII ///< Produce N'...' when input's not pure ASCII.
3142  };
3143  /// SQL-encode string
3144  ///
3145  /// There are some assumptions/notes about the function:
3146  /// 1. Only for MS SQL and Sybase.
3147  /// 2. Only for string values in WHERE and LIKE clauses.
3148  /// 3. The ' symbol must not be used as an escape symbol in LIKE clause.
3149  /// 4. It must not be used for non-string values.
3150  /// 5. It expects a string without any outer quotes, and
3151  /// it adds single quotes to the returned string.
3152  /// 6. It expects UTF-8 (including its subsets, ASCII and Latin1) or
3153  /// Win1252 string, and the input encoding is preserved.
3154  /// @param str
3155  /// The string to encode
3156  /// @param flag
3157  /// Whether to tag the result with an N prefix if it contains any
3158  /// non-ASCII characters. Such tagging is generally advisable,
3159  /// but off by default per historical practice, since there are
3160  /// corner cases in which it may be inappropriate.
3161  /// @return
3162  /// Encoded string with added outer single quotes
3163  static CStringUTF8 SQLEncode(const CStringUTF8& str, ESqlEncode flag);
3164 
3166  { return SQLEncode(str, eSqlEnc_Plain); }
3167 
3168  /// URL-decode string
3169  static string URLDecode(const CTempString str, EUrlDecode flag = eUrlDec_All);
3170  /// URL-decode string to itself
3171  static void URLDecodeInPlace(string& str, EUrlDecode flag = eUrlDec_All);
3172  static SIZE_TYPE URLDecodeInPlace(char* str, SIZE_TYPE len, EUrlDecode flag = eUrlDec_All);
3173 
3174  /// Check if the string needs the requested URL-encoding
3175  static bool NeedsURLEncoding(const CTempString str, EUrlEncode flag = eUrlEnc_SkipMarkChars);
3176 
3177  /// Base64-encode string.
3178  ///
3179  /// @param str
3180  /// The string to encode.
3181  /// @param line_len
3182  /// Specify a length for Base64-encoded lines. Default 0 mean no line breaks at all.
3183  /// @return
3184  /// Encoded string.
3185  /// @sa Base64Decode, BASE64_Encode, BASE64_Deccode
3186  static string Base64Encode(const CTempString str, size_t line_len = 0);
3187 
3188  /// Base64-decode string
3189  ///
3190  /// @param str
3191  /// The string to decode.
3192  /// @return
3193  /// Encoded string, or empty line on encoding error.
3194  /// @sa Base64Encode, BASE64_Encode, BASE64_Deccode
3195  static string Base64Decode(const CTempString str);
3196 
3197  /// Check if the string contains a valid IP address
3198  static bool IsIPAddress(const CTempStringEx str);
3199 
3200 
3201  /// How to wrap the words in a string to a new line.
3202  enum EWrapFlags {
3203  fWrap_Hyphenate = 0x1, ///< Add a hyphen when breaking words?
3204  fWrap_HTMLPre = 0x2, ///< Wrap as pre-formatted HTML?
3205  fWrap_FlatFile = 0x4 ///< Wrap for flat file use.
3206  };
3207  typedef int TWrapFlags; ///< Bitwise OR of "EWrapFlags"
3208 
3209  /// Wrap the specified string into lines of a specified width.
3210  ///
3211  /// Split string "str" into lines of width "width" and add the
3212  /// resulting lines to the list "arr". Normally, all
3213  /// lines will begin with "prefix" (counted against "width"),
3214  /// but the first line will instead begin with "prefix1" if
3215  /// you supply it.
3216  ///
3217  /// @param str
3218  /// String to be split into wrapped lines.
3219  /// @param width
3220  /// Width of each wrapped line.
3221  /// @param arr
3222  /// List of strings containing wrapped lines.
3223  /// @param flags
3224  /// How to wrap the words to a new line. See EWrapFlags documentation.
3225  /// @param prefix
3226  /// The prefix string added to each wrapped line, except the first line,
3227  /// unless "prefix1" is set.
3228  /// If "prefix" is set to 0(default), do not add a prefix string to the
3229  /// wrapped lines.
3230  /// @param prefix1
3231  /// The prefix string for the first line. Use this for the first line
3232  /// instead of "prefix".
3233  /// If "prefix1" is set to 0(default), do not add a prefix string to the
3234  /// first line.
3235  /// @return
3236  /// Return "arr", the list of wrapped lines.
3237  template<typename _D>
3238  static void WrapIt(const string& str, SIZE_TYPE width,
3239  _D& dest, TWrapFlags flags = 0,
3240  const string* prefix = 0,
3241  const string* prefix1 = 0);
3242 
3244  {
3245  public:
3246  virtual ~IWrapDest() {}
3247  virtual void Append(const string& s) = 0;
3248  virtual void Append(const CTempString& s) = 0;
3249  };
3250 
3252  {
3253  protected:
3254  list<string>& m_list;
3255  public:
3256  CWrapDestStringList(list<string>& l) : m_list(l) {};
3257  virtual void Append(const string& s)
3258  {
3259  m_list.push_back(s);
3260  }
3261  virtual void Append(const CTempString& s)
3262  {
3263  m_list.push_back(NcbiEmptyString);
3264  m_list.back().assign(s.data(), s.length());
3265  }
3266  };
3267 
3268  static void Wrap(const string& str, SIZE_TYPE width,
3269  IWrapDest& dest, TWrapFlags flags,
3270  const string* prefix,
3271  const string* prefix1);
3272 
3273  static list<string>& Wrap(const string& str, SIZE_TYPE width,
3274  list<string>& arr, TWrapFlags flags = 0,
3275  const string* prefix = 0,
3276  const string* prefix1 = 0);
3277 
3278  static list<string>& Wrap(const string& str, SIZE_TYPE width,
3279  list<string>& arr, TWrapFlags flags,
3280  const string& prefix,
3281  const string* prefix1 = 0);
3282 
3283  static list<string>& Wrap(const string& str, SIZE_TYPE width,
3284  list<string>& arr, TWrapFlags flags,
3285  const string& prefix,
3286  const string& prefix1);
3287 
3288 
3289  /// Wrap the list using the specified criteria.
3290  ///
3291  /// WrapList() is similar to Wrap(), but tries to avoid splitting any
3292  /// elements of the list to be wrapped. Also, the "delim" only applies
3293  /// between elements on the same line; if you want everything to end with
3294  /// commas or such, you should add them first.
3295  ///
3296  /// @param l
3297  /// The list to be wrapped.
3298  /// @param width
3299  /// Width of each wrapped line.
3300  /// @param delim
3301  /// Delimiters used to split elements on the same line.
3302  /// @param arr
3303  /// List containing the wrapped list result.
3304  /// @param flags
3305  /// How to wrap the words to a new line. See EWrapFlags documentation.
3306  /// @param prefix
3307  /// The prefix string added to each wrapped line, except the first line,
3308  /// unless "prefix1" is set.
3309  /// If "prefix" is set to 0(default), do not add a prefix string to the
3310  /// wrapped lines.
3311  /// @param prefix1
3312  /// The prefix string for the first line. Use this for the first line
3313  /// instead of "prefix".
3314  /// If "prefix1" is set to 0(default), do not add a prefix string to the
3315  /// first line.
3316  /// @return
3317  /// Return "arr", the wrapped list.
3318  static list<string>& WrapList(const list<string>& l, SIZE_TYPE width,
3319  const string& delim, list<string>& arr,
3320  TWrapFlags flags = 0,
3321  const string* prefix = 0,
3322  const string* prefix1 = 0);
3323 
3324  static list<string>& WrapList(const list<string>& l, SIZE_TYPE width,
3325  const string& delim, list<string>& arr,
3326  TWrapFlags flags,
3327  const string& prefix,
3328  const string* prefix1 = 0);
3329 
3330  static list<string>& WrapList(const list<string>& l, SIZE_TYPE width,
3331  const string& delim, list<string>& arr,
3332  TWrapFlags flags,
3333  const string& prefix,
3334  const string& prefix1);
3335 
3336 
3337  /// Justify the specified string into a series of lines of the same width.
3338  ///
3339  /// Split string "str" into a series of lines, all of which (except for the
3340  /// final one) are to be exactly "width" characters wide (by adding extra
3341  /// inner spaces between words when necessary), and store the resultant
3342  /// lines in the list "par". Normally, all lines in "par" will begin with
3343  /// "pfx" (counted against "width"), but the first line can instead begin
3344  /// with "pfx1" if provided.
3345  ///
3346  /// @note Words exceeding the specified "width" will not be split between
3347  /// lines but occupy individual lines (which will be wider than "width").
3348  ///
3349  /// @param str
3350  /// String to be split into justified lines.
3351  /// @param width
3352  /// Width of every line (except for the last one).
3353  /// @param par
3354  /// Resultant list of justified lines.
3355  /// @param pfx
3356  /// The prefix string added to each line, except for the first line
3357  /// if non-NULL "pfx1" is also set. Empty(or NULL) "pfx" causes no
3358  /// additions.
3359  /// @param pfx1
3360  /// The prefix string for the first line, if non-NULL.
3361  /// @return
3362  /// Return "par", the list of justified lines (a paragraph).
3363  static list<string>& Justify(const CTempString str,
3364  SIZE_TYPE width,
3365  list<string>& par,
3366  const CTempString* pfx = 0,
3367  const CTempString* pfx1 = 0);
3368 
3369  static list<string>& Justify(const CTempString str,
3370  SIZE_TYPE width,
3371  list<string>& par,
3372  const CTempString pfx,
3373  const CTempString* pfx1 = 0);
3374 
3375  static list<string>& Justify(const CTempString str,
3376  SIZE_TYPE width,
3377  list<string>& par,
3378  const CTempString pfx,
3379  const CTempString pfx1);
3380 
3381  /// Flags for Dedent() method
3383  fDedent_NormalizeEmptyLines = 1 << 0, ///< Each line containing only whitespace will be normalized
3384  ///< to a single newline character in the output. Such lines
3385  ///< are excluded from detecting common whitespace prefix.
3386  // Next flags can be useful for processing RAW multi-line literals "R(...)"
3387  fDedent_SkipFirstLine = 1 << 1, ///< Ignore first line and skip it from the result.
3388  fDedent_SkipEmptyFirstLine = 1 << 2, ///< Ignore first line and skip it from the result, if it is empty only.
3389  };
3390  typedef int TDedentFlags; ///< Bitwise OR of EDedentFlags
3391 
3392  /// Dedent multi-line string, removing common whitespace prefix for each line.
3393  ///
3394  /// @param str
3395  /// String to be dedented.
3396  /// @param flags
3397  /// Optional flags to tune up how to dedent string.
3398  /// @return
3399  /// String with removed common whitespace indentation.
3400  /// @note
3401  /// Empty lines, and lines containing whitespace only with fDedent_NormalizeEmptyLines flag,
3402  /// are not used in computing common whitespace prefix.
3403  /// @note
3404  /// Assumes that whitespace prefixes are the same on each line, in other words,
3405  /// if a common prefix have a mix of spaces and tabulation characters, it should
3406  /// be the same for each line. Or this method can works incorrectly.
3407  /// Also, you can use Replace() first to replace tabulations and make whitespace
3408  /// consistent across lines.
3409  /// @sa
3410  /// Replace, DedentR
3411  static string Dedent(const CTempString str, TDedentFlags flags = 0);
3412 
3413  /// Dedent multi-line string, removing common whitespace prefix for each line.
3414  ///
3415  /// Version for RAW multi-line literals "R(...)", embedded into the C++ code.
3416  /// @example
3417  ///
3418  /// make_request(NStr::DedentR(R"(
3419  /// {
3420  /// "param1": some_val,
3421  /// "param2": another_val,
3422  /// "param3": "These lines are easy-to-read ",
3423  /// "param4": "and don't interrupt the flow of indentation."
3424  /// }
3425  /// )");
3426  /// @sa
3427  /// Dedent
3428  static string DedentR(const CTempString str);
3429 
3430  /// Search for a field.
3431  ///
3432  /// @param str
3433  /// C or C++ string to search in.
3434  /// @param field_no
3435  /// Zero-based field number.
3436  /// @param delimiters
3437  /// A set of single-character delimiters.
3438  /// @param merge
3439  /// Whether to merge or not adjacent delimiters. Default: not to merge.
3440  /// @return
3441  /// Found field; or empty string if the required field is not found.
3442  /// @note
3443  /// Field 0 spans up to the first-found delimiter or the end-of-string.
3444  static string GetField(const CTempString str,
3445  size_t field_no,
3446  const CTempString delimiters,
3447  EMergeDelims merge = eNoMergeDelims);
3448 
3449  /// Search for a field.
3450  ///
3451  /// @param str
3452  /// C or C++ string to search in.
3453  /// @param field_no
3454  /// Zero-based field number.
3455  /// @param delimiter
3456  /// A single-character delimiter.
3457  /// @param merge
3458  /// Whether to merge or not adjacent delimiters. Default: not to merge.
3459  /// @return
3460  /// Found field; or empty string if the required field is not found.
3461  /// @note
3462  /// Field 0 spans up to the delimiter or the end-of-string.
3463  static string GetField(const CTempString str,
3464  size_t field_no,
3465  char delimiter,
3466  EMergeDelims merge = eNoMergeDelims);
3467 
3468  /// Search for a field.
3469  /// Avoid memory allocation at the expense of some usage safety.
3470  ///
3471  /// @param str
3472  /// C or C++ string to search in.
3473  /// @param field_no
3474  /// Zero-based field number.
3475  /// @param delimiters
3476  /// A set of single-character delimiters.
3477  /// @param merge
3478  /// Whether to merge or not adjacent delimiters. Default: not to merge.
3479  /// @return
3480  /// Found field; or empty string if the required field is not found.
3481  /// @note
3482  /// Field 0 spans up to the first-found delimiter or the end-of-string.
3483  /// @warning
3484  /// The return value stores a pointer to the input string 'str' so
3485  /// the return object validity time matches lifetime of the input 'str'.
3486  static
3487  CTempString GetField_Unsafe(const CTempString str,
3488  size_t field_no,
3489  const CTempString delimiters,
3490  EMergeDelims merge = eNoMergeDelims);
3491 
3492  /// Search for a field.
3493  /// Avoid memory allocation at the expense of some usage safety.
3494  ///
3495  /// @param str
3496  /// C or C++ string to search in.
3497  /// @param field_no
3498  /// Zero-based field number.
3499  /// @param delimiter
3500  /// A single-character delimiter.
3501  /// @param merge
3502  /// Whether to merge or not adjacent delimiters. Default: not to merge.
3503  /// @return
3504  /// Found field; or empty string if the required field is not found.
3505  /// @note
3506  /// Field 0 spans up to the delimiter or the end-of-string.
3507  /// @warning
3508  /// The return value stores a pointer to the input string 'str' so
3509  /// the return object validity time matches lifetime of the input 'str'.
3510  static
3511  CTempString GetField_Unsafe(const CTempString str,
3512  size_t field_no,
3513  char delimiter,
3514  EMergeDelims merge = eNoMergeDelims);
3515 
3516 private:
3517 // implementations
3518 
3519 // StringToNumeric
3520  static bool x_ReportLimitsError(const CTempString str, TStringToNumFlags flags);
3521 
3522  template< typename TNumeric, typename TSource>
3524  {
3526  return x_ReportLimitsError(str, flags);
3527  }
3528  return true;
3529  }
3530  template< typename TNumeric, typename TSource>
3532  {
3533  // dont use ::min() for float types, it returns positive value
3535  return x_ReportLimitsError(str, flags);
3536  }
3537  return true;
3538  }
3539 
3540  template <typename TNumeric>
3541  requires std::signed_integral<TNumeric> && (sizeof(TNumeric) < sizeof(int))
3542  static TNumeric
3543  x_StringToNumeric(const CTempString str, TStringToNumFlags flags, int base)
3544  {
3545  int n = StringToInt(str, flags, base);
3546  return x_VerifyIntLimits<TNumeric>(n, str, flags) ? (TNumeric)n : 0;
3547  }
3548  template <typename TNumeric>
3549  requires std::unsigned_integral<TNumeric> && (sizeof(TNumeric) < sizeof(unsigned int))
3550  static TNumeric
3551  x_StringToNumeric(const CTempString str, TStringToNumFlags flags, int base)
3552  {
3553  unsigned int n = StringToUInt(str, flags, base);
3554  return x_VerifyIntLimits<TNumeric>(n, str, flags) ? (TNumeric)n : 0;
3555  }
3556 
3557  template <typename TNumeric>
3558  requires std::signed_integral<TNumeric> && (sizeof(TNumeric) == sizeof(int)) && (!std::same_as<TNumeric, long>)
3559  static TNumeric
3560  x_StringToNumeric(const CTempString str, TStringToNumFlags flags, int base)
3561  {
3562  return StringToInt(str, flags, base);
3563  }
3564  template <typename TNumeric>
3565  requires std::unsigned_integral<TNumeric> && (sizeof(TNumeric) == sizeof(unsigned int)) && (!std::same_as<TNumeric, unsigned long>)
3566  static TNumeric
3567  x_StringToNumeric(const CTempString str, TStringToNumFlags flags, int base)
3568  {
3569  return StringToUInt(str, flags, base);
3570  }
3571  template <typename TNumeric>
3572  requires std::same_as<TNumeric, long>
3573  static TNumeric
3575  {
3576  return StringToLong(str, flags, base);
3577  }
3578  template <typename TNumeric>
3579  requires std::same_as<TNumeric, unsigned long>
3580  static TNumeric
3582  {
3583  return StringToULong(str, flags, base);
3584  }
3585  template <typename TNumeric>
3586  requires std::signed_integral<TNumeric> && (sizeof(TNumeric) == sizeof(Int8)) && (!std::same_as<TNumeric, long>)
3587  static TNumeric
3588  x_StringToNumeric(const CTempString str, TStringToNumFlags flags, int base)
3589  {
3590  return StringToInt8(str, flags, base);
3591  }
3592  template <typename TNumeric>
3593  requires std::unsigned_integral<TNumeric> && (sizeof(TNumeric) == sizeof(Uint8)) && (!std::same_as<TNumeric, unsigned long>)
3594  static TNumeric
3595  x_StringToNumeric(const CTempString str, TStringToNumFlags flags, int base)
3596  {
3597  return StringToUInt8(str, flags, base);
3598  }
3599  template <typename TStrictId>
3600  static typename enable_if< is_integral<typename TStrictId::TId>::value && is_member_function_pointer<decltype(&TStrictId::Get)>::value, TStrictId>::type
3602  {
3603  return TStrictId(StringToNumeric<typename TStrictId::TId>(str, flags, base));
3604  }
3605 
3606  template <typename TNumeric>
3607  requires std::same_as<TNumeric, float>
3608  static TNumeric
3610  {
3611  double n = StringToDouble(str, flags);
3612  return x_VerifyFloatLimits<TNumeric>(n, str, flags) ? (TNumeric)n : 0;
3613  }
3614  template <typename TNumeric>
3615  requires std::same_as<TNumeric, double>
3616  static TNumeric
3618  {
3619  return StringToDouble(str, flags);
3620  }
3621 
3622  template <typename TNumeric>
3623  requires std::signed_integral<TNumeric> && (sizeof(TNumeric) < sizeof(int))
3624  static bool
3625  x_StringToNumeric(const CTempString str, TNumeric* value, TStringToNumFlags flags, int base)
3626  {
3627  int n = StringToInt(str, flags, base);
3628  *value = 0;
3629  if (( !n && errno ) || !x_VerifyIntLimits<TNumeric>(n, str, flags)) {
3630  return false;
3631  }
3632  *value = (TNumeric) n;
3633  return true;
3634  }
3635  template <typename TNumeric>
3636  requires std::unsigned_integral<TNumeric> && (sizeof(TNumeric) < sizeof(unsigned int))
3637  static bool
3638  x_StringToNumeric(const CTempString str, TNumeric* value, TStringToNumFlags flags, int base)
3639  {
3640  unsigned int n = StringToUInt(str, flags, base);
3641  *value = 0;
3642  if (( !n && errno ) || !x_VerifyIntLimits<TNumeric>(n, str, flags)) {
3643  return false;
3644  }
3645  *value = (TNumeric) n;
3646  return true;
3647  }
3648  template <typename TNumeric>
3649  requires std::signed_integral<TNumeric> && (sizeof(TNumeric) == sizeof(int)) && (!std::same_as<TNumeric, long>)
3650  static bool
3651  x_StringToNumeric(const CTempString str, TNumeric* value, TStringToNumFlags flags, int base)
3652  {
3653  *value = StringToInt(str, flags, base);
3654  return (*value || !errno);
3655  }
3656  template <typename TNumeric>
3657  requires std::unsigned_integral<TNumeric> && (sizeof(TNumeric) == sizeof(unsigned int)) && (!std::same_as<TNumeric, unsigned long>)
3658  static bool
3659  x_StringToNumeric(const CTempString str, TNumeric* value, TStringToNumFlags flags, int base)
3660  {
3661  *value = StringToUInt(str, flags, base);
3662  return (*value || !errno);
3663  }
3664  static bool
3665  x_StringToNumeric(const CTempString str, long* value, TStringToNumFlags flags, int base)
3666  {
3667  *value = StringToLong(str, flags, base);
3668  return (*value || !errno);
3669  }
3670  static bool
3671  x_StringToNumeric(const CTempString str, unsigned long* value, TStringToNumFlags flags, int base)
3672  {
3673  *value = StringToULong(str, flags, base);
3674  return (*value || !errno);
3675  }
3676  template <typename TNumeric>
3677  requires std::signed_integral<TNumeric> && (sizeof(TNumeric) == sizeof(Int8)) && (!std::same_as<TNumeric, long>)
3678  static bool
3679  x_StringToNumeric(const CTempString str, TNumeric* value, TStringToNumFlags flags, int base)
3680  {
3681  *value = StringToInt8(str, flags, base);
3682  return (*value || !errno);
3683  }
3684  template <typename TNumeric>
3685  requires std::unsigned_integral<TNumeric> && (sizeof(TNumeric) == sizeof(Uint8)) && (!std::same_as<TNumeric, unsigned long>)
3686  static bool
3687  x_StringToNumeric(const CTempString str, TNumeric* value, TStringToNumFlags flags, int base)
3688  {
3689  *value = StringToUInt8(str, flags, base);
3690  return (*value || !errno);
3691  }
3692  static bool
3693  x_StringToNumeric(const CTempString str, float* value, TStringToNumFlags flags, int /*base*/)
3694  {
3695  double n = StringToDouble(str, flags);
3696  *value = 0;
3697  if (( !n && errno ) || !x_VerifyFloatLimits<float>(n, str, flags)) {
3698  return false;
3699  }
3700  *value = (float) n;
3701  return true;
3702  }
3703  static bool
3704  x_StringToNumeric(const CTempString str, double* value, TStringToNumFlags flags, int /*base*/)
3705  {
3706  *value = StringToDouble(str, flags);
3707  return (*value || !errno);
3708  }
3709  template <typename TStrictId>
3710  static typename enable_if< is_integral<typename TStrictId::TId>::value && is_member_function_pointer<decltype(&TStrictId::Get)>::value, bool>::type
3712  {
3713  return x_StringToNumeric(str, &value->Set(), flags, base);
3714  }
3715 
3716 // NumericToString
3717  template<typename TNumeric>
3718  requires std::signed_integral<TNumeric> && (sizeof(TNumeric) <= sizeof(int)) && (!std::same_as<TNumeric, long>)
3719  static void
3720  x_NumericToString(string& out_str, TNumeric value, TNumToStringFlags flags, int base)
3721  {
3722  IntToString(out_str, value, flags, base);
3723  }
3724  template<typename TNumeric>
3725  requires std::unsigned_integral<TNumeric> && (sizeof(TNumeric) <= sizeof(unsigned int)) && (!std::same_as<TNumeric, unsigned long>)
3726  static void
3727  x_NumericToString(string& out_str, TNumeric value, TNumToStringFlags flags, int base)
3728  {
3729  UIntToString(out_str, value, flags, base);
3730  }
3731  static void
3732  x_NumericToString(string& out_str, long value, TNumToStringFlags flags, int base)
3733  {
3734  LongToString(out_str, value, flags, base);
3735  }
3736  static void
3737  x_NumericToString(string& out_str, unsigned long value, TNumToStringFlags flags, int base)
3738  {
3739  ULongToString(out_str, value, flags, base);
3740  }
3741 #if NCBI_COMPILER_MSVC && (_MSC_VER < 1900)
3742  static void
3743  x_NumericToString(string& out_str, Int8 value, TNumToStringFlags flags, int base)
3744  {
3745  Int8ToString(out_str, value, flags, base);
3746  }
3747  static void
3748  x_NumericToString(string& out_str, Uint8 value, TNumToStringFlags flags, int base)
3749  {
3750  UInt8ToString(out_str, value, flags, base);
3751  }
3752 #endif
3753  template<typename TNumeric>
3754  requires std::signed_integral<TNumeric> && (sizeof(TNumeric) == sizeof(Int8)) && (!std::same_as<TNumeric, long>)
3755  static void
3756  x_NumericToString(string& out_str, TNumeric value, TNumToStringFlags flags, int base)
3757  {
3758  Int8ToString(out_str, value, flags, base);
3759  }
3760  template<typename TNumeric>
3761  requires std::unsigned_integral<TNumeric> && (sizeof(TNumeric) == sizeof(Uint8)) && (!std::same_as<TNumeric, unsigned long>)
3762  static void
3763  x_NumericToString(string& out_str, TNumeric value, TNumToStringFlags flags, int base)
3764  {
3765  UInt8ToString(out_str, value, flags, base);
3766  }
3767  template<typename TNumeric>
3768  requires std::floating_point<TNumeric>
3769  static void
3770  x_NumericToString(string& out_str, TNumeric value, TNumToStringFlags flags, int /*base*/)
3771  {
3772  DoubleToString(out_str, value, -1, flags);
3773  }
3774  template <typename TStrictId>
3775  static typename enable_if< is_integral<typename TStrictId::TId>::value && is_member_function_pointer<decltype(&TStrictId::Get)>::value, void>::type
3776  x_NumericToString(string& out_str, TStrictId value, TNumToStringFlags flags, int base)
3777  {
3778  return x_NumericToString(out_str, value.Get(), flags, base);
3779  }
3780 
3781 
3782 // Join
3783  template<typename TIterator>
3784  static string xx_Join( TIterator from, TIterator to, const CTempString& delim);
3785 
3786  template<typename TIterator>
3787  requires std::same_as<typename TIterator::iterator_category, std::input_iterator_tag> &&
3788  std::convertible_to<typename TIterator::value_type, string>
3789  static string
3790  x_Join( TIterator from, TIterator to, const CTempString& delim)
3791  {
3792  return TransformJoin(from, to, delim, [](const typename TIterator::value_type& i){ return i;});
3793  }
3794 
3795  template<typename TIterator>
3796  requires std::convertible_to<typename TIterator::iterator_category, std::forward_iterator_tag> &&
3797  std::convertible_to<typename TIterator::value_type, string>
3798  static string
3799  x_Join( TIterator from, TIterator to, const CTempString& delim)
3800  {
3801  return xx_Join(from, to, delim);
3802  }
3803 
3804  template<typename TValue>
3805  requires std::convertible_to<TValue, string>
3806  static string
3807  x_Join( TValue* from, TValue* to, const CTempString& delim)
3808  {
3809  return xx_Join(from, to, delim);
3810  }
3811 
3812  template<typename TIterator>
3813  requires (std::integral<typename TIterator::value_type> || std::floating_point<typename TIterator::value_type>) &&
3814  std::convertible_to<typename TIterator::iterator_category, std::input_iterator_tag>
3815  static string
3816  x_Join( TIterator from, TIterator to, const CTempString& delim)
3817  {
3818  return TransformJoin( from, to, delim, [](const typename TIterator::value_type& i){ return NumericToString(i);});
3819  }
3820 
3821  template<typename TValue>
3822  requires std::integral<TValue> || std::floating_point<TValue>
3823  static string
3824  x_Join( TValue* from, TValue* to, const CTempString& delim)
3825  {
3826  return TransformJoin( from, to, delim, [](const TValue& i){ return NumericToString(i);});
3827  }
3828 }; // class NStr
3829 
3830 
3831 
3832 /////////////////////////////////////////////////////////////////////////////
3833 ///
3834 
3835 
3838 
3839 /// Type for character in UCS-2 encoding
3840 typedef char16_t TCharUCS2;
3841 /// Type for string in UCS-2 encoding
3842 typedef basic_string<TCharUCS2> TStringUCS2;
3843 
3844 
3845 /// Operator for writing TStringUCS2 to stream.
3846 /// Operator is needed for using in SDBAPI.
3848 {
3849  os.write((const char*)str.data(), str.size() * sizeof(TCharUCS2));
3850  return os;
3851 }
3852 
3853 
3854 
3855 /////////////////////////////////////////////////////////////////////////////
3856 ///
3857 /// CUtf8 --
3858 ///
3859 /// Utility class to handle strings in UTF8 encoding.
3860 /// Can convert data to and from the following encodings:
3861 /// ISO 8859-1 (Latin1)
3862 /// Microsoft Windows code page 1252
3863 /// UCS-2, UCS-4
3864 
3866 {
3867 public:
3868  /// How to verify character encoding of the source data
3869  enum EValidate {
3871  eValidate
3872  };
3873 
3874  /// Convert into UTF8 from a C/C++ string
3875  ///
3876  /// @param src
3877  /// Source string
3878  /// @param encoding
3879  /// Character encoding of the source string
3880  /// @param validate
3881  /// Verify the character encoding of the source
3882  static CStringUTF8 AsUTF8(const CTempString& src,
3883  EEncoding encoding,
3884  EValidate validate = eNoValidate)
3885  {
3886  CStringUTF8 u8;
3887  return x_Append(u8,src,encoding,validate);
3888  }
3889 
3890 #if defined(HAVE_WSTRING)
3891  /// Convert into UTF8 from a C/C++ string
3892  ///
3893  /// @param src
3894  /// Source string
3895  /// @param lcl
3896  /// String locale
3897  static CStringUTF8 AsUTF8(const CTempString& src, const locale& lcl)
3898  {
3899  CStringUTF8 u8;
3900  return x_Append(u8,src,lcl);
3901  }
3902 #endif
3903 
3904  /// Convert into UTF8 from a Unicode C++ string
3905  ///
3906  /// @param src
3907  /// Source string
3908  /// @attention
3909  /// Only for TStringUnicode, TStringUCS4, TStringUCS2, wstring types
3910  template <typename TChar>
3911  requires integral<TChar> && (sizeof(TChar) > 1)
3913  AsUTF8(const basic_string<TChar>& src)
3914  {
3915  CStringUTF8 u8;
3916  return x_Append(u8, src.data(), src.size());
3917  }
3918 
3919  /// Convert into UTF8 from a Unicode character buffer
3920  ///
3921  /// @param src
3922  /// Source character buffer
3923  /// @param tchar_count
3924  /// Number of characters in the buffer;
3925  /// If it equals to NPOS, buffer is assumed to be zero-terminated
3926  template <typename TChar>
3927  requires integral<TChar> && (sizeof(TChar) > 1)
3929  AsUTF8(const TChar* src, SIZE_TYPE tchar_count = NPOS)
3930  {
3931  CStringUTF8 u8;
3932  return x_Append(u8, src, tchar_count);
3933  }
3934 
3935  /// Convert Unicode C++ string into UTF8 and append it to existing string
3936  ///
3937  /// @param dest
3938  /// Existing UTF8 string
3939  /// @param src
3940  /// Source Unicode string
3941  /// return
3942  /// reference to modified dest string
3943  template <typename TChar>
3944  requires integral<TChar> && (sizeof(TChar) > 1)
3946  AppendAsUTF8(CStringUTF8& dest, const basic_string<TChar>& src)
3947  {
3948  return x_Append(dest, src.data(), src.size());
3949  }
3950 
3951  /// Convert Unicode character buffer into UTF8 and append it to existing string
3952  ///
3953  /// @param dest
3954  /// Existing UTF8 string
3955  /// @param src
3956  /// Source Unicode character buffer
3957  /// @param tchar_count
3958  /// Number of characters in the buffer;
3959  /// If it equals to NPOS, buffer is assumed to be zero-terminated
3960  /// return
3961  /// reference to modified dest string
3962  template <typename TChar>
3963  requires integral<TChar> && (sizeof(TChar) > 1)
3965  AppendAsUTF8(CStringUTF8& dest, const TChar* src, SIZE_TYPE tchar_count = NPOS)
3966  {
3967  return x_Append(dest, src, tchar_count);
3968  }
3969 
3970  /// Convert Unicode symbol into UTF8 and append it to existing string
3971  ///
3972  /// @param dest
3973  /// Existing UTF8 string
3974  /// @param ch
3975  /// Unicode symbol
3976  /// return
3977  /// reference to modified dest string
3978  template <typename TChar>
3979  requires integral<TChar> && (sizeof(TChar) > 1)
3981  AppendAsUTF8(CStringUTF8& dest, TChar ch)
3982  {
3983  return x_Append(dest, &ch, 1);
3984  }
3985 
3986  /// Convert non-Unicode C++ string into UTF8 and append it to existing string
3987  ///
3988  /// @param dest
3989  /// Existing UTF8 string
3990  /// @param src
3991  /// Source string
3992  /// @param encoding
3993  /// Character encoding of the source string
3994  /// @param validate
3995  /// Verify the character encoding of the source
3996  /// return
3997  /// reference to modified dest string
3998  static CStringUTF8& AppendAsUTF8(CStringUTF8& dest,
3999  const CTempString& src,
4000  EEncoding encoding,
4001  EValidate validate = eNoValidate)
4002  {
4003  return x_Append(dest,src,encoding,validate);
4004  }
4005 
4006 #if defined(HAVE_WSTRING)
4007  /// Convert non-Unicode C++ string into UTF8 and append it to existing string
4008  ///
4009  /// @param dest
4010  /// Existing UTF8 string
4011  /// @param src
4012  /// Source string
4013  /// @param lcl
4014  /// Source string locale
4015  /// return
4016  /// reference to modified dest string
4017  static CStringUTF8& AppendAsUTF8(CStringUTF8& dest,
4018  const CTempString& src,
4019  const locale& lcl)
4020  {
4021  return x_Append(dest,src,lcl);
4022  }
4023 #endif
4024 
4025  /// Convert non-Unicode character into UTF8 and append it to existing string
4026  ///
4027  /// @param dest
4028  /// Existing UTF8 string
4029  /// @param ch
4030  /// Character
4031  /// @param encoding
4032  /// Character encoding
4033  /// @param validate
4034  /// Verify the character encoding of the source
4035  /// return
4036  /// reference to modified dest string
4037  static CStringUTF8& AppendAsUTF8(CStringUTF8& dest,
4038  char ch,
4039  EEncoding encoding,
4040  EValidate validate = eNoValidate)
4041  {
4042  return x_Append(dest,CTempString(&ch,1),encoding,validate);
4043  }
4044 
4045 #if defined(HAVE_WSTRING)
4046  /// Convert non-Unicode character into UTF8 and append it to existing string
4047  ///
4048  /// @param dest
4049  /// Existing UTF8 string
4050  /// @param ch
4051  /// Character
4052  /// @param lcl
4053  /// Character locale
4054  /// return
4055  /// reference to modified dest string
4056  static CStringUTF8& AppendAsUTF8(CStringUTF8& dest,
4057  char ch,
4058  const locale& lcl)
4059  {
4060  return x_Append(dest,CTempString(&ch,1),lcl);
4061  }
4062 #endif
4063 
4064  /// Convert UTF8 string into a single-byte character representation
4065  ///
4066  /// Can throw a CStringException if the conversion is impossible
4067  /// or the string has invalid UTF-8 encoding.
4068  ///
4069  /// @param src
4070  /// Source UTF8 string
4071  /// @param encoding
4072  /// Encoding of the result
4073  /// @param substitute_on_error
4074  /// If the conversion is impossible, append the provided string
4075  /// or, if substitute_on_error equals 0, throw an exception
4076  /// @param validate
4077  /// Verify UTF8 character encoding of the source
4078  /// @return
4079  /// C++ string
4080  static string AsSingleByteString
4081  (const CTempString& src, EEncoding encoding,
4082  const char* substitute_on_error = 0, EValidate validate = eNoValidate);
4083 
4084 #if defined(HAVE_WSTRING)
4085  static string AsSingleByteString
4086  (const CTempString& src, const locale& lcl,
4087  const char* substitute_on_error = 0, EValidate validate = eNoValidate);
4088 #endif
4089 
4090  /// Convert UTF8 string into Unicode
4091  ///
4092  /// Can throw a CStringException if the conversion is impossible
4093  /// or the string has invalid UTF-8 encoding.
4094  ///
4095  /// @param src
4096  /// Source UTF8 string
4097  /// @param substitute_on_error
4098  /// If the conversion is impossible, append the provided string
4099  /// or, if substitute_on_error equals 0, throw an exception
4100  /// @param validate
4101  /// Verify UTF8 character encoding of the source
4102  /// @attention
4103  /// Only for TStringUnicode, TStringUCS4, TStringUCS2, wstring types
4104  template <typename TChar>
4105  requires integral<TChar> && (sizeof(TChar) > 1)
4106  static basic_string<TChar>
4107  AsBasicString(const CTempString& src, const TChar* substitute_on_error, EValidate validate = eNoValidate)
4108  {
4109  return x_AsBasicString(src,substitute_on_error,validate);
4110  }
4111 
4112  template <typename TChar>
4113  requires integral<TChar> && (sizeof(TChar) > 1)
4114  static basic_string<TChar>
4115  AsBasicString(const CTempString& src)
4116  {
4117  return x_AsBasicString<TChar>(src,nullptr,eNoValidate);
4118  }
4119 
4120  /// Get the number of symbols (code points) in UTF8 string
4121  ///
4122  /// @param src
4123  /// Source UTF8 string
4124  /// @return
4125  /// Number of symbols (code points)
4126  static SIZE_TYPE GetSymbolCount(const CTempString& src);
4127 
4128  /// Get the number of valid UTF-8 symbols (code points) in buffer
4129  ///
4130  /// @param src
4131  /// Character buffer
4132  /// @return
4133  /// Number of valid symbols (no exception thrown)
4134  static SIZE_TYPE GetValidSymbolCount(const CTempString& src);
4135 
4136  /// Get the number of valid UTF-8 bytes (code units) in buffer
4137  ///
4138  /// @param src
4139  /// Character buffer
4140  /// @return
4141  /// Number of valid bytes (no exception thrown)
4142  static SIZE_TYPE GetValidBytesCount(const CTempString& src);
4143 
4144  /// Check buffer for presence of UTF-8 byte sequence and return length of first symbol
4145  ///
4146  /// @param src
4147  /// Character buffer
4148  /// @return
4149  /// Number of bytes
4150  static SIZE_TYPE EvaluateSymbolLength(const CTempString& src);
4151 
4152  /// Check that the character is valid first byte of an UTF8 byte sequence
4153  ///
4154  /// @param ch
4155  /// Character
4156  /// @param more
4157  /// Number of additional bytes to expect
4158  /// @return
4159  /// true, if this is a valid first byte
4160  static bool EvaluateFirst(char ch, SIZE_TYPE& more) {
4161  return x_EvalFirst(ch, more);
4162  }
4163 
4164  /// Check that the character is valid continuation byte of an UTF8 byte sequence
4165  ///
4166  /// @param ch
4167  /// Character
4168  /// @return
4169  /// true, if this is a valid byte
4170  static bool EvaluateNext(char ch) {
4171  return x_EvalNext(ch);
4172  }
4173 
4174  /// Check the encoding of the C/C++ string
4175  ///
4176  /// Check that the encoding of the source is the same, or
4177  /// is compatible with the specified one
4178  /// @param src
4179  /// Source string
4180  /// @param encoding
4181  /// Character encoding form to check against
4182  /// @return
4183  /// Boolean result: encoding is same or compatible
4184  static bool MatchEncoding(const CTempString& src, EEncoding encoding);
4185 
4186  /// Guess the encoding of the C/C++ string
4187  ///
4188  /// It can distinguish between UTF-8, Latin1, and Win1252 only
4189  /// @param src
4190  /// Character buffer
4191  /// @return
4192  /// Encoding as guessed; eEncoding_Unknown if cannot guess
4193  static EEncoding GuessEncoding(const CTempString& src);
4194 
4195  /// Give Encoding name as string
4196  ///
4197  /// @param encoding
4198  /// EEncoding enum. (Throw CStringException if passed eEncoding_Unknown.)
4199  /// @return
4200  /// Encoding name
4201  static string EncodingToString(EEncoding encoding);
4202 
4203  /// Convert encoding name into EEncoding enum, taking into account synonyms
4204  /// as per http://www.iana.org/assignments/character-sets
4205  ///
4206  /// @param encoding_name
4207  /// Name of the encoding
4208  /// @return
4209  /// EEncoding enum; eEncoding_Unknown for unsupported encodings
4210  static EEncoding StringToEncoding(const CTempString& encoding_name);
4211 
4212  /// Convert encoded character into Unicode
4213  ///
4214  /// @param ch
4215  /// Encoded character
4216  /// @param encoding
4217  /// Character encoding
4218  /// @return
4219  /// Unicode code point (symbol)
4220  static TUnicodeSymbol CharToSymbol(char ch, EEncoding encoding);
4221 
4222 #if defined(HAVE_WSTRING)
4223  /// Convert encoded character into Unicode
4224  ///
4225  /// @param ch
4226  /// Encoded character
4227  /// @param lcl
4228  /// Character locale
4229  /// @return
4230  /// Unicode code point (symbol)
4231  static TUnicodeSymbol CharToSymbol(char ch, const locale& lcl);
4232 #endif
4233 
4234  /// Convert Unicode code point into encoded character
4235  ///
4236  /// @param sym
4237  /// Unicode code point (symbol)
4238  /// @param encoding
4239  /// Character encoding
4240  /// @return
4241  /// Encoded character
4242  static char SymbolToChar(TUnicodeSymbol sym, EEncoding encoding);
4243 
4244 #if defined(HAVE_WSTRING)
4245  /// Convert Unicode code point into encoded character
4246  ///
4247  /// @param sym
4248  /// Unicode code point (symbol)
4249  /// @param lcl
4250  /// Character locale
4251  /// @return
4252  /// Encoded character
4253  static char SymbolToChar(TUnicodeSymbol sym, const locale& lcl);
4254 #endif
4255 
4256  /// Determines if a symbol is whitespace
4257  /// per http://unicode.org/charts/uca/chart_Whitespace.html
4258  ///
4259  /// @param sym
4260  /// Unicode code point (symbol)
4261  /// @sa
4262  /// TruncateSpacesInPlace, TruncateSpaces_Unsafe, TruncateSpaces
4263  static bool IsWhiteSpace(TUnicodeSymbol sym);
4264 
4265  /// Truncate whitespace in the string (in-place)
4266  ///
4267  /// @param src
4268  /// UTF8 string
4269  /// @param side
4270  /// Which end of the string to truncate whitespace from.
4271  /// Default is to truncate whitespace from both ends.
4272  /// @return
4273  /// Reference to src
4274  /// @sa
4275  /// IsWhiteSpace, TruncateSpaces_Unsafe, TruncateSpaces
4276  static CStringUTF8& TruncateSpacesInPlace
4278 
4279  /// Truncate whitespace in the string
4280  ///
4281  /// @param str
4282  /// Source string, in UTF8 encoding
4283  /// @param side
4284  /// Which end of the string to truncate whitespace from.
4285  /// Default is to truncate whitespace from both ends.
4286  /// @sa
4287  /// IsWhiteSpace, TruncateSpacesInPlace, TruncateSpaces_Unsafe
4288  static CStringUTF8 TruncateSpaces
4289  (const CTempString& str, NStr::ETrunc side = NStr::eTrunc_Both);
4290 
4291  /// Truncate whitespace in the string
4292  ///
4293  /// @param str
4294  /// Source string, in UTF8 encoding
4295  /// @param side
4296  /// Which end of the string to truncate whitespace from.
4297  /// Default is to truncate whitespace from both ends.
4298  /// @attention
4299  /// The lifespan of the result string is the same as one of the source.
4300  /// So, for example, if the source is temporary string, then the result
4301  /// will be invalid right away (will point to already released memory).
4302  /// @sa
4303  /// IsWhiteSpace, TruncateSpacesInPlace, TruncateSpaces
4304  static CTempString TruncateSpaces_Unsafe
4305  (const CTempString& str, NStr::ETrunc side = NStr::eTrunc_Both);
4306 
4307  /// Convert sequence of UTF8 code units into Unicode code point
4308  ///
4309  /// @param src
4310  /// Zero-terminated buffer, in UTF8 encoding
4311  /// @return
4312  /// Unicode code point
4313  static TUnicodeSymbol Decode(const char*& src);
4314 
4315  /// Convert sequence of UTF8 code units into Unicode code point
4316  ///
4317  /// @param src
4318  /// C++ string iterator
4319  /// @return
4320  /// Unicode code point
4321  static TUnicodeSymbol Decode(string::const_iterator& src);
4322 
4323  /// Begin converting first character of UTF8 sequence into Unicode
4324  ///
4325  /// @param ch
4326  /// Character
4327  /// @param more
4328  /// If the character is valid, - how many more characters to expect
4329  /// @return
4330  /// Part of Unicode code point. Zero if the character is invalid.
4331  static TUnicodeSymbol DecodeFirst(char ch, SIZE_TYPE& more);
4332 
4333  /// Convert next character of UTF8 sequence into Unicode
4334  ///
4335  /// @param ch
4336  /// Character
4337  /// @param chU
4338  /// Incomplete Unicode code point
4339  /// @return
4340  /// Accumulated Unicode code point. Zero if the character is invalid.
4341  static TUnicodeSymbol DecodeNext(TUnicodeSymbol chU, char ch);
4342 
4343 private:
4344  static void x_Validate(const CTempString& str);
4345 
4346  static SIZE_TYPE x_GetValidSymbolCount
4347  (const CTempString& src, CTempString::const_iterator& err);
4348 
4349  static CStringUTF8& x_AppendChar(CStringUTF8& u8str, TUnicodeSymbol ch);
4350 
4351  static CStringUTF8& x_Append(CStringUTF8& u8str, const CTempString& src,
4352  EEncoding encoding, EValidate validate);
4353 #if defined(HAVE_WSTRING)
4354  static CStringUTF8& x_Append(CStringUTF8& u8str, const CTempString& src, const locale& lcl);
4355 #endif
4356  template <typename TChar>
4357  static bool x_TCharToUnicodeSymbol(TUnicodeSymbol& u, const TChar* src);
4358  template <typename TChar>
4359  static CStringUTF8& x_Append(CStringUTF8& u8str, const TChar* src, SIZE_TYPE tchar_count);
4360 
4361  template <typename TChar>
4362  static basic_string<TChar> x_AsBasicString
4363  (const CTempString& src,
4364  const TChar* substitute_on_error, EValidate validate);
4365 
4366  template <typename TIterator>
4367  static TUnicodeSymbol x_Decode(TIterator& src);
4368 
4369  static SIZE_TYPE x_BytesNeeded(TUnicodeSymbol ch);
4370  static bool x_EvalFirst(char ch, SIZE_TYPE& more);
4371  static bool x_EvalNext(char ch);
4372 
4373  // returns part of the string around an error in Utf8 encoding
4374  static CTempString x_GetErrorFragment(const CTempString& src);
4375 
4377 };
4378 
4379 // deprecated CStringUTF8 is there
4381 
4382 
4383 
4384 /////////////////////////////////////////////////////////////////////////////
4385 ///
4386 /// CParseTemplException --
4387 ///
4388 /// Define template class for parsing exception. This class is used to define
4389 /// exceptions for complex parsing tasks and includes an additional m_Pos
4390 /// data member. The constructor requires that an additional positional
4391 /// parameter be supplied along with the description message.
4392 
4393 template <class TBase>
4395 {
4396 public:
4397  /// Error types that for exception class.
4398  enum EErrCode {
4399  eErr ///< Generic error
4400  };
4401 
4402  /// Translate from the error code value to its string representation.
4403  virtual const char* GetErrCodeString(void) const override
4404  {
4405  switch (GetErrCode()) {
4406  case eErr: return "eErr";
4407  default: return CException::GetErrCodeString();
4408  }
4409  }
4410 
4411  /// Constructor.
4412  ///
4413  /// Report "pos" along with "what".
4415  const CException* prev_exception,
4416  EErrCode err_code,const string& message,
4417  string::size_type pos, EDiagSev severity = eDiag_Error)
4418  : TBase(info, prev_exception, message, severity, 0), m_Pos(pos)
4419  {
4420  this->x_Init(info,
4421  string("{") + NStr::SizetToString(m_Pos) +
4422  "} " + message,
4423  prev_exception,
4424  severity);
4425  this->x_InitErrCode((CException::EErrCode) err_code);
4426  }
4427 
4428  /// Constructor.
4430  : TBase(other)
4431  {
4432  m_Pos = other.m_Pos;
4433  this->x_Assign(other);
4434  }
4435 
4436  /// Destructor.
4437  virtual ~CParseTemplException(void) noexcept {}
4438 
4439  /// Report error position.
4440  virtual void ReportExtra(ostream& out) const override
4441  {
4442  out << "m_Pos = " << (unsigned long)m_Pos;
4443  }
4444 
4445  // Attributes.
4446 
4447  /// Get exception class type.
4448  virtual const char* GetType(void) const override
4449  { return "CParseTemplException"; }
4450 
4451  typedef int TErrCode;
4452  /// Get error code.
4453  TErrCode GetErrCode(void) const
4454  {
4455  return typeid(*this) == typeid(CParseTemplException<TBase>) ?
4456  (TErrCode) this->x_GetErrCode() :
4458  }
4459 
4460  /// Get error position.
4461  string::size_type GetPos(void) const noexcept { return m_Pos; }
4462 
4463 protected:
4465  const CException* prev_exception,
4466  const string& message,
4467  string::size_type pos, EDiagSev severity, CException::TFlags flags)
4468  : TBase(info, prev_exception, message, severity, flags), m_Pos(pos)
4469  {
4470  this->x_Init(info,
4471  string("{") + NStr::SizetToString(m_Pos) +
4472  "} " + message,
4473  prev_exception,
4474  severity);
4475  }
4476  /// Constructor.
4478  {
4479  m_Pos = 0;
4480  }
4481 
4482  /// Helper clone method.
4483  virtual const CException* x_Clone(void) const override
4484  {
4485  return new CParseTemplException<TBase>(*this);
4486  }
4487 
4488 private:
4489  string::size_type m_Pos; ///< Error position
4490 };
4491 
4492 
4493 /////////////////////////////////////////////////////////////////////////////
4494 ///
4495 /// CStringException --
4496 ///
4497 /// Define exceptions generated by string classes.
4498 ///
4499 /// CStringException inherits its basic functionality from
4500 /// CParseTemplException<CCoreException> and defines additional error codes
4501 /// for string parsing.
4502 
4504 {
4505 public:
4506  /// Error types that string classes can generate.
4507  enum EErrCode {
4508  eConvert, ///< Failure to convert string
4509  eBadArgs, ///< Bad arguments to string methods
4510  eFormat ///< Wrong format for any input to string methods
4511  };
4512 
4513  /// Translate from the error code value to its string representation.
4514  virtual const char* GetErrCodeString(void) const override;
4515 
4516  // Standard exception boilerplate code.
4518  CParseTemplException<CCoreException>, std::string::size_type);
4519 };
4520 
4521 
4522 
4523 /////////////////////////////////////////////////////////////////////////////
4524 ///
4525 /// CStringPairsParser --
4526 ///
4527 /// Base class for parsing a string to a set of name-value pairs.
4528 
4529 
4530 /// Decoder interface. Names and values can be decoded with different rules.
4532 {
4533 public:
4534  /// Type of string to be decoded
4537  eValue
4538  };
4539  /// Decode the string. Must throw CStringException if the source string
4540  /// is not valid.
4541  virtual string Decode(const CTempString src, EStringType stype) const = 0;
4542  virtual ~IStringDecoder(void) {}
4543 };
4544 
4545 
4546 /// Encoder interface. Names and values can be encoded with different rules.
4548 {
4549 public:
4550  /// Type of string to be decoded
4553  eValue
4554  };
4555  /// Encode the string.
4556  virtual string Encode(const CTempString src, EStringType stype) const = 0;
4557  virtual ~IStringEncoder(void) {}
4558 };
4559 
4560 
4561 /// URL-decoder for string pairs parser
4563 {
4564 public:
4566 
4567  virtual string Decode(const CTempString src, EStringType stype) const;
4568 
4569 private:
4571 };
4572 
4573 
4574 /// URL-encoder for string pairs parser
4576 {
4577 public:
4579 
4580  virtual string Encode(const CTempString src, EStringType stype) const;
4581 
4582 private:
4584 };
4585 
4586 
4587 /// Template for parsing string into pairs of name and value or merging
4588 /// them back into a single string.
4589 /// The container class must hold pairs of strings (pair<string, string>).
4590 template<class TContainer>
4592 {
4593 public:
4594  typedef TContainer TStrPairs;
4595  /// The container's value type must be pair<string, string>
4596  /// or a compatible type.
4598 
4599  /// Create parser with the specified decoder/encoder and default separators.
4600  ///
4601  /// @param decoder
4602  /// String decoder (Url, Xml etc.)
4603  /// @param own_decoder
4604  /// Decoder ownership flag
4605  /// @param decoder
4606  /// String encoder (Url, Xml etc.), optional
4607  /// @param own_encoder
4608  /// Encoder ownership flag, optional
4610  EOwnership own_decoder = eTakeOwnership,
4611  IStringEncoder* encoder = NULL,
4612  EOwnership own_encoder = eTakeOwnership)
4613  : m_ArgSep("&"),
4614  m_ValSep("="),
4615  m_Decoder(decoder, own_decoder),
4616  m_Encoder(encoder, own_encoder)
4617  {
4618  }
4619 
4620  /// Create parser with the specified parameters.
4621  ///
4622  /// @param arg_sep
4623  /// Separator between name+value pairs
4624  /// @param val_sep
4625  /// Separator between name and value
4626  /// @param decoder
4627  /// String decoder (Url, Xml etc.)
4628  /// @param own_decoder
4629  /// Decoder ownership flag
4630  /// @param encoder
4631  /// String encoder (Url, Xml etc.)
4632  /// @param own_encoder
4633  /// Encoder ownership flag
4634  CStringPairs(const CTempString arg_sep,
4635  const CTempString val_sep,
4636  IStringDecoder* decoder = NULL,
4637  EOwnership own_decoder = eTakeOwnership,
4638  IStringEncoder* encoder = NULL,
4639  EOwnership own_encoder = eTakeOwnership)
4640  : m_ArgSep(arg_sep),
4641  m_ValSep(val_sep),
4642  m_Decoder(decoder, own_decoder),
4643  m_Encoder(encoder, own_encoder)
4644  {
4645  }
4646 
4647  /// Create parser with the selected URL-encoding/decoding options
4648  /// and default separators.
4649  ///
4650  /// @param decode_flag
4651  /// URL-decoding flag
4652  /// @param encode_flag
4653  /// URL-encoding flag
4655  NStr::EUrlEncode encode_flag)
4656  : m_ArgSep("&"),
4657  m_ValSep("="),
4658  m_Decoder(new CStringDecoder_Url(decode_flag), eTakeOwnership),
4659  m_Encoder(new CStringEncoder_Url(encode_flag), eTakeOwnership)
4660  {
4661  }
4662 
4663  virtual ~CStringPairs(void) {}
4664 
4665  /// Set string decoder.
4666  ///
4667  /// @param decoder
4668  /// String decoder (Url, Xml etc.)
4669  /// @param own
4670  /// Decoder ownership flag
4672  { m_Decoder.reset(decoder, own); }
4673  /// Get decoder or NULL. Does not affect decoder ownership.
4675 
4676  /// Set string encoder.
4677  ///
4678  /// @param encoder
4679  /// String encoder (Url, Xml etc.)
4680  /// @param own
4681  /// Encoder ownership flag
4683  { m_Encoder.reset(encoder, own); }
4684  /// Get encoder or NULL. Does not affect encoder ownership.
4686 
4687  /// Parse the string.
4688  ///
4689  /// @param str
4690  /// String to parse. The parser assumes the string is formatted like
4691  /// "name1<valsep>value1<argsep>name2<valsep>value2...". Each name and
4692  /// value is passed to the decoder (if not NULL) before storing the pair.
4693  /// @param merge_argsep
4694  /// Flag for merging separators between pairs. By default the separators
4695  /// are merged to prevent pairs where both name and value are empty.
4696  void Parse(const CTempString str,
4697  NStr::EMergeDelims merge_argsep = NStr::eMergeDelims)
4698  {
4700  m_Decoder.get(), eNoOwnership, merge_argsep);
4701  }
4702 
4703  /// Parse the string using the provided decoder, put data into the
4704  /// container.
4705  ///
4706  /// @param pairs
4707  /// Container to be filled with the parsed name/value pairs
4708  /// @param str
4709  /// String to parse. The parser assumes the string is formatted like
4710  /// "name1<valsep>value1<argsep>name2<valsep>value2...". Each name and
4711  /// value is passed to the decoder (if not NULL) before storing the pair.
4712  /// @param decoder
4713  /// String decoder (Url, Xml etc.)
4714  /// @param own
4715  /// Flag indicating if the decoder must be deleted by the function.
4716  /// @param merge_argsep
4717  /// Flag for merging separators between pairs. By default the separators
4718  /// are merged to prevent pairs where both name and value are empty.
4719  static void Parse(TStrPairs& pairs,
4720  const CTempString str,
4721  const CTempString arg_sep,
4722  const CTempString val_sep,
4723  IStringDecoder* decoder = NULL,
4724  EOwnership own = eTakeOwnership,
4725  NStr::EMergeDelims merge_argsep = NStr::eMergeDelims)
4726  {
4727  AutoPtr<IStringDecoder> decoder_guard(decoder, own);
4728  list<string> lst;
4729  NStr::Split(str, arg_sep, lst, (NStr::TSplitFlags)merge_argsep);
4730  pairs.clear();
4731  ITERATE(list<string>, it, lst) {
4732  string name, val;
4733  NStr::SplitInTwo(*it, val_sep, name, val);
4734  if ( decoder ) {
4735  try {
4736  name = decoder->Decode(name, IStringDecoder::eName);
4737  val = decoder->Decode(val, IStringDecoder::eValue);
4738  }
4739  catch (const CStringException&) {
4740  // Discard all data
4741  pairs.clear();
4742  throw;
4743  }
4744  }
4745  pairs.insert(pairs.end(), TStrPair(name, val));
4746  }
4747  }
4748 
4749  /// Merge name-value pairs into a single string using the currently set
4750  /// separators and the provided encoder if any.
4751  string Merge(void) const
4752  {
4753  return Merge(m_Data, m_ArgSep, m_ValSep,
4755  }
4756 
4757  /// Merge name-value pairs from the provided container, separators
4758  /// and encoder. Delete the encoder if the ownership flag allows.
4759  ///
4760  /// @param pairs
4761  /// Container with the name/value pairs to be merged.
4762  /// @param arg_sep
4763  /// Separator to be inserted between pairs.
4764  /// @param val_sep
4765  /// Separator to be inserted between name and value.
4766  /// @param encoder
4767  /// String encoder (Url, Xml etc.)
4768  /// @param own
4769  /// Flag indicating if the encoder must be deleted by the function.
4770  static string Merge(const TStrPairs& pairs,
4771  const string& arg_sep,
4772  const string& val_sep,
4773  IStringEncoder* encoder = NULL,
4774  EOwnership own = eTakeOwnership)
4775  {
4776  AutoPtr<IStringEncoder> encoder_guard(encoder, own);
4777  string ret;
4778  ITERATE(typename TStrPairs, it, pairs) {
4779  if ( !ret.empty() ) {
4780  ret += arg_sep;
4781  }
4782  if ( encoder ) {
4783  ret += encoder->Encode(it->first, IStringEncoder::eName) +
4784  val_sep +
4785  encoder->Encode(it->second, IStringEncoder::eValue);
4786  }
4787  else {
4788  ret += it->first + val_sep + it->second;
4789  }
4790  }
4791  return ret;
4792  }
4793 
4794  /// Read data
4795  const TStrPairs& GetPairs(void) const { return m_Data; }
4796  /// Get non-const data
4797  TStrPairs& GetPairs(void) { return m_Data; }
4798 
4799 private:
4800  string m_ArgSep; // Separator between name+value pairs ("&")
4801  string m_ValSep; // Separator between name and value ("=")
4802  AutoPtr<IStringDecoder> m_Decoder; // String decoder (Url, Xml etc.)
4803  AutoPtr<IStringEncoder> m_Encoder; // String encoder (Url, Xml etc.)
4804  TStrPairs m_Data; // Parsed data
4805 };
4806 
4807 
4808 typedef vector<pair<string, string> > TStringPairsVector;
4810 
4811 
4812 /////////////////////////////////////////////////////////////////////////////
4813 ///
4814 /// CEncodedString --
4815 ///
4816 /// Class to detect if a string needs to be URL-encoded and hold both
4817 /// encoded and original versions.
4818 ///
4819 
4821 {
4822 public:
4824  CEncodedString(const CTempString s,
4826 
4827  /// Set new original string
4828  void SetString(const CTempString s,
4830 
4831  /// Check if the original string was encoded.
4832  bool IsEncoded(void) const { return m_Encoded.get() != 0; }
4833  /// Get the original unencoded string
4834  const string& GetOriginalString(void) const { return m_Original; }
4835  /// Get encoded string
4836  const string& GetEncodedString(void) const
4837  { return IsEncoded() ? *m_Encoded : m_Original; }
4838 
4839  /// Check if the string is empty
4840  bool IsEmpty(void) const { return m_Original.empty(); }
4841 
4842 private:
4843  string m_Original;
4844  unique_ptr<string> m_Encoded;
4845 };
4846 
4847 
4848 /////////////////////////////////////////////////////////////////////////////
4849 // Predicates
4850 //
4851 
4852 
4853 /////////////////////////////////////////////////////////////////////////////
4854 ///
4855 /// Define Case-sensitive string comparison methods.
4856 ///
4857 /// Used as arguments to template functions for specifying the type of
4858 /// comparison.
4859 
4860 template <typename T>
4862 {
4863  /// Return difference between "s1" and "s2".
4864  int Compare(const T& s1, const T& s2) const;
4865 
4866  /// Return TRUE if s1 < s2.
4867  bool Less(const T& s1, const T& s2) const;
4868 
4869  /// Return TRUE if s1 == s2.
4870  bool Equals(const T& s1, const T& s2) const;
4871 
4872  /// Return TRUE if s1 < s2.
4873  bool operator()(const T& s1, const T& s2) const;
4874 };
4875 
4878 
4879 
4880 
4881 /////////////////////////////////////////////////////////////////////////////
4882 ///
4883 /// Define Case-insensitive string comparison methods.
4884 ///
4885 /// Used as arguments to template functions for specifying the type of
4886 /// comparison.
4887 ///
4888 /// @sa PNocase_Conditional_Generic
4889 
4890 template <typename T>
4892 {
4893  /// Return difference between "s1" and "s2".
4894  int Compare(const T& s1, const T& s2) const;
4895 
4896  /// Return TRUE if s1 < s2.
4897  bool Less(const T& s1, const T& s2) const;
4898 
4899  /// Return TRUE if s1 == s2.
4900  bool Equals(const T& s1, const T& s2) const;
4901 
4902  /// Return TRUE if s1 < s2 ignoring case.
4903  bool operator()(const T& s1, const T& s2) const;
4904 };
4905 
4908 
4909 
4910 /////////////////////////////////////////////////////////////////////////////
4911 ///
4912 /// Define Case-insensitive string comparison methods.
4913 /// Case sensitivity can be turned on and off at runtime.
4914 ///
4915 /// Used as arguments to template functions for specifying the type of
4916 /// comparison.
4917 ///
4918 /// @sa PNocase_Generic
4919 
4920 template <typename T>
4922 {
4923 public:
4924  /// Construction
4926 
4927  /// Get comparison type
4929 
4930  /// Set comparison type
4931  void SetCase(NStr::ECase case_sens) { m_CaseSensitive = case_sens; }
4932 
4933  /// Return difference between "s1" and "s2".
4934  int Compare(const T& s1, const T& s2) const;
4935 
4936  /// Return TRUE if s1 < s2.
4937  bool Less(const T& s1, const T& s2) const;
4938 
4939  /// Return TRUE if s1 == s2.
4940  bool Equals(const T& s1, const T& s2) const;
4941 
4942  /// Return TRUE if s1 < s2 ignoring case.
4943  bool operator()(const T& s1, const T& s2) const;
4944 private:
4945  NStr::ECase m_CaseSensitive; ///< case sensitive when TRUE
4946 };
4947 
4950 
4951 
4952 /////////////////////////////////////////////////////////////////////////////
4953 ///
4954 /// Define Case-insensitive string equality (not less-than) comparison method
4955 ///
4956 /// Used as arguments to template functions for specifying the type of
4957 /// equality comparison
4958 ///
4959 /// @sa PEqualNocase_Conditional_Generic
4960 
4961 template <typename T>
4963  : public PNocase_Generic<T>
4964 {
4965 public:
4966  /// Return TRUE if s1 < s2 ignoring case.
4967  bool operator()(const T& s1, const T& s2) const
4968  {
4969  return this->Equals(s1, s2);
4970  }
4971 };
4972 
4975 
4976 
4977 /////////////////////////////////////////////////////////////////////////////
4978 ///
4979 /// Define Case-insensitive string equality (not less-than) comparison method
4980 /// Case sensitivity can be turned on and off at runtime.
4981 ///
4982 /// Used as arguments to template functions for specifying the type of
4983 /// comparison.
4984 ///
4985 /// @sa PEqualNocase_Generic
4986 
4987 template <typename T>
4989  : public PNocase_Conditional_Generic<T>
4990 {
4991 public:
4992  /// Construction
4994  : PNocase_Conditional_Generic<T>(case_sens)
4995  {
4996  }
4997 
4998  /// Return TRUE if s1 < s2 ignoring case.
4999  bool operator()(const T& s1, const T& s2) const
5000  {
5001  return this->Equals(s1, s2);
5002  }
5003 };
5004 
5007 
5008 /////////////////////////////////////////////////////////////////////////////
5009 ///
5010 /// PQuickStringLess implements an ordering of strings,
5011 /// that is more efficient than usual lexicographical order.
5012 /// It can be used in cases when no specific order is required,
5013 /// e.g. only simple key lookup is needed.
5014 /// Current implementation first compares lengths of strings,
5015 /// and will compare string data only when lengths are the same.
5016 ///
5018 {
5019  bool operator()(const CTempString s1, const CTempString s2) const {
5020  size_t len1 = s1.size(), len2 = s2.size();
5021  return len1 < len2 ||
5022  (len1 == len2 && ::memcmp(s1.data(), s2.data(), len1) < 0);
5023  }
5024 };
5025 
5026 
5027 /////////////////////////////////////////////////////////////////////////////
5028 // Algorithms
5029 //
5030 
5031 
5032 /// Check equivalence of arguments using predicate.
5033 template<class Arg1, class Arg2, class Pred>
5034 inline
5035 bool AStrEquiv(const Arg1& x, const Arg2& y, Pred pr)
5036 {
5037  return pr.Equals(x, y);
5038 }
5039 
5040 
5041 /* @} */
5042 
5043 
5044 
5045 /////////////////////////////////////////////////////////////////////////////
5046 //
5047 // IMPLEMENTATION of INLINE functions
5048 //
5049 /////////////////////////////////////////////////////////////////////////////
5050 
5051 
5052 /////////////////////////////////////////////////////////////////////////////
5053 // NStr::
5054 //
5055 
5056 inline
5058  TNumToStringFlags flags, int base)
5059 {
5060  string ret;
5061  IntToString(ret, value, flags, base);
5062  return ret;
5063 }
5064 
5065 inline
5066 string NStr::IntToString(unsigned int value,
5067  TNumToStringFlags flags, int base)
5068 {
5069  string ret;
5070  IntToString(ret, (int)value, flags, base);
5071  return ret;
5072 }
5073 
5074 inline
5075 void NStr::IntToString(string& out_str, unsigned int value,
5076  TNumToStringFlags flags, int base)
5077 {
5078  IntToString(out_str, (int)value, flags, base);
5079 }
5080 
5081 inline
5082 string NStr::UIntToString(unsigned int value,
5083  TNumToStringFlags flags, int base)
5084 {
5085  string ret;
5086  ULongToString(ret, value, flags, base);
5087  return ret;
5088 }
5089 
5090 inline
5092  TNumToStringFlags flags, int base)
5093 {
5094  string ret;
5095  UIntToString(ret, (unsigned int)value, flags, base);
5096  return ret;
5097 }
5098 
5099 inline
5100 void NStr::UIntToString(string& out_str, unsigned int value,
5101  TNumToStringFlags flags, int base)
5102 {
5103  ULongToString(out_str, value, flags, base);
5104 }
5105 
5106 inline
5107 void NStr::UIntToString(string& out_str, int value,
5108  TNumToStringFlags flags, int base)
5109 {
5110  UIntToString(out_str, (unsigned int)value, flags, base);
5111 }
5112 
5113 inline
5115  TNumToStringFlags flags, int base)
5116 {
5117  string ret;
5118  LongToString(ret, value, flags, base);
5119  return ret;
5120 }
5121 
5122 inline
5123 string NStr::ULongToString(unsigned long value,
5124  TNumToStringFlags flags, int base)
5125 {
5126  string ret;
5127  ULongToString(ret, value, flags, base);
5128  return ret;
5129 }
5130 
5131 inline
5133  TNumToStringFlags flags, int base)
5134 {
5135  string ret;
5137  return ret;
5138 }
5139 
5140 inline
5142  TNumToStringFlags flags, int base)
5143 {
5144  string ret;
5146  return ret;
5147 }
5148 
5149 inline
5151  TNumToStringFlags flags /* = 0 */,
5152  unsigned int max_digits /* = 3 */)
5153 {
5154  string ret;
5155  NStr::UInt8ToString_DataSize(ret, value, flags, max_digits);
5156  return ret;
5157 }
5158 
5159 inline
5162 {
5163  string str;
5165  return str;
5166 }
5167 
5168 inline
5169 int NStr::HexChar(char ch)
5170 {
5171  unsigned int rc = ch - '0';
5172  if (rc <= 9) {
5173  return rc;
5174  } else {
5175  rc = (ch | ' ') - 'a';
5176  return rc <= 5 ? int(rc + 10) : -1;
5177  }
5178 }
5179 
5180 inline
5181 int NStr::strcmp(const char* s1, const char* s2)
5182 {
5183  return ::strcmp(s1, s2);
5184 }
5185 
5186 inline
5187 int NStr::strncmp(const char* s1, const char* s2, size_t n)
5188 {
5189  return ::strncmp(s1, s2, n);
5190 }
5191 
5192 inline
5193 int NStr::strcasecmp(const char* s1, const char* s2)
5194 {
5195 #if defined(HAVE_STRICMP)
5196 #if NCBI_COMPILER_MSVC && (_MSC_VER >= 1400)
5197  return ::_stricmp(s1, s2);
5198 #else
5199  return ::stricmp(s1, s2);
5200 #endif
5201 
5202 #elif defined(HAVE_STRCASECMP_LC)
5203  return ::strcasecmp(s1, s2);
5204 
5205 #else
5206  int diff = 0;
5207  for ( ;; ++s1, ++s2) {
5208  char c1 = *s1;
5209  // calculate difference
5210  diff = tolower((unsigned char) c1) - tolower((unsigned char)(*s2));
5211  // if end of string or different
5212  if (!c1 || diff)
5213  break; // return difference
5214  }
5215  return diff;
5216 #endif
5217 }
5218 
5219 inline
5220 int NStr::strncasecmp(const char* s1, const char* s2, size_t n)
5221 {
5222 #if defined(HAVE_STRICMP)
5223 #if NCBI_COMPILER_MSVC && (_MSC_VER >= 1400)
5224  return ::_strnicmp(s1, s2, n);
5225 #else
5226  return ::strnicmp(s1, s2, n);
5227 #endif
5228 
5229 #elif defined(HAVE_STRCASECMP_LC)
5230  return ::strncasecmp(s1, s2, n);
5231 
5232 #else
5233  int diff = 0;
5234  for ( ; ; ++s1, ++s2, --n) {
5235  if (n == 0)
5236  return 0;
5237  char c1 = *s1;
5238  // calculate difference
5239  diff = tolower((unsigned char) c1) - tolower((unsigned char)(*s2));
5240  // if end of string or different
5241  if (!c1 || diff)
5242  break; // return difference
5243  }
5244  return diff;
5245 #endif
5246 }
5247 
5248 inline
5249 size_t NStr::strftime(char* s, size_t maxsize, const char* format,
5250  const struct tm* timeptr)
5251 {
5252  string x_format = Replace(format, "%T", "%H:%M:%S");
5253  ReplaceInPlace(x_format, "%D", "%m/%d/%y");
5254  return ::strftime(s, maxsize, x_format.c_str(), timeptr);
5255 }
5256 
5257 inline
5258 int NStr::CompareCase(const char* s1, const char* s2)
5259 {
5260  return NStr::strcmp(s1, s2);
5261 }
5262 
5263 inline
5264 int NStr::CompareNocase(const char* s1, const char* s2)
5265 {
5266  return NStr::strcasecmp(s1, s2);
5267 }
5268 
5269 inline
5271  const char* s2, ECase use_case)
5272 {
5273  return use_case == eCase ? CompareCase(s1.substr(pos, n), s2)
5274  : CompareNocase(s1.substr(pos, n), s2);
5275 }
5276 
5277 inline
5279  const CTempString s2, ECase use_case)
5280 {
5281  return use_case == eCase ? CompareCase(s1.substr(pos, n), s2)
5282  : CompareNocase(s1.substr(pos, n), s2);
5283 }
5284 
5285 inline
5286 int NStr::Compare(const char* s1, const char* s2, ECase use_case)
5287 {
5288  return use_case == eCase ? CompareCase(s1, s2) : CompareNocase(s1, s2);
5289 }
5290 
5291 inline
5292 int NStr::Compare(const CTempStringEx s1, const CTempStringEx s2, ECase use_case)
5293 {
5294  return use_case == eCase ? CompareCase(s1, s2) : CompareNocase(s1, s2);
5295 }
5296 
5297 inline
5298 bool NStr::EqualCase(const CTempString s1, SIZE_TYPE pos, SIZE_TYPE n, const char* s2)
5299 {
5300  return s1.substr(pos, n) == s2;
5301 }
5302 
5303 inline
5305 {
5306  return s1.substr(pos, n) == s2;
5307 }
5308 
5309 inline
5310 bool NStr::EqualCase(const char* s1, const char* s2)
5311 {
5312  size_t n = strlen(s1);
5313  if (n != strlen(s2)) {
5314  return false;
5315  }
5316  return NStr::strncmp(s1, s2, n) == 0;
5317 }
5318 
5319 inline
5321 {
5322  return s1 == s2;
5323 }
5324 
5325 inline
5326 bool NStr::EqualNocase(const CTempString s1, SIZE_TYPE pos, SIZE_TYPE n, const char* s2)
5327 {
5328  return CompareNocase(s1.substr(pos, n), s2) == 0;
5329 }
5330 
5331 inline
5333 {
5334  return CompareNocase(s1.substr(pos, n), s2) == 0;
5335 }
5336 
5337 inline
5338 bool NStr::EqualNocase(const char* s1, const char* s2)
5339 {
5340  size_t n = strlen(s1);
5341  if (n != strlen(s2)) {
5342  return false;
5343  }
5344  return NStr::strncasecmp(s1, s2, n) == 0;
5345 }
5346 
5347 inline
5349 {
5350  if (s1.length() != s2.length()) {
5351  return false;
5352  }
5353  return CompareNocase(s1, s2) == 0;
5354 }
5355 
5356 inline
5358  const char* s2, ECase use_case)
5359 {
5360  return use_case == eCase ? EqualCase(s1.substr(pos, n), s2)
5361  : EqualNocase(s1.substr(pos, n), s2);
5362 }
5363 
5364 inline
5366  const CTempString s2, ECase use_case)
5367 {
5368  return use_case == eCase ? EqualCase(s1.substr(pos, n), s2)
5369  : EqualNocase(s1.substr(pos, n), s2);
5370 }
5371 
5372 inline
5373 bool NStr::Equal(const char* s1, const char* s2, ECase use_case)
5374 {
5375  return use_case == eCase ? EqualCase(s1, s2) : EqualNocase(s1, s2);
5376 }
5377 
5378 inline
5379 bool NStr::Equal(const CTempStringEx s1, const CTempStringEx s2, ECase use_case)
5380 {
5381  return use_case == eCase ? EqualCase(s1, s2) : EqualNocase(s1, s2);
5382 }
5383 
5384 inline
5385 bool NStr::StartsWith(const CTempString str, const CTempString start, ECase use_case)
5386 {
5387  return str.size() >= start.size() &&
5388  Equal(str.substr(0, start.size()), start, use_case);
5389 }
5390 
5391 inline
5392 bool NStr::StartsWith(const CTempString str, char start, ECase use_case)
5393 {
5394  return !str.empty() &&
5395  (use_case == eCase ? (str[0] == start)
5396  : (str[0] == start ||
5397  toupper((unsigned char) str[0]) == start ||
5398  tolower((unsigned char) str[0]))
5399  );
5400 }
5401 
5402 inline
5403 bool NStr::EndsWith(const CTempString str, const CTempString end, ECase use_case)
5404 {
5405  return str.size() >= end.size() &&
5406  Equal(str.substr(str.size() - end.size(), end.size()), end, use_case);
5407 }
5408 
5409 inline
5410 bool NStr::EndsWith(const CTempString str, char end, ECase use_case)
5411 {
5412  if (!str.empty()) {
5413  char last = str[str.length() - 1];
5414  return use_case == eCase ? (last == end)
5415  : (last == end ||
5416  toupper((unsigned char) last) == end ||
5417  tolower((unsigned char) last) == end);
5418  }
5419  return false;
5420 }
5421 
5422 inline
5424 {
5425  const SIZE_TYPE n = min(s1.length(), s2.length());
5426  for (SIZE_TYPE i = 0; i < n; i++) {
5427  if (s1[i] != s2[i]) {
5428  return i;
5429  }
5430  }
5431  return n;
5432 }
5433 
5434 inline
5436 {
5437  const SIZE_TYPE len1 = s1.length();
5438  const SIZE_TYPE len2 = s2.length();
5439  const SIZE_TYPE n = min(len1, len2);
5440  for (SIZE_TYPE i = 1; i <= n; i++) {
5441  if (s1[len1 - i] != s2[len2 - i]) {
5442  return i - 1;
5443  }
5444  }
5445  return n;
5446 }
5447 
5448 inline
5450  SIZE_TYPE start, SIZE_TYPE end, EOccurrence where,
5451  ECase use_case)
5452 {
5453  SIZE_TYPE pos = Find(CTempString(str, start, end - start), pattern, use_case,
5454  where == eFirst ? eForwardSearch : eReverseSearch, 0);
5455  if (pos == NPOS) {
5456  return NPOS;
5457  }
5458  return pos + start;
5459 }
5460 
5461 // @deprecated
5462 inline
5464  SIZE_TYPE start, SIZE_TYPE end, EOccurrence where)
5465 {
5466  if (where == eFirst) {
5467  SIZE_TYPE pos = str.find(pattern, start);
5468  return (pos == NPOS || (pos + pattern.length()) > end) ? NPOS : pos;
5469  } else {
5470  SIZE_TYPE pos = str.rfind(pattern, end);
5471  return (pos == NPOS || pos < start) ? NPOS : pos;
5472  }
5473 }
5474 
5475 inline
5477 {
5478  return Find(str, pattern, eCase);
5479 }
5480 
5481 inline
5483 {
5484  SIZE_TYPE pos = Find(CTempString(str, start), pattern, eCase);
5485  if (pos == NPOS) {
5486  return NPOS;
5487  }
5488  return pos + start;
5489 }
5490 
5491 inline
5493 {
5494  return Find(str, pattern, eNocase);
5495 }
5496 
5497 inline
5499 {
5500  SIZE_TYPE pos = Find(CTempString(str, start), pattern, eNocase);
5501  if (pos == NPOS) {
5502  return NPOS;
5503  }
5504  return pos + start;
5505 }
5506 
5507 inline
5508 const string* NStr::FindCase(const list<string>& lst, const CTempString val)
5509 {
5510  return Find(lst, val, eCase);
5511 }
5512 
5513 inline
5514 const string* NStr::FindNoCase(const list <string>& lst, const CTempString val)
5515 {
5516  return Find(lst, val, eNocase);
5517 }
5518 
5519 inline
5520 const string* NStr::FindCase(const vector <string>& vec, const CTempString val)
5521 {
5522  return Find(vec, val, eCase);
5523 }
5524 
5525 inline
5526 const string* NStr::FindNoCase(const vector <string>& vec, const CTempString val)
5527 {
5528  return Find(vec, val, eNocase);
5529 }
5530 
5531 template<typename TIterator, typename FTransform>
5532 string
5533 NStr::TransformJoin( TIterator from, TIterator to, const CTempString& delim, FTransform fnTransform)
5534 {
5535  if (from == to) {
5536  return kEmptyStr;
5537  }
5538  string result(fnTransform(*from++));
5539  for ( ; from != to; ++from) {
5540  result.append(delim).append(fnTransform(*from));
5541  }
5542  return result;
5543 }
5544 
5545 template<typename TIterator>
5546 string
5548 {
5549  if (from == to) {
5550  return kEmptyStr;
5551  }
5552  string result(*from++);
5553  size_t sz_all = 0, sz_delim = delim.size();
5554  for ( TIterator f = from; f != to; ++f) {
5555  sz_all += string(*f).size() + sz_delim;
5556  }
5557  result.reserve(result.size() + sz_all);
5558  for ( ; from != to; ++from) {
5559  result.append(delim).append(string(*from));
5560  }
5561  return result;
5562 }
5563 
5564 inline
5565 list<string>& NStr::Wrap(const string& str, SIZE_TYPE width, list<string>& arr,
5566  NStr::TWrapFlags flags, const string& prefix,
5567  const string* prefix1)
5568 {
5569  return Wrap(str, width, arr, flags, &prefix, prefix1);
5570 }
5571 
5572 inline
5573 list<string>& NStr::Wrap(const string& str, SIZE_TYPE width, list<string>& arr,
5574  NStr::TWrapFlags flags, const string& prefix,
5575  const string& prefix1)
5576 {
5577  return Wrap(str, width, arr, flags, &prefix, &prefix1);
5578 }
5579 
5580 inline
5581 list<string>& NStr::WrapList(const list<string>& l, SIZE_TYPE width,
5582  const string& delim, list<string>& arr,
5583  NStr::TWrapFlags flags, const string& prefix,
5584  const string* prefix1)
5585 {
5586  return WrapList(l, width, delim, arr, flags, &prefix, prefix1);
5587 }
5588 
5589 inline
5590 list<string>& NStr::WrapList(const list<string>& l, SIZE_TYPE width,
5591  const string& delim, list<string>& arr,
5592  NStr::TWrapFlags flags, const string& prefix,
5593  const string& prefix1)
5594 {
5595  return WrapList(l, width, delim, arr, flags, &prefix, &prefix1);
5596 }
5597 
5598 inline
5599 list<string>& NStr::Justify(const CTempString str, SIZE_TYPE width,
5600  list<string>& par, const CTempString pfx,
5601  const CTempString* pfx1)
5602 {
5603  return Justify(str, width, par, &pfx, pfx1);
5604 }
5605 
5606 inline
5607 list<string>& NStr::Justify(const CTempString str, SIZE_TYPE width,
5608  list<string>& par, const CTempString pfx,
5609  const CTempString pfx1)
5610 {
5611  return Justify(str, width, par, &pfx, &pfx1);
5612 }
5613 
5614 inline
5616 {
5618 }
5619 
5620 
5621 /////////////////////////////////////////////////////////////////////////////
5622 // CUtf8::
5623 //
5624 
5627  return x_GetValidSymbolCount(src, err);
5628 }
5629 
5632  x_GetValidSymbolCount(src,err);
5633  return (err-src.begin());
5634 }
5635 inline TUnicodeSymbol CUtf8::Decode(const char*& src) {
5636  return x_Decode(src);
5637 }
5638 inline TUnicodeSymbol CUtf8::Decode(string::const_iterator& src) {
5639  return x_Decode(src);
5640 }
5641 
5642 template <typename TIterator> inline TUnicodeSymbol
5644 {
5645  SIZE_TYPE more=0;
5646  TUnicodeSymbol sym = DecodeFirst(*src,more);
5647  while (more--) {
5648  sym = DecodeNext(sym, *(++src));
5649  }
5650  return sym;
5651 }
5652 
5653 template <typename TChar> basic_string<TChar>
5655  const TChar* substitute_on_error, EValidate validate)
5656 {
5657  if (validate == eValidate) {
5658  x_Validate(str);
5659  }
5661  basic_string<TChar> result;
5662  result.reserve(CUtf8::GetSymbolCount(str) + 1);
5663  CTempString::const_iterator src = str.begin();
5664  CTempString::const_iterator to = str.end();
5665  for (; src != to; ++src) {
5666  TUnicodeSymbol ch = Decode(src);
5667  if (sizeof(TChar) > 2 && ch >= 0xD800 && ch <= 0xDBFF) {
5668  TUnicodeSymbol ch2 = Decode(++src);
5669  ch = (ch - 0xD800) * 0x400 + (ch2 - 0xDC00) + 0x10000;
5670  }
5671  if (ch > max_char) {
5672  if (sizeof(TChar) == 2) {
5673  ch -= 0x10000;
5674  TUnicodeSymbol hi = ch / 0x400 + 0xD800;
5675  TUnicodeSymbol lo = ch % 0x400 + 0xDC00;
5676  result.append(1, (TChar)hi);
5677  result.append(1, (TChar)lo);
5678  continue;
5679  }
5680  if (substitute_on_error) {
5681  result.append(substitute_on_error);
5682  continue;
5683  } else {
5684  NCBI_THROW2(CStringException, eConvert,
5685  "Failed to convert symbol to wide character",
5686  (src - str.begin()));
5687  }
5688  }
5689  result.append(1, (TChar)ch);
5690  }
5691  return result;
5692 }
5693 
5694 template <typename TChar> bool
5696 {
5697  if ( *src >= 0xD800 && *src <= 0xDBFF &&
5698  *(src+1) >= 0xDC00 && *(src+1) <= 0xDFFF && sizeof(TChar) == 2) {
5699  ch = (*(src) - 0xD800) * 0x400 + (*(src+1) - 0xDC00) + 0x10000;
5700  return true;
5701  }
5702  ch = *(src);
5703  return false;
5704 }
5705 
5706 template <typename TChar> CStringUTF8&
5708 {
5709  const TChar* srcBuf;
5710  SIZE_TYPE needed = 0;
5711  SIZE_TYPE pos=0;
5712 
5713  for (pos=0, srcBuf=src;
5714  (to == NPOS) ? (*srcBuf != 0) : (pos<to); ++pos, ++srcBuf) {
5715  TUnicodeSymbol ch;
5716  if (x_TCharToUnicodeSymbol(ch, srcBuf)) {
5717  ++pos;
5718  ++srcBuf;
5719  }
5720  needed += x_BytesNeeded( ch );
5721  }
5722  if ( !needed ) {
5723  return u8str;
5724  }
5725  u8str.reserve(max(u8str.capacity(),u8str.length()+needed+1));
5726  for (pos=0, srcBuf=src;
5727  (to == NPOS) ? (*srcBuf != 0) : (pos<to); ++pos, ++srcBuf) {
5728  TUnicodeSymbol ch;
5729  if (x_TCharToUnicodeSymbol(ch, srcBuf)) {
5730  ++pos;
5731  ++srcBuf;
5732  }
5733  x_AppendChar( u8str, ch );
5734  }
5735  return u8str;
5736 }
5737 
5738 inline CStringUTF8
5740  CStringUTF8 u8;
5742 }
5743 
5744 // deprecated CStringUTF8 is there
5746 
5747 
5748 
5749 /////////////////////////////////////////////////////////////////////////////
5750 // PCase_Generic::
5751 //
5752 
5753 template <typename T>
5754 inline
5755 int PCase_Generic<T>::Compare(const T& s1, const T& s2) const
5756 {
5757  return NStr::Compare(s1, s2, NStr::eCase);
5758 }
5759 
5760 template <typename T>
5761 inline
5762 bool PCase_Generic<T>::Less(const T& s1, const T& s2) const
5763 {
5764  return Compare(s1, s2) < 0;
5765 }
5766 
5767 template <typename T>
5768 inline
5769 bool PCase_Generic<T>::Equals(const T& s1, const T& s2) const
5770 {
5771  return Compare(s1, s2) == 0;
5772 }
5773 
5774 template <typename T>
5775 inline
5776 bool PCase_Generic<T>::operator()(const T& s1, const T& s2) const
5777 {
5778  return Less(s1, s2);
5779 }
5780 
5781 
5782 
5783 ////////////////////////////////////////////////////////////////////////////
5784 // PNocase_Generic<T>::
5785 //
5786 
5787 
5788 template <typename T>
5789 inline
5790 int PNocase_Generic<T>::Compare(const T& s1, const T& s2) const
5791 {
5792  return NStr::Compare(s1, s2, NStr::eNocase);
5793 }
5794 
5795 template <typename T>
5796 inline
5797 bool PNocase_Generic<T>::Less(const T& s1, const T& s2) const
5798 {
5799  return Compare(s1, s2) < 0;
5800 }
5801 
5802 template <typename T>
5803 inline
5804 bool PNocase_Generic<T>::Equals(const T& s1, const T& s2) const
5805 {
5806  return Compare(s1, s2) == 0;
5807 }
5808 
5809 template <typename T>
5810 inline
5811 bool PNocase_Generic<T>::operator()(const T& s1, const T& s2) const
5812 {
5813  return Less(s1, s2);
5814 }
5815 
5816 ////////////////////////////////////////////////////////////////////////////
5817 // PNocase_Conditional_Generic<T>::
5818 //
5819 
5820 template <typename T>
5821 inline
5823  : m_CaseSensitive(cs)
5824 {}
5825 
5826 template <typename T>
5827 inline
5828 int PNocase_Conditional_Generic<T>::Compare(const T& s1, const T& s2) const
5829 {
5830  return NStr::Compare(s1, s2, m_CaseSensitive);
5831 }
5832 
5833 template <typename T>
5834 inline
5835 bool PNocase_Conditional_Generic<T>::Less(const T& s1, const T& s2) const
5836 {
5837  return Compare(s1, s2) < 0;
5838 }
5839 
5840 template <typename T>
5841 inline
5842 bool PNocase_Conditional_Generic<T>::Equals(const T& s1, const T& s2) const
5843 {
5844  return Compare(s1, s2) == 0;
5845 }
5846 
5847 template <typename T>
5848 inline
5849 bool PNocase_Conditional_Generic<T>::operator()(const T& s1, const T& s2) const
5850 {
5851  return Less(s1, s2);
5852 }
5853 
5854 
5856 
5857 #endif /* CORELIB___NCBISTR__HPP */
#define static
void x_Assign(CObject_id &dst, const CObject_id &src)
Definition: Seq_id.cpp:339
ncbi::TMaskedQueryRegions mask
Incapsulate compile time information such as __FILE__, __LINE__, NCBI_MODULE, current function.
Definition: ncbidiag.hpp:65
CEncodedString –.
Definition: ncbistr.hpp:4821
Empty "C++" string.
Definition: ncbistr.hpp:68
CParseTemplException –.
Definition: ncbistr.hpp:4395
Definition: parse.hpp:44
URL-decoder for string pairs parser.
Definition: ncbistr.hpp:4563
URL-encoder for string pairs parser.
Definition: ncbistr.hpp:4576
CStringException –.
Definition: ncbistr.hpp:4504
Template for parsing string into pairs of name and value or merging them back into a single string.
Definition: ncbistr.hpp:4592
Helper class to allocate memory for CTempString[Ex] on demand in the functions which need to modify t...
Definition: tempstr.hpp:1051
CTempString implements a light-weight string on top of a storage buffer whose lifetime management is ...
Definition: tempstr.hpp:65
CUtf8 –.
Definition: ncbistr.hpp:3866
CStringPairsParser –.
Definition: ncbistr.hpp:4532
Encoder interface. Names and values can be encoded with different rules.
Definition: ncbistr.hpp:4548
NStr –.
Definition: ncbistr.hpp:213
requires static std::same_as< TNumeric, float > TNumeric x_StringToNumeric(const CTempString str, TStringToNumFlags flags, int)
Definition: ncbistr.hpp:3609
requires std::signed_integral< TNumeric > TStrictId ::type x_StringToNumeric(const CTempString str, TStringToNumFlags flags, int base)
Definition: ncbistr.hpp:3601
requires std::convertible_to< typename TIterator::iterator_category, std::forward_iterator_tag > &&static std::convertible_to< typename TIterator::value_type, string > string x_Join(TIterator from, TIterator to, const CTempString &delim)
Definition: ncbistr.hpp:3799
requires std::integral< TValue > static std::floating_point< TValue > string x_Join(TValue *from, TValue *to, const CTempString &delim)
Definition: ncbistr.hpp:3824
Define Case-insensitive string equality (not less-than) comparison method Case sensitivity can be tur...
Definition: ncbistr.hpp:4990
Define Case-insensitive string equality (not less-than) comparison method.
Definition: ncbistr.hpp:4964
Define Case-insensitive string comparison methods.
Definition: ncbistr.hpp:4922
BEGIN_NCBI_NAMESPACE
Definition: ncbistr.hpp:50
static uch flags
#define T(s)
Definition: common.h:230
char TChar
Definition: interfaces.hpp:78
std::ofstream out("events_result.xml")
main entry point for tests
static DLIST_TYPE *DLIST_NAME() last(DLIST_LIST_TYPE *list)
Definition: dlist.tmpl.h:51
static char precision
Definition: genparams.c:28
static const char * str(char *buf, int n)
Definition: stats.c:84
static const char * validate(DSNINFO *di)
Go looking for trouble.
Definition: winsetup.c:179
static FILE * f
Definition: readconf.c:23
void reset() noexcept
Reset will delete the old pointer (if owned)
Definition: ncbimisc.hpp:523
#define ITERATE(Type, Var, Cont)
ITERATE macro to sequence through container elements.
Definition: ncbimisc.hpp:914
element_type * get(void) const noexcept
Get pointer.
Definition: ncbimisc.hpp:509
@ eTakeOwnership
An object can take ownership of another.
Definition: ncbi_types.h:135
@ eNoOwnership
No ownership is assumed.
Definition: ncbi_types.h:134
string
Definition: cgiapp.hpp:692
EUrlEncode
Definition: cgi_util.hpp:56
EUrlDecode
Definition: cgi_util.hpp:65
#define NULL
Definition: ncbistd.hpp:225
Nlm_Int8 LIBCALL StringToInt8(const char *str, const char **endptr)
Definition: ncbistr.hpp:408
char *LIBCALL Int8ToString(Nlm_Int8 value, char *str, size_t str_size)
Definition: ncbistr.hpp:420
EDiagSev
Severity level for the posted diagnostics.
Definition: ncbidiag.hpp:648
@ eDiag_Error
Error message.
Definition: ncbidiag.hpp:651
#define NCBI_THROW2(exception_class, err_code, message, extra)
Throw exception with extra parameter.
Definition: ncbiexpt.hpp:1754
EErrCode
Error types that an application can generate.
Definition: ncbiexpt.hpp:884
virtual const char * GetErrCodeString(void) const
Get error code interpreted as text.
Definition: ncbiexpt.cpp:444
#define EXCEPTION_VIRTUAL_BASE
Do not use virtual base classes in exception declaration at all, because in this case derived class s...
Definition: ncbiexpt.hpp:1388
@ eInvalid
To be used ONLY as a return value; please, NEVER throw an exception with this code.
Definition: ncbiexpt.hpp:885
EStringType
String type.
Definition: serialdef.hpp:185
sequence::ECompare Compare(const CSeq_loc &loc1, const CSeq_loc &loc2, CScope *scope)
Returns the sequence::ECompare containment relationship between CSeq_locs.
#define NCBI_ATTRIBUTE_PRINTF(fmt, args)
#define NCBI_DEPRECATED
int64_t Int8
8-byte (64-bit) signed integer
Definition: ncbitype.h:104
uint64_t Uint8
8-byte (64-bit) unsigned integer
Definition: ncbitype.h:105
std::string CStringUTF8
Definition: ncbistl.hpp:253
IO_PREFIX::ostream CNcbiOstream
Portable alias for ostream.
Definition: ncbistre.hpp:149
EStringToNumFlags EConvErrFlags
Formerly split out.
Definition: ncbistr.hpp:280
EJsonEncode
Json-encode flags.
Definition: ncbistr.hpp:3064
CParseTemplException(const CDiagCompileInfo &info, const CException *prev_exception, const string &message, string::size_type pos, EDiagSev severity, CException::TFlags flags)
Definition: ncbistr.hpp:4464
bool operator()(const CTempString s1, const CTempString s2) const
Definition: ncbistr.hpp:5019
static void NumericToString(string &out_str, TNumeric value, TNumToStringFlags flags=0, int base=10)
Convert numeric value to string.
Definition: ncbistr.hpp:675
std::string::size_type SIZE_TYPE
Definition: ncbistr.hpp:102
static bool x_TCharToUnicodeSymbol(TUnicodeSymbol &u, const TChar *src)
Definition: ncbistr.hpp:5695
NStr::EUrlDecode m_Flag
Definition: ncbistr.hpp:4570
static void x_Validate(const CTempString &str)
Definition: ncbistr.cpp:7039
EEncoding
Definition: ncbistr.hpp:169
virtual void Append(const string &s)=0
static string SizetToString(size_t value, TNumToStringFlags flags=0, int base=10)
Convert size_t to string.
Definition: ncbistr.cpp:2724
CParseTemplException(void)
Constructor.
Definition: ncbistr.hpp:4477
PEqualNocase_Generic< const char * > PEqualNocase_CStr
Definition: ncbistr.hpp:4974
vector< pair< string, string > > TStringPairsVector
Definition: ncbistr.hpp:4808
static TUnicodeSymbol x_Decode(TIterator &src)
Definition: ncbistr.hpp:5643
static bool x_VerifyIntLimits(TSource v, const CTempString str, TStringToNumFlags flags)
Definition: ncbistr.hpp:3523
EPrintableMode
How to display printable strings.
Definition: ncbistr.hpp:2700
static string Int8ToString(Int8 value, TNumToStringFlags flags=0, int base=10)
Convert Int8 to string.
Definition: ncbistr.hpp:5132
requires static std::same_as< TNumeric, unsigned long > TNumeric x_StringToNumeric(const CTempString str, TStringToNumFlags flags, int base)
Definition: ncbistr.hpp:3581
int TXmlEncode
Definition: ncbistr.hpp:3010
EDedentFlags
Flags for Dedent() method.
Definition: ncbistr.hpp:3382
int Compare(const T &s1, const T &s2) const
Return difference between "s1" and "s2".
Definition: ncbistr.hpp:5790
PCase_Generic< string > PCase
Definition: ncbistr.hpp:4876
PNocase_Generic< const char * > PNocase_CStr
Definition: ncbistr.hpp:4907
ESS_Flags
Flags for Sanitize().
Definition: ncbistr.hpp:2806
int TDedentFlags
Bitwise OR of EDedentFlags.
Definition: ncbistr.hpp:3390
EStringToNumFlags
String to number conversion flags.
Definition: ncbistr.hpp:239
string::size_type m_Pos
Error position.
Definition: ncbistr.hpp:4489
EErrCode
Error types that for exception class.
Definition: ncbistr.hpp:4398
void Parse(const CTempString str, NStr::EMergeDelims merge_argsep=NStr::eMergeDelims)
Parse the string.
Definition: ncbistr.hpp:4696
static CStringUTF8 & x_Append(CStringUTF8 &u8str, const CTempString &src, EEncoding encoding, EValidate validate)
Definition: ncbistr.cpp:7073
CStringPairs(IStringDecoder *decoder=NULL, EOwnership own_decoder=eTakeOwnership, IStringEncoder *encoder=NULL, EOwnership own_encoder=eTakeOwnership)
Create parser with the specified decoder/encoder and default separators.
Definition: ncbistr.hpp:4609
static string DoubleToString(double value, int precision=-1, TNumToStringFlags flags=0)
Convert double to string.
Definition: ncbistr.hpp:5160
string Merge(void) const
Merge name-value pairs into a single string using the currently set separators and the provided encod...
Definition: ncbistr.hpp:4751
CParseTemplException(const CDiagCompileInfo &info, const CException *prev_exception, EErrCode err_code, const string &message, string::size_type pos, EDiagSev severity=eDiag_Error)
Constructor.
Definition: ncbistr.hpp:4414
static bool StringToNumeric(const CTempString str, TNumeric *value, TStringToNumFlags flags=0, int base=10)
Convert string to a numeric value.
Definition: ncbistr.hpp:326
#define kEmptyStr
Definition: ncbistr.hpp:93
char16_t TCharUCS2
Type for character in UCS-2 encoding.
Definition: ncbistr.hpp:3840
ESqlEncode
SQL encode flags.
Definition: ncbistr.hpp:3139
ESplitFlags
Flags for Split*() methods.
Definition: ncbistr.hpp:2470
EWrapFlags
How to wrap the words in a string to a new line.
Definition: ncbistr.hpp:3202
static int CompareNocase(const CTempString s1, SIZE_TYPE pos, SIZE_TYPE n, const char *s2)
Case-insensitive compare of a substring with another string.
Definition: ncbistr.cpp:199
CNcbiOstream & operator<<(CNcbiOstream &os, const TStringUCS2 &str)
Operator for writing TStringUCS2 to stream.
Definition: ncbistr.hpp:3847
EUrlEncode
URL-encode flags.
Definition: ncbistr.hpp:3114
EMergeDelims
Whether to merge adjacent delimiters.
Definition: ncbistr.hpp:2487
AutoPtr< IStringDecoder > m_Decoder
Definition: ncbistr.hpp:4802
CWrapDestStringList(list< string > &l)
Definition: ncbistr.hpp:3256
EOccurrence
Whether it is the first or last occurrence.
Definition: ncbistr.hpp:1910
static string Merge(const TStrPairs &pairs, const string &arg_sep, const string &val_sep, IStringEncoder *encoder=NULL, EOwnership own=eTakeOwnership)
Merge name-value pairs from the provided container, separators and encoder.
Definition: ncbistr.hpp:4770
const string & GetEncodedString(void) const
Get encoded string.
Definition: ncbistr.hpp:4836
int TPrintableMode
Bitwise OR of EPrintableMode flags.
Definition: ncbistr.hpp:2709
TStrPairs & GetPairs(void)
Get non-const data.
Definition: ncbistr.hpp:4797
int TNumToStringFlags
Bitwise OR of "ENumToStringFlags".
Definition: ncbistr.hpp:236
static list< string > & Split(const CTempString str, const CTempString delim, list< string > &arr, TSplitFlags flags=0, vector< SIZE_TYPE > *token_pos=NULL)
Split a string using specified delimiters.
Definition: ncbistr.cpp:3433
virtual string Encode(const CTempString src, EStringType stype) const =0
Encode the string.
NStr::EUrlEncode m_Flag
Definition: ncbistr.hpp:4583
void SetDecoder(IStringDecoder *decoder, EOwnership own=eTakeOwnership)
Set string decoder.
Definition: ncbistr.hpp:4671
CParseTemplException(const CParseTemplException< TBase > &other)
Constructor.
Definition: ncbistr.hpp:4429
const char * impl_ToCString(const char *s)
Definition: ncbistr.hpp:159
CStringPairs(const CTempString arg_sep, const CTempString val_sep, IStringDecoder *decoder=NULL, EOwnership own_decoder=eTakeOwnership, IStringEncoder *encoder=NULL, EOwnership own_encoder=eTakeOwnership)
Create parser with the specified parameters.
Definition: ncbistr.hpp:4634
EUrlDecode
URL decode flags.
Definition: ncbistr.hpp:3130
static SIZE_TYPE FindNoCase(const CTempString str, const CTempString pattern, SIZE_TYPE start, SIZE_TYPE end, EOccurrence which=eFirst)
Find the pattern in the specified range of a string using a case insensitive search.
Definition: ncbistr.cpp:2966
virtual ~IWrapDest()
Definition: ncbistr.hpp:3246
CEncodedString(void)
Definition: ncbistr.hpp:4823
bool Less(const T &s1, const T &s2) const
Return TRUE if s1 < s2.
Definition: ncbistr.hpp:5797
static CTempString TruncateSpaces_Unsafe(const CTempString &str, NStr::ETrunc side=NStr::eTrunc_Both)
Truncate whitespace in the string.
Definition: ncbistr.cpp:7257
static bool EndsWith(const CTempString str, const CTempString end, ECase use_case=eCase)
Check if a string ends with a specified suffix value.
Definition: ncbistr.hpp:5403
requires std::signed_integral< TNumeric > TStringToNumFlags flags
Definition: ncbistr.hpp:3543
static SIZE_TYPE x_BytesNeeded(TUnicodeSymbol ch)
Definition: ncbistr.cpp:7130
static string LongToString(long value, TNumToStringFlags flags=0, int base=10)
Convert Int to string.
Definition: ncbistr.hpp:5114
char TXChar
Definition: ncbistr.hpp:142
unique_ptr< string > m_Encoded
Definition: ncbistr.hpp:4844
static int strcmp(const char *s1, const char *s2)
String compare.
Definition: ncbistr.hpp:5181
EDirection
Search direction for Find() methods.
Definition: ncbistr.hpp:1916
requires std::signed_integral< TNumeric > void ::type x_NumericToString(string &out_str, TStrictId value, TNumToStringFlags flags, int base)
Definition: ncbistr.hpp:3776
EXmlEncode
XML-encode flags.
Definition: ncbistr.hpp:2998
NStr::ECase m_CaseSensitive
case sensitive when TRUE
Definition: ncbistr.hpp:4945
static bool EvaluateNext(char ch)
Check that the character is valid continuation byte of an UTF8 byte sequence.
Definition: ncbistr.hpp:4170
PEqualNocase_Conditional_Generic< string > PEqualNocase_Conditional
Definition: ncbistr.hpp:5005
#define NPOS
Definition: ncbistr.hpp:103
bool IsEmpty(void) const
Check if the string is empty.
Definition: ncbistr.hpp:4840
virtual void Append(const CTempString &s)
Definition: ncbistr.hpp:3261
static string TransformJoin(TIterator from, TIterator to, const CTempString &delim, FTransform fnTransform)
Definition: ncbistr.hpp:5533
static int strncasecmp(const char *s1, const char *s2, size_t n)
Case-insensitive comparison of two zero-terminated strings, narrowed to the specified number of chara...
Definition: ncbistr.hpp:5220
static CTempString TruncateSpaces(const CTempString str, ETrunc where=eTrunc_Both)
Definition: ncbistr.hpp:2250
IStringEncoder * GetEncoder(void)
Get encoder or NULL. Does not affect encoder ownership.
Definition: ncbistr.hpp:4685
static string Join(const initializer_list< TValue > &arr, const CTempString &delim)
Definition: ncbistr.hpp:2676
string TXString
Definition: ncbistr.hpp:143
PEqualNocase_Generic< string > PEqualNocase
Definition: ncbistr.hpp:4973
static TNumeric StringToNumeric(const CTempString str, TStringToNumFlags flags=0, int base=10)
Convert string to a numeric value.
Definition: ncbistr.hpp:300
static string Join(TInputIterator from, TInputIterator to, const CTempString &delim)
Definition: ncbistr.hpp:2682
static string JoinNumeric(TInputIterator from, TInputIterator to, const CTempString &delim)
Definition: ncbistr.hpp:2688
ENumToStringFlags
Number to string conversion flags.
Definition: ncbistr.hpp:220
static string IntToString(int value, TNumToStringFlags flags=0, int base=10)
Convert int to string.
Definition: ncbistr.hpp:5057
static CStringUTF8 TruncateSpaces(const CTempString &str, NStr::ETrunc side=NStr::eTrunc_Both)
Truncate whitespace in the string.
Definition: ncbistr.hpp:5739
static SIZE_TYPE CommonSuffixSize(const CTempString s1, const CTempString s2)
Determine the common suffix of two strings.
Definition: ncbistr.hpp:5435
virtual const char * GetType(void) const override
Get exception class type.
Definition: ncbistr.hpp:4448
string::size_type GetPos(void) const noexcept
Get error position.
Definition: ncbistr.hpp:4461
int Compare(const T &s1, const T &s2) const
Return difference between "s1" and "s2".
Definition: ncbistr.hpp:5828
virtual void ReportExtra(ostream &out) const override
Report error position.
Definition: ncbistr.hpp:4440
void SetEncoder(IStringEncoder *encoder, EOwnership own=eTakeOwnership)
Set string encoder.
Definition: ncbistr.hpp:4682
static string DedentR(const CTempString str)
Definition: ncbistr.hpp:5615
const string & GetOriginalString(void) const
Get the original unencoded string.
Definition: ncbistr.hpp:4834
NCBI_EXCEPTION_DEFAULT2(CStringException, CParseTemplException< CCoreException >, std::string::size_type)
requires std::integral< TNumeric > std::floating_point< TNumeric > static std::convertible_to< TNumeric, Int8 > string NumericToString(TNumeric value, TNumToStringFlags flags=0, int base=10)
Convert numeric value to string.
Definition: ncbistr.hpp:644
CStringPairs(NStr::EUrlDecode decode_flag, NStr::EUrlEncode encode_flag)
Create parser with the selected URL-encoding/decoding options and default separators.
Definition: ncbistr.hpp:4654
static string Dedent(const CTempString str, TDedentFlags flags=0)
Dedent multi-line string, removing common whitespace prefix for each line.
Definition: ncbistr.cpp:5479
EErrCode
Error types that string classes can generate.
Definition: ncbistr.hpp:4507
static SIZE_TYPE Find(const CTempString str, const CTempString pattern, ECase use_case=eCase, EDirection direction=eForwardSearch, SIZE_TYPE occurrence=0)
Find the pattern in the string.
Definition: ncbistr.cpp:2864
static CStringUTF8 AsUTF8(const CTempString &src, const locale &lcl)
Convert into UTF8 from a C/C++ string.
Definition: ncbistr.hpp:3897
PNocase_Generic< string > PNocase
Definition: ncbistr.hpp:4906
const char * const_iterator
Definition: tempstr.hpp:71
static SIZE_TYPE GetValidSymbolCount(const CTempString &src)
Get the number of valid UTF-8 symbols (code points) in buffer.
Definition: ncbistr.hpp:5625
TUnicodeSymbol TCharUCS4
Definition: ncbistr.hpp:3836
static int HexChar(char ch)
Convert character to integer.
Definition: ncbistr.hpp:5169
static void ToUpper(const char *)
Privatized ToUpper() with const char* parameter to prevent passing of constant strings.
static string Join(const TContainer &arr, const CTempString &delim)
Join strings using the specified delimiter.
Definition: ncbistr.hpp:2670
static void Parse(TStrPairs &pairs, const CTempString str, const CTempString arg_sep, const CTempString val_sep, IStringDecoder *decoder=NULL, EOwnership own=eTakeOwnership, NStr::EMergeDelims merge_argsep=NStr::eMergeDelims)
Parse the string using the provided decoder, put data into the container.
Definition: ncbistr.hpp:4719
virtual ~IStringEncoder(void)
Definition: ncbistr.hpp:4557
virtual ~IStringDecoder(void)
Definition: ncbistr.hpp:4542
int TSplitFlags
Bitwise OR of ESplitFlags.
Definition: ncbistr.hpp:2483
static enable_if< is_integral< typename TStrictId::TId >::value &&is_member_function_pointer< decltype(&TStrictId::Get)>::value, string >::type NumericToString(TStrictId value, TNumToStringFlags flags=0, int base=10)
Definition: ncbistr.hpp:652
ETrunc
Which end to truncate a string.
Definition: ncbistr.hpp:2210
static bool EqualCase(const CTempString s1, SIZE_TYPE pos, SIZE_TYPE n, const char *s2)
Case-sensitive equality of a substring with another string.
Definition: ncbistr.hpp:5298
static basic_string< TChar > x_AsBasicString(const CTempString &src, const TChar *substitute_on_error, EValidate validate)
Definition: ncbistr.hpp:5654
const char * data(void) const
Return a pointer to the array represented.
Definition: tempstr.hpp:313
static string UInt8ToString_DataSize(Uint8 value, TNumToStringFlags flags=0, unsigned int max_digits=3)
Convert UInt8 to string using "software" qualifiers.
Definition: ncbistr.hpp:5150
virtual ~CParseTemplException(void) noexcept
Destructor.
Definition: ncbistr.hpp:4437
AutoPtr< IStringEncoder > m_Encoder
Definition: ncbistr.hpp:4803
basic_string< TUnicodeSymbol > TStringUnicode
Unicode string.
Definition: ncbistr.hpp:113
const wchar_t *const kEmptyWCStr
Definition: ncbistr.cpp:71
char32_t TUnicodeSymbol
Unicode character.
Definition: ncbistr.hpp:111
bool operator()(const T &s1, const T &s2) const
Return TRUE if s1 < s2 ignoring case.
Definition: ncbistr.hpp:4967
static TUnicodeSymbol DecodeFirst(char ch, SIZE_TYPE &more)
Begin converting first character of UTF8 sequence into Unicode.
Definition: ncbistr.cpp:7189
static int strcasecmp(const char *s1, const char *s2)
Case-insensitive comparison of two zero-terminated strings.
Definition: ncbistr.hpp:5193
EStringType
Type of string to be decoded.
Definition: ncbistr.hpp:4551
TStringUnicode TStringUCS4
Definition: ncbistr.hpp:3837
static bool x_VerifyFloatLimits(TSource v, const CTempString str, TStringToNumFlags flags)
Definition: ncbistr.hpp:3531
bool AStrEquiv(const Arg1 &x, const Arg2 &y, Pred pr)
Check equivalence of arguments using predicate.
Definition: ncbistr.hpp:5035
static string & Replace(const string &src, const string &search, const string &replace, string &dst, SIZE_TYPE start_pos=0, SIZE_TYPE max_replace=0, SIZE_TYPE *num_replace=0)
Replace occurrences of a substring within a string.
Definition: ncbistr.cpp:3286
virtual ~CStringPairs(void)
Definition: ncbistr.hpp:4663
static SIZE_TYPE FindCase(const CTempString str, const CTempString pattern, SIZE_TYPE start, SIZE_TYPE end, EOccurrence which=eFirst)
Find the pattern in the specified range of a string using a case sensitive search.
Definition: ncbistr.hpp:5463
CStringPairs< TStringPairsVector > CStringPairsParser
Definition: ncbistr.hpp:4809
static int Compare(const CTempString s1, SIZE_TYPE pos, SIZE_TYPE n, const char *s2, ECase use_case=eCase)
Compare of a substring with another string.
Definition: ncbistr.hpp:5270
static size_t strftime(char *s, size_t maxsize, const char *format, const struct tm *timeptr)
Wrapper for the function strftime() that corrects handling D and T time formats on MS Windows.
Definition: ncbistr.hpp:5249
static CStringUTF8 SQLEncode(const CStringUTF8 &str)
Definition: ncbistr.hpp:3165
string m_ArgSep
Definition: ncbistr.hpp:4800
virtual const CException * x_Clone(void) const override
Helper clone method.
Definition: ncbistr.hpp:4483
static CStringUTF8 & x_AppendChar(CStringUTF8 &u8str, TUnicodeSymbol ch)
Definition: ncbistr.cpp:7050
virtual void Append(const string &s)
Definition: ncbistr.hpp:3257
static CStringUTF8 AsUTF8(const CTempString &src, EEncoding encoding, EValidate validate=eNoValidate)
Convert into UTF8 from a C/C++ string.
Definition: ncbistr.hpp:3882
bool Equals(const T &s1, const T &s2) const
Return TRUE if s1 == s2.
Definition: ncbistr.hpp:5769
requires integral< TChar > const TChar * substitute_on_error
Definition: ncbistr.hpp:4107
basic_string< TCharUCS2 > TStringUCS2
Type for string in UCS-2 encoding.
Definition: ncbistr.hpp:3842
EQuoted
Define that string is quoted or not.
Definition: ncbistr.hpp:2960
IStringDecoder * GetDecoder(void)
Get decoder or NULL. Does not affect decoder ownership.
Definition: ncbistr.hpp:4674
static list< string > & WrapList(const list< string > &l, SIZE_TYPE width, const string &delim, list< string > &arr, TWrapFlags flags=0, const string *prefix=0, const string *prefix1=0)
Wrap the list using the specified criteria.
Definition: ncbistr.cpp:5342
static string xx_Join(TIterator from, TIterator to, const CTempString &delim)
Definition: ncbistr.hpp:5547
int THtmlDecode
Definition: ncbistr.hpp:3044
return x_VerifyIntLimits< TNumeric >(n, str, flags) ?(TNumeric) n requires std::signed_integral< TNumeric > static long TNumeric x_StringToNumeric(const CTempString str, TStringToNumFlags flags, int base)
Definition: ncbistr.hpp:3574
requires std::signed_integral< TNumeric > bool ::type x_StringToNumeric(const CTempString str, TStrictId *value, TStringToNumFlags flags, int base)
Definition: ncbistr.hpp:3711
virtual void Append(const CTempString &s)=0
EStringType
Type of string to be decoded.
Definition: ncbistr.hpp:4535
virtual string Decode(const CTempString src, EStringType stype) const =0
Decode the string.
TStrPairs m_Data
Definition: ncbistr.hpp:4804
#define NcbiEmptyString
Definition: ncbistr.hpp:92
static SIZE_TYPE x_GetValidSymbolCount(const CTempString &src, CTempString::const_iterator &err)
Definition: ncbistr.cpp:6658
static string UIntToString(unsigned int value, TNumToStringFlags flags=0, int base=10)
Convert UInt to string.
Definition: ncbistr.hpp:5082
static bool StartsWith(const CTempString str, const CTempString start, ECase use_case=eCase)
Check if a string starts with a specified prefix value.
Definition: ncbistr.hpp:5385
PNocase_Conditional_Generic(NStr::ECase case_sens=NStr::eCase)
Construction.
Definition: ncbistr.hpp:5822
const TStrPairs & GetPairs(void) const
Read data.
Definition: ncbistr.hpp:4795
TContainer TStrPairs
Definition: ncbistr.hpp:4594
bool IsEncoded(void) const
Check if the original string was encoded.
Definition: ncbistr.hpp:4832
END_NCBI_NAMESPACE
Definition: ncbistr.hpp:5855
EHtmlEncode
HTML-decode flags.
Definition: ncbistr.hpp:3020
bool Equals(const T &s1, const T &s2) const
Return TRUE if s1 == s2.
Definition: ncbistr.hpp:5842
bool operator()(const T &s1, const T &s2) const
Return TRUE if s1 < s2.
Definition: ncbistr.hpp:5776
static TUnicodeSymbol DecodeNext(TUnicodeSymbol chU, char ch)
Convert next character of UTF8 sequence into Unicode.
Definition: ncbistr.cpp:7212
static SIZE_TYPE FindWord(const CTempString str, const CTempString word, EOccurrence which, ECase use_case=eCase)
Find given word in the string.
Definition: ncbistr.hpp:2201
requires(std::integral< typename TIterator::value_type >||std::floating_point< typename TIterator::value_type >) &&std
Definition: ncbistr.hpp:3813
requires integral< TChar > const TChar EValidate validate
Definition: ncbistr.hpp:4107
string m_Original
Definition: ncbistr.hpp:4843
static bool SplitInTwo(const CTempString str, const CTempString delim, string &str1, string &str2, TSplitFlags flags=0)
Split a string into two pieces using the specified delimiters.
Definition: ncbistr.cpp:3526
bool Less(const T &s1, const T &s2) const
Return TRUE if s1 < s2.
Definition: ncbistr.hpp:5762
size_type length(void) const
Return the length of the represented array.
Definition: tempstr.hpp:320
bool Equals(const T &s1, const T &s2) const
Return TRUE if s1 == s2.
Definition: ncbistr.hpp:5804
static string ULongToString(unsigned long value, TNumToStringFlags flags=0, int base=10)
Convert unsigned long to string.
Definition: ncbistr.hpp:5123
TContainer::value_type TStrPair
The container's value type must be pair<string, string> or a compatible type.
Definition: ncbistr.hpp:4597
int TSS_Flags
Bitwise OR of ESS_Flags.
Definition: ncbistr.hpp:2826
static list< string > & Justify(const CTempString str, SIZE_TYPE width, list< string > &par, const CTempString *pfx=0, const CTempString *pfx1=0)
Justify the specified string into a series of lines of the same width.
Definition: ncbistr.cpp:5394
static const wstring & Get(void)
Get string.
Definition: ncbistr.hpp:83
list< string > & m_list
Definition: ncbistr.hpp:3254
requires std::same_as< typename TIterator::iterator_category, std::input_iterator_tag > &&static std::convertible_to< typename TIterator::value_type, string > string x_Join(TIterator from, TIterator to, const CTempString &delim)
Definition: ncbistr.hpp:3790
static string Sanitize(CTempString str, TSS_Flags flags=fSS_print)
Sanitize a string, allowing only specified classes of characters.
Definition: ncbistr.hpp:2849
PNocase_Conditional_Generic< string > PNocase_Conditional
Definition: ncbistr.hpp:4948
CTempString substr(size_type pos) const
Obtain a substring from this string, beginning at a given offset.
Definition: tempstr.hpp:776
requires std::signed_integral< TNumeric > TNumeric * value
Definition: ncbistr.hpp:3625
requires static std::convertible_to< TValue, string > string x_Join(TValue *from, TValue *to, const CTempString &delim)
Definition: ncbistr.hpp:3807
bool operator()(const T &s1, const T &s2) const
Return TRUE if s1 < s2 ignoring case.
Definition: ncbistr.hpp:5811
static CTempString TruncateSpaces(const char *str, ETrunc where=eTrunc_Both)
Definition: ncbistr.hpp:2259
static void ToLower(const char *)
Privatized ToLower() with const char* parameter to prevent passing of constant strings.
int THtmlEncode
Definition: ncbistr.hpp:3028
static TUnicodeSymbol Decode(const char *&src)
Convert sequence of UTF8 code units into Unicode code point.
Definition: ncbistr.hpp:5635
static bool EqualNocase(const CTempString s1, SIZE_TYPE pos, SIZE_TYPE n, const char *s2)
Case-insensitive equality of a substring with another string.
Definition: ncbistr.hpp:5326
EHtmlDecode
HTML-decode flags.
Definition: ncbistr.hpp:3039
void SetCase(NStr::ECase case_sens)
Set comparison type.
Definition: ncbistr.hpp:4931
ECase
Which type of string comparison.
Definition: ncbistr.hpp:1175
static int strncmp(const char *s1, const char *s2, size_t n)
String compare up to specified number of characters.
Definition: ncbistr.hpp:5187
TErrCode GetErrCode(void) const
Get error code.
Definition: ncbistr.hpp:4453
int TWrapFlags
Bitwise OR of "EWrapFlags".
Definition: ncbistr.hpp:3207
int TStringToNumFlags
Bitwise OR of "EStringToNumFlags".
Definition: ncbistr.hpp:281
bool Less(const T &s1, const T &s2) const
Return TRUE if s1 < s2.
Definition: ncbistr.hpp:5835
NStr::ECase GetCase() const
Get comparison type.
Definition: ncbistr.hpp:4928
static SIZE_TYPE GetValidBytesCount(const CTempString &src)
Get the number of valid UTF-8 bytes (code units) in buffer.
Definition: ncbistr.hpp:5630
static void Wrap(const string &str, SIZE_TYPE width, IWrapDest &dest, TWrapFlags flags, const string *prefix, const string *prefix1)
Definition: ncbistr.cpp:5323
int Compare(const T &s1, const T &s2) const
Return difference between "s1" and "s2".
Definition: ncbistr.hpp:5755
static bool Equal(const CTempString s1, SIZE_TYPE pos, SIZE_TYPE n, const char *s2, ECase use_case=eCase)
Test for equality of a substring with another string.
Definition: ncbistr.hpp:5357
EValidate
How to verify character encoding of the source data.
Definition: ncbistr.hpp:3869
static const string & Get(void)
Get string.
Definition: ncbistr.hpp:72
static string & ReplaceInPlace(string &src, const string &search, const string &replace, SIZE_TYPE start_pos=0, SIZE_TYPE max_replace=0, SIZE_TYPE *num_replace=0)
Replace occurrences of a substring within a string.
Definition: ncbistr.cpp:3377
bool operator()(const T &s1, const T &s2) const
Return TRUE if s1 < s2 ignoring case.
Definition: ncbistr.hpp:4999
string m_ValSep
Definition: ncbistr.hpp:4801
const char *const kEmptyCStr
Empty "C" string (points to a '\0').
Definition: ncbistr.cpp:68
PNocase_Conditional_Generic< const char * > PNocase_Conditional_CStr
Definition: ncbistr.hpp:4949
bool operator()(const T &s1, const T &s2) const
Return TRUE if s1 < s2 ignoring case.
Definition: ncbistr.hpp:5849
static SIZE_TYPE Find(const CTempString str, const CTempString pattern, SIZE_TYPE start)
Wrapper for backward-compatibility.
Definition: ncbistr.hpp:2003
size_type size(void) const
Return the length of the represented array.
Definition: tempstr.hpp:327
PCase_Generic< const char * > PCase_CStr
Definition: ncbistr.hpp:4877
static int CompareCase(const CTempString s1, SIZE_TYPE pos, SIZE_TYPE n, const char *s2)
Case-sensitive compare of a substring with another string.
Definition: ncbistr.cpp:115
static string UInt8ToString(Uint8 value, TNumToStringFlags flags=0, int base=10)
Convert UInt8 to string.
Definition: ncbistr.hpp:5141
TStringToNumFlags TConvErrFlags
Formerly split out.
Definition: ncbistr.hpp:282
PEqualNocase_Conditional_Generic< const char * > PEqualNocase_Conditional_CStr
Definition: ncbistr.hpp:5006
PEqualNocase_Conditional_Generic(NStr::ECase case_sens=NStr::eCase)
Construction.
Definition: ncbistr.hpp:4993
EEscSeqRange
C-style escape sequences parsing mode.
Definition: ncbistr.hpp:2911
static bool EvaluateFirst(char ch, SIZE_TYPE &more)
Check that the character is valid first byte of an UTF8 byte sequence.
Definition: ncbistr.hpp:4160
static SIZE_TYPE CommonPrefixSize(const CTempString s1, const CTempString s2)
Determine the common prefix of two strings.
Definition: ncbistr.hpp:5423
requires std::signed_integral< TNumeric > TStringToNumFlags int base
Definition: ncbistr.hpp:3544
const_iterator begin() const
Return an iterator to the string's starting position.
Definition: tempstr.hpp:299
virtual const char * GetErrCodeString(void) const override
Translate from the error code value to its string representation.
Definition: ncbistr.hpp:4403
static int StringToNumeric(const string &str)
Definition: ncbistr.hpp:350
@ eEncoding_Windows_1252
Definition: ncbistr.hpp:177
@ eEncoding_Ascii
Definition: ncbistr.hpp:172
@ eEncoding_ISO8859_1
Note: From the point of view of the C++.
Definition: ncbistr.hpp:173
@ eEncoding_CESU8
Definition: ncbistr.hpp:178
@ eEncoding_UTF8
Definition: ncbistr.hpp:171
@ eEncoding_Unknown
Definition: ncbistr.hpp:170
@ fDedent_SkipEmptyFirstLine
Ignore first line and skip it from the result, if it is empty only.
Definition: ncbistr.hpp:3388
@ eErr
Generic error.
Definition: ncbistr.hpp:4399
@ eSqlEnc_Plain
Always produce '...', with no tag.
Definition: ncbistr.hpp:3140
@ eUrlEnc_ProcessMarkChars
Convert all non-alphanumeric chars, spaces are converted to '+'.
Definition: ncbistr.hpp:3116
@ eUrlEnc_URIQueryValue
Encode query part of an URI, arg value.
Definition: ncbistr.hpp:3124
@ eUrlEnc_PercentOnly
Convert all non-alphanumeric chars including space and '' to %## format.
Definition: ncbistr.hpp:3117
@ eUrlEnc_URIHost
Encode host part of an URI.
Definition: ncbistr.hpp:3121
@ eUrlEnc_URIQueryName
Encode query part of an URI, arg name.
Definition: ncbistr.hpp:3123
@ eUrlEnc_URIPath
Encode path part of an URI.
Definition: ncbistr.hpp:3122
@ eUrlEnc_Path
Same as ProcessMarkChars but preserves valid path characters ('/', '.')
Definition: ncbistr.hpp:3118
@ eUrlEnc_URIScheme
Encode scheme part of an URI.
Definition: ncbistr.hpp:3119
@ eUrlEnc_URIUserinfo
Encode userinfo part of an URI.
Definition: ncbistr.hpp:3120
@ eUrlEnc_SkipMarkChars
Do not convert chars like '!', '(' etc.
Definition: ncbistr.hpp:3115
@ eUrlEnc_Cookie
Same as SkipMarkChars with encoded ','.
Definition: ncbistr.hpp:3126
@ eUrlEnc_URIFragment
Encode fragment part of an URI.
Definition: ncbistr.hpp:3125
@ eMergeDelims
Definition: ncbistr.hpp:2488
@ eFirst
First occurrence.
Definition: ncbistr.hpp:1911
@ eUrlDec_All
Decode '+' to space.
Definition: ncbistr.hpp:3131
@ eReverseSearch
Search in a backward direction.
Definition: ncbistr.hpp:1918
@ eForwardSearch
Search in a forward direction.
Definition: ncbistr.hpp:1917
@ eConvert
Failure to convert string.
Definition: ncbistr.hpp:4508
@ eBadArgs
Bad arguments to string methods.
Definition: ncbistr.hpp:4509
@ eTrunc_Both
Truncate whitespace at both begin and end of string.
Definition: ncbistr.hpp:2213
@ eTrunc_End
Truncate trailing whitespace only.
Definition: ncbistr.hpp:2212
@ eTrunc_Begin
Truncate leading whitespace only.
Definition: ncbistr.hpp:2211
@ eQuoted
String is quoted.
Definition: ncbistr.hpp:2961
@ eNocase
Case insensitive compare.
Definition: ncbistr.hpp:1177
@ eCase
Case sensitive compare.
Definition: ncbistr.hpp:1176
@ eNoValidate
Definition: ncbistr.hpp:3870
@ eValidate
Definition: ncbistr.hpp:3871
@ eEscSeqRange_Throw
Throw an exception.
Definition: ncbistr.hpp:2916
@ eEscSeqRange_Errno
Set errno to ERANGE, return empty string.
Definition: ncbistr.hpp:2917
enum ENcbiOwnership EOwnership
Ownership relations between objects.
#define NCBI_XNCBI_EXPORT
Definition: ncbi_export.h:1299
unsigned int
A callback function used to compare two keys in a database.
Definition: types.hpp:1282
The blob sat and sat key Both must be positive integers</td > n< td > Non empty string The interpretation of the blob id depends on a processor Cassandra n processor expects the following format
char * buf
int i
yy_size_t n
int len
static MDB_envinfo info
Definition: mdb_load.c:37
vector< CSeq_align const * >::const_iterator TIterator
const TYPE & Get(const CNamedParameterList *param)
constexpr int CompareNocase(const std::string_view &l, const std::string_view &r)
mdb_mode_t mode
Definition: lmdb++.h:62
double value_type
The numeric datatype used by the parser.
Definition: muParserDef.h:228
const struct ncbi::grid::netcache::search::fields::SIZE size
const GenericPointer< typename T::ValueType > T2 value
Definition: pointer.h:1227
int strncmp(const char *str1, const char *str2, size_t count)
Definition: odbc_utils.hpp:133
int strcmp(const char *str1, const char *str2)
Definition: odbc_utils.hpp:160
static const BitmapCharRec ch2
Definition: ncbi_10x20.c:1819
#define strncasecmp
#define strcasecmp
int tolower(Uchar c)
Definition: ncbictype.hpp:72
int toupper(Uchar c)
Definition: ncbictype.hpp:73
Defines NCBI C++ Toolkit portable error codes.
T max(T x_, T y_)
T min(T x_, T y_)
static bool IsWhiteSpace(char c)
Definition: objistrxml.cpp:212
static const char * locale
Definition: pcre2grep.c:212
static const char delimiter[]
static SLJIT_INLINE sljit_ins l(sljit_gpr r, sljit_s32 d, sljit_gpr x, sljit_gpr b)
Define Case-sensitive string comparison methods.
Definition: ncbistr.hpp:4862
Define Case-insensitive string comparison methods.
Definition: ncbistr.hpp:4892
PQuickStringLess implements an ordering of strings, that is more efficient than usual lexicographical...
Definition: ncbistr.hpp:5018
Definition: type.c:6
else result
Definition: token2.c:20
#define Unknown
Definition: utilfun.h:40
void Encode(const CRawScoreVector< Key, Score > &, vector< char > &)
void Decode(const vector< char > &, CRawScoreVector< Key, Score > &)
#define const
Definition: zconf.h:232
unsigned char uch
Definition: zutil.h:39
Modified on Sat Nov 07 14:10:59 2026 by modify_doxy.py rev. 717554