cpl_string.h

Go to the documentation of this file.

/**********************************************************************
 *
 * Name:     cpl_string.h
 * Project:  CPL - Common Portability Library
 * Purpose:  String and StringList functions.
 * Author:   Daniel Morissette, dmorissette@mapgears.com
 *
 **********************************************************************
 * Copyright (c) 1998, Daniel Morissette
 * Copyright (c) 2008-2014, Even Rouault <even dot rouault at spatialys.com>
 *
 * SPDX-License-Identifier: MIT
 ****************************************************************************/
 
#ifndef CPL_STRING_H_INCLUDED
#define CPL_STRING_H_INCLUDED
 
#include "cpl_error.h"
#include "cpl_conv.h"
#include "cpl_vsi.h"
 
#include <stdbool.h>

 
CPL_C_START
 
char CPL_DLL **CSLAddString(char **papszStrList,
                            const char *pszNewString) CPL_WARN_UNUSED_RESULT;
char CPL_DLL **
CSLAddStringMayFail(char **papszStrList,
                    const char *pszNewString) CPL_WARN_UNUSED_RESULT;
int CPL_DLL CSLCount(CSLConstList papszStrList);
const char CPL_DLL *CSLGetField(CSLConstList, int);
void CPL_DLL CPL_STDCALL CSLDestroy(char **papszStrList);
char CPL_DLL **CSLDuplicate(CSLConstList papszStrList) CPL_WARN_UNUSED_RESULT;
char CPL_DLL **CSLMerge(char **papszOrig,
                        CSLConstList papszOverride) CPL_WARN_UNUSED_RESULT;
 
char CPL_DLL **CSLTokenizeString(const char *pszString) CPL_WARN_UNUSED_RESULT;
char CPL_DLL **
CSLTokenizeStringComplex(const char *pszString, const char *pszDelimiter,
                         int bHonourStrings,
                         int bAllowEmptyTokens) CPL_WARN_UNUSED_RESULT;
char CPL_DLL **CSLTokenizeString2(const char *pszString,
                                  const char *pszDelimiter,
                                  int nCSLTFlags) CPL_WARN_UNUSED_RESULT;

#define CSLT_HONOURSTRINGS 0x0001
#define CSLT_ALLOWEMPTYTOKENS 0x0002
#define CSLT_PRESERVEQUOTES 0x0004
#define CSLT_PRESERVEESCAPES 0x0008
#define CSLT_STRIPLEADSPACES 0x0010
#define CSLT_STRIPENDSPACES 0x0020
 
int CPL_DLL CSLPrint(CSLConstList papszStrList, FILE *fpOut);
char CPL_DLL **CSLLoad(const char *pszFname) CPL_WARN_UNUSED_RESULT;
char CPL_DLL **CSLLoad2(const char *pszFname, int nMaxLines, int nMaxCols,
                        CSLConstList papszOptions) CPL_WARN_UNUSED_RESULT;
int CPL_DLL CSLSave(CSLConstList papszStrList, const char *pszFname);
 
char CPL_DLL **
CSLInsertStrings(char **papszStrList, int nInsertAtLineNo,
                 CSLConstList papszNewLines) CPL_WARN_UNUSED_RESULT;
char CPL_DLL **CSLInsertString(char **papszStrList, int nInsertAtLineNo,
                               const char *pszNewLine) CPL_WARN_UNUSED_RESULT;
char CPL_DLL **
CSLRemoveStrings(char **papszStrList, int nFirstLineToDelete, int nNumToRemove,
                 char ***ppapszRetStrings) CPL_WARN_UNUSED_RESULT;
int CPL_DLL CSLFindString(CSLConstList papszList, const char *pszTarget);
int CPL_DLL CSLFindStringCaseSensitive(CSLConstList papszList,
                                       const char *pszTarget);
int CPL_DLL CSLPartialFindString(CSLConstList papszHaystack,
                                 const char *pszNeedle);
int CPL_DLL CSLFindName(CSLConstList papszStrList, const char *pszName);
int CPL_DLL CSLFetchBoolean(CSLConstList papszStrList, const char *pszKey,
                            int bDefault);
 
