SDTS_AL
cpl_string.h
Go to the documentation of this file.
1 /**********************************************************************
2  * $Id: cpl_string.h 33788 2016-03-26 00:45:58Z goatbar $
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 mines-paris dot org>
12  *
13  * Permission is hereby granted, free of charge, to any person obtaining a
14  * copy of this software and associated documentation files (the "Software"),
15  * to deal in the Software without restriction, including without limitation
16  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
17  * and/or sell copies of the Software, and to permit persons to whom the
18  * Software is furnished to do so, subject to the following conditions:
19  *
20  * The above copyright notice and this permission notice shall be included
21  * in all copies or substantial portions of the Software.
22  *
23  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
24  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
25  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
26  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
27  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
28  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
29  * DEALINGS IN THE SOFTWARE.
30  ****************************************************************************/
31 
32 #ifndef CPL_STRING_H_INCLUDED
33 #define CPL_STRING_H_INCLUDED
34 
35 #include "cpl_error.h"
36 #include "cpl_conv.h"
37 #include "cpl_vsi.h"
38 
61 CPL_C_START
62 
63 char CPL_DLL **CSLAddString(char **papszStrList,
64  const char *pszNewString) CPL_WARN_UNUSED_RESULT;
65 char CPL_DLL **CSLAddStringMayFail(
66  char **papszStrList, const char *pszNewString) CPL_WARN_UNUSED_RESULT;
67 #ifdef __cplusplus
68  int CPL_DLL CSLCount(const char * const *papszStrList);
69 #else
70  int CPL_DLL CSLCount(char **papszStrList);
71 #endif
72 const char CPL_DLL *CSLGetField( char **, int );
73 void CPL_DLL CPL_STDCALL CSLDestroy(char **papszStrList);
74 char CPL_DLL **CSLDuplicate(char **papszStrList) CPL_WARN_UNUSED_RESULT;
75 char CPL_DLL **CSLMerge( char **papszOrig,
76  char **papszOverride ) CPL_WARN_UNUSED_RESULT;
77 
78 char CPL_DLL **CSLTokenizeString(const char *pszString ) CPL_WARN_UNUSED_RESULT;
79 char CPL_DLL **CSLTokenizeStringComplex(
80  const char *pszString, const char *pszDelimiter, int bHonourStrings,
81  int bAllowEmptyTokens ) CPL_WARN_UNUSED_RESULT;
82 char CPL_DLL **CSLTokenizeString2( const char *pszString,
83  const char *pszDelimiter,
84  int nCSLTFlags ) CPL_WARN_UNUSED_RESULT;
85 
86 #define CSLT_HONOURSTRINGS 0x0001
87 #define CSLT_ALLOWEMPTYTOKENS 0x0002
88 #define CSLT_PRESERVEQUOTES 0x0004
89 #define CSLT_PRESERVEESCAPES 0x0008
90 #define CSLT_STRIPLEADSPACES 0x0010
91 #define CSLT_STRIPENDSPACES 0x0020
92 
93 int CPL_DLL CSLPrint(char **papszStrList, FILE *fpOut);
94 char CPL_DLL **CSLLoad(const char *pszFname) CPL_WARN_UNUSED_RESULT;
95 char CPL_DLL **CSLLoad2(const char *pszFname, int nMaxLines, int nMaxCols,
96  char** papszOptions) CPL_WARN_UNUSED_RESULT;
97 int CPL_DLL CSLSave(char **papszStrList, const char *pszFname);
98 
99 char CPL_DLL **CSLInsertStrings(char **papszStrList, int nInsertAtLineNo,
100  char **papszNewLines) CPL_WARN_UNUSED_RESULT;
101 char CPL_DLL **CSLInsertString(char **papszStrList, int nInsertAtLineNo,
102  const char *pszNewLine) CPL_WARN_UNUSED_RESULT;
103 char CPL_DLL **CSLRemoveStrings(
104  char **papszStrList, int nFirstLineToDelete,
105  int nNumToRemove, char ***ppapszRetStrings) CPL_WARN_UNUSED_RESULT;
106 int CPL_DLL CSLFindString( char **, const char * );
107 int CPL_DLL CSLFindStringCaseSensitive( char **, const char * );
108 int CPL_DLL CSLPartialFindString( char **papszHaystack,
109  const char * pszNeedle );
110 int CPL_DLL CSLFindName(char **papszStrList, const char *pszName);
111 int CPL_DLL CSLFetchBoolean( char **papszStrList, const char *pszKey,
112  int bDefault );
113 
114 /* TODO: Deprecate CSLTestBoolean. Remove in GDAL 3.x. */
115 int CPL_DLL CSLTestBoolean( const char *pszValue );
116 int CPL_DLL CPLTestBoolean( const char *pszValue );
117 
118 #ifdef __cplusplus
119 #ifdef DO_NOT_USE_DEBUG_BOOL
120 #define CPLTestBool(x) CPL_TO_BOOL(CPLTestBoolean(x))
121 #else
122 /* Prefer these for C++ code. */
123 #ifdef DEBUG_BOOL
124 extern "C++" {
125 #endif
126 bool CPL_DLL CPLTestBool( const char *pszValue );
127 #ifdef DEBUG_BOOL
128 }
129 #endif
130 #endif
131 bool CPL_DLL CPLFetchBool( const char **papszStrList, const char *pszKey,
132  bool bDefault );
133 #endif /* __cplusplus */
134 
135 const char CPL_DLL *
136  CPLParseNameValue(const char *pszNameValue, char **ppszKey );
137 const char CPL_DLL *
138  CSLFetchNameValue(char **papszStrList, const char *pszName);
139 const char CPL_DLL *
140  CSLFetchNameValueDef(char **papszStrList, const char *pszName,
141  const char *pszDefault );
142 char CPL_DLL **
143  CSLFetchNameValueMultiple(char **papszStrList, const char *pszName);
144 char CPL_DLL **
145  CSLAddNameValue(char **papszStrList,
146  const char *pszName,
147  const char *pszValue) CPL_WARN_UNUSED_RESULT;
148 char CPL_DLL **
149  CSLSetNameValue(char **papszStrList,
150  const char *pszName,
151  const char *pszValue) CPL_WARN_UNUSED_RESULT;
152 void CPL_DLL CSLSetNameValueSeparator( char ** papszStrList,
153  const char *pszSeparator );
154 
155 char CPL_DLL ** CSLParseCommandLine(const char* pszCommandLine);
156 
157 #define CPLES_BackslashQuotable 0
158 #define CPLES_XML 1
159 #define CPLES_URL 2
160 #define CPLES_SQL 3
161 #define CPLES_CSV 4
162 #define CPLES_XML_BUT_QUOTES 5
163 
164 char CPL_DLL *CPLEscapeString( const char *pszString, int nLength,
165  int nScheme ) CPL_WARN_UNUSED_RESULT;
166 char CPL_DLL *CPLUnescapeString( const char *pszString, int *pnLength,
167  int nScheme ) CPL_WARN_UNUSED_RESULT;
168 
169 char CPL_DLL *CPLBinaryToHex( int nBytes,
170  const GByte *pabyData ) CPL_WARN_UNUSED_RESULT;
171 GByte CPL_DLL *CPLHexToBinary( const char *pszHex,
172  int *pnBytes ) CPL_WARN_UNUSED_RESULT;
173 
174 char CPL_DLL *CPLBase64Encode( int nBytes,
175  const GByte *pabyData ) CPL_WARN_UNUSED_RESULT;
176 int CPL_DLL CPLBase64DecodeInPlace( GByte* pszBase64 );
177 
178 typedef enum
179 {
180  CPL_VALUE_STRING,
181  CPL_VALUE_REAL,
182  CPL_VALUE_INTEGER
183 } CPLValueType;
184 
185 CPLValueType CPL_DLL CPLGetValueType(const char* pszValue);
186 
187 size_t CPL_DLL CPLStrlcpy(char* pszDest, const char* pszSrc, size_t nDestSize);
188 size_t CPL_DLL CPLStrlcat(char* pszDest, const char* pszSrc, size_t nDestSize);
189 size_t CPL_DLL CPLStrnlen(const char *pszStr, size_t nMaxLen);
190 
191 /* -------------------------------------------------------------------- */
192 /* Locale independent formatting functions. */
193 /* -------------------------------------------------------------------- */
194 int CPL_DLL CPLvsnprintf(char *str, size_t size, const char* fmt,
195  va_list args) CPL_PRINT_FUNC_FORMAT (3, 0);
196 int CPL_DLL CPLsnprintf(char *str, size_t size,
197  const char* fmt, ...) CPL_PRINT_FUNC_FORMAT(3,4);
198 #if defined(GDAL_COMPILATION) && !defined(DONT_DEPRECATE_SPRINTF)
199 int CPL_DLL CPLsprintf(char *str, const char* fmt, ...)
200  CPL_PRINT_FUNC_FORMAT(2, 3) CPL_WARN_DEPRECATED("Use CPLsnprintf instead");
201 #else
202 int CPL_DLL CPLsprintf(char *str, const char* fmt, ...)
203  CPL_PRINT_FUNC_FORMAT(2, 3);
204 #endif
205 int CPL_DLL CPLprintf(const char* fmt, ...) CPL_PRINT_FUNC_FORMAT(1, 2);
206 /* caution: only works with limited number of formats */
207 int CPL_DLL CPLsscanf(const char* str, const char* fmt, ...)
208  CPL_SCAN_FUNC_FORMAT(2, 3);
209 
210 const char CPL_DLL *CPLSPrintf(const char *fmt, ...)
211  CPL_PRINT_FUNC_FORMAT(1, 2) CPL_WARN_UNUSED_RESULT;
212 char CPL_DLL **CSLAppendPrintf(char **papszStrList, const char *fmt, ...)
213  CPL_PRINT_FUNC_FORMAT(2, 3) CPL_WARN_UNUSED_RESULT;
214 int CPL_DLL CPLVASPrintf(char **buf, const char *fmt, va_list args )
215  CPL_PRINT_FUNC_FORMAT(2, 0);
216 
217 /* -------------------------------------------------------------------- */
218 /* RFC 23 character set conversion/recoding API (cpl_recode.cpp). */
219 /* -------------------------------------------------------------------- */
220 #define CPL_ENC_LOCALE ""
221 #define CPL_ENC_UTF8 "UTF-8"
222 #define CPL_ENC_UTF16 "UTF-16"
223 #define CPL_ENC_UCS2 "UCS-2"
224 #define CPL_ENC_UCS4 "UCS-4"
225 #define CPL_ENC_ASCII "ASCII"
226 #define CPL_ENC_ISO8859_1 "ISO-8859-1"
227 
228 int CPL_DLL CPLEncodingCharSize( const char *pszEncoding );
229 void CPL_DLL CPLClearRecodeWarningFlags( void );
230 char CPL_DLL *CPLRecode(
231  const char *pszSource, const char *pszSrcEncoding,
232  const char *pszDstEncoding ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
233 char CPL_DLL *CPLRecodeFromWChar(
234  const wchar_t *pwszSource, const char *pszSrcEncoding,
235  const char *pszDstEncoding ) CPL_WARN_UNUSED_RESULT;
236 wchar_t CPL_DLL *CPLRecodeToWChar(
237  const char *pszSource, const char *pszSrcEncoding,
238  const char *pszDstEncoding ) CPL_WARN_UNUSED_RESULT;
239 int CPL_DLL CPLIsUTF8(const char* pabyData, int nLen);
240 char CPL_DLL *CPLForceToASCII(
241  const char* pabyData, int nLen,
242  char chReplacementChar) CPL_WARN_UNUSED_RESULT;
243 int CPL_DLL CPLStrlenUTF8(const char *pszUTF8Str);
244 
245 CPL_C_END
246 
247 /************************************************************************/
248 /* CPLString */
249 /************************************************************************/
250 
251 #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
252 
253 #include <string>
254 
255 /*
256  * Simple trick to avoid "using" declaration in header for new compilers
257  * but make it still working with old compilers which throw C2614 errors.
258  *
259  * Define MSVC_OLD_STUPID_BEHAVIOUR
260  * for old compilers: VC++ 5 and 6 as well as eVC++ 3 and 4.
261  */
262 
263 /*
264  * Detect old MSVC++ compiler <= 6.0
265  * 1200 - VC++ 6.0
266  * 1200-1202 - eVC++ 4.0
267  */
268 #if defined(_MSC_VER)
269 # if (_MSC_VER <= 1202)
270 # define MSVC_OLD_STUPID_BEHAVIOUR
271 # endif
272 #endif
273 
274 /* Avoid C2614 errors */
275 #ifdef MSVC_OLD_STUPID_BEHAVIOUR
276  using std::string;
277 # define gdal_std_string string
278 #else
279 # define gdal_std_string std::string
280 #endif
281 
283 class CPL_DLL CPLString : public gdal_std_string
284 {
285 public:
286 
287  CPLString(void) {}
288  CPLString( const std::string &oStr ) : gdal_std_string( oStr ) {}
289  CPLString( const char *pszStr ) : gdal_std_string( pszStr ) {}
290 
291  operator const char* (void) const { return c_str(); }
292 
293  char& operator[](std::string::size_type i)
294  {
295  return gdal_std_string::operator[](i);
296  }
297 
298  const char& operator[](std::string::size_type i) const
299  {
300  return gdal_std_string::operator[](i);
301  }
302 
303  char& operator[](int i)
304  {
305  return gdal_std_string::operator[](
306  static_cast<std::string::size_type>(i));
307  }
308 
309  const char& operator[](int i) const
310  {
311  return gdal_std_string::operator[](
312  static_cast<std::string::size_type>(i));
313  }
314 
315  void Clear() { resize(0); }
316 
317  // NULL safe assign and free.
318  void Seize(char *pszValue)
319  {
320  if (pszValue == NULL )
321  Clear();
322  else
323  {
324  *this = pszValue;
325  CPLFree(pszValue);
326  }
327  }
328 
329  /* There seems to be a bug in the way the compiler count indices...
330  * Should be CPL_PRINT_FUNC_FORMAT (1, 2) */
331  CPLString &Printf(
332  const char *pszFormat, ... ) CPL_PRINT_FUNC_FORMAT (2, 3);
333  CPLString &vPrintf(
334  const char *pszFormat, va_list args ) CPL_PRINT_FUNC_FORMAT(2, 0);
335  CPLString &FormatC( double dfValue, const char *pszFormat = NULL );
336  CPLString &Trim();
337  CPLString &Recode( const char *pszSrcEncoding, const char *pszDstEncoding );
338 
339  /* case insensitive find alternates */
340  size_t ifind( const std::string & str, size_t pos = 0 ) const;
341  size_t ifind( const char * s, size_t pos = 0 ) const;
342  CPLString &toupper( void );
343  CPLString &tolower( void );
344 };
345 
346 CPLString CPLOPrintf(const char *pszFormat, ... ) CPL_PRINT_FUNC_FORMAT (1, 2);
347 CPLString CPLOvPrintf(
348  const char *pszFormat, va_list args) CPL_PRINT_FUNC_FORMAT (1, 0);
349 
350 /* -------------------------------------------------------------------- */
351 /* URL processing functions, here since they depend on CPLString. */
352 /* -------------------------------------------------------------------- */
353 CPLString CPL_DLL CPLURLGetValue(const char* pszURL, const char* pszKey);
354 CPLString CPL_DLL CPLURLAddKVP(const char* pszURL, const char* pszKey,
355  const char* pszValue);
356 
357 /************************************************************************/
358 /* CPLStringList */
359 /************************************************************************/
360 
362 class CPL_DLL CPLStringList
363 {
364  char **papszList;
365  mutable int nCount;
366  mutable int nAllocation;
367  bool bOwnList;
368  bool bIsSorted;
369 
370  void Initialize();
371  void MakeOurOwnCopy();
372  void EnsureAllocation( int nMaxLength );
373  int FindSortedInsertionPoint( const char *pszLine );
374 
375  public:
376  CPLStringList();
377  CPLStringList( char **papszList, int bTakeOwnership=TRUE );
378  CPLStringList( const CPLStringList& oOther );
379  ~CPLStringList();
380 
381  CPLStringList &Clear();
382 
383  int size() const { return Count(); }
384  int Count() const;
385 
386  CPLStringList &AddString( const char *pszNewString );
387  CPLStringList &AddStringDirectly( char *pszNewString );
388 
389  CPLStringList &InsertString( int nInsertAtLineNo, const char *pszNewLine )
390  { return InsertStringDirectly( nInsertAtLineNo, CPLStrdup(pszNewLine) ); }
391  CPLStringList &InsertStringDirectly( int nInsertAtLineNo, char *pszNewLine);
392 
393  // CPLStringList &InsertStrings( int nInsertAtLineNo, char **papszNewLines );
394  // CPLStringList &RemoveStrings( int nFirstLineToDelete, int nNumToRemove=1 );
395 
396  int FindString( const char *pszTarget ) const
397  { return CSLFindString( papszList, pszTarget ); }
398  int PartialFindString( const char *pszNeedle ) const
399  { return CSLPartialFindString( papszList, pszNeedle ); }
400 
401  int FindName( const char *pszName ) const;
402  bool FetchBool( const char *pszKey, bool bDefault ) const;
403  // Deprecated.
404  int FetchBoolean( const char *pszKey, int bDefault ) const;
405  const char *FetchNameValue( const char *pszKey ) const;
406  const char *FetchNameValueDef(
407  const char *pszKey, const char *pszDefault ) const;
408  CPLStringList &AddNameValue( const char *pszKey, const char *pszValue );
409  CPLStringList &SetNameValue( const char *pszKey, const char *pszValue );
410 
411  CPLStringList &Assign( char **papszListIn, int bTakeOwnership=TRUE );
412  CPLStringList &operator=(char **papszListIn) {
413  return Assign( papszListIn, TRUE ); }
414  CPLStringList &operator=(const CPLStringList& oOther);
415 
416  char * operator[](int i);
417  char * operator[](size_t i) { return (*this)[static_cast<int>(i)]; }
418  const char * operator[](int i) const;
419  const char * operator[](size_t i) const {
420  return (*this)[static_cast<int>(i)]; }
421 
422  char **List() { return papszList; }
423  char **StealList();
424 
425  CPLStringList &Sort();
426  int IsSorted() const { return bIsSorted; }
427 
428  operator char**(void) { return List(); }
429 };
430 
431 #endif /* def __cplusplus && !CPL_SUPRESS_CPLUSPLUS */
432 
433 #endif /* CPL_STRING_H_INCLUDED */
char CPL_DLL * CPLRecode(const char *pszSource, const char *pszSrcEncoding, const char *pszDstEncoding) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL
Definition: cpl_recode.cpp:74
size_t CPL_DLL CPLStrnlen(const char *pszStr, size_t nMaxLen)
Definition: cpl_string.cpp:2734
int CPL_DLL CPLTestBoolean(const char *pszValue)
Definition: cpl_string.cpp:1537
int CPL_DLL CPLStrlenUTF8(const char *pszUTF8Str)
Definition: cpl_recode.cpp:355
int CPL_DLL CPLIsUTF8(const char *pabyData, int nLen)
Definition: cpl_recode.cpp:243
char CPL_DLL ** CSLLoad2(const char *pszFname, int nMaxLines, int nMaxCols, char **papszOptions) CPL_WARN_UNUSED_RESULT
Definition: cpl_string.cpp:299
char CPL_DLL ** CSLSetNameValue(char **papszStrList, const char *pszName, const char *pszValue) CPL_WARN_UNUSED_RESULT
Definition: cpl_string.cpp:1831
CPLValueType CPL_DLL CPLGetValueType(const char *pszValue)
Definition: cpl_string.cpp:2511
char CPL_DLL * CPLStrdup(const char *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL
Definition: cpl_conv.cpp:261
wchar_t CPL_DLL * CPLRecodeToWChar(const char *pszSource, const char *pszSrcEncoding, const char *pszDstEncoding) CPL_WARN_UNUSED_RESULT
Definition: cpl_recode.cpp:200
char CPL_DLL ** CSLDuplicate(char **papszStrList) CPL_WARN_UNUSED_RESULT
Definition: cpl_string.cpp:214
char CPL_DLL * CPLEscapeString(const char *pszString, int nLength, int nScheme) CPL_WARN_UNUSED_RESULT
Definition: cpl_string.cpp:1982
int CPL_DLL CPLEncodingCharSize(const char *pszEncoding)
Definition: cpl_recode.cpp:309
int CPL_DLL CSLFindStringCaseSensitive(char **, const char *)
Definition: cpl_string.cpp:684
char CPL_DLL * CPLUnescapeString(const char *pszString, int *pnLength, int nScheme) CPL_WARN_UNUSED_RESULT
Definition: cpl_string.cpp:2198
char CPL_DLL ** CSLParseCommandLine(const char *pszCommandLine)
Definition: cpl_string.cpp:2758
void CPL_DLL CPL_STDCALL CSLDestroy(char **papszStrList)
Definition: cpl_string.cpp:186
int CPL_DLL CSLFindString(char **, const char *)
Definition: cpl_string.cpp:650
size_t CPL_DLL CPLStrlcpy(char *pszDest, const char *pszSrc, size_t nDestSize)
Definition: cpl_string.cpp:2642
size_t CPL_DLL CPLStrlcat(char *pszDest, const char *pszSrc, size_t nDestSize)
Definition: cpl_string.cpp:2699
char CPL_DLL ** CSLMerge(char **papszOrig, char **papszOverride) CPL_WARN_UNUSED_RESULT
Merge two lists.
Definition: cpl_string.cpp:254
int CPL_DLL CSLPartialFindString(char **papszHaystack, const char *pszNeedle)
Definition: cpl_string.cpp:716
int CPL_DLL CSLTestBoolean(const char *pszValue)
Definition: cpl_string.cpp:1515
char CPL_DLL * CPLForceToASCII(const char *pabyData, int nLen, char chReplacementChar) CPL_WARN_UNUSED_RESULT
Definition: cpl_recode.cpp:267
char CPL_DLL ** CSLLoad(const char *pszFname) CPL_WARN_UNUSED_RESULT
Definition: cpl_string.cpp:379
const char CPL_DLL * CPLParseNameValue(const char *pszNameValue, char **ppszKey)
Definition: cpl_string.cpp:1712
char CPL_DLL ** CSLTokenizeString2(const char *pszString, const char *pszDelimiter, int nCSLTFlags) CPL_WARN_UNUSED_RESULT
Definition: cpl_string.cpp:814
char CPL_DLL * CPLBinaryToHex(int nBytes, const GByte *pabyData) CPL_WARN_UNUSED_RESULT
Definition: cpl_string.cpp:2414
int CPL_DLL CSLFindName(char **papszStrList, const char *pszName)
Definition: cpl_string.cpp:1666
void CPL_DLL CSLSetNameValueSeparator(char **papszStrList, const char *pszSeparator)
Definition: cpl_string.cpp:1910
char CPL_DLL * CPLRecodeFromWChar(const wchar_t *pwszSource, const char *pszSrcEncoding, const char *pszDstEncoding) CPL_WARN_UNUSED_RESULT
Definition: cpl_recode.cpp:142