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

Generated for GDAL by doxygen 1.8.6.