/* TODO: Deprecate CSLTestBoolean.  Remove in GDAL 3.x. */
int CPL_DLL CSLTestBoolean(const char *pszValue);
/* Do not use CPLTestBoolean in C++ code.  Use CPLTestBool. */
int CPL_DLL CPLTestBoolean(const char *pszValue);
 
bool CPL_DLL CPLTestBool(const char *pszValue);
bool CPL_DLL CPLFetchBool(CSLConstList papszStrList, const char *pszKey,
                          bool bDefault);
 
CPLErr CPL_DLL CPLParseMemorySize(const char *pszValue, GIntBig *pnValue,
                                  bool *pbUnitSpecified);
 
const char CPL_DLL *CPLParseNameValue(const char *pszNameValue, char **ppszKey);
const char CPL_DLL *CPLParseNameValueSep(const char *pszNameValue,
                                         char **ppszKey, char chSep);
 
const char CPL_DLL *CSLFetchNameValue(CSLConstList papszStrList,
                                      const char *pszName);
const char CPL_DLL *CSLFetchNameValueDef(CSLConstList papszStrList,
                                         const char *pszName,
                                         const char *pszDefault);
char CPL_DLL **CSLFetchNameValueMultiple(CSLConstList papszStrList,
                                         const char *pszName);
char CPL_DLL **CSLAddNameValue(char **papszStrList, const char *pszName,
                               const char *pszValue) CPL_WARN_UNUSED_RESULT;
char CPL_DLL **CSLSetNameValue(char **papszStrList, const char *pszName,
                               const char *pszValue) CPL_WARN_UNUSED_RESULT;
void CPL_DLL CSLSetNameValueSeparator(char **papszStrList,
                                      const char *pszSeparator);
 
char CPL_DLL **CSLParseCommandLine(const char *pszCommandLine);

#define CPLES_BackslashQuotable 0
#define CPLES_XML 1
#define CPLES_URL 2
#define CPLES_SQL 3
#define CPLES_CSV 4
#define CPLES_XML_BUT_QUOTES 5
#define CPLES_CSV_FORCE_QUOTING 6
#define CPLES_SQLI 7
 
char CPL_DLL *CPLEscapeString(const char *pszString, int nLength,
                              int nScheme) CPL_WARN_UNUSED_RESULT;
char CPL_DLL *CPLUnescapeString(const char *pszString, int *pnLength,
                                int nScheme) CPL_WARN_UNUSED_RESULT;
 
char CPL_DLL *CPLBinaryToHex(int nBytes,
                             const GByte *pabyData) CPL_WARN_UNUSED_RESULT;
GByte CPL_DLL *CPLHexToBinary(const char *pszHex,
                              int *pnBytes) CPL_WARN_UNUSED_RESULT;
 
char CPL_DLL *CPLBase64Encode(int nBytes,
                              const GByte *pabyData) CPL_WARN_UNUSED_RESULT;
int CPL_DLL CPLBase64DecodeInPlace(GByte *pszBase64) CPL_WARN_UNUSED_RESULT;

typedef enum
{
    CPL_VALUE_STRING, 
    CPL_VALUE_REAL,   
    CPL_VALUE_INTEGER 
} CPLValueType;
 
CPLValueType CPL_DLL CPLGetValueType(const char *pszValue);
 
int CPL_DLL CPLToupper(int c);
int CPL_DLL CPLTolower(int c);
 
size_t CPL_DLL CPLStrlcpy(char *pszDest, const char *pszSrc, size_t nDestSize);
size_t CPL_DLL CPLStrlcat(char *pszDest, const char *pszSrc, size_t nDestSize);
size_t CPL_DLL CPLStrnlen(const char *pszStr, size_t nMaxLen);
 
/* -------------------------------------------------------------------- */
/*      Locale independent formatting functions.                        */
/* -------------------------------------------------------------------- */
int CPL_DLL CPLvsnprintf(char *str, size_t size,
                         CPL_FORMAT_STRING(const char *fmt), va_list args)
    CPL_PRINT_FUNC_FORMAT(3, 0);
 
