OGR
cpl_string.h
Go to the documentation of this file.
1 /**********************************************************************
2  * $Id: cpl_string.h 27044 2014-03-16 23:41:27Z rouault $
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_vsi.h"
36 #include "cpl_error.h"
37 #include "cpl_conv.h"
38 
61 CPL_C_START
62 
63 char CPL_DLL **CSLAddString(char **papszStrList, const char *pszNewString) CPL_WARN_UNUSED_RESULT;
64 int CPL_DLL CSLCount(char **papszStrList);
65 const char CPL_DLL *CSLGetField( char **, int );
66 void CPL_DLL CPL_STDCALL CSLDestroy(char **papszStrList);
67 char CPL_DLL **CSLDuplicate(char **papszStrList) CPL_WARN_UNUSED_RESULT;
68 char CPL_DLL **CSLMerge( char **papszOrig, char **papszOverride ) CPL_WARN_UNUSED_RESULT;
69 
70 char CPL_DLL **CSLTokenizeString(const char *pszString ) CPL_WARN_UNUSED_RESULT;
71 char CPL_DLL **CSLTokenizeStringComplex(const char *pszString,
72  const char *pszDelimiter,
73  int bHonourStrings, int bAllowEmptyTokens ) CPL_WARN_UNUSED_RESULT;
74 char CPL_DLL **CSLTokenizeString2( const char *pszString,
75  const char *pszDelimeter,
76  int nCSLTFlags ) CPL_WARN_UNUSED_RESULT;
77 
78 #define CSLT_HONOURSTRINGS 0x0001
79 #define CSLT_ALLOWEMPTYTOKENS 0x0002
80 #define CSLT_PRESERVEQUOTES 0x0004
81 #define CSLT_PRESERVEESCAPES 0x0008
82 #define CSLT_STRIPLEADSPACES 0x0010
83 #define CSLT_STRIPENDSPACES 0x0020
84 
85 int CPL_DLL CSLPrint(char **papszStrList, FILE *fpOut);
86 char CPL_DLL **CSLLoad(const char *pszFname) CPL_WARN_UNUSED_RESULT;
87 char CPL_DLL **CSLLoad2(const char *pszFname, int nMaxLines, int nMaxCols, char** papszOptions) CPL_WARN_UNUSED_RESULT;
88 int CPL_DLL CSLSave(char **papszStrList, const char *pszFname);
89 
90 char CPL_DLL **CSLInsertStrings(char **papszStrList, int nInsertAtLineNo,
91  char **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 **CSLRemoveStrings(char **papszStrList, int nFirstLineToDelete,
95  int nNumToRemove, char ***ppapszRetStrings) CPL_WARN_UNUSED_RESULT;
96 int CPL_DLL CSLFindString( char **, const char * );
97 int CPL_DLL CSLPartialFindString( char **papszHaystack,
98  const char * pszNeedle );
99 int CPL_DLL CSLFindName(char **papszStrList, const char *pszName);
100 int CPL_DLL CSLTestBoolean( const char *pszValue );
101 int CPL_DLL CSLFetchBoolean( char **papszStrList, const char *pszKey,
102  int bDefault );
103 
104 const char CPL_DLL *CPLSPrintf(const char *fmt, ...) CPL_PRINT_FUNC_FORMAT(1, 2);
105 char CPL_DLL **CSLAppendPrintf(char **papszStrList, const char *fmt, ...) CPL_PRINT_FUNC_FORMAT(2, 3) CPL_WARN_UNUSED_RESULT;
106 int CPL_DLL CPLVASPrintf(char **buf, const char *fmt, va_list args );
107 
108 const char CPL_DLL *
109  CPLParseNameValue(const char *pszNameValue, char **ppszKey );
110 const char CPL_DLL *
111  CSLFetchNameValue(char **papszStrList, const char *pszName);
112 const char CPL_DLL *
113  CSLFetchNameValueDef(char **papszStrList, const char *pszName,
114  const char *pszDefault );
115 char CPL_DLL **
116  CSLFetchNameValueMultiple(char **papszStrList, const char *pszName);
117 char CPL_DLL **
118  CSLAddNameValue(char **papszStrList,
119  const char *pszName, const char *pszValue) CPL_WARN_UNUSED_RESULT;
120 char CPL_DLL **
121  CSLSetNameValue(char **papszStrList,
122  const char *pszName, const char *pszValue) CPL_WARN_UNUSED_RESULT;
123 void CPL_DLL CSLSetNameValueSeparator( char ** papszStrList,
124  const char *pszSeparator );
125 
126 #define CPLES_BackslashQuotable 0
127 #define CPLES_XML 1
128 #define CPLES_URL 2
129 #define CPLES_SQL 3
130 #define CPLES_CSV 4
131 #define CPLES_XML_BUT_QUOTES 5
132 
133 char CPL_DLL *CPLEscapeString( const char *pszString, int nLength,
134  int nScheme ) CPL_WARN_UNUSED_RESULT;
135 char CPL_DLL *CPLUnescapeString( const char *pszString, int *pnLength,
136  int nScheme ) CPL_WARN_UNUSED_RESULT;
137 
138 char CPL_DLL *CPLBinaryToHex( int nBytes, const GByte *pabyData ) CPL_WARN_UNUSED_RESULT;
139 GByte CPL_DLL *CPLHexToBinary( const char *pszHex, int *pnBytes ) CPL_WARN_UNUSED_RESULT;
140 
141 char CPL_DLL *CPLBase64Encode( int nBytes, const GByte *pabyData ) CPL_WARN_UNUSED_RESULT;
142 int CPL_DLL CPLBase64DecodeInPlace(GByte* pszBase64);
143 
144 typedef enum
145 {
146  CPL_VALUE_STRING,
147  CPL_VALUE_REAL,
148  CPL_VALUE_INTEGER
149 } CPLValueType;
150 
151 CPLValueType CPL_DLL CPLGetValueType(const char* pszValue);
152 
153 size_t CPL_DLL CPLStrlcpy(char* pszDest, const char* pszSrc, size_t nDestSize);
154 size_t CPL_DLL CPLStrlcat(char* pszDest, const char* pszSrc, size_t nDestSize);
155 size_t CPL_DLL CPLStrnlen (const char *pszStr, size_t nMaxLen);
156 
157 /* -------------------------------------------------------------------- */
158 /* RFC 23 character set conversion/recoding API (cpl_recode.cpp). */
159 /* -------------------------------------------------------------------- */
160 #define CPL_ENC_LOCALE ""
161 #define CPL_ENC_UTF8 "UTF-8"
162 #define CPL_ENC_UTF16 "UTF-16"
163 #define CPL_ENC_UCS2 "UCS-2"
164 #define CPL_ENC_UCS4 "UCS-4"
165 #define CPL_ENC_ASCII "ASCII"
166 #define CPL_ENC_ISO8859_1 "ISO-8859-1"
167 
168 int CPL_DLL CPLEncodingCharSize( const char *pszEncoding );
169 void CPL_DLL CPLClearRecodeWarningFlags( void );
170 char CPL_DLL *CPLRecode( const char *pszSource,
171  const char *pszSrcEncoding,
172  const char *pszDstEncoding ) CPL_WARN_UNUSED_RESULT;
173 char CPL_DLL *CPLRecodeFromWChar( const wchar_t *pwszSource,
174  const char *pszSrcEncoding,
175  const char *pszDstEncoding ) CPL_WARN_UNUSED_RESULT;
176 wchar_t CPL_DLL *CPLRecodeToWChar( const char *pszSource,
177  const char *pszSrcEncoding,
178  const char *pszDstEncoding ) CPL_WARN_UNUSED_RESULT;
179 int CPL_DLL CPLIsUTF8(const char* pabyData, int nLen);
180 char CPL_DLL *CPLForceToASCII(const char* pabyData, int nLen, char chReplacementChar) CPL_WARN_UNUSED_RESULT;
181 int CPL_DLL CPLStrlenUTF8(const char *pszUTF8Str);
182 
183 CPL_C_END
184 
185 /************************************************************************/
186 /* CPLString */
187 /************************************************************************/
188 
189 #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
190 
191 #include <string>
192 
193 /*
194  * Simple trick to avoid "using" declaration in header for new compilers
195  * but make it still working with old compilers which throw C2614 errors.
196  *
197  * Define MSVC_OLD_STUPID_BEHAVIOUR
198  * for old compilers: VC++ 5 and 6 as well as eVC++ 3 and 4.
199  */
200 
201 /*
202  * Detect old MSVC++ compiler <= 6.0
203  * 1200 - VC++ 6.0
204  * 1200-1202 - eVC++ 4.0
205  */
206 #if defined(_MSC_VER)
207 # if (_MSC_VER <= 1202)
208 # define MSVC_OLD_STUPID_BEHAVIOUR
209 # endif
210 #endif
211 
212 /* Avoid C2614 errors */
213 #ifdef MSVC_OLD_STUPID_BEHAVIOUR
214  using std::string;
215 # define gdal_std_string string
216 #else
217 # define gdal_std_string std::string
218 #endif
219 
220 /* Remove annoying warnings in Microsoft eVC++ and Microsoft Visual C++ */
221 #if defined(WIN32CE)
222 # pragma warning(disable:4251 4275 4786)
223 #endif
224 
226 class CPL_DLL CPLString : public gdal_std_string
227 {
228 public:
229 
230 
231  CPLString(void) {}
232  CPLString( const std::string &oStr ) : gdal_std_string( oStr ) {}
233  CPLString( const char *pszStr ) : gdal_std_string( pszStr ) {}
234 
235  operator const char* (void) const { return c_str(); }
236 
237  char& operator[](std::string::size_type i)
238  {
239  return gdal_std_string::operator[](i);
240  }
241 
242  const char& operator[](std::string::size_type i) const
243  {
244  return gdal_std_string::operator[](i);
245  }
246 
247  char& operator[](int i)
248  {
249  return gdal_std_string::operator[](static_cast<std::string::size_type>(i));
250  }
251 
252  const char& operator[](int i) const
253  {
254  return gdal_std_string::operator[](static_cast<std::string::size_type>(i));
255  }
256 
257  void Clear() { resize(0); }
258 
259  // NULL safe assign and free.
260  void Seize(char *pszValue)
261  {
262  if (pszValue == NULL )
263  Clear();
264  else
265  {
266  *this = pszValue;
267  CPLFree(pszValue);
268  }
269  }
270 
271  /* There seems to be a bug in the way the compiler count indices... Should be CPL_PRINT_FUNC_FORMAT (1, 2) */
272  CPLString &Printf( const char *pszFormat, ... ) CPL_PRINT_FUNC_FORMAT (2, 3);
273  CPLString &vPrintf( const char *pszFormat, va_list args );
274  CPLString &FormatC( double dfValue, const char *pszFormat = NULL );
275  CPLString &Trim();
276  CPLString &Recode( const char *pszSrcEncoding, const char *pszDstEncoding );
277 
278  /* case insensitive find alternates */
279  size_t ifind( const std::string & str, size_t pos = 0 ) const;
280  size_t ifind( const char * s, size_t pos = 0 ) const;
281  CPLString &toupper( void );
282  CPLString &tolower( void );
283 };
284 
285 CPLString CPLOPrintf(const char *pszFormat, ... ) CPL_PRINT_FUNC_FORMAT (1, 2);
286 CPLString CPLOvPrintf(const char *pszFormat, va_list args);
287 
288 /* -------------------------------------------------------------------- */
289 /* URL processing functions, here since they depend on CPLString. */
290 /* -------------------------------------------------------------------- */
291 CPLString CPL_DLL CPLURLGetValue(const char* pszURL, const char* pszKey);
292 CPLString CPL_DLL CPLURLAddKVP(const char* pszURL, const char* pszKey,
293  const char* pszValue);
294 
295 /************************************************************************/
296 /* CPLStringList */
297 /************************************************************************/
298 
300 class CPL_DLL CPLStringList
301 {
302  char **papszList;
303  mutable int nCount;
304  mutable int nAllocation;
305  int bOwnList;
306  int bIsSorted;
307 
308  void Initialize();
309  void MakeOurOwnCopy();
310  void EnsureAllocation( int nMaxLength );
311  int FindSortedInsertionPoint( const char *pszLine );
312 
313  public:
314  CPLStringList();
315  CPLStringList( char **papszList, int bTakeOwnership=TRUE );
316  CPLStringList( const CPLStringList& oOther );
317  ~CPLStringList();
318 
319  CPLStringList &Clear();
320 
321  int size() const { return Count(); }
322  int Count() const;
323 
324  CPLStringList &AddString( const char *pszNewString );
325  CPLStringList &AddStringDirectly( char *pszNewString );
326 
327  CPLStringList &InsertString( int nInsertAtLineNo, const char *pszNewLine )
328  { return InsertStringDirectly( nInsertAtLineNo, CPLStrdup(pszNewLine) ); }
329  CPLStringList &InsertStringDirectly( int nInsertAtLineNo, char *pszNewLine);
330 
331 // CPLStringList &InsertStrings( int nInsertAtLineNo, char **papszNewLines );
332 // CPLStringList &RemoveStrings( int nFirstLineToDelete, int nNumToRemove=1 );
333 
334  int FindString( const char *pszTarget ) const
335  { return CSLFindString( papszList, pszTarget ); }
336  int PartialFindString( const char *pszNeedle ) const
337  { return CSLPartialFindString( papszList, pszNeedle ); }
338 
339  int FindName( const char *pszName ) const;
340  int FetchBoolean( const char *pszKey, int bDefault ) const;
341  const char *FetchNameValue( const char *pszKey ) const;
342  const char *FetchNameValueDef( const char *pszKey, const char *pszDefault ) const;
343  CPLStringList &AddNameValue( const char *pszKey, const char *pszValue );
344  CPLStringList &SetNameValue( const char *pszKey, const char *pszValue );
345 
346  CPLStringList &Assign( char **papszList, int bTakeOwnership=TRUE );
347  CPLStringList &operator=(char **papszListIn) { return Assign( papszListIn, TRUE ); }
348  CPLStringList &operator=(const CPLStringList& oOther);
349 
350  char * operator[](int i);
351  char * operator[](size_t i) { return (*this)[(int)i]; }
352  const char * operator[](int i) const;
353  const char * operator[](size_t i) const { return (*this)[(int)i]; }
354 
355  char **List() { return papszList; }
356  char **StealList();
357 
358  CPLStringList &Sort();
359  int IsSorted() const { return bIsSorted; }
360 
361  operator char**(void) { return List(); }
362 };
363 
364 #endif /* def __cplusplus && !CPL_SUPRESS_CPLUSPLUS */
365 
366 #endif /* _CPL_STRING_H_INCLUDED */
int CPLEncodingCharSize(const char *pszEncoding)
Definition: cpl_recode.cpp:309
size_t CPLStrlcat(char *pszDest, const char *pszSrc, size_t nDestSize)
Definition: cpl_string.cpp:2151
int CSLTestBoolean(const char *pszValue)
Definition: cpl_string.cpp:1039
char * CPLForceToASCII(const char *pabyData, int nLen, char chReplacementChar)
Definition: cpl_recode.cpp:268
char * CPLRecodeFromWChar(const wchar_t *pwszSource, const char *pszSrcEncoding, const char *pszDstEncoding)
Definition: cpl_recode.cpp:142
char * CPLEscapeString(const char *pszString, int nLength, int nScheme)
Definition: cpl_string.cpp:1479
CPLString CPLURLGetValue(const char *pszURL, const char *pszKey)
Definition: cplstring.cpp:342
int CSLFindName(char **papszStrList, const char *pszName)
Definition: cpl_string.cpp:1149
Convenient string class based on std::string.
Definition: cpl_string.h:226
wchar_t * CPLRecodeToWChar(const char *pszSource, const char *pszSrcEncoding, const char *pszDstEncoding)
Definition: cpl_recode.cpp:201
char * CPLUnescapeString(const char *pszString, int *pnLength, int nScheme)
Definition: cpl_string.cpp:1675
size_t CPLStrlcpy(char *pszDest, const char *pszSrc, size_t nDestSize)
Definition: cpl_string.cpp:2097
int CSLPartialFindString(char **papszHaystack, const char *pszNeedle)
Definition: cpl_string.cpp:685
char * CPLRecode(const char *pszSource, const char *pszSrcEncoding, const char *pszDstEncoding)
Definition: cpl_recode.cpp:74
void CSLSetNameValueSeparator(char **papszStrList, const char *pszSeparator)
Definition: cpl_string.cpp:1406
char ** CSLTokenizeString2(const char *pszString, const char *pszDelimeter, int nCSLTFlags)
Definition: cpl_string.cpp:788
char ** CSLDuplicate(char **papszStrList)
Definition: cpl_string.cpp:204
char * CPLBinaryToHex(int nBytes, const GByte *pabyData)
Definition: cpl_string.cpp:1880
String list class designed around our use of C "char**" string lists.
Definition: cpl_string.h:300
char ** CSLMerge(char **papszOrig, char **papszOverride)
Merge two lists.
Definition: cpl_string.cpp:247
CPLValueType CPLGetValueType(const char *pszValue)
Definition: cpl_string.cpp:1982
size_t CPLStrnlen(const char *pszStr, size_t nMaxLen)
Definition: cpl_string.cpp:2186
CPLStringList & InsertString(int nInsertAtLineNo, const char *pszNewLine)
Insert into the list at identified location.
Definition: cpl_string.h:327
CPLString CPLURLAddKVP(const char *pszURL, const char *pszKey, const char *pszValue)
Definition: cplstring.cpp:375
int CSLCount(char **papszStrList)
Definition: cpl_string.cpp:117
char ** CSLLoad2(const char *pszFname, int nMaxLines, int nMaxCols, char **papszOptions)
Definition: cpl_string.cpp:294
char ** CSLLoad(const char *pszFname)
Definition: cpl_string.cpp:373
char ** CSLSetNameValue(char **papszStrList, const char *pszName, const char *pszValue)
Definition: cpl_string.cpp:1323
const char * CPLParseNameValue(const char *pszNameValue, char **ppszKey)
Definition: cpl_string.cpp:1196
void CSLDestroy(char **papszStrList)
Definition: cpl_string.cpp:172
int CPLIsUTF8(const char *pabyData, int nLen)
Definition: cpl_recode.cpp:244
char * CPLStrdup(const char *)
Definition: cpl_conv.cpp:247
int CPLStrlenUTF8(const char *pszUTF8Str)
Definition: cpl_recode.cpp:355
int CSLFindString(char **, const char *)
Definition: cpl_string.cpp:651

Generated for GDAL by doxygen 1.8.11.