GDAL

cpl_string.h
Go to the documentation of this file.
1/**********************************************************************
2 * $Id$
3 *
4 * Name: cpl_string.h
5 * Project: CPL - Common Portability Library
6 * Purpose: String and StringList functions.
7 * Author: Daniel Morissette, dmorissette@mapgears.com
8 *
9 **********************************************************************
10 * Copyright (c) 1998, Daniel Morissette
11 * Copyright (c) 2008-2014, Even Rouault <even dot rouault at spatialys.com>
12 *
13 * SPDX-License-Identifier: MIT
14 ****************************************************************************/
15
16#ifndef CPL_STRING_H_INCLUDED
17#define CPL_STRING_H_INCLUDED
18
19#include "cpl_error.h"
20#include "cpl_conv.h"
21#include "cpl_vsi.h"
22
23#include <stdbool.h>
24
47 CPL_C_START
48
49 char CPL_DLL **CSLAddString(char **papszStrList,
50 const char *pszNewString) CPL_WARN_UNUSED_RESULT;
51 char CPL_DLL **
52 CSLAddStringMayFail(char **papszStrList,
53 const char *pszNewString) CPL_WARN_UNUSED_RESULT;
54 int CPL_DLL CSLCount(CSLConstList papszStrList);
55 const char CPL_DLL *CSLGetField(CSLConstList, int);
56 void CPL_DLL CPL_STDCALL CSLDestroy(char **papszStrList);
57 char CPL_DLL **CSLDuplicate(CSLConstList papszStrList) CPL_WARN_UNUSED_RESULT;
58 char CPL_DLL **CSLMerge(char **papszOrig,
59 CSLConstList papszOverride) CPL_WARN_UNUSED_RESULT;
60
61 char CPL_DLL **CSLTokenizeString(const char *pszString) CPL_WARN_UNUSED_RESULT;
62 char CPL_DLL **
63 CSLTokenizeStringComplex(const char *pszString, const char *pszDelimiter,
64 int bHonourStrings,
65 int bAllowEmptyTokens) CPL_WARN_UNUSED_RESULT;
66 char CPL_DLL **CSLTokenizeString2(const char *pszString,
67 const char *pszDelimiter,
68 int nCSLTFlags) CPL_WARN_UNUSED_RESULT;
69
71#define CSLT_HONOURSTRINGS 0x0001
73#define CSLT_ALLOWEMPTYTOKENS 0x0002
75#define CSLT_PRESERVEQUOTES 0x0004
77#define CSLT_PRESERVEESCAPES 0x0008
79#define CSLT_STRIPLEADSPACES 0x0010
81#define CSLT_STRIPENDSPACES 0x0020
82
83 int CPL_DLL CSLPrint(CSLConstList papszStrList, FILE *fpOut);
84 char CPL_DLL **CSLLoad(const char *pszFname) CPL_WARN_UNUSED_RESULT;
85 char CPL_DLL **CSLLoad2(const char *pszFname, int nMaxLines, int nMaxCols,
86 CSLConstList papszOptions) CPL_WARN_UNUSED_RESULT;
87 int CPL_DLL CSLSave(CSLConstList papszStrList, const char *pszFname);
88
89 char CPL_DLL **
90 CSLInsertStrings(char **papszStrList, int nInsertAtLineNo,
91 CSLConstList papszNewLines) CPL_WARN_UNUSED_RESULT;
92 char CPL_DLL **CSLInsertString(char **papszStrList, int nInsertAtLineNo,
93 const char *pszNewLine) CPL_WARN_UNUSED_RESULT;
94 char CPL_DLL **
95 CSLRemoveStrings(char **papszStrList, int nFirstLineToDelete, int nNumToRemove,
96 char ***ppapszRetStrings) CPL_WARN_UNUSED_RESULT;
97 int CPL_DLL CSLFindString(CSLConstList papszList, const char *pszTarget);
98 int CPL_DLL CSLFindStringCaseSensitive(CSLConstList papszList,
99 const char *pszTarget);
100 int CPL_DLL CSLPartialFindString(CSLConstList papszHaystack,
101 const char *pszNeedle);
102 int CPL_DLL CSLFindName(CSLConstList papszStrList, const char *pszName);
103 int CPL_DLL CSLFetchBoolean(CSLConstList papszStrList, const char *pszKey,
104 int bDefault);
105
106/* TODO: Deprecate CSLTestBoolean. Remove in GDAL 3.x. */
107 int CPL_DLL CSLTestBoolean(const char *pszValue);
108/* Do not use CPLTestBoolean in C++ code. Use CPLTestBool. */
109 int CPL_DLL CPLTestBoolean(const char *pszValue);
110
111 bool CPL_DLL CPLTestBool(const char *pszValue);
112 bool CPL_DLL CPLFetchBool(CSLConstList papszStrList, const char *pszKey,
113 bool bDefault);
114
115 CPLErr CPL_DLL CPLParseMemorySize(const char *pszValue, GIntBig *pnValue,
116 bool *pbUnitSpecified);
117
118 const char CPL_DLL *CPLParseNameValue(const char *pszNameValue, char **ppszKey);
119 const char CPL_DLL *CPLParseNameValueSep(const char *pszNameValue,
120 char **ppszKey, char chSep);
121
122 const char CPL_DLL *CSLFetchNameValue(CSLConstList papszStrList,
123 const char *pszName);
124 const char CPL_DLL *CSLFetchNameValueDef(CSLConstList papszStrList,
125 const char *pszName,
126 const char *pszDefault);
127 char CPL_DLL **CSLFetchNameValueMultiple(CSLConstList papszStrList,
128 const char *pszName);
129 char CPL_DLL **CSLAddNameValue(char **papszStrList, const char *pszName,
130 const char *pszValue) CPL_WARN_UNUSED_RESULT;
131 char CPL_DLL **CSLSetNameValue(char **papszStrList, const char *pszName,
132 const char *pszValue) CPL_WARN_UNUSED_RESULT;
133 void CPL_DLL CSLSetNameValueSeparator(char **papszStrList,
134 const char *pszSeparator);
135
136 char CPL_DLL **CSLParseCommandLine(const char *pszCommandLine);
137
139#define CPLES_BackslashQuotable 0
141#define CPLES_XML 1
143#define CPLES_URL 2
145#define CPLES_SQL 3
147#define CPLES_CSV 4
150#define CPLES_XML_BUT_QUOTES 5
152#define CPLES_CSV_FORCE_QUOTING 6
154#define CPLES_SQLI 7
155
156 char CPL_DLL *CPLEscapeString(const char *pszString, int nLength,
157 int nScheme) CPL_WARN_UNUSED_RESULT;
158 char CPL_DLL *CPLUnescapeString(const char *pszString, int *pnLength,
159 int nScheme) CPL_WARN_UNUSED_RESULT;
160
161 char CPL_DLL *CPLBinaryToHex(int nBytes,
162 const GByte *pabyData) CPL_WARN_UNUSED_RESULT;
163 GByte CPL_DLL *CPLHexToBinary(const char *pszHex,
164 int *pnBytes) CPL_WARN_UNUSED_RESULT;
165
166 char CPL_DLL *CPLBase64Encode(int nBytes,
167 const GByte *pabyData) CPL_WARN_UNUSED_RESULT;
168 int CPL_DLL CPLBase64DecodeInPlace(GByte *pszBase64) CPL_WARN_UNUSED_RESULT;
169
171 typedef enum
172{
173 CPL_VALUE_STRING,
174 CPL_VALUE_REAL,
175 CPL_VALUE_INTEGER
176} CPLValueType;
177
178 CPLValueType CPL_DLL CPLGetValueType(const char *pszValue);
179
180 int CPL_DLL CPLToupper(int c);
181 int CPL_DLL CPLTolower(int c);
182
183 size_t CPL_DLL CPLStrlcpy(char *pszDest, const char *pszSrc, size_t nDestSize);
184 size_t CPL_DLL CPLStrlcat(char *pszDest, const char *pszSrc, size_t nDestSize);
185 size_t CPL_DLL CPLStrnlen(const char *pszStr, size_t nMaxLen);
186
187/* -------------------------------------------------------------------- */
188/* Locale independent formatting functions. */
189/* -------------------------------------------------------------------- */
190 int CPL_DLL CPLvsnprintf(char *str, size_t size,
191 CPL_FORMAT_STRING(const char *fmt), va_list args)
192 CPL_PRINT_FUNC_FORMAT(3, 0);
193
194/* ALIAS_CPLSNPRINTF_AS_SNPRINTF might be defined to enable GCC 7 */
195/* -Wformat-truncation= warnings, but shouldn't be set for normal use */
196#if defined(ALIAS_CPLSNPRINTF_AS_SNPRINTF)
197#define CPLsnprintf snprintf
198#else
199 int CPL_DLL CPLsnprintf(char *str, size_t size,
200 CPL_FORMAT_STRING(const char *fmt), ...)
201 CPL_PRINT_FUNC_FORMAT(3, 4);
202#endif
203
205#if defined(GDAL_COMPILATION) && !defined(DONT_DEPRECATE_SPRINTF)
206 int CPL_DLL CPLsprintf(char *str, CPL_FORMAT_STRING(const char *fmt), ...)
207 CPL_PRINT_FUNC_FORMAT(2, 3) CPL_WARN_DEPRECATED("Use CPLsnprintf instead");
208#else
209 int CPL_DLL CPLsprintf(char *str, CPL_FORMAT_STRING(const char *fmt), ...)
210 CPL_PRINT_FUNC_FORMAT(2, 3);
211#endif
213 int CPL_DLL CPLprintf(CPL_FORMAT_STRING(const char *fmt), ...)
214 CPL_PRINT_FUNC_FORMAT(1, 2);
215
216/* For some reason Doxygen_Suppress is needed to avoid warning. Not sure why */
218/* caution: only works with limited number of formats */
219 int CPL_DLL CPLsscanf(const char *str, CPL_SCANF_FORMAT_STRING(const char *fmt),
220 ...) CPL_SCAN_FUNC_FORMAT(2, 3);
223const char CPL_DLL *CPLSPrintf(CPL_FORMAT_STRING(const char *fmt), ...)
224 CPL_PRINT_FUNC_FORMAT(1, 2) CPL_WARN_UNUSED_RESULT;
225 char CPL_DLL **CSLAppendPrintf(char **papszStrList,
226 CPL_FORMAT_STRING(const char *fmt), ...)
227 CPL_PRINT_FUNC_FORMAT(2, 3) CPL_WARN_UNUSED_RESULT;
228 int CPL_DLL CPLVASPrintf(char **buf, CPL_FORMAT_STRING(const char *fmt),
229 va_list args) CPL_PRINT_FUNC_FORMAT(2, 0);
230
231/* -------------------------------------------------------------------- */
232/* RFC 23 character set conversion/recoding API (cpl_recode.cpp). */
233/* -------------------------------------------------------------------- */
235#define CPL_ENC_LOCALE ""
237#define CPL_ENC_UTF8 "UTF-8"
239#define CPL_ENC_UTF16 "UTF-16"
241#define CPL_ENC_UCS2 "UCS-2"
243#define CPL_ENC_UCS4 "UCS-4"
245#define CPL_ENC_ASCII "ASCII"
247#define CPL_ENC_ISO8859_1 "ISO-8859-1"
248
249 int CPL_DLL CPLEncodingCharSize(const char *pszEncoding);
251 void CPL_DLL CPLClearRecodeWarningFlags(void);
253 char CPL_DLL *CPLRecode(const char *pszSource, const char *pszSrcEncoding,
254 const char *pszDstEncoding)
255 CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
256 char CPL_DLL *
257 CPLRecodeFromWChar(const wchar_t *pwszSource, const char *pszSrcEncoding,
258 const char *pszDstEncoding) CPL_WARN_UNUSED_RESULT;
259 wchar_t CPL_DLL *
260 CPLRecodeToWChar(const char *pszSource, const char *pszSrcEncoding,
261 const char *pszDstEncoding) CPL_WARN_UNUSED_RESULT;
262 int CPL_DLL CPLIsUTF8(const char *pabyData, int nLen);
263 bool CPL_DLL CPLIsASCII(const char *pabyData, size_t nLen);
264 char CPL_DLL *CPLForceToASCII(const char *pabyData, int nLen,
265 char chReplacementChar) CPL_WARN_UNUSED_RESULT;
266 char CPL_DLL *CPLUTF8ForceToASCII(const char *pszStr, char chReplacementChar)
267 CPL_WARN_UNUSED_RESULT;
268 int CPL_DLL CPLStrlenUTF8(const char *pszUTF8Str);
269 int CPL_DLL CPLCanRecode(const char *pszTestStr, const char *pszSrcEncoding,
270 const char *pszDstEncoding) CPL_WARN_UNUSED_RESULT;
271 CPL_C_END
272
273/************************************************************************/
274/* CPLString */
275/************************************************************************/
276
277#if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
278
279 extern "C++"
280{
281#ifndef DOXYGEN_SKIP
282#include <string>
283#include <vector>
284#endif
285
286// VC++ implicitly applies __declspec(dllexport) to template base classes
287// of classes marked with __declspec(dllexport).
288// Hence, if marked with CPL_DLL, VC++ would export symbols for the
289// specialization of std::basic_string<char>, since it is a base class of
290// CPLString. As a result, if an application linked both gdal.dll and a static
291// library that (implicitly) instantiates std::string (almost all do!), then the
292// linker would emit an error concerning duplicate symbols for std::string. The
293// least intrusive solution is to not mark the whole class with
294// __declspec(dllexport) for VC++, but only its non-inline methods.
295#ifdef _MSC_VER
296#define CPLSTRING_CLASS_DLL
297#define CPLSTRING_METHOD_DLL CPL_DLL
298#else
300#define CPLSTRING_CLASS_DLL CPL_DLL
301#define CPLSTRING_METHOD_DLL
303#endif
304
306 class CPLSTRING_CLASS_DLL CPLString : public std::string
307 {
308 public:
310 CPLString(void)
311 {
312 }
313
315 // cppcheck-suppress noExplicitConstructor
316 CPLString(const std::string &oStr) : std::string(oStr)
317 {
318 }
319
321 // cppcheck-suppress noExplicitConstructor
322 CPLString(const char *pszStr) : std::string(pszStr)
323 {
324 }
325
327 CPLString(const char *pszStr, size_t n) : std::string(pszStr, n)
328 {
329 }
330
332 operator const char *(void) const
333 {
334 return c_str();
335 }
336
338 char &operator[](std::string::size_type i)
339 {
340 return std::string::operator[](i);
341 }
342
344 const char &operator[](std::string::size_type i) const
345 {
346 return std::string::operator[](i);
347 }
348
350 char &operator[](int i)
351 {
352 return std::string::operator[](
353 static_cast<std::string::size_type>(i));
354 }
355
357 const char &operator[](int i) const
358 {
359 return std::string::operator[](
360 static_cast<std::string::size_type>(i));
361 }
362
364 void Clear()
365 {
366 resize(0);
367 }
368
372 void Seize(char *pszValue)
373 {
374 if (pszValue == nullptr)
375 Clear();
376 else
377 {
378 *this = pszValue;
379 CPLFree(pszValue);
380 }
381 }
382
383 /* There seems to be a bug in the way the compiler count indices...
384 * Should be CPL_PRINT_FUNC_FORMAT (1, 2) */
385 CPLSTRING_METHOD_DLL CPLString &
386 Printf(CPL_FORMAT_STRING(const char *pszFormat), ...)
387 CPL_PRINT_FUNC_FORMAT(2, 3);
388 CPLSTRING_METHOD_DLL CPLString &
389 vPrintf(CPL_FORMAT_STRING(const char *pszFormat), va_list args)
390 CPL_PRINT_FUNC_FORMAT(2, 0);
391 CPLSTRING_METHOD_DLL CPLString &
392 FormatC(double dfValue, const char *pszFormat = nullptr);
393 CPLSTRING_METHOD_DLL CPLString &Trim();
394 CPLSTRING_METHOD_DLL CPLString &Recode(const char *pszSrcEncoding,
395 const char *pszDstEncoding);
396 CPLSTRING_METHOD_DLL CPLString &replaceAll(const std::string &osBefore,
397 const std::string &osAfter);
398 CPLSTRING_METHOD_DLL CPLString &replaceAll(const std::string &osBefore,
399 char chAfter);
400 CPLSTRING_METHOD_DLL CPLString &replaceAll(char chBefore,
401 const std::string &osAfter);
402 CPLSTRING_METHOD_DLL CPLString &replaceAll(char chBefore, char chAfter);
403
404 /* case insensitive find alternates */
405 CPLSTRING_METHOD_DLL size_t ifind(const std::string &str,
406 size_t pos = 0) const;
407 CPLSTRING_METHOD_DLL size_t ifind(const char *s, size_t pos = 0) const;
408 CPLSTRING_METHOD_DLL CPLString &toupper(void);
409 CPLSTRING_METHOD_DLL CPLString &tolower(void);
410
411 CPLSTRING_METHOD_DLL bool endsWith(const std::string &osStr) const;
412 };
413
414#undef CPLSTRING_CLASS_DLL
415#undef CPLSTRING_METHOD_DLL
416
417 CPLString CPL_DLL CPLOPrintf(CPL_FORMAT_STRING(const char *pszFormat), ...)
418 CPL_PRINT_FUNC_FORMAT(1, 2);
419 CPLString CPL_DLL CPLOvPrintf(CPL_FORMAT_STRING(const char *pszFormat),
420 va_list args) CPL_PRINT_FUNC_FORMAT(1, 0);
421 CPLString CPL_DLL CPLQuotedSQLIdentifier(const char *pszIdent);
422
423 /* -------------------------------------------------------------------- */
424 /* URL processing functions, here since they depend on CPLString. */
425 /* -------------------------------------------------------------------- */
426 CPLString CPL_DLL CPLURLGetValue(const char *pszURL, const char *pszKey);
427 CPLString CPL_DLL CPLURLAddKVP(const char *pszURL, const char *pszKey,
428 const char *pszValue);
429
430 /************************************************************************/
431 /* CPLStringList */
432 /************************************************************************/
433
435 class CPL_DLL CPLStringList
436 {
437 char **papszList = nullptr;
438 mutable int nCount = 0;
439 mutable int nAllocation = 0;
440 bool bOwnList = false;
441 bool bIsSorted = false;
442
443 bool MakeOurOwnCopy();
444 bool EnsureAllocation(int nMaxLength);
445 int FindSortedInsertionPoint(const char *pszLine);
446
447 public:
448 CPLStringList();
449 explicit CPLStringList(char **papszList, int bTakeOwnership = TRUE);
450 explicit CPLStringList(CSLConstList papszList);
451 explicit CPLStringList(const std::vector<std::string> &aosList);
452 explicit CPLStringList(std::initializer_list<const char *> oInitList);
453 CPLStringList(const CPLStringList &oOther);
454 CPLStringList(CPLStringList &&oOther);
455 ~CPLStringList();
456
457 static const CPLStringList BoundToConstList(CSLConstList papszList);
458
459 CPLStringList &Clear();
460
462 inline void clear()
463 {
464 Clear();
465 }
466
468 int size() const
469 {
470 return Count();
471 }
472
473 int Count() const;
474
476 bool empty() const
477 {
478 return Count() == 0;
479 }
480
481 CPLStringList &AddString(const char *pszNewString);
482 CPLStringList &AddStringDirectly(char *pszNewString);
483
484 CPLStringList &InsertString(int nInsertAtLineNo, const char *pszNewLine)
485 {
486 return InsertStringDirectly(nInsertAtLineNo, CPLStrdup(pszNewLine));
487 }
488
489 CPLStringList &InsertStringDirectly(int nInsertAtLineNo,
490 char *pszNewLine);
491
492 // CPLStringList &InsertStrings( int nInsertAtLineNo, char
493 // **papszNewLines ); CPLStringList &RemoveStrings( int
494 // nFirstLineToDelete, int nNumToRemove=1 );
495
497 int FindString(const char *pszTarget) const
498 {
499 return CSLFindString(papszList, pszTarget);
500 }
501
504 int PartialFindString(const char *pszNeedle) const
505 {
506 return CSLPartialFindString(papszList, pszNeedle);
507 }
508
509 int FindName(const char *pszName) const;
510 bool FetchBool(const char *pszKey, bool bDefault) const;
511 // Deprecated.
512 int FetchBoolean(const char *pszKey, int bDefault) const;
513 const char *FetchNameValue(const char *pszKey) const;
514 const char *FetchNameValueDef(const char *pszKey,
515 const char *pszDefault) const;
516 CPLStringList &AddNameValue(const char *pszKey, const char *pszValue);
517 CPLStringList &SetNameValue(const char *pszKey, const char *pszValue);
518
519 CPLStringList &Assign(char **papszListIn, int bTakeOwnership = TRUE);
520
522 CPLStringList &operator=(char **papszListIn)
523 {
524 return Assign(papszListIn, TRUE);
525 }
526
528 CPLStringList &operator=(const CPLStringList &oOther);
530 CPLStringList &operator=(CSLConstList papszListIn);
532 CPLStringList &operator=(CPLStringList &&oOther);
533
535 char *operator[](int i);
536
538 char *operator[](size_t i)
539 {
540 return (*this)[static_cast<int>(i)];
541 }
542
544 const char *operator[](int i) const;
545
547 const char *operator[](size_t i) const
548 {
549 return (*this)[static_cast<int>(i)];
550 }
551
553 const char *operator[](const char *pszKey) const
554 {
555 return FetchNameValue(pszKey);
556 }
557
559 inline const char *front() const
560 {
561 return papszList[0];
562 }
563
565 inline const char *back() const
566 {
567 return papszList[size() - 1];
568 }
569
571 const char *const *begin() const
572 {
573 return papszList ? &papszList[0] : nullptr;
574 }
575
577 const char *const *end() const
578 {
579 return papszList ? &papszList[size()] : nullptr;
580 }
581
583 char **List()
584 {
585 return papszList;
586 }
587
589 CSLConstList List() const
590 {
591 return papszList;
592 }
593
594 char **StealList();
595
596 CPLStringList &Sort();
597
599 int IsSorted() const
600 {
601 return bIsSorted;
602 }
603
605 operator char **(void)
606 {
607 return List();
608 }
609
611 operator CSLConstList(void) const
612 {
613 return List();
614 }
615
617 operator std::vector<std::string>(void) const
618 {
619 return std::vector<std::string>{begin(), end()};
620 }
621 };
622
623#ifdef GDAL_COMPILATION
624
625#include <iterator> // For std::input_iterator_tag
626#include <memory>
627#include <utility> // For std::pair
628
630 struct CPL_DLL CSLDestroyReleaser
631 {
632 void operator()(char **papszStr) const
633 {
634 CSLDestroy(papszStr);
635 }
636 };
637
641 using CSLUniquePtr = std::unique_ptr<char *, CSLDestroyReleaser>;
642
645 using CPLCharUniquePtr = std::unique_ptr<char, VSIFreeReleaser>;
646
647 namespace cpl
648 {
649
652 struct CPL_DLL CSLIterator
653 {
654 using iterator_category = std::input_iterator_tag;
655 using difference_type = std::ptrdiff_t;
656 using value_type = const char *;
657 using pointer = value_type *;
658 using reference = value_type &;
659
660 CSLConstList m_papszList = nullptr;
661 bool m_bAtEnd = false;
662
663 inline const char *operator*() const
664 {
665 return *m_papszList;
666 }
667
668 inline CSLIterator &operator++()
669 {
670 if (m_papszList)
671 ++m_papszList;
672 return *this;
673 }
674
675 bool operator==(const CSLIterator &other) const;
676
677 inline bool operator!=(const CSLIterator &other) const
678 {
679 return !(operator==(other));
680 }
681 };
682
689 struct CPL_DLL CSLIteratorWrapper
690 {
691 public:
693 inline explicit CSLIteratorWrapper(CSLConstList papszList)
694 : m_papszList(papszList)
695 {
696 }
697
699 inline CSLIterator begin() const
700 {
701 return {m_papszList, false};
702 }
703
705 inline CSLIterator end() const
706 {
707 return {m_papszList, true};
708 }
709
710 private:
711 CSLConstList m_papszList;
712 };
713
718 inline CSLIteratorWrapper Iterate(CSLConstList papszList)
719 {
720 return CSLIteratorWrapper{papszList};
721 }
722
724 inline CSLIteratorWrapper Iterate(const CPLStringList &aosList)
725 {
726 return Iterate(aosList.List());
727 }
728
732 inline CSLIteratorWrapper Iterate(char **) = delete;
733
738 struct CPL_DLL CSLNameValueIterator
739 {
740 using iterator_category = std::input_iterator_tag;
741 using difference_type = std::ptrdiff_t;
742 using value_type = std::pair<const char *, const char *>;
743 using pointer = value_type *;
744 using reference = value_type &;
745
746 CSLConstList m_papszList = nullptr;
747 bool m_bReturnNullKeyIfNotNameValue = false;
748 std::string m_osKey{};
749
750 value_type operator*();
751
752 inline CSLNameValueIterator &operator++()
753 {
754 if (m_papszList)
755 ++m_papszList;
756 return *this;
757 }
758
759 inline bool operator==(const CSLNameValueIterator &other) const
760 {
761 return m_papszList == other.m_papszList;
762 }
763
764 inline bool operator!=(const CSLNameValueIterator &other) const
765 {
766 return !(operator==(other));
767 }
768 };
769
783 struct CPL_DLL CSLNameValueIteratorWrapper
784 {
785 public:
787 inline explicit CSLNameValueIteratorWrapper(
788 CSLConstList papszList, bool bReturnNullKeyIfNotNameValue)
789 : m_papszList(papszList),
790 m_bReturnNullKeyIfNotNameValue(bReturnNullKeyIfNotNameValue)
791 {
792 }
793
795 inline CSLNameValueIterator begin() const
796 {
797 return {m_papszList, m_bReturnNullKeyIfNotNameValue};
798 }
799
801 CSLNameValueIterator end() const;
802
803 private:
804 CSLConstList m_papszList;
805 const bool m_bReturnNullKeyIfNotNameValue;
806 };
807
824 inline CSLNameValueIteratorWrapper
825 IterateNameValue(CSLConstList papszList,
826 bool bReturnNullKeyIfNotNameValue = false)
827 {
828 return CSLNameValueIteratorWrapper{papszList,
829 bReturnNullKeyIfNotNameValue};
830 }
831
833 inline CSLNameValueIteratorWrapper
834 IterateNameValue(const CPLStringList &aosList,
835 bool bReturnNullKeyIfNotNameValue = false)
836 {
837 return IterateNameValue(aosList.List(), bReturnNullKeyIfNotNameValue);
838 }
839
843 inline CSLIteratorWrapper IterateNameValue(char **, bool = false) = delete;
844
848 inline std::vector<std::string> ToVector(CSLConstList papszList)
849 {
850 return CPLStringList::BoundToConstList(papszList);
851 }
852
853 inline std::vector<std::string> ToVector(char **) = delete;
854
855 } // namespace cpl
856
857#endif
858
859} // extern "C++"
860
861#endif /* def __cplusplus && !CPL_SUPRESS_CPLUSPLUS */
862
863#endif /* CPL_STRING_H_INCLUDED */
CPLStringList
String list class designed around our use of C "char**" string lists.
Definition: cpl_string.h:436
CPLStringList::operator[]
const char * operator[](size_t i) const
Return string at specified index.
Definition: cpl_string.h:547
CPLStringList::operator[]
const char * operator[](const char *pszKey) const
Return value corresponding to pszKey, or nullptr.
Definition: cpl_string.h:553
CPLStringList::IsSorted
int IsSorted() const
Returns whether the list is sorted.
Definition: cpl_string.h:599
CPLStringList::empty
bool empty() const
Return whether the list is empty.
Definition: cpl_string.h:476
CPLStringList::end
const char *const * end() const
end() implementation
Definition: cpl_string.h:577
CPLStringList::operator=
CPLStringList & operator=(CSLConstList papszListIn)
Assignment operator.
CPLStringList::List
char ** List()
Return list.
Definition: cpl_string.h:583
CPLStringList::clear
void clear()
Clear the list.
Definition: cpl_string.h:462
CPLStringList::InsertString
CPLStringList & InsertString(int nInsertAtLineNo, const char *pszNewLine)
Insert into the list at identified location.
Definition: cpl_string.h:484
CPLStringList::operator=
CPLStringList & operator=(char **papszListIn)
Assignment operator.
Definition: cpl_string.h:522
CPLStringList::operator[]
char * operator[](size_t i)
Return string at specified index.
Definition: cpl_string.h:538
CPLStringList::size
int size() const
Return size of list.
Definition: cpl_string.h:468
CPLStringList::List
CSLConstList List() const
Return list.
Definition: cpl_string.h:589
CPLStringList::front
const char * front() const
Return first element.
Definition: cpl_string.h:559
CPLStringList::begin
const char *const * begin() const
begin() implementation
Definition: cpl_string.h:571
CPLStringList::FindString
int FindString(const char *pszTarget) const
Return index of pszTarget in the list, or -1.
Definition: cpl_string.h:497
CPLStringList::back
const char * back() const
Return last element.
Definition: cpl_string.h:565
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:504
CPLString
Convenient string class based on std::string.
Definition: cpl_string.h:307
CPLString::Clear
void Clear()
Clear the string.
Definition: cpl_string.h:364
CPLString::CPLString
CPLString(void)
Constructor.
Definition: cpl_string.h:310
CPLString::operator[]
const char & operator[](std::string::size_type i) const
Return character at specified index.
Definition: cpl_string.h:344
CPLString::CPLString
CPLString(const std::string &oStr)
Constructor.
Definition: cpl_string.h:316
CPLString::Seize
void Seize(char *pszValue)
Assign specified string and take ownership of it (assumed to be allocated with CPLMalloc()).
Definition: cpl_string.h:372
CPLString::operator[]
char & operator[](int i)
Return character at specified index.
Definition: cpl_string.h:350
CPLString::operator[]
const char & operator[](int i) const
Return character at specified index.
Definition: cpl_string.h:357
CPLString::operator[]
char & operator[](std::string::size_type i)
Return character at specified index.
Definition: cpl_string.h:338
CPLString::CPLString
CPLString(const char *pszStr, size_t n)
Constructor.
Definition: cpl_string.h:327
CPLString::CPLString
CPLString(const char *pszStr)
Constructor.
Definition: cpl_string.h:322
cpl_conv.h
Various convenience functions for CPL.
CPLFree
#define CPLFree
Alias of VSIFree()
Definition: cpl_conv.h:82
CPLStrdup
char * CPLStrdup(const char *)
Safe version of strdup() function.
Definition: cpl_conv.cpp:294
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:940
CPL_C_END
#define CPL_C_END
Macro to end a block of C symbols.
Definition: cpl_port.h:283
CPL_C_START
#define CPL_C_START
Macro to start a block of C symbols.
Definition: cpl_port.h:279
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:954
CPL_RETURNS_NONNULL
#define CPL_RETURNS_NONNULL
Qualifier for a function that does not return NULL.
Definition: cpl_port.h:1002
CPL_PRINT_FUNC_FORMAT
#define CPL_PRINT_FUNC_FORMAT(format_idx, arg_idx)
Tag a function to have printf() formatting.
Definition: cpl_port.h:938
CSLConstList
char ** CSLConstList
Type of a constant null-terminated list of nul terminated strings.
Definition: cpl_port.h:1179
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:964
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:956
GByte
unsigned char GByte
Unsigned byte type.
Definition: cpl_port.h:169
GIntBig
long long GIntBig
Large signed integer type (generally 64-bit integer type).
Definition: cpl_port.h:199
CSLFindStringCaseSensitive
int CSLFindStringCaseSensitive(CSLConstList papszList, const char *pszTarget)
Find a string within a string list(case sensitive)
Definition: cpl_string.cpp:689
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:1131
CPLEscapeString
char * CPLEscapeString(const char *pszString, int nLength, int nScheme)
Apply escaping to string to preserve special characters.
Definition: cpl_string.cpp:2202
CPLBinaryToHex
char * CPLBinaryToHex(int nBytes, const GByte *pabyData)
Binary to hexadecimal translation.
Definition: cpl_string.cpp:2776
CSLTokenizeStringComplex
char ** CSLTokenizeStringComplex(const char *pszString, const char *pszDelimiter, int bHonourStrings, int bAllowEmptyTokens)
Obsolete tokenizing api.
Definition: cpl_string.cpp:752
CPLprintf
int CPLprintf(const char *fmt,...)
printf() wrapper that is not sensitive to LC_NUMERIC settings.
Definition: cpl_string.cpp:1406
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:2004
CPLQuotedSQLIdentifier
CPLString CPLQuotedSQLIdentifier(const char *pszIdent)
Return a CPLString of the SQL quoted identifier.
Definition: cplstring.cpp:512
CPLOPrintf
CPLString CPLOPrintf(const char *pszFormat,...)
Return a CPLString with the content of sprintf()
Definition: cplstring.cpp:480
CPLStrlcat
size_t CPLStrlcat(char *pszDest, const char *pszSrc, size_t nDestSize)
Appends a source string to a destination buffer.
Definition: cpl_string.cpp:3062
CSLPrint
int CSLPrint(CSLConstList papszStrList, FILE *fpOut)
Print a StringList to fpOut.
Definition: cpl_string.cpp:446
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:300
CSLTokenizeString2
char ** CSLTokenizeString2(const char *pszString, const char *pszDelimiter, int nCSLTFlags)
Tokenize a string.
Definition: cpl_string.cpp:819
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:398
CPLStrlcpy
size_t CPLStrlcpy(char *pszDest, const char *pszSrc, size_t nDestSize)
Copy source string to a destination buffer.
Definition: cpl_string.cpp:3005
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:1685
CPLRecodeFromWChar
char * CPLRecodeFromWChar(const wchar_t *pwszSource, const char *pszSrcEncoding, const char *pszDstEncoding)
Convert wchar_t string to UTF-8.
Definition: cpl_recode.cpp:165
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:1351
CPLIsASCII
bool CPLIsASCII(const char *pabyData, size_t nLen)
Test if a string is encoded as ASCII.
Definition: cpl_recode.cpp:263
CPLValueType
CPLValueType
Type of value.
Definition: cpl_string.h:172
CPL_VALUE_INTEGER
@ CPL_VALUE_INTEGER
Integer.
Definition: cpl_string.h:175
CPL_VALUE_STRING
@ CPL_VALUE_STRING
String.
Definition: cpl_string.h:173
CPL_VALUE_REAL
@ CPL_VALUE_REAL
Real number.
Definition: cpl_string.h:174
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:1614
CSLFindName
int CSLFindName(CSLConstList papszStrList, const char *pszName)
Find StringList entry with given key name.
Definition: cpl_string.cpp:1717
CPLParseMemorySize
CPLErr CPLParseMemorySize(const char *pszValue, GIntBig *pnValue, bool *pbUnitSpecified)
Parse a memory size from a string.
Definition: cpl_string.cpp:1758
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:1039
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:1921
CPLTolower
int CPLTolower(int c)
Converts a (ASCII) uppercase character to lowercase.
Definition: cpl_string.cpp:3151
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:1194
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:655
CSLSave
int CSLSave(CSLConstList papszStrList, const char *pszFname)
Write a StringList to a text file.
Definition: cpl_string.cpp:397
CPLTestBool
bool CPLTestBool(const char *pszValue)
Test what boolean value contained in the string.
Definition: cpl_string.cpp:1542
CSLParseCommandLine
char ** CSLParseCommandLine(const char *pszCommandLine)
Tokenize command line arguments in a list of strings.
Definition: cpl_string.cpp:3121
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:1658
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:3097
CPLUTF8ForceToASCII
char * CPLUTF8ForceToASCII(const char *pszStr, char chReplacementChar)
Return a new string that is made only of ASCII characters.
Definition: cpl_recode.cpp:351
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:547
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:2124
CPLIsUTF8
int CPLIsUTF8(const char *pabyData, int nLen)
Test if a string is encoded as UTF-8.
Definition: cpl_recode_stub.cpp:502
CSLPartialFindString
int CSLPartialFindString(CSLConstList papszHaystack, const char *pszNeedle)
Find a substring within a string list.
Definition: cpl_string.cpp:721
CSLTokenizeString
char ** CSLTokenizeString(const char *pszString)
Tokenizes a string and returns a StringList with one string for each token.
Definition: cpl_string.cpp:742
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:1969
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:2869
CSLSetNameValue
char ** CSLSetNameValue(char **papszStrList, const char *pszName, const char *pszValue)
Assign value to name in StringList.
Definition: cpl_string.cpp:2043
CSLRemoveStrings
char ** CSLRemoveStrings(char **papszStrList, int nFirstLineToDelete, int nNumToRemove, char ***ppapszRetStrings)
Remove strings inside a StringList.
Definition: cpl_string.cpp:573
CSLLoad
char ** CSLLoad(const char *pszFname)
Load a text file into a string list.
Definition: cpl_string.cpp:382
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:80
CSLLoad2
char ** CSLLoad2(const char *pszFname, int nMaxLines, int nMaxCols, CSLConstList papszOptions)
Load a text file into a string list.
Definition: cpl_string.cpp:306
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:431
CSLFetchBoolean
int CSLFetchBoolean(CSLConstList papszStrList, const char *pszKey, int bDefault)
DEPRECATED.
Definition: cpl_string.cpp:1647
CPLStrlenUTF8
int CPLStrlenUTF8(const char *pszUTF8Str)
Return the number of UTF-8 characters of a nul-terminated string.
Definition: cpl_recode.cpp:1168
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:1020
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:482
CPLOvPrintf
CPLString CPLOvPrintf(const char *pszFormat, va_list args)
Return a CPLString with the content of vsprintf()
Definition: cplstring.cpp:499
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:1874
CSLTestBoolean
int CSLTestBoolean(const char *pszValue)
Test what boolean value contained in the string.
Definition: cpl_string.cpp:1567
CPLSPrintf
const char * CPLSPrintf(const char *fmt,...)
CPLSPrintf() that works with 10 static buffer.
Definition: cpl_string.cpp:967
CPLToupper
int CPLToupper(int c)
Converts a (ASCII) lowercase character to uppercase.
Definition: cpl_string.cpp:3136
CPLHexToBinary
GByte * CPLHexToBinary(const char *pszHex, int *pnBytes)
Hexadecimal to binary translation.
Definition: cpl_string.cpp:2830
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:1122
CPLUnescapeString
char * CPLUnescapeString(const char *pszString, int *pnLength, int nScheme)
Unescape a string.
Definition: cpl_string.cpp:2552
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:1589
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:222
cpl_vsi.h
Standard C Covers.
begin
OGRLayer::FeatureIterator begin(OGRLayer *poLayer)
Return begin of feature iterator.
Definition: ogrsf_frmts.h:421
end
OGRLayer::FeatureIterator end(OGRLayer *poLayer)
Return end of feature iterator.
Definition: ogrsf_frmts.h:429