Go to the documentation of this file.
32 #ifndef CPL_STRING_H_INCLUDED
33 #define CPL_STRING_H_INCLUDED
72 void CPL_DLL CPL_STDCALL
CSLDestroy(
char **papszStrList);
74 char CPL_DLL **
CSLMerge(
char **papszOrig,
83 const char *pszDelimiter,
87 #define CSLT_HONOURSTRINGS 0x0001
89 #define CSLT_ALLOWEMPTYTOKENS 0x0002
91 #define CSLT_PRESERVEQUOTES 0x0004
93 #define CSLT_PRESERVEESCAPES 0x0008
95 #define CSLT_STRIPLEADSPACES 0x0010
97 #define CSLT_STRIPENDSPACES 0x0020
101 char CPL_DLL **
CSLLoad2(
const char *pszFname,
int nMaxLines,
int nMaxCols,
108 char CPL_DLL **
CSLInsertString(
char **papszStrList,
int nInsertAtLineNo,
111 CSLRemoveStrings(
char **papszStrList,
int nFirstLineToDelete,
int nNumToRemove,
115 const char *pszTarget);
117 const char *pszNeedle);
134 const char *pszName);
137 const char *pszDefault);
139 const char *pszName);
140 char CPL_DLL **
CSLAddNameValue(
char **papszStrList,
const char *pszName,
142 char CPL_DLL **
CSLSetNameValue(
char **papszStrList,
const char *pszName,
145 const char *pszSeparator);
150 #define CPLES_BackslashQuotable 0
161 #define CPLES_XML_BUT_QUOTES 5
163 #define CPLES_CSV_FORCE_QUOTING 6
191 size_t CPL_DLL
CPLStrlcpy(
char *pszDest,
const char *pszSrc,
size_t nDestSize);
192 size_t CPL_DLL
CPLStrlcat(
char *pszDest,
const char *pszSrc,
size_t nDestSize);
193 size_t CPL_DLL
CPLStrnlen(
const char *pszStr,
size_t nMaxLen);
204 #if defined(ALIAS_CPLSNPRINTF_AS_SNPRINTF)
205 #define CPLsnprintf snprintf
213 #if defined(GDAL_COMPILATION) && !defined(DONT_DEPRECATE_SPRINTF)
243 #define CPL_ENC_LOCALE ""
245 #define CPL_ENC_UTF8 "UTF-8"
247 #define CPL_ENC_UTF16 "UTF-16"
249 #define CPL_ENC_UCS2 "UCS-2"
251 #define CPL_ENC_UCS4 "UCS-4"
253 #define CPL_ENC_ASCII "ASCII"
255 #define CPL_ENC_ISO8859_1 "ISO-8859-1"
259 void CPL_DLL CPLClearRecodeWarningFlags(
void);
261 char CPL_DLL *
CPLRecode(
const char *pszSource,
const char *pszSrcEncoding,
262 const char *pszDstEncoding)
270 int CPL_DLL
CPLIsUTF8(
const char *pabyData,
int nLen);
271 bool CPL_DLL
CPLIsASCII(
const char *pabyData,
size_t nLen);
275 int CPL_DLL
CPLCanRecode(
const char *pszTestStr,
const char *pszSrcEncoding,
283 #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
301 #define CPLSTRING_CLASS_DLL
302 #define CPLSTRING_METHOD_DLL CPL_DLL
305 #define CPLSTRING_CLASS_DLL CPL_DLL
306 #define CPLSTRING_METHOD_DLL
311 class CPLSTRING_CLASS_DLL
CPLString :
public std::string
329 CPLString(
const char *pszStr,
size_t n) : std::string(pszStr, n)
334 operator const char *(void)
const
342 return std::string::operator[](i);
348 return std::string::operator[](i);
354 return std::string::operator[](
355 static_cast<std::string::size_type
>(i));
361 return std::string::operator[](
362 static_cast<std::string::size_type
>(i));
376 if (pszValue ==
nullptr)
394 FormatC(
double dfValue, const
char *pszFormat =
nullptr);
396 CPLSTRING_METHOD_DLL
CPLString &Recode(const
char *pszSrcEncoding,
397 const
char *pszDstEncoding);
398 CPLSTRING_METHOD_DLL
CPLString &replaceAll(const std::
string &osBefore,
399 const std::
string &osAfter);
400 CPLSTRING_METHOD_DLL
CPLString &replaceAll(const std::
string &osBefore,
402 CPLSTRING_METHOD_DLL
CPLString &replaceAll(
char chBefore,
403 const std::
string &osAfter);
404 CPLSTRING_METHOD_DLL
CPLString &replaceAll(
char chBefore,
char chAfter);
407 CPLSTRING_METHOD_DLL
size_t ifind(const std::
string &str,
408 size_t pos = 0) const;
409 CPLSTRING_METHOD_DLL
size_t ifind(const
char *s,
size_t pos = 0) const;
410 CPLSTRING_METHOD_DLL
CPLString &toupper(
void);
411 CPLSTRING_METHOD_DLL
CPLString &tolower(
void);
413 CPLSTRING_METHOD_DLL
bool endsWith(const std::
string &osStr) const;
416 #undef CPLSTRING_CLASS_DLL
417 #undef CPLSTRING_METHOD_DLL
430 const
char *pszValue);
439 char **papszList =
nullptr;
440 mutable int nCount = 0;
441 mutable int nAllocation = 0;
442 bool bOwnList =
false;
443 bool bIsSorted =
false;
445 bool MakeOurOwnCopy();
446 bool EnsureAllocation(
int nMaxLength);
447 int FindSortedInsertionPoint(
const char *pszLine);
451 explicit CPLStringList(
char **papszList,
int bTakeOwnership = TRUE);
477 return InsertStringDirectly(nInsertAtLineNo,
CPLStrdup(pszNewLine));
498 int FindName(
const char *pszName)
const;
499 bool FetchBool(
const char *pszKey,
bool bDefault)
const;
501 int FetchBoolean(
const char *pszKey,
int bDefault)
const;
502 const char *FetchNameValue(
const char *pszKey)
const;
503 const char *FetchNameValueDef(
const char *pszKey,
504 const char *pszDefault)
const;
505 CPLStringList &AddNameValue(
const char *pszKey,
const char *pszValue);
506 CPLStringList &SetNameValue(
const char *pszKey,
const char *pszValue);
508 CPLStringList &Assign(
char **papszListIn,
int bTakeOwnership = TRUE);
512 return Assign(papszListIn, TRUE);
522 char *operator[](
int i);
526 return (*
this)[
static_cast<int>(i)];
529 const char *operator[](
int i)
const;
533 return (*
this)[
static_cast<int>(i)];
538 return FetchNameValue(pszKey);
544 return papszList ? &papszList[0] :
nullptr;
548 const char *
const *
end()
const
550 return papszList ? &papszList[size()] :
nullptr;
573 operator char **(void)
584 #ifdef GDAL_COMPILATION
589 struct CPL_DLL CSLDestroyReleaser
591 void operator()(
char **papszStr)
const
599 using CSLUniquePtr = std::unique_ptr<char *, CSLDestroyReleaser>;
602 struct CPL_DLL CPLFreeReleaser
604 void operator()(
void *p)
const
613 using CPLCharUniquePtr = std::unique_ptr<char, CPLFreeReleaser>;
char ** CSLLoad2(const char *pszFname, int nMaxLines, int nMaxCols, CSLConstList papszOptions)
Load a text file into a string list.
Definition: cpl_string.cpp:321
CPLStringList & operator=(char **papszListIn)
Assignment operator.
Definition: cpl_string.h:510
#define CPL_PRINT_FUNC_FORMAT(format_idx, arg_idx)
Tag a function to have printf() formatting.
Definition: cpl_port.h:950
char * CPLRecodeFromWChar(const wchar_t *pwszSource, const char *pszSrcEncoding, const char *pszDstEncoding)
Convert wchar_t string to UTF-8.
Definition: cpl_recode.cpp:178
char ** CSLInsertString(char **papszStrList, int nInsertAtLineNo, const char *pszNewLine)
Insert a string at a given line number inside a StringList.
Definition: cpl_string.cpp:563
char ** CSLTokenizeString2(const char *pszString, const char *pszDelimiter, int nCSLTFlags)
Tokenize a string.
Definition: cpl_string.cpp:835
int CSLFindStringCaseSensitive(CSLConstList papszList, const char *pszTarget)
Find a string within a string list(case sensitive)
Definition: cpl_string.cpp:705
unsigned char GByte
Unsigned byte type.
Definition: cpl_port.h:196
const char *const * begin() const
begin() implementation
Definition: cpl_string.h:542
CPLString(const char *pszStr, size_t n)
Constructor.
Definition: cpl_string.h:329
CPLString CPLURLAddKVP(const char *pszURL, const char *pszKey, const char *pszValue)
Return a new URL with a new key=value pair.
Definition: cplstring.cpp:446
char ** CSLMerge(char **papszOrig, CSLConstList papszOverride)
Merge two lists.
Definition: cpl_string.cpp:273
int CPLIsUTF8(const char *pabyData, int nLen)
Test if a string is encoded as UTF-8.
Definition: cpl_recode.cpp:276
char * CPLEscapeString(const char *pszString, int nLength, int nScheme)
Apply escaping to string to preserve special characters.
Definition: cpl_string.cpp:2058
char ** CSLLoad(const char *pszFname)
Load a text file into a string list.
Definition: cpl_string.cpp:398
CPLString CPLOvPrintf(const char *pszFormat, va_list args)
Return a CPLString with the content of vsprintf()
Definition: cplstring.cpp:514
CPLStringList & InsertString(int nInsertAtLineNo, const char *pszNewLine)
Insert into the list at identified location.
Definition: cpl_string.h:475
size_t CPLStrlcat(char *pszDest, const char *pszSrc, size_t nDestSize)
Appends a source string to a destination buffer.
Definition: cpl_string.cpp:2914
String list class designed around our use of C "char**" string lists.
Definition: cpl_string.h:437
int CSLFindName(CSLConstList papszStrList, const char *pszName)
Find StringList entry with given key name.
Definition: cpl_string.cpp:1733
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:2725
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:1674
char ** CSLSetNameValue(char **papszStrList, const char *pszName, const char *pszValue)
Assign value to name in StringList.
Definition: cpl_string.cpp:1899
int CPLsnprintf(char *str, size_t size, const char *fmt,...)
snprintf() wrapper that is not sensitive to LC_NUMERIC settings.
Definition: cpl_string.cpp:1367
char ** CSLAppendPrintf(char **papszStrList, const char *fmt,...)
Use CPLSPrintf() to append a new line at the end of a StringList.
Definition: cpl_string.cpp:1036
int CSLCount(CSLConstList papszStrList)
Return number of items in a string list.
Definition: cpl_string.cpp:147
CSLConstList List() const
Return list.
Definition: cpl_string.h:559
Convenient string class based on std::string.
Definition: cpl_string.h:311
int size() const
Return size of list.
Definition: cpl_string.h:460
bool CPLFetchBool(CSLConstList papszStrList, const char *pszKey, bool bDefault)
Check for boolean key value.
Definition: cpl_string.cpp:1630
@ CPL_VALUE_STRING
String.
Definition: cpl_string.h:184
int CSLPartialFindString(CSLConstList papszHaystack, const char *pszNeedle)
Find a substring within a string list.
Definition: cpl_string.cpp:737
int FindString(const char *pszTarget) const
Return index of pszTarget in the list, or -1.
Definition: cpl_string.h:487
CPLString(const std::string &oStr)
Constructor.
Definition: cpl_string.h:320
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:173
const char & operator[](std::string::size_type i) const
Return character at specified index.
Definition: cpl_string.h:346
#define CPL_C_START
Macro to start a block of C symbols.
Definition: cpl_port.h:306
int CSLTestBoolean(const char *pszValue)
Test what boolean value contained in the string.
Definition: cpl_string.cpp:1583
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:235
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:498
bool CPLTestBool(const char *pszValue)
Test what boolean value contained in the string.
Definition: cpl_string.cpp:1558
char & operator[](int i)
Return character at specified index.
Definition: cpl_string.h:352
int CPLprintf(const char *fmt,...)
printf() wrapper that is not sensitive to LC_NUMERIC settings.
Definition: cpl_string.cpp:1422
void Seize(char *pszValue)
Assign specified string and take ownership of it (assumed to be allocated with CPLMalloc()).
Definition: cpl_string.h:374
const char & operator[](int i) const
Return character at specified index.
Definition: cpl_string.h:359
char ** CSLConstList
Type of a constant null-terminated list of nul terminated strings.
Definition: cpl_port.h:1178
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:1055
char * operator[](size_t i)
Return string at specified index.
Definition: cpl_string.h:524
char * CPLBase64Encode(int nBytes, const GByte *pabyData)
Base64 encode a buffer.
Definition: cpl_base64.cpp:196
size_t CPLStrlcpy(char *pszDest, const char *pszSrc, size_t nDestSize)
Copy source string to a destination buffer.
Definition: cpl_string.cpp:2857
bool empty() const
Return whether the list is empty.
Definition: cpl_string.h:467
char & operator[](std::string::size_type i)
Return character at specified index.
Definition: cpl_string.h:340
#define CPL_SCAN_FUNC_FORMAT(format_idx, arg_idx)
Tag a function to have scanf() formatting.
Definition: cpl_port.h:952
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:413
#define CPL_C_END
Macro to end a block of C symbols.
Definition: cpl_port.h:310
int CSLPrint(CSLConstList papszStrList, FILE *fpOut)
Print a StringList to fpOut.
Definition: cpl_string.cpp:462
char ** List()
Return list.
Definition: cpl_string.h:554
int CSLFindString(CSLConstList papszList, const char *pszTarget)
Find a string within a string list (case insensitive).
Definition: cpl_string.cpp:671
@ CPL_VALUE_INTEGER
Integer.
Definition: cpl_string.h:186
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:77
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:1147
const char * CPLSPrintf(const char *fmt,...)
CPLSPrintf() that works with 10 static buffer.
Definition: cpl_string.cpp:983
int IsSorted() const
Returns whether the list is sorted.
Definition: cpl_string.h:567
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:1860
char ** CSLAddStringMayFail(char **papszStrList, const char *pszNewString)
Same as CSLAddString() but may return NULL in case of (memory) failure.
Definition: cpl_string.cpp:92
int CPLStrlenUTF8(const char *pszUTF8Str)
Return the number of UTF-8 characters of a nul-terminated string.
Definition: cpl_recode.cpp:415
const char * operator[](size_t i) const
Return string at specified index.
Definition: cpl_string.h:531
const char * CPLParseNameValue(const char *pszNameValue, char **ppszKey)
Parse NAME=VALUE string into name and value components.
Definition: cpl_string.cpp:1778
char ** CSLTokenizeStringComplex(const char *pszString, const char *pszDelimiter, int bHonourStrings, int bAllowEmptyTokens)
Obsolete tokenizing api.
Definition: cpl_string.cpp:768
char * CPLUnescapeString(const char *pszString, int *pnLength, int nScheme)
Unescape a string.
Definition: cpl_string.cpp:2408
int CPLEncodingCharSize(const char *pszEncoding)
Return bytes per character for encoding.
Definition: cpl_recode.cpp:369
const char *const * end() const
end() implementation
Definition: cpl_string.h:548
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:2949
int CSLSave(CSLConstList papszStrList, const char *pszFname)
Write a StringList to a text file.
Definition: cpl_string.cpp:413
bool CPLIsASCII(const char *pabyData, size_t nLen)
Test if a string is encoded as ASCII.
Definition: cpl_recode.cpp:295
char ** CSLDuplicate(CSLConstList papszStrList)
Clone a string list.
Definition: cpl_string.cpp:228
int PartialFindString(const char *pszNeedle) const
Return index of pszTarget in the list (using partial search), or -1.
Definition: cpl_string.h:493
#define CPL_SCANF_FORMAT_STRING(arg)
Macro into which to wrap the format argument of a sscanf-like function.
Definition: cpl_port.h:968
void CSLDestroy(char **papszStrList)
Free string list.
Definition: cpl_string.cpp:200
@ CPL_VALUE_REAL
Real number.
Definition: cpl_string.h:185
CPLValueType
Type of value.
Definition: cpl_string.h:182
#define CPL_WARN_UNUSED_RESULT
Qualifier to warn when the return value of a function is not used.
Definition: cpl_port.h:976
#define CPL_FORMAT_STRING(arg)
Macro into which to wrap the format argument of a printf-like function.
Definition: cpl_port.h:966
CPLString(const char *pszStr)
Constructor.
Definition: cpl_string.h:325
char ** CSLTokenizeString(const char *pszString)
Tokenizes a string and returns a StringList with one string for each token.
Definition: cpl_string.cpp:758
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:1980
char * CPLForceToASCII(const char *pabyData, int nLen, char chReplacementChar)
Return a new string that is made only of ASCII characters.
Definition: cpl_recode.cpp:327
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:1825
int CPLTestBoolean(const char *pszValue)
Test what boolean value contained in the string.
Definition: cpl_string.cpp:1605
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:1701
char ** CSLRemoveStrings(char **papszStrList, int nFirstLineToDelete, int nNumToRemove, char ***ppapszRetStrings)
Remove strings inside a StringList.
Definition: cpl_string.cpp:589
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:441
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:83
void Clear()
Clear the string.
Definition: cpl_string.h:366
CPLString CPLOPrintf(const char *pszFormat,...)
Return a CPLString with the content of sprintf()
Definition: cplstring.cpp:495
char * CPLStrdup(const char *)
Safe version of strdup() function.
Definition: cpl_conv.cpp:306
char * CPLBinaryToHex(int nBytes, const GByte *pabyData)
Binary to hexadecimal translation.
Definition: cpl_string.cpp:2632
CPLString(void)
Constructor.
Definition: cpl_string.h:315
const char * operator[](const char *pszKey) const
Return value corresponding to pszKey, or nullptr.
Definition: cpl_string.h:536
char ** CSLParseCommandLine(const char *pszCommandLine)
Tokenize command line arguments in a list of strings.
Definition: cpl_string.cpp:2973
int CPLBase64DecodeInPlace(GByte *pszBase64)
Decode base64 string "pszBase64" (null terminated) in place.
Definition: cpl_base64.cpp:90
int CSLFetchBoolean(CSLConstList papszStrList, const char *pszKey, int bDefault)
DEPRECATED.
Definition: cpl_string.cpp:1663
CPLString CPLQuotedSQLIdentifier(const char *pszIdent)
Return a CPLString of the SQL quoted identifier.
Definition: cplstring.cpp:527
#define CPLFree
Alias of VSIFree()
Definition: cpl_conv.h:98
#define CPL_RETURNS_NONNULL
Qualifier for a function that does not return NULL.
Definition: cpl_port.h:1014
GByte * CPLHexToBinary(const char *pszHex, int *pnBytes)
Hexadecimal to binary translation.
Definition: cpl_string.cpp:2686