GDAL

cpl_string.h
Go to the documentation of this file.
1/**********************************************************************
2 *
3 * Name: cpl_string.h
4 * Project: CPL - Common Portability Library
5 * Purpose: String and StringList functions.
6 * Author: Daniel Morissette, dmorissette@mapgears.com
7 *
8 **********************************************************************
9 * Copyright (c) 1998, Daniel Morissette
10 * Copyright (c) 2008-2014, Even Rouault <even dot rouault at spatialys.com>
11 *
12 * SPDX-License-Identifier: MIT
13 ****************************************************************************/
14
15#ifndef CPL_STRING_H_INCLUDED
16#define CPL_STRING_H_INCLUDED
17
18#include "cpl_error.h"
19#include "cpl_conv.h"
20#include "cpl_vsi.h"
21
22#include <stdbool.h>
23
46 CPL_C_START
47
48 char CPL_DLL **CSLAddString(char **papszStrList,
49 const char *pszNewString) CPL_WARN_UNUSED_RESULT;
50 char CPL_DLL **
51 CSLAddStringMayFail(char **papszStrList,
52 const char *pszNewString) CPL_WARN_UNUSED_RESULT;
53 int CPL_DLL CSLCount(CSLConstList papszStrList);
54 const char CPL_DLL *CSLGetField(CSLConstList, int);
55 void CPL_DLL CPL_STDCALL CSLDestroy(char **papszStrList);
56 char CPL_DLL **CSLDuplicate(CSLConstList papszStrList) CPL_WARN_UNUSED_RESULT;
57 char CPL_DLL **CSLMerge(char **papszOrig,
58 CSLConstList papszOverride) CPL_WARN_UNUSED_RESULT;
59
60 char CPL_DLL **CSLTokenizeString(const char *pszString) CPL_WARN_UNUSED_RESULT;
61 char CPL_DLL **
62 CSLTokenizeStringComplex(const char *pszString, const char *pszDelimiter,
63 int bHonourStrings,
64 int bAllowEmptyTokens) CPL_WARN_UNUSED_RESULT;
65 char CPL_DLL **CSLTokenizeString2(const char *pszString,
66 const char *pszDelimiter,
67 int nCSLTFlags) CPL_WARN_UNUSED_RESULT;
68
70#define CSLT_HONOURSTRINGS 0x0001
72#define CSLT_ALLOWEMPTYTOKENS 0x0002
74#define CSLT_PRESERVEQUOTES 0x0004
76#define CSLT_PRESERVEESCAPES 0x0008
78#define CSLT_STRIPLEADSPACES 0x0010
80#define CSLT_STRIPENDSPACES 0x0020
81
82 int CPL_DLL CSLPrint(CSLConstList papszStrList, FILE *fpOut);
83 char CPL_DLL **CSLLoad(const char *pszFname) CPL_WARN_UNUSED_RESULT;
84 char CPL_DLL **CSLLoad2(const char *pszFname, int nMaxLines, int nMaxCols,
85 CSLConstList papszOptions) CPL_WARN_UNUSED_RESULT;
86 int CPL_DLL CSLSave(CSLConstList papszStrList, const char *pszFname);
87
88 char CPL_DLL **
89 CSLInsertStrings(char **papszStrList, int nInsertAtLineNo,
90 CSLConstList papszNewLines) CPL_WARN_UNUSED_RESULT;
91 char CPL_DLL **CSLInsertString(char **papszStrList, int nInsertAtLineNo,
92 const char *pszNewLine) CPL_WARN_UNUSED_RESULT;
93 char CPL_DLL **
94 CSLRemoveStrings(char **papszStrList, int nFirstLineToDelete, int nNumToRemove,
95 char ***ppapszRetStrings) CPL_WARN_UNUSED_RESULT;
96 int CPL_DLL CSLFindString(CSLConstList papszList, const char *pszTarget);
97 int CPL_DLL CSLFindStringCaseSensitive(CSLConstList papszList,
98 const char *pszTarget);
99 int CPL_DLL CSLPartialFindString(CSLConstList papszHaystack,
100 const char *pszNeedle);
101 int CPL_DLL CSLFindName(CSLConstList papszStrList, const char *pszName);
102 int CPL_DLL CSLFetchBoolean(CSLConstList papszStrList, const char *pszKey,
103 int bDefault);
104
105/* TODO: Deprecate CSLTestBoolean. Remove in GDAL 3.x. */
106 int CPL_DLL CSLTestBoolean(const char *pszValue);
107/* Do not use CPLTestBoolean in C++ code. Use CPLTestBool. */
108 int CPL_DLL CPLTestBoolean(const char *pszValue);
109
110 bool CPL_DLL CPLTestBool(const char *pszValue);
111 bool CPL_DLL CPLFetchBool(CSLConstList papszStrList, const char *pszKey,
112 bool bDefault);
113
114 CPLErr CPL_DLL CPLParseMemorySize(const char *pszValue, GIntBig *pnValue,
115 bool *pbUnitSpecified);
116
117 const char CPL_DLL *CPLParseNameValue(const char *pszNameValue, char **ppszKey);
118 const char CPL_DLL *CPLParseNameValueSep(const char *pszNameValue,
119 char **ppszKey, char chSep);
120
121 const char CPL_DLL *CSLFetchNameValue(CSLConstList papszStrList,
122 const char *pszName);
123 const char CPL_DLL *CSLFetchNameValueDef(CSLConstList papszStrList,
124 const char *pszName,
125 const char *pszDefault);
126 char CPL_DLL **CSLFetchNameValueMultiple(CSLConstList papszStrList,
127 const char *pszName);
128 char CPL_DLL **CSLAddNameValue(char **papszStrList, const char *pszName,
129 const char *pszValue) CPL_WARN_UNUSED_RESULT;
130 char CPL_DLL **CSLSetNameValue(char **papszStrList, const char *pszName,
131 const char *pszValue) CPL_WARN_UNUSED_RESULT;
132 void CPL_DLL CSLSetNameValueSeparator(char **papszStrList,
133 const char *pszSeparator);
134
135 char CPL_DLL **CSLParseCommandLine(const char *pszCommandLine);
136
138#define CPLES_BackslashQuotable 0
140#define CPLES_XML 1
142#define CPLES_URL 2
144#define CPLES_SQL 3
146#define CPLES_CSV 4
149#define CPLES_XML_BUT_QUOTES 5
151#define CPLES_CSV_FORCE_QUOTING 6
153#define CPLES_SQLI 7
154
155 char CPL_DLL *CPLEscapeString(const char *pszString, int nLength,
156 int nScheme) CPL_WARN_UNUSED_RESULT;
157 char CPL_DLL *CPLUnescapeString(const char *pszString, int *pnLength,
158 int nScheme) CPL_WARN_UNUSED_RESULT;
159
160 char CPL_DLL *CPLBinaryToHex(int nBytes,
161 const GByte *pabyData) CPL_WARN_UNUSED_RESULT;
162 GByte CPL_DLL *CPLHexToBinary(const char *pszHex,
163 int *pnBytes) CPL_WARN_UNUSED_RESULT;
164
165 char CPL_DLL *CPLBase64Encode(int nBytes,
166 const GByte *pabyData) CPL_WARN_UNUSED_RESULT;
167 int CPL_DLL CPLBase64DecodeInPlace(GByte *pszBase64) CPL_WARN_UNUSED_RESULT;
168
170 typedef enum
171{
172 CPL_VALUE_STRING,
173 CPL_VALUE_REAL,
174 CPL_VALUE_INTEGER
175} CPLValueType;
176
177 CPLValueType CPL_DLL CPLGetValueType(const char *pszValue);
178
179 int CPL_DLL CPLToupper(int c);
180 int CPL_DLL CPLTolower(int c);
181
182 size_t CPL_DLL CPLStrlcpy(char *pszDest, const char *pszSrc, size_t nDestSize);
183 size_t CPL_DLL CPLStrlcat(char *pszDest, const char *pszSrc, size_t nDestSize);
184 size_t CPL_DLL CPLStrnlen(const char *pszStr, size_t nMaxLen);
185
186/* -------------------------------------------------------------------- */
187/* Locale independent formatting functions. */
188/* -------------------------------------------------------------------- */
189 int CPL_DLL CPLvsnprintf(char *str, size_t size,
190 CPL_FORMAT_STRING(const char *fmt), va_list args)
191 CPL_PRINT_FUNC_FORMAT(3, 0);
192
193/* ALIAS_CPLSNPRINTF_AS_SNPRINTF might be defined to enable GCC 7 */
194/* -Wformat-truncation= warnings, but shouldn't be set for normal use */
195#if defined(ALIAS_CPLSNPRINTF_AS_SNPRINTF)
196#define CPLsnprintf snprintf
197#else
198 int CPL_DLL CPLsnprintf(char *str, size_t size,
199 CPL_FORMAT_STRING(const char *fmt), ...)
200 CPL_PRINT_FUNC_FORMAT(3, 4);
201#endif
202
204#if defined(GDAL_COMPILATION) && !defined(DONT_DEPRECATE_SPRINTF)
205 int CPL_DLL CPLsprintf(char *str, CPL_FORMAT_STRING(const char *fmt), ...)
206 CPL_PRINT_FUNC_FORMAT(2, 3) CPL_WARN_DEPRECATED("Use CPLsnprintf instead");
207#else
208 int CPL_DLL CPLsprintf(char *str, CPL_FORMAT_STRING(const char *fmt), ...)
209 CPL_PRINT_FUNC_FORMAT(2, 3);
210#endif
212 int CPL_DLL CPLprintf(CPL_FORMAT_STRING(const char *fmt), ...)
213 CPL_PRINT_FUNC_FORMAT(1, 2);
214
215/* For some reason Doxygen_Suppress is needed to avoid warning. Not sure why */
217/* caution: only works with limited number of formats */
218 int CPL_DLL CPLsscanf(const char *str, CPL_SCANF_FORMAT_STRING(const char *fmt),
219 ...) CPL_SCAN_FUNC_FORMAT(2, 3);
222const char CPL_DLL *CPLSPrintf(CPL_FORMAT_STRING(const char *fmt), ...)
223 CPL_PRINT_FUNC_FORMAT(1, 2) CPL_WARN_UNUSED_RESULT;
224 char CPL_DLL **CSLAppendPrintf(char **papszStrList,
225 CPL_FORMAT_STRING(const char *fmt), ...)
226 CPL_PRINT_FUNC_FORMAT(2, 3) CPL_WARN_UNUSED_RESULT;
227 int CPL_DLL CPLVASPrintf(char **buf, CPL_FORMAT_STRING(const char *fmt),
228 va_list args) CPL_PRINT_FUNC_FORMAT(2, 0);
229
230/* -------------------------------------------------------------------- */
231/* RFC 23 character set conversion/recoding API (cpl_recode.cpp). */
232/* -------------------------------------------------------------------- */
234#define CPL_ENC_LOCALE ""
236#define CPL_ENC_UTF8 "UTF-8"
238#define CPL_ENC_UTF16 "UTF-16"
240#define CPL_ENC_UCS2 "UCS-2"
242#define CPL_ENC_UCS4 "UCS-4"
244#define CPL_ENC_ASCII "ASCII"
246#define CPL_ENC_ISO8859_1 "ISO-8859-1"
247
248 int CPL_DLL CPLEncodingCharSize(const char *pszEncoding);
250 void CPL_DLL CPLClearRecodeWarningFlags(void);
252 char CPL_DLL *CPLRecode(const char *pszSource, const char *pszSrcEncoding,
253 const char *pszDstEncoding)
254 CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
255 char CPL_DLL *
256 CPLRecodeFromWChar(const wchar_t *pwszSource, const char *pszSrcEncoding,
257 const char *pszDstEncoding) CPL_WARN_UNUSED_RESULT;
258 wchar_t CPL_DLL *
259 CPLRecodeToWChar(const char *pszSource, const char *pszSrcEncoding,
260 const char *pszDstEncoding) CPL_WARN_UNUSED_RESULT;
261 int CPL_DLL CPLIsUTF8(const char *pabyData, int nLen);
262 bool CPL_DLL CPLIsASCII(const char *pabyData, size_t nLen);
263 char CPL_DLL *CPLForceToASCII(const char *pabyData, int nLen,
264 char chReplacementChar) CPL_WARN_UNUSED_RESULT;
265 char CPL_DLL *CPLUTF8ForceToASCII(const char *pszStr, char chReplacementChar)
266 CPL_WARN_UNUSED_RESULT;
267 int CPL_DLL CPLStrlenUTF8(const char *pszUTF8Str)
269 CPL_WARN_DEPRECATED("Use CPLStrlenUTF8Ex() instead")
271 ;
272 size_t CPL_DLL CPLStrlenUTF8Ex(const char *pszUTF8Str);
273 int CPL_DLL CPLCanRecode(const char *pszTestStr, const char *pszSrcEncoding,
274 const char *pszDstEncoding) CPL_WARN_UNUSED_RESULT;
275 CPL_C_END
276
277#if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
278
279 extern "C++"
280{
281 std::string CPL_DLL CPLRemoveSQLComments(const std::string &osInput);
282}
283
284#endif
285
286/************************************************************************/
287/* CPLString */
288/************************************************************************/
289
290#if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
291
292 extern "C++"
293{
294#ifndef DOXYGEN_SKIP
295#include <string>
296#include <vector>
297#endif
298
299// VC++ implicitly applies __declspec(dllexport) to template base classes
300// of classes marked with __declspec(dllexport).
301// Hence, if marked with CPL_DLL, VC++ would export symbols for the
302// specialization of std::basic_string<char>, since it is a base class of
303// CPLString. As a result, if an application linked both gdal.dll and a static
304// library that (implicitly) instantiates std::string (almost all do!), then the
305// linker would emit an error concerning duplicate symbols for std::string. The
306// least intrusive solution is to not mark the whole class with
307// __declspec(dllexport) for VC++, but only its non-inline methods.
308#ifdef _MSC_VER
309#define CPLSTRING_CLASS_DLL
310#define CPLSTRING_METHOD_DLL CPL_DLL
311#else
313#define CPLSTRING_CLASS_DLL CPL_DLL
314#define CPLSTRING_METHOD_DLL
316#endif
317
319 class CPLSTRING_CLASS_DLL CPLString : public std::string
320 {
321 public:
323 CPLString(void)
324 {
325 }
326
328 // cppcheck-suppress noExplicitConstructor
329 CPLString(const std::string &oStr) : std::string(oStr)
330 {
331 }
332
334 // cppcheck-suppress noExplicitConstructor
335 CPLString(const char *pszStr) : std::string(pszStr)
336 {
337 }
338
340 CPLString(const char *pszStr, size_t n) : std::string(pszStr, n)
341 {
342 }
343
345 operator const char *(void) const
346 {
347 return c_str();
348 }
349
351 char &operator[](std::string::size_type i)
352 {
353 return std::string::operator[](i);
354 }
355
357 const char &operator[](std::string::size_type i) const
358 {
359 return std::string::operator[](i);
360 }
361
363 char &operator[](int i)
364 {
365 return std::string::operator[](
366 static_cast<std::string::size_type>(i));
367 }
368
370 const char &operator[](int i) const
371 {
372 return std::string::operator[](
373 static_cast<std::string::size_type>(i));
374 }
375
377 void Clear()
378 {
379 resize(0);
380 }
381
385 void Seize(char *pszValue)
386 {
387 if (pszValue == nullptr)
388 Clear();
389 else
390 {
391 *this = pszValue;
392 CPLFree(pszValue);
393 }
394 }
395
396 /* There seems to be a bug in the way the compiler count indices...
397 * Should be CPL_PRINT_FUNC_FORMAT (1, 2) */
398 CPLSTRING_METHOD_DLL CPLString &
399 Printf(CPL_FORMAT_STRING(const char *pszFormat), ...)
400 CPL_PRINT_FUNC_FORMAT(2, 3);
401 CPLSTRING_METHOD_DLL CPLString &
402 vPrintf(CPL_FORMAT_STRING(const char *pszFormat), va_list args)
403 CPL_PRINT_FUNC_FORMAT(2, 0);
404 CPLSTRING_METHOD_DLL CPLString &
405 FormatC(double dfValue, const char *pszFormat = nullptr);
406 CPLSTRING_METHOD_DLL CPLString &Trim();
407 CPLSTRING_METHOD_DLL CPLString &Recode(const char *pszSrcEncoding,
408 const char *pszDstEncoding);
409 CPLSTRING_METHOD_DLL CPLString &replaceAll(const std::string &osBefore,
410 const std::string &osAfter);
411 CPLSTRING_METHOD_DLL CPLString &replaceAll(const std::string &osBefore,
412 char chAfter);
413 CPLSTRING_METHOD_DLL CPLString &replaceAll(char chBefore,
414 const std::string &osAfter);
415 CPLSTRING_METHOD_DLL CPLString &replaceAll(char chBefore, char chAfter);
416
417 /* case insensitive find alternates */
418 CPLSTRING_METHOD_DLL size_t ifind(const std::string &str,
419 size_t pos = 0) const;
420 CPLSTRING_METHOD_DLL size_t ifind(const char *s, size_t pos = 0) const;
421 CPLSTRING_METHOD_DLL CPLString &toupper(void);
422 CPLSTRING_METHOD_DLL CPLString &tolower(void);
423
424 CPLSTRING_METHOD_DLL bool endsWith(const std::string &osStr) const;
425
426 CPLSTRING_METHOD_DLL CPLString URLEncode() const;
427
428 CPLSTRING_METHOD_DLL CPLString SQLQuotedIdentifier() const;
429
430 CPLSTRING_METHOD_DLL CPLString SQLQuotedLiteral() const;
431
432 private:
433 operator void *(void) = delete;
434 };
435
436#undef CPLSTRING_CLASS_DLL
437#undef CPLSTRING_METHOD_DLL
438
439 CPLString CPL_DLL CPLOPrintf(CPL_FORMAT_STRING(const char *pszFormat), ...)
440 CPL_PRINT_FUNC_FORMAT(1, 2);
441 CPLString CPL_DLL CPLOvPrintf(CPL_FORMAT_STRING(const char *pszFormat),
442 va_list args) CPL_PRINT_FUNC_FORMAT(1, 0);
443 CPLString CPL_DLL CPLQuotedSQLIdentifier(const char *pszIdent);
444
445 /* -------------------------------------------------------------------- */
446 /* URL processing functions, here since they depend on CPLString. */
447 /* -------------------------------------------------------------------- */
448 CPLString CPL_DLL CPLURLGetValue(const char *pszURL, const char *pszKey);
449 CPLString CPL_DLL CPLURLAddKVP(const char *pszURL, const char *pszKey,
450 const char *pszValue);
451
452 /************************************************************************/
453 /* CPLStringList */
454 /************************************************************************/
455
457 class CPL_DLL CPLStringList
458 {
459 char **papszList = nullptr;
460 mutable int nCount = 0;
461 mutable int nAllocation = 0;
462 bool bOwnList = false;
463 bool bIsSorted = false;
464
465 bool MakeOurOwnCopy();
466 bool EnsureAllocation(int nMaxLength);
467 int FindSortedInsertionPoint(const char *pszLine);
468
469 public:
470 CPLStringList();
471 explicit CPLStringList(char **papszList, int bTakeOwnership = TRUE);
472 explicit CPLStringList(CSLConstList papszList);
473 explicit CPLStringList(const std::vector<std::string> &aosList);
474 explicit CPLStringList(std::initializer_list<const char *> oInitList);
475 CPLStringList(const CPLStringList &oOther);
476 CPLStringList(CPLStringList &&oOther);
477 ~CPLStringList();
478
479 static const CPLStringList BoundToConstList(CSLConstList papszList);
480
481 CPLStringList &Clear();
482
484 inline void clear()
485 {
486 Clear();
487 }
488
490 int size() const
491 {
492 return Count();
493 }
494
495 int Count() const;
496
498 bool empty() const
499 {
500 return Count() == 0;
501 }
502
503 CPLStringList &AddString(const char *pszNewString);
504 CPLStringList &AddString(const std::string &newString);
505 CPLStringList &AddStringDirectly(char *pszNewString);
506
508 void push_back(const char *pszNewString)
509 {
510 AddString(pszNewString);
511 }
512
514 void push_back(const std::string &osStr)
515 {
516 AddString(osStr.c_str());
517 }
518
519 CPLStringList &InsertString(int nInsertAtLineNo, const char *pszNewLine)
520 {
521 return InsertStringDirectly(nInsertAtLineNo, CPLStrdup(pszNewLine));
522 }
523
524 CPLStringList &InsertStringDirectly(int nInsertAtLineNo,
525 char *pszNewLine);
526
527 // CPLStringList &InsertStrings( int nInsertAtLineNo, char
528 // **papszNewLines ); CPLStringList &RemoveStrings( int
529 // nFirstLineToDelete, int nNumToRemove=1 );
530
532 int FindString(const char *pszTarget) const
533 {
534 return CSLFindString(papszList, pszTarget);
535 }
536
539 int PartialFindString(const char *pszNeedle) const
540 {
541 return CSLPartialFindString(papszList, pszNeedle);
542 }
543
544 int FindName(const char *pszName) const;
545 bool FetchBool(const char *pszKey, bool bDefault) const;
546 // Deprecated.
547 int FetchBoolean(const char *pszKey, int bDefault) const;
548 const char *FetchNameValue(const char *pszKey) const;
549 const char *FetchNameValueDef(const char *pszKey,
550 const char *pszDefault) const;
551 CPLStringList &AddNameValue(const char *pszKey, const char *pszValue);
552 CPLStringList &SetNameValue(const char *pszKey, const char *pszValue);
553
554 CPLStringList &Assign(char **papszListIn, int bTakeOwnership = TRUE);
555
557 CPLStringList &operator=(char **papszListIn)
558 {
559 return Assign(papszListIn, TRUE);
560 }
561
563 CPLStringList &operator=(const CPLStringList &oOther);
565 CPLStringList &operator=(CSLConstList papszListIn);
567 CPLStringList &operator=(CPLStringList &&oOther);
568
570 char *operator[](int i);
571
573 char *operator[](size_t i)
574 {
575 return (*this)[static_cast<int>(i)];
576 }
577
579 const char *operator[](int i) const;
580
582 const char *operator[](size_t i) const
583 {
584 return (*this)[static_cast<int>(i)];
585 }
586
588 const char *operator[](const char *pszKey) const
589 {
590 return FetchNameValue(pszKey);
591 }
592
594 inline const char *front() const
595 {
596 return papszList[0];
597 }
598
600 inline const char *back() const
601 {
602 return papszList[size() - 1];
603 }
604
606 const char *const *begin() const
607 {
608 return papszList ? &papszList[0] : nullptr;
609 }
610
612 const char *const *end() const
613 {
614 return papszList ? &papszList[size()] : nullptr;
615 }
616
618 char **List()
619 {
620 return papszList;
621 }
622
624 CSLConstList List() const
625 {
626 return papszList;
627 }
628
629 char **StealList();
630
631 CPLStringList &Sort();
632
634 int IsSorted() const
635 {
636 return bIsSorted;
637 }
638
640 operator char **(void)
641 {
642 return List();
643 }
644
646 operator CSLConstList(void) const
647 {
648 return List();
649 }
650
652 operator std::vector<std::string>(void) const
653 {
654 return std::vector<std::string>{begin(), end()};
655 }
656
657 private:
658 operator void *(void) = delete;
659 };
660
661#ifdef GDAL_COMPILATION
662
663#include <iterator> // For std::input_iterator_tag
664#include <memory>
665#include <string_view>
666#include <utility> // For std::pair
667
669 struct CPL_DLL CSLDestroyReleaser
670 {
671 void operator()(char **papszStr) const
672 {
673 CSLDestroy(papszStr);
674 }
675 };
676
680 using CSLUniquePtr = std::unique_ptr<char *, CSLDestroyReleaser>;
681
684 using CPLCharUniquePtr = std::unique_ptr<char, VSIFreeReleaser>;
685
686 namespace cpl
687 {
688
692 template <class StringType>
693 inline bool starts_with(const StringType &str, const char *prefix)
694 {
695 const size_t prefixLen = strlen(prefix);
696 return str.size() >= prefixLen &&
697 str.compare(0, prefixLen, prefix, prefixLen) == 0;
698 }
699
701 template <class StringType>
702 inline bool starts_with(const StringType &str, const std::string &prefix)
703 {
704 return str.size() >= prefix.size() &&
705 str.compare(0, prefix.size(), prefix) == 0;
706 }
707
709 template <class StringType>
710 inline bool starts_with(const StringType &str, std::string_view prefix)
711 {
712 return str.size() >= prefix.size() &&
713 str.compare(0, prefix.size(), prefix) == 0;
714 }
715
717 template <class StringType>
718 inline bool ends_with(const StringType &str, const char *suffix)
719 {
720 const size_t suffixLen = strlen(suffix);
721 return str.size() >= suffixLen &&
722 str.compare(str.size() - suffixLen, suffixLen, suffix,
723 suffixLen) == 0;
724 }
725
727 template <class StringType>
728 inline bool ends_with(const StringType &str, const std::string &suffix)
729 {
730 return str.size() >= suffix.size() &&
731 str.compare(str.size() - suffix.size(), suffix.size(), suffix) ==
732 0;
733 }
734
736 template <class StringType>
737 inline bool ends_with(const StringType &str, std::string_view suffix)
738 {
739 return str.size() >= suffix.size() &&
740 str.compare(str.size() - suffix.size(), suffix.size(), suffix) ==
741 0;
742 }
743
745 struct CPL_DLL CSLIterator
746 {
747 using iterator_category = std::input_iterator_tag;
748 using difference_type = std::ptrdiff_t;
749 using value_type = const char *;
750 using pointer = value_type *;
751 using reference = value_type &;
752
753 CSLConstList m_papszList = nullptr;
754 bool m_bAtEnd = false;
755
756 inline const char *operator*() const
757 {
758 return *m_papszList;
759 }
760
761 inline CSLIterator &operator++()
762 {
763 if (m_papszList)
764 ++m_papszList;
765 return *this;
766 }
767
768 bool operator==(const CSLIterator &other) const;
769
770 inline bool operator!=(const CSLIterator &other) const
771 {
772 return !(operator==(other));
773 }
774 };
775
782 struct CPL_DLL CSLIteratorWrapper
783 {
784 public:
786 inline explicit CSLIteratorWrapper(CSLConstList papszList)
787 : m_papszList(papszList)
788 {
789 }
790
792 inline CSLIterator begin() const
793 {
794 return {m_papszList, false};
795 }
796
798 inline CSLIterator end() const
799 {
800 return {m_papszList, true};
801 }
802
803 private:
804 CSLConstList m_papszList;
805 };
806
811 inline CSLIteratorWrapper Iterate(CSLConstList papszList)
812 {
813 return CSLIteratorWrapper{papszList};
814 }
815
817 inline CSLIteratorWrapper Iterate(const CPLStringList &aosList)
818 {
819 return Iterate(aosList.List());
820 }
821
825 inline CSLIteratorWrapper Iterate(char **) = delete;
826
831 struct CPL_DLL CSLNameValueIterator
832 {
833 using iterator_category = std::input_iterator_tag;
834 using difference_type = std::ptrdiff_t;
835 using value_type = std::pair<const char *, const char *>;
836 using pointer = value_type *;
837 using reference = value_type &;
838
839 CSLConstList m_papszList = nullptr;
840 bool m_bReturnNullKeyIfNotNameValue = false;
841 std::string m_osKey{};
842
843 value_type operator*();
844
845 inline CSLNameValueIterator &operator++()
846 {
847 if (m_papszList)
848 ++m_papszList;
849 return *this;
850 }
851
852 inline bool operator==(const CSLNameValueIterator &other) const
853 {
854 return m_papszList == other.m_papszList;
855 }
856
857 inline bool operator!=(const CSLNameValueIterator &other) const
858 {
859 return !(operator==(other));
860 }
861 };
862
876 struct CPL_DLL CSLNameValueIteratorWrapper
877 {
878 public:
880 inline explicit CSLNameValueIteratorWrapper(
881 CSLConstList papszList, bool bReturnNullKeyIfNotNameValue)
882 : m_papszList(papszList),
883 m_bReturnNullKeyIfNotNameValue(bReturnNullKeyIfNotNameValue)
884 {
885 }
886
888 inline CSLNameValueIterator begin() const
889 {
890 return {m_papszList, m_bReturnNullKeyIfNotNameValue};
891 }
892
894 CSLNameValueIterator end() const;
895
896 private:
897 CSLConstList m_papszList;
898 const bool m_bReturnNullKeyIfNotNameValue;
899 };
900
917 inline CSLNameValueIteratorWrapper
918 IterateNameValue(CSLConstList papszList,
919 bool bReturnNullKeyIfNotNameValue = false)
920 {
921 return CSLNameValueIteratorWrapper{papszList,
922 bReturnNullKeyIfNotNameValue};
923 }
924
926 inline CSLNameValueIteratorWrapper
927 IterateNameValue(const CPLStringList &aosList,
928 bool bReturnNullKeyIfNotNameValue = false)
929 {
930 return IterateNameValue(aosList.List(), bReturnNullKeyIfNotNameValue);
931 }
932
936 inline CSLIteratorWrapper IterateNameValue(char **, bool = false) = delete;
937
941 inline std::vector<std::string> ToVector(CSLConstList papszList)
942 {
943 return CPLStringList::BoundToConstList(papszList);
944 }
945
946 inline std::vector<std::string> ToVector(char **) = delete;
947
948 } // namespace cpl
949
950#endif
951
952} // extern "C++"
953
954#endif /* def __cplusplus && !CPL_SUPRESS_CPLUSPLUS */
955
956#endif /* CPL_STRING_H_INCLUDED */
CPLStringList
String list class designed around our use of C "char**" string lists.
Definition cpl_string.h:458
CPLStringList::operator[]
const char * operator[](size_t i) const
Return string at specified index.
Definition cpl_string.h:582
CPLStringList::operator[]
const char * operator[](const char *pszKey) const
Return value corresponding to pszKey, or nullptr.
Definition cpl_string.h:588
CPLStringList::IsSorted
int IsSorted() const
Returns whether the list is sorted.
Definition cpl_string.h:634
CPLStringList::empty
bool empty() const
Return whether the list is empty.
Definition cpl_string.h:498
CPLStringList::end
const char *const * end() const
end() implementation
Definition cpl_string.h:612
CPLStringList::operator=
CPLStringList & operator=(CSLConstList papszListIn)
Assignment operator.
CPLStringList::push_back
void push_back(const std::string &osStr)
Add a string to the list.
Definition cpl_string.h:514
CPLStringList::List
char ** List()
Return list.
Definition cpl_string.h:618
CPLStringList::clear
void clear()
Clear the list.
Definition cpl_string.h:484
CPLStringList::push_back
void push_back(const char *pszNewString)
Add a string to the list.
Definition cpl_string.h:508
CPLStringList::InsertString
CPLStringList & InsertString(int nInsertAtLineNo, const char *pszNewLine)
Insert into the list at identified location.
Definition cpl_string.h:519
CPLStringList::operator=
CPLStringList & operator=(char **papszListIn)
Assignment operator.
Definition cpl_string.h:557
CPLStringList::operator[]
char * operator[](size_t i)
Return string at specified index.
Definition cpl_string.h:573
CPLStringList::size
int size() const
Return size of list.
Definition cpl_string.h:490
CPLStringList::List
CSLConstList List() const
Return list.
Definition cpl_string.h:624
CPLStringList::front
const char * front() const
Return first element.
Definition cpl_string.h:594
CPLStringList::begin
const char *const * begin() const
begin() implementation
Definition cpl_string.h:606
CPLStringList::FindString
int FindString(const char *pszTarget) const
Return index of pszTarget in the list, or -1.
Definition cpl_string.h:532
CPLStringList::back
const char * back() const
Return last element.
Definition cpl_string.h:600
CPLStringList::BoundToConstList
static const CPLStringList BoundToConstList(CSLConstList papszList)
Return a CPLStringList that wraps the passed list.
Definition cplstringlist.cpp:158
CPLStringList::PartialFindString
int PartialFindString(const char *pszNeedle) const
Return index of pszTarget in the list (using partial search), or -1.
Definition cpl_string.h:539
CPLString
Convenient string class based on std::string.
Definition cpl_string.h:320
CPLString::Clear
void Clear()
Clear the string.
Definition cpl_string.h:377
CPLString::CPLString
CPLString(void)
Constructor.
Definition cpl_string.h:323
CPLString::operator[]
const char & operator[](std::string::size_type i) const
Return character at specified index.
Definition cpl_string.h:357
CPLString::CPLString
CPLString(const std::string &oStr)
Constructor.
Definition cpl_string.h:329
CPLString::Seize
void Seize(char *pszValue)
Assign specified string and take ownership of it (assumed to be allocated with CPLMalloc()).
Definition cpl_string.h:385
CPLString::operator[]
char & operator[](int i)
Return character at specified index.
Definition cpl_string.h:363
CPLString::operator[]
const char & operator[](int i) const
Return character at specified index.
Definition cpl_string.h:370
CPLString::operator[]
char & operator[](std::string::size_type i)
Return character at specified index.
Definition cpl_string.h:351
CPLString::CPLString
CPLString(const char *pszStr, size_t n)
Constructor.
Definition cpl_string.h:340
CPLString::CPLString
CPLString(const char *pszStr)
Constructor.
Definition cpl_string.h:335
cpl_conv.h
Various convenience functions for CPL.
CPLFree
#define CPLFree
Alias of VSIFree()
Definition cpl_conv.h:90
cpl_error.h
CPL error handling services.
CPLErr
CPLErr
Error category.
Definition cpl_error.h:37
CPL_SCAN_FUNC_FORMAT
#define CPL_SCAN_FUNC_FORMAT(format_idx, arg_idx)
Tag a function to have scanf() formatting.
Definition cpl_port.h:846
CPL_C_END
#define CPL_C_END
Macro to end a block of C symbols.
Definition cpl_port.h:289
CPL_C_START
#define CPL_C_START
Macro to start a block of C symbols.
Definition cpl_port.h:285
CPL_FORMAT_STRING
#define CPL_FORMAT_STRING(arg)
Macro into which to wrap the format argument of a printf-like function.
Definition cpl_port.h:860
CPL_RETURNS_NONNULL
#define CPL_RETURNS_NONNULL
Qualifier for a function that does not return NULL.
Definition cpl_port.h:908
CPL_PRINT_FUNC_FORMAT
#define CPL_PRINT_FUNC_FORMAT(format_idx, arg_idx)
Tag a function to have printf() formatting.
Definition cpl_port.h:844
CSLConstList
char ** CSLConstList
Type of a constant null-terminated list of nul terminated strings.
Definition cpl_port.h:1087
CPL_WARN_UNUSED_RESULT
#define CPL_WARN_UNUSED_RESULT
Qualifier to warn when the return value of a function is not used.
Definition cpl_port.h:870
CPL_SCANF_FORMAT_STRING
#define CPL_SCANF_FORMAT_STRING(arg)
Macro into which to wrap the format argument of a sscanf-like function.
Definition cpl_port.h:862
GByte
unsigned char GByte
Unsigned byte type.
Definition cpl_port.h:175
GIntBig
long long GIntBig
Large signed integer type (generally 64-bit integer type).
Definition cpl_port.h:205
CSLFindStringCaseSensitive
int CSLFindStringCaseSensitive(CSLConstList papszList, const char *pszTarget)
Find a string within a string list(case sensitive)
Definition cpl_string.cpp:687
CPLvsnprintf
int CPLvsnprintf(char *str, size_t size, const char *fmt, va_list args)
vsnprintf() wrapper that is not sensitive to LC_NUMERIC settings.
Definition cpl_string.cpp:1128
CPLEscapeString
char * CPLEscapeString(const char *pszString, int nLength, int nScheme)
Apply escaping to string to preserve special characters.
Definition cpl_string.cpp:2215
CPLBinaryToHex
char * CPLBinaryToHex(int nBytes, const GByte *pabyData)
Binary to hexadecimal translation.
Definition cpl_string.cpp:2789
CPLRemoveSQLComments
std::string CPLRemoveSQLComments(const std::string &osInput)
Remove SQL comments from a string.
Definition cpl_string.cpp:3181
CSLTokenizeStringComplex
char ** CSLTokenizeStringComplex(const char *pszString, const char *pszDelimiter, int bHonourStrings, int bAllowEmptyTokens)
Obsolete tokenizing api.
Definition cpl_string.cpp:750
CPLprintf
int CPLprintf(const char *fmt,...)
printf() wrapper that is not sensitive to LC_NUMERIC settings.
Definition cpl_string.cpp:1400
CPLBase64DecodeInPlace
int CPLBase64DecodeInPlace(GByte *pszBase64)
Decode base64 string "pszBase64" (null terminated) in place.
Definition cpl_base64.cpp:90
CSLAddNameValue
char ** CSLAddNameValue(char **papszStrList, const char *pszName, const char *pszValue)
Add a new entry to a StringList of "Name=Value" pairs, ("Name:Value" pairs are also supported for bac...
Definition cpl_string.cpp:2016
CPLStrlenUTF8Ex
size_t CPLStrlenUTF8Ex(const char *pszUTF8Str)
Return the number of UTF-8 characters of a nul-terminated string.
Definition cpl_recode.cpp:1198
CPLQuotedSQLIdentifier
CPLString CPLQuotedSQLIdentifier(const char *pszIdent)
Return a CPLString of the SQL quoted identifier.
Definition cplstring.cpp:613
CPLOPrintf
CPLString CPLOPrintf(const char *pszFormat,...)
Return a CPLString with the content of sprintf()
Definition cplstring.cpp:581
CPLStrlcat
size_t CPLStrlcat(char *pszDest, const char *pszSrc, size_t nDestSize)
Appends a source string to a destination buffer.
Definition cpl_string.cpp:3080
CSLPrint
int CSLPrint(CSLConstList papszStrList, FILE *fpOut)
Print a StringList to fpOut.
Definition cpl_string.cpp:445
CPLForceToASCII
char * CPLForceToASCII(const char *pabyData, int nLen, char chReplacementChar)
Return a new string that is made only of ASCII characters.
Definition cpl_recode.cpp:296
CSLTokenizeString2
char ** CSLTokenizeString2(const char *pszString, const char *pszDelimiter, int nCSLTFlags)
Tokenize a string.
Definition cpl_string.cpp:817
CPLURLGetValue
CPLString CPLURLGetValue(const char *pszURL, const char *pszKey)
Return the value matching a key from a key=value pair in a URL.
Definition cplstring.cpp:500
CPLStrlcpy
size_t CPLStrlcpy(char *pszDest, const char *pszSrc, size_t nDestSize)
Copy source string to a destination buffer.
Definition cpl_string.cpp:3024
CSLFetchNameValue
const char * CSLFetchNameValue(CSLConstList papszStrList, const char *pszName)
In a StringList of "Name=Value" pairs, look for the first value associated with the specified name.
Definition cpl_string.cpp:1678
CPLRecodeFromWChar
char * CPLRecodeFromWChar(const wchar_t *pwszSource, const char *pszSrcEncoding, const char *pszDstEncoding)
Convert wchar_t string to UTF-8.
Definition cpl_recode.cpp:163
CPLsnprintf
int CPLsnprintf(char *str, size_t size, const char *fmt,...)
snprintf() wrapper that is not sensitive to LC_NUMERIC settings.
Definition cpl_string.cpp:1347
CPLIsASCII
bool CPLIsASCII(const char *pabyData, size_t nLen)
Test if a string is encoded as ASCII.
Definition cpl_recode.cpp:260
CPLValueType
CPLValueType
Type of value.
Definition cpl_string.h:171
CPL_VALUE_INTEGER
@ CPL_VALUE_INTEGER
Integer.
Definition cpl_string.h:174
CPL_VALUE_STRING
@ CPL_VALUE_STRING
String.
Definition cpl_string.h:172
CPL_VALUE_REAL
@ CPL_VALUE_REAL
Real number.
Definition cpl_string.h:173
CSLDestroy
void CSLDestroy(char **papszStrList)
Free string list.
Definition cpl_string.cpp:185
CPLFetchBool
bool CPLFetchBool(CSLConstList papszStrList, const char *pszKey, bool bDefault)
Check for boolean key value.
Definition cpl_string.cpp:1607
CSLFindName
int CSLFindName(CSLConstList papszStrList, const char *pszName)
Find StringList entry with given key name.
Definition cpl_string.cpp:1710
CPLParseMemorySize
CPLErr CPLParseMemorySize(const char *pszValue, GIntBig *pnValue, bool *pbUnitSpecified)
Parse a memory size from a string.
Definition cpl_string.cpp:1751
CPLVASPrintf
int CPLVASPrintf(char **buf, const char *fmt, va_list args)
This is intended to serve as an easy to use C callable vasprintf() alternative.
Definition cpl_string.cpp:1037
CPLParseNameValueSep
const char * CPLParseNameValueSep(const char *pszNameValue, char **ppszKey, char chSep)
Parse NAME<Sep>VALUE string into name and value components.
Definition cpl_string.cpp:1933
CPLTolower
int CPLTolower(int c)
Converts a (ASCII) uppercase character to lowercase.
Definition cpl_string.cpp:3167
CPLCanRecode
int CPLCanRecode(const char *pszTestStr, const char *pszSrcEncoding, const char *pszDstEncoding)
Checks if it is possible to recode a string from one encoding to another.
Definition cpl_recode.cpp:1226
CSLGetField
const char * CSLGetField(CSLConstList, int)
Fetches the indicated field, being careful not to crash if the field doesn't exist within this string...
Definition cpl_string.cpp:158
CSLFindString
int CSLFindString(CSLConstList papszList, const char *pszTarget)
Find a string within a string list (case insensitive).
Definition cpl_string.cpp:654
CSLSave
int CSLSave(CSLConstList papszStrList, const char *pszFname)
Write a StringList to a text file.
Definition cpl_string.cpp:396
CPLTestBool
bool CPLTestBool(const char *pszValue)
Test what boolean value contained in the string.
Definition cpl_string.cpp:1535
CSLParseCommandLine
char ** CSLParseCommandLine(const char *pszCommandLine)
Tokenize command line arguments in a list of strings.
Definition cpl_string.cpp:3137
CSLFetchNameValueDef
const char * CSLFetchNameValueDef(CSLConstList papszStrList, const char *pszName, const char *pszDefault)
Same as CSLFetchNameValue() but return pszDefault in case of no match.
Definition cpl_string.cpp:1651
CSLCount
int CSLCount(CSLConstList papszStrList)
Return number of items in a string list.
Definition cpl_string.cpp:132
CSLAddString
char ** CSLAddString(char **papszStrList, const char *pszNewString)
Append a string to a StringList and return a pointer to the modified StringList.
Definition cpl_string.cpp:68
CPLStrnlen
size_t CPLStrnlen(const char *pszStr, size_t nMaxLen)
Returns the length of a NUL terminated string by reading at most the specified number of bytes.
Definition cpl_string.cpp:3114
CPLUTF8ForceToASCII
char * CPLUTF8ForceToASCII(const char *pszStr, char chReplacementChar)
Return a new string that is made only of ASCII characters.
Definition cpl_recode.cpp:347
CSLInsertString
char ** CSLInsertString(char **papszStrList, int nInsertAtLineNo, const char *pszNewLine)
Insert a string at a given line number inside a StringList.
Definition cpl_string.cpp:546
CSLSetNameValueSeparator
void CSLSetNameValueSeparator(char **papszStrList, const char *pszSeparator)
Replace the default separator (":" or "=") with the passed separator in the given name/value list.
Definition cpl_string.cpp:2136
CPLIsUTF8
int CPLIsUTF8(const char *pabyData, int nLen)
Test if a string is encoded as UTF-8.
Definition cpl_recode_stub.cpp:500
CSLPartialFindString
int CSLPartialFindString(CSLConstList papszHaystack, const char *pszNeedle)
Find a substring within a string list.
Definition cpl_string.cpp:719
CSLTokenizeString
char ** CSLTokenizeString(const char *pszString)
Tokenizes a string and returns a StringList with one string for each token.
Definition cpl_string.cpp:740
CSLFetchNameValueMultiple
char ** CSLFetchNameValueMultiple(CSLConstList papszStrList, const char *pszName)
In a StringList of "Name=Value" pairs, look for all the values with the specified name.
Definition cpl_string.cpp:1981
CPLGetValueType
CPLValueType CPLGetValueType(const char *pszValue)
Detect the type of the value contained in a string, whether it is a real, an integer or a string Lead...
Definition cpl_string.cpp:2889
CSLSetNameValue
char ** CSLSetNameValue(char **papszStrList, const char *pszName, const char *pszValue)
Assign value to name in StringList.
Definition cpl_string.cpp:2055
CSLRemoveStrings
char ** CSLRemoveStrings(char **papszStrList, int nFirstLineToDelete, int nNumToRemove, char ***ppapszRetStrings)
Remove strings inside a StringList.
Definition cpl_string.cpp:572
CSLLoad
char ** CSLLoad(const char *pszFname)
Load a text file into a string list.
Definition cpl_string.cpp:381
CPLRecode
char * CPLRecode(const char *pszSource, const char *pszSrcEncoding, const char *pszDstEncoding)
Convert a string from a source encoding to a destination encoding.
Definition cpl_recode.cpp:79
CSLLoad2
char ** CSLLoad2(const char *pszFname, int nMaxLines, int nMaxCols, CSLConstList papszOptions)
Load a text file into a string list.
Definition cpl_string.cpp:305
CPLURLAddKVP
CPLString CPLURLAddKVP(const char *pszURL, const char *pszKey, const char *pszValue)
Return a new URL with a new key=value pair.
Definition cplstring.cpp:532
CSLFetchBoolean
int CSLFetchBoolean(CSLConstList papszStrList, const char *pszKey, int bDefault)
DEPRECATED.
Definition cpl_string.cpp:1640
CPLStrlenUTF8
int CPLStrlenUTF8(const char *pszUTF8Str)
Return the number of UTF-8 characters of a nul-terminated string.
Definition cpl_recode.cpp:1164
CSLAppendPrintf
char ** CSLAppendPrintf(char **papszStrList, const char *fmt,...)
Use CPLSPrintf() to append a new line at the end of a StringList.
Definition cpl_string.cpp:1018
CSLInsertStrings
char ** CSLInsertStrings(char **papszStrList, int nInsertAtLineNo, CSLConstList papszNewLines)
Copies the contents of a StringList inside another StringList before the specified line.
Definition cpl_string.cpp:481
CPLOvPrintf
CPLString CPLOvPrintf(const char *pszFormat, va_list args)
Return a CPLString with the content of vsprintf()
Definition cplstring.cpp:600
CSLDuplicate
char ** CSLDuplicate(CSLConstList papszStrList)
Clone a string list.
Definition cpl_string.cpp:213
CPLParseNameValue
const char * CPLParseNameValue(const char *pszNameValue, char **ppszKey)
Parse NAME=VALUE string into name and value components.
Definition cpl_string.cpp:1886
CSLTestBoolean
int CSLTestBoolean(const char *pszValue)
Test what boolean value contained in the string.
Definition cpl_string.cpp:1560
CPLSPrintf
const char * CPLSPrintf(const char *fmt,...)
CPLSPrintf() that works with 10 static buffer.
Definition cpl_string.cpp:965
CPLToupper
int CPLToupper(int c)
Converts a (ASCII) lowercase character to uppercase.
Definition cpl_string.cpp:3152
CPLHexToBinary
GByte * CPLHexToBinary(const char *pszHex, int *pnBytes)
Hexadecimal to binary translation.
Definition cpl_string.cpp:2850
CSLMerge
char ** CSLMerge(char **papszOrig, CSLConstList papszOverride)
Merge two lists.
Definition cpl_string.cpp:258
CSLAddStringMayFail
char ** CSLAddStringMayFail(char **papszStrList, const char *pszNewString)
Same as CSLAddString() but may return NULL in case of (memory) failure.
Definition cpl_string.cpp:77
CPLEncodingCharSize
int CPLEncodingCharSize(const char *pszEncoding)
Return bytes per character for encoding.
Definition cpl_recode.cpp:1118
CPLUnescapeString
char * CPLUnescapeString(const char *pszString, int *pnLength, int nScheme)
Unescape a string.
Definition cpl_string.cpp:2565
CPLBase64Encode
char * CPLBase64Encode(int nBytes, const GByte *pabyData)
Base64 encode a buffer.
Definition cpl_base64.cpp:196
CPLTestBoolean
int CPLTestBoolean(const char *pszValue)
Test what boolean value contained in the string.
Definition cpl_string.cpp:1582
CPLRecodeToWChar
wchar_t * CPLRecodeToWChar(const char *pszSource, const char *pszSrcEncoding, const char *pszDstEncoding)
Convert UTF-8 string to a wchar_t string.
Definition cpl_recode.cpp:219
cpl_vsi.h
Standard C Covers.
begin
OGRLayer::FeatureIterator begin(OGRLayer *poLayer)
Return begin of feature iterator.
Definition ogrsf_frmts.h:470
end
OGRLayer::FeatureIterator end(OGRLayer *poLayer)
Return end of feature iterator.
Definition ogrsf_frmts.h:478