/* ALIAS_CPLSNPRINTF_AS_SNPRINTF might be defined to enable GCC 7 */
/* -Wformat-truncation= warnings, but shouldn't be set for normal use */
#if defined(ALIAS_CPLSNPRINTF_AS_SNPRINTF)
#define CPLsnprintf snprintf
#else
int CPL_DLL CPLsnprintf(char *str, size_t size,
                        CPL_FORMAT_STRING(const char *fmt), ...)
    CPL_PRINT_FUNC_FORMAT(3, 4);
#endif

#if defined(GDAL_COMPILATION) && !defined(DONT_DEPRECATE_SPRINTF)
int CPL_DLL CPLsprintf(char *str, CPL_FORMAT_STRING(const char *fmt), ...)
    CPL_PRINT_FUNC_FORMAT(2, 3) CPL_WARN_DEPRECATED("Use CPLsnprintf instead");
#else
int CPL_DLL CPLsprintf(char *str, CPL_FORMAT_STRING(const char *fmt), ...)
    CPL_PRINT_FUNC_FORMAT(2, 3);
#endif
int CPL_DLL CPLprintf(CPL_FORMAT_STRING(const char *fmt), ...)
    CPL_PRINT_FUNC_FORMAT(1, 2);
 
/* For some reason Doxygen_Suppress is needed to avoid warning. Not sure why */
/* caution: only works with limited number of formats */
int CPL_DLL CPLsscanf(const char *str, CPL_SCANF_FORMAT_STRING(const char *fmt),
                      ...) CPL_SCAN_FUNC_FORMAT(2, 3);
 
const char CPL_DLL *CPLSPrintf(CPL_FORMAT_STRING(const char *fmt), ...)
    CPL_PRINT_FUNC_FORMAT(1, 2) CPL_WARN_UNUSED_RESULT;
char CPL_DLL **CSLAppendPrintf(char **papszStrList,
                               CPL_FORMAT_STRING(const char *fmt), ...)
    CPL_PRINT_FUNC_FORMAT(2, 3) CPL_WARN_UNUSED_RESULT;
int CPL_DLL CPLVASPrintf(char **buf, CPL_FORMAT_STRING(const char *fmt),
                         va_list args) CPL_PRINT_FUNC_FORMAT(2, 0);
 
/* -------------------------------------------------------------------- */
/*      RFC 23 character set conversion/recoding API (cpl_recode.cpp).  */
/* -------------------------------------------------------------------- */
#define CPL_ENC_LOCALE ""
#define CPL_ENC_UTF8 "UTF-8"
#define CPL_ENC_UTF16 "UTF-16"
#define CPL_ENC_UCS2 "UCS-2"
#define CPL_ENC_UCS4 "UCS-4"
#define CPL_ENC_ASCII "ASCII"
#define CPL_ENC_ISO8859_1 "ISO-8859-1"
 
int CPL_DLL CPLEncodingCharSize(const char *pszEncoding);
void CPL_DLL CPLClearRecodeWarningFlags(void);
char CPL_DLL *CPLRecode(const char *pszSource, const char *pszSrcEncoding,
                        const char *pszDstEncoding)
    CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
char CPL_DLL *
CPLRecodeFromWChar(const wchar_t *pwszSource, const char *pszSrcEncoding,
                   const char *pszDstEncoding) CPL_WARN_UNUSED_RESULT;
wchar_t CPL_DLL *
CPLRecodeToWChar(const char *pszSource, const char *pszSrcEncoding,
                 const char *pszDstEncoding) CPL_WARN_UNUSED_RESULT;
int CPL_DLL CPLIsUTF8(const char *pabyData, int nLen);
bool CPL_DLL CPLIsASCII(const char *pabyData, size_t nLen);
char CPL_DLL *CPLForceToASCII(const char *pabyData, int nLen,
                              char chReplacementChar) CPL_WARN_UNUSED_RESULT;
char CPL_DLL *CPLUTF8ForceToASCII(const char *pszStr, char chReplacementChar)
    CPL_WARN_UNUSED_RESULT;
int CPL_DLL CPLStrlenUTF8(const char *pszUTF8Str)
    CPL_WARN_DEPRECATED("Use CPLStrlenUTF8Ex() instead")
    ;
size_t CPL_DLL CPLStrlenUTF8Ex(const char *pszUTF8Str);
int CPL_DLL CPLCanRecode(const char *pszTestStr, const char *pszSrcEncoding,
                         const char *pszDstEncoding) CPL_WARN_UNUSED_RESULT;
CPL_C_END
 
#if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
 
extern "C++"
{
    std::string CPL_DLL CPLRemoveSQLComments(const std::string &osInput);
}
 
#endif
 
/************************************************************************/
/*                              CPLString                               */
/************************************************************************/
 
#if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
 
extern "C++"
{
#ifndef DOXYGEN_SKIP
#include <string>
#include <vector>
#endif
 
// VC++ implicitly applies __declspec(dllexport) to template base classes
// of classes marked with __declspec(dllexport).
// Hence, if marked with CPL_DLL, VC++ would export symbols for the
// specialization of std::basic_string<char>, since it is a base class of
// CPLString. As a result, if an application linked both gdal.dll and a static
// library that (implicitly) instantiates std::string (almost all do!), then the
// linker would emit an error concerning duplicate symbols for std::string. The
// least intrusive solution is to not mark the whole class with
// __declspec(dllexport) for VC++, but only its non-inline methods.
#ifdef _MSC_VER
#define CPLSTRING_CLASS_DLL
#define CPLSTRING_METHOD_DLL CPL_DLL
#else
#define CPLSTRING_CLASS_DLL CPL_DLL
#define CPLSTRING_METHOD_DLL
#endif

    class CPLSTRING_CLASS_DLL CPLString : public std::string
    {
      public:
        CPLString(void)
        {
        }

        // cppcheck-suppress noExplicitConstructor
        CPLString(const std::string &oStr) : std::string(oStr)
        {
        }

        // cppcheck-suppress noExplicitConstructor
        CPLString(const char *pszStr) : std::string(pszStr)
        {
        }

        CPLString(const char *pszStr, size_t n) : std::string(pszStr, n)
        {
        }

        operator const char *(void) const
        {
            return c_str();
        }

        char &operator[](std::string::size_type i)
        {
            return std::string::operator[](i);
        }

        const char &operator[](std::string::size_type i) const
        {
            return std::string::operator[](i);
        }

        char &operator[](int i)
        {
            return std::string::operator[](
                static_cast<std::string::size_type>(i));
        }

        const char &operator[](int i) const
        {
            return std::string::operator[](
                static_cast<std::string::size_type>(i));
        }

        void Clear()
        {
            resize(0);
        }

        void Seize(char *pszValue)
        {
            if (pszValue == nullptr)
                Clear();
            else
            {
                *this = pszValue;
                CPLFree(pszValue);
            }
        }
 
        /* There seems to be a bug in the way the compiler count indices...
         * Should be CPL_PRINT_FUNC_FORMAT (1, 2) */
        CPLSTRING_METHOD_DLL CPLString &
        Printf(CPL_FORMAT_STRING(const char *pszFormat), ...)
            CPL_PRINT_FUNC_FORMAT(2, 3);
        CPLSTRING_METHOD_DLL CPLString &
        vPrintf(CPL_FORMAT_STRING(const char *pszFormat), va_list args)
            CPL_PRINT_FUNC_FORMAT(2, 0);
        CPLSTRING_METHOD_DLL CPLString &
        FormatC(double dfValue, const char *pszFormat = nullptr);
        CPLSTRING_METHOD_DLL CPLString &Trim();
        CPLSTRING_METHOD_DLL CPLString &Recode(const char *pszSrcEncoding,
                                               const char *pszDstEncoding);
        CPLSTRING_METHOD_DLL CPLString &replaceAll(const std::string &osBefore,
                                                   const std::string &osAfter);
        CPLSTRING_METHOD_DLL CPLString &replaceAll(const std::string &osBefore,
                                                   char chAfter);
        CPLSTRING_METHOD_DLL CPLString &replaceAll(char chBefore,
                                                   const std::string &osAfter);
        CPLSTRING_METHOD_DLL CPLString &replaceAll(char chBefore, char chAfter);
 
        /* case insensitive find alternates */
        CPLSTRING_METHOD_DLL size_t ifind(const std::string &str,
                                          size_t pos = 0) const;
        CPLSTRING_METHOD_DLL size_t ifind(const char *s, size_t pos = 0) const;
        CPLSTRING_METHOD_DLL CPLString &toupper(void);
        CPLSTRING_METHOD_DLL CPLString &tolower(void);
 
        CPLSTRING_METHOD_DLL bool endsWith(const std::string &osStr) const;
 
        CPLSTRING_METHOD_DLL CPLString URLEncode() const;
 
      private:
        operator void *(void) = delete;
    };
 
#undef CPLSTRING_CLASS_DLL
#undef CPLSTRING_METHOD_DLL
 
    CPLString CPL_DLL CPLOPrintf(CPL_FORMAT_STRING(const char *pszFormat), ...)
        CPL_PRINT_FUNC_FORMAT(1, 2);
    CPLString CPL_DLL CPLOvPrintf(CPL_FORMAT_STRING(const char *pszFormat),
                                  va_list args) CPL_PRINT_FUNC_FORMAT(1, 0);
    CPLString CPL_DLL CPLQuotedSQLIdentifier(const char *pszIdent);
 
    /* -------------------------------------------------------------------- */
    /*      URL processing functions, here since they depend on CPLString.  */
    /* -------------------------------------------------------------------- */
    CPLString CPL_DLL CPLURLGetValue(const char *pszURL, const char *pszKey);
    CPLString CPL_DLL CPLURLAddKVP(const char *pszURL, const char *pszKey,
                                   const char *pszValue);
 
    /************************************************************************/
    /*                            CPLStringList                             */
    /************************************************************************/

    class CPL_DLL CPLStringList
    {
        char **papszList = nullptr;
        mutable int nCount = 0;
        mutable int nAllocation = 0;
        bool bOwnList = false;
        bool bIsSorted = false;
 
        bool MakeOurOwnCopy();
        bool EnsureAllocation(int nMaxLength);
        int FindSortedInsertionPoint(const char *pszLine);
 
      public:
        CPLStringList();
        explicit CPLStringList(char **papszList, int bTakeOwnership = TRUE);
        explicit CPLStringList(CSLConstList papszList);
        explicit CPLStringList(const std::vector<std::string> &aosList);
        explicit CPLStringList(std::initializer_list<const char *> oInitList);
        CPLStringList(const CPLStringList &oOther);
        CPLStringList(CPLStringList &&oOther);
        ~CPLStringList();
 
        static const CPLStringList BoundToConstList(CSLConstList papszList);
 
        CPLStringList &Clear();

        inline void clear()
        {
            Clear();
        }

        int size() const
        {
            return Count();
        }
 
        int Count() const;

        bool empty() const
        {
            return Count() == 0;
        }
 
        CPLStringList &AddString(const char *pszNewString);
        CPLStringList &AddString(const std::string &newString);
        CPLStringList &AddStringDirectly(char *pszNewString);

        void push_back(const char *pszNewString)
        {
            AddString(pszNewString);
        }

        void push_back(const std::string &osStr)
        {
            AddString(osStr.c_str());
        }
 
        CPLStringList &InsertString(int nInsertAtLineNo, const char *pszNewLine)
        {
            return InsertStringDirectly(nInsertAtLineNo, CPLStrdup(pszNewLine));
        }
 
        CPLStringList &InsertStringDirectly(int nInsertAtLineNo,
                                            char *pszNewLine);
 
        // CPLStringList &InsertStrings( int nInsertAtLineNo, char
        // **papszNewLines ); CPLStringList &RemoveStrings( int
        // nFirstLineToDelete, int nNumToRemove=1 );

        int FindString(const char *pszTarget) const
        {
            return CSLFindString(papszList, pszTarget);
        }

        int PartialFindString(const char *pszNeedle) const
        {
            return CSLPartialFindString(papszList, pszNeedle);
        }
 
        int FindName(const char *pszName) const;
        bool FetchBool(const char *pszKey, bool bDefault) const;
        // Deprecated.
        int FetchBoolean(const char *pszKey, int bDefault) const;
        const char *FetchNameValue(const char *pszKey) const;
        const char *FetchNameValueDef(const char *pszKey,
                                      const char *pszDefault) const;
        CPLStringList &AddNameValue(const char *pszKey, const char *pszValue);
        CPLStringList &SetNameValue(const char *pszKey, const char *pszValue);
 
        CPLStringList &Assign(char **papszListIn, int bTakeOwnership = TRUE);

        CPLStringList &operator=(char **papszListIn)
        {
            return Assign(papszListIn, TRUE);
        }

        CPLStringList &operator=(const CPLStringList &oOther);
        CPLStringList &operator=(CSLConstList papszListIn);
        CPLStringList &operator=(CPLStringList &&oOther);

        char *operator[](int i);

        char *operator[](size_t i)
        {
            return (*this)[static_cast<int>(i)];
        }

        const char *operator[](int i) const;

        const char *operator[](size_t i) const
        {
            return (*this)[static_cast<int>(i)];
        }

        const char *operator[](const char *pszKey) const
        {
            return FetchNameValue(pszKey);
        }

        inline const char *front() const
        {
            return papszList[0];
        }

        inline const char *back() const
        {
            return papszList[size() - 1];
        }

        const char *const *begin() const
        {
            return papszList ? &papszList[0] : nullptr;
        }

        const char *const *end() const
        {
            return papszList ? &papszList[size()] : nullptr;
        }

        char **List()
        {
            return papszList;
        }

        CSLConstList List() const
        {
            return papszList;
        }
 
        char **StealList();
 
        CPLStringList &Sort();

        int IsSorted() const
        {
            return bIsSorted;
        }

        operator char **(void)
        {
            return List();
        }

        operator CSLConstList(void) const
        {
            return List();
        }

        operator std::vector<std::string>(void) const
        {
            return std::vector<std::string>{begin(), end()};
        }
 
      private:
        operator void *(void) = delete;
    };
 
#ifdef GDAL_COMPILATION
 
#include <iterator>  // For std::input_iterator_tag
#include <memory>
#include <string_view>
#include <utility>  // For std::pair

    struct CPL_DLL CSLDestroyReleaser
    {
        void operator()(char **papszStr) const
        {
            CSLDestroy(papszStr);
        }
    };


    using CSLUniquePtr = std::unique_ptr<char *, CSLDestroyReleaser>;

    using CPLCharUniquePtr = std::unique_ptr<char, VSIFreeReleaser>;
 
    namespace cpl
    {


    template <class StringType>
    inline bool starts_with(const StringType &str, const char *prefix)
    {
        const size_t prefixLen = strlen(prefix);
        return str.size() >= prefixLen &&
               str.compare(0, prefixLen, prefix, prefixLen) == 0;
    }

    template <class StringType>
    inline bool starts_with(const StringType &str, const std::string &prefix)
    {
        return str.size() >= prefix.size() &&
               str.compare(0, prefix.size(), prefix) == 0;
    }

    template <class StringType>
    inline bool starts_with(const StringType &str, std::string_view prefix)
    {
        return str.size() >= prefix.size() &&
               str.compare(0, prefix.size(), prefix) == 0;
    }

    template <class StringType>
    inline bool ends_with(const StringType &str, const char *suffix)
    {
        const size_t suffixLen = strlen(suffix);
        return str.size() >= suffixLen &&
               str.compare(str.size() - suffixLen, suffixLen, suffix,
                           suffixLen) == 0;
    }

    template <class StringType>
    inline bool ends_with(const StringType &str, const std::string &suffix)
    {
        return str.size() >= suffix.size() &&
               str.compare(str.size() - suffix.size(), suffix.size(), suffix) ==
                   0;
    }

    template <class StringType>
    inline bool ends_with(const StringType &str, std::string_view suffix)
    {
        return str.size() >= suffix.size() &&
               str.compare(str.size() - suffix.size(), suffix.size(), suffix) ==
                   0;
    }

    struct CPL_DLL CSLIterator
    {
        using iterator_category = std::input_iterator_tag;
        using difference_type = std::ptrdiff_t;
        using value_type = const char *;
        using pointer = value_type *;
        using reference = value_type &;
 
        CSLConstList m_papszList = nullptr;
        bool m_bAtEnd = false;
 
        inline const char *operator*() const
        {
            return *m_papszList;
        }
 
        inline CSLIterator &operator++()
        {
            if (m_papszList)
                ++m_papszList;
            return *this;
        }
 
        bool operator==(const CSLIterator &other) const;
 
        inline bool operator!=(const CSLIterator &other) const
        {
            return !(operator==(other));
        }
    };


    struct CPL_DLL CSLIteratorWrapper
    {
      public:
        inline explicit CSLIteratorWrapper(CSLConstList papszList)
            : m_papszList(papszList)
        {
        }

        inline CSLIterator begin() const
        {
            return {m_papszList, false};
        }

        inline CSLIterator end() const
        {
            return {m_papszList, true};
        }
 
      private:
        CSLConstList m_papszList;
    };

    inline CSLIteratorWrapper Iterate(CSLConstList papszList)
    {
        return CSLIteratorWrapper{papszList};
    }

    inline CSLIteratorWrapper Iterate(const CPLStringList &aosList)
    {
        return Iterate(aosList.List());
    }


    inline CSLIteratorWrapper Iterate(char **) = delete;


    struct CPL_DLL CSLNameValueIterator
    {
        using iterator_category = std::input_iterator_tag;
        using difference_type = std::ptrdiff_t;
        using value_type = std::pair<const char *, const char *>;
        using pointer = value_type *;
        using reference = value_type &;
 
        CSLConstList m_papszList = nullptr;
        bool m_bReturnNullKeyIfNotNameValue = false;
        std::string m_osKey{};
 
        value_type operator*();
 
        inline CSLNameValueIterator &operator++()
        {
            if (m_papszList)
                ++m_papszList;
            return *this;
        }
 
        inline bool operator==(const CSLNameValueIterator &other) const
        {
            return m_papszList == other.m_papszList;
        }
 
        inline bool operator!=(const CSLNameValueIterator &other) const
        {
            return !(operator==(other));
        }
    };


    struct CPL_DLL CSLNameValueIteratorWrapper
    {
      public:
        inline explicit CSLNameValueIteratorWrapper(
            CSLConstList papszList, bool bReturnNullKeyIfNotNameValue)
            : m_papszList(papszList),
              m_bReturnNullKeyIfNotNameValue(bReturnNullKeyIfNotNameValue)
        {
        }

        inline CSLNameValueIterator begin() const
        {
            return {m_papszList, m_bReturnNullKeyIfNotNameValue};
        }

        CSLNameValueIterator end() const;
 
      private:
        CSLConstList m_papszList;
        const bool m_bReturnNullKeyIfNotNameValue;
    };

    inline CSLNameValueIteratorWrapper
    IterateNameValue(CSLConstList papszList,
                     bool bReturnNullKeyIfNotNameValue = false)
    {
        return CSLNameValueIteratorWrapper{papszList,
                                           bReturnNullKeyIfNotNameValue};
    }

    inline CSLNameValueIteratorWrapper
    IterateNameValue(const CPLStringList &aosList,
                     bool bReturnNullKeyIfNotNameValue = false)
    {
        return IterateNameValue(aosList.List(), bReturnNullKeyIfNotNameValue);
    }


    inline CSLIteratorWrapper IterateNameValue(char **, bool = false) = delete;


    inline std::vector<std::string> ToVector(CSLConstList papszList)
    {
        return CPLStringList::BoundToConstList(papszList);
    }
 
    inline std::vector<std::string> ToVector(char **) = delete;
 
    }  // namespace cpl
 
#endif
 
}  // extern "C++"
 
#endif /* def __cplusplus && !CPL_SUPRESS_CPLUSPLUS */
 
#endif /* CPL_STRING_H_INCLUDED */