OGR
cpl_string.h
Go to the documentation of this file.
1 /**********************************************************************
2  * $Id: cpl_string.h 23431 2011-11-27 15:02:24Z 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  *
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 /* unescape only for now */
128 #define CPLES_SQL 3
129 #define CPLES_CSV 4
130 
131 char CPL_DLL *CPLEscapeString( const char *pszString, int nLength,
132  int nScheme ) CPL_WARN_UNUSED_RESULT;
133 char CPL_DLL *CPLUnescapeString( const char *pszString, int *pnLength,
134  int nScheme ) CPL_WARN_UNUSED_RESULT;
135 
136 char CPL_DLL *CPLBinaryToHex( int nBytes, const GByte *pabyData ) CPL_WARN_UNUSED_RESULT;
137 GByte CPL_DLL *CPLHexToBinary( const char *pszHex, int *pnBytes ) CPL_WARN_UNUSED_RESULT;
138 
139 char CPL_DLL *CPLBase64Encode( int nBytes, const GByte *pabyData ) CPL_WARN_UNUSED_RESULT;
140 int CPL_DLL CPLBase64DecodeInPlace(GByte* pszBase64);
141 
142 typedef enum
143 {
144  CPL_VALUE_STRING,
145  CPL_VALUE_REAL,
146  CPL_VALUE_INTEGER
147 } CPLValueType;
148 
149 CPLValueType CPL_DLL CPLGetValueType(const char* pszValue);
150 
151 size_t CPL_DLL CPLStrlcpy(char* pszDest, const char* pszSrc, size_t nDestSize);
152 size_t CPL_DLL CPLStrlcat(char* pszDest, const char* pszSrc, size_t nDestSize);
153 size_t CPL_DLL CPLStrnlen (const char *pszStr, size_t nMaxLen);
154 
155 /* -------------------------------------------------------------------- */
156 /* RFC 23 character set conversion/recoding API (cpl_recode.cpp). */
157 /* -------------------------------------------------------------------- */
158 #define CPL_ENC_LOCALE ""
159 #define CPL_ENC_UTF8 "UTF-8"
160 #define CPL_ENC_UTF16 "UTF-16"
161 #define CPL_ENC_UCS2 "UCS-2"
162 #define CPL_ENC_UCS4 "UCS-4"
163 #define CPL_ENC_ASCII "ASCII"
164 #define CPL_ENC_ISO8859_1 "ISO-8859-1"
165 
166 int CPL_DLL CPLEncodingCharSize( const char *pszEncoding );
167 char CPL_DLL *CPLRecode( const char *pszSource,
168  const char *pszSrcEncoding,
169  const char *pszDstEncoding ) CPL_WARN_UNUSED_RESULT;
170 char CPL_DLL *CPLRecodeFromWChar( const wchar_t *pwszSource,
171  const char *pszSrcEncoding,
172  const char *pszDstEncoding ) CPL_WARN_UNUSED_RESULT;
173 wchar_t CPL_DLL *CPLRecodeToWChar( const char *pszSource,
174  const char *pszSrcEncoding,
175  const char *pszDstEncoding ) CPL_WARN_UNUSED_RESULT;
176 int CPL_DLL CPLIsUTF8(const char* pabyData, int nLen);
177 char CPL_DLL *CPLForceToASCII(const char* pabyData, int nLen, char chReplacementChar) CPL_WARN_UNUSED_RESULT;
178 
179 CPL_C_END
180 
181 /************************************************************************/
182 /* CPLString */
183 /************************************************************************/
184 
185 #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
186 
187 #include <string>
188 
189 /*
190  * Simple trick to avoid "using" declaration in header for new compilers
191  * but make it still working with old compilers which throw C2614 errors.
192  *
193  * Define MSVC_OLD_STUPID_BEHAVIOUR
194  * for old compilers: VC++ 5 and 6 as well as eVC++ 3 and 4.
195  */
196 
197 /*
198  * Detect old MSVC++ compiler <= 6.0
199  * 1200 - VC++ 6.0
200  * 1200-1202 - eVC++ 4.0
201  */
202 #if defined(_MSC_VER)
203 # if (_MSC_VER <= 1202)
204 # define MSVC_OLD_STUPID_BEHAVIOUR
205 # endif
206 #endif
207 
208 /* Avoid C2614 errors */
209 #ifdef MSVC_OLD_STUPID_BEHAVIOUR
210  using std::string;
211 # define gdal_std_string string
212 #else
213 # define gdal_std_string std::string
214 #endif
215 
216 /* Remove annoying warnings in Microsoft eVC++ and Microsoft Visual C++ */
217 #if defined(WIN32CE)
218 # pragma warning(disable:4251 4275 4786)
219 #endif
220 
222 class CPL_DLL CPLString : public gdal_std_string
223 {
224 public:
225 
226 
227  CPLString(void) {}
228  CPLString( const std::string &oStr ) : gdal_std_string( oStr ) {}
229  CPLString( const char *pszStr ) : gdal_std_string( pszStr ) {}
230 
231  operator const char* (void) const { return c_str(); }
232 
233  char& operator[](std::string::size_type i)
234  {
235  return gdal_std_string::operator[](i);
236  }
237 
238  const char& operator[](std::string::size_type i) const
239  {
240  return gdal_std_string::operator[](i);
241  }
242 
243  char& operator[](int i)
244  {
245  return gdal_std_string::operator[](static_cast<std::string::size_type>(i));
246  }
247 
248  const char& operator[](int i) const
249  {
250  return gdal_std_string::operator[](static_cast<std::string::size_type>(i));
251  }
252 
253  void Clear() { resize(0); }
254 
255  /* There seems to be a bug in the way the compiler count indices... Should be CPL_PRINT_FUNC_FORMAT (1, 2) */
256  CPLString &Printf( const char *pszFormat, ... ) CPL_PRINT_FUNC_FORMAT (2, 3);
257  CPLString &vPrintf( const char *pszFormat, va_list args );
258  CPLString &FormatC( double dfValue, const char *pszFormat = NULL );
259  CPLString &Trim();
260  CPLString &Recode( const char *pszSrcEncoding, const char *pszDstEncoding );
261 
262  /* case insensitive find alternates */
263  size_t ifind( const std::string & str, size_t pos = 0 ) const;
264  size_t ifind( const char * s, size_t pos = 0 ) const;
265  CPLString &toupper( void );
266  CPLString &tolower( void );
267 };
268 
269 /* -------------------------------------------------------------------- */
270 /* URL processing functions, here since they depend on CPLString. */
271 /* -------------------------------------------------------------------- */
272 CPLString CPL_DLL CPLURLGetValue(const char* pszURL, const char* pszKey);
273 CPLString CPL_DLL CPLURLAddKVP(const char* pszURL, const char* pszKey,
274  const char* pszValue);
275 
276 /************************************************************************/
277 /* CPLStringList */
278 /************************************************************************/
279 
281 class CPL_DLL CPLStringList
282 {
283  char **papszList;
284  mutable int nCount;
285  mutable int nAllocation;
286  int bOwnList;
287  int bIsSorted;
288 
289  void Initialize();
290  void MakeOurOwnCopy();
291  void EnsureAllocation( int nMaxLength );
292  int FindSortedInsertionPoint( const char *pszLine );
293 
294  public:
295  CPLStringList();
296  CPLStringList( char **papszList, int bTakeOwnership=TRUE );
297  CPLStringList( const CPLStringList& oOther );
298  ~CPLStringList();
299 
300  CPLStringList &Clear();
301 
302  int size() const { return Count(); }
303  int Count() const;
304 
305  CPLStringList &AddString( const char *pszNewString );
306  CPLStringList &AddStringDirectly( char *pszNewString );
307 
308  CPLStringList &InsertString( int nInsertAtLineNo, const char *pszNewLine )
309  { return InsertStringDirectly( nInsertAtLineNo, CPLStrdup(pszNewLine) ); }
310  CPLStringList &InsertStringDirectly( int nInsertAtLineNo, char *pszNewLine);
311 
312 // CPLStringList &InsertStrings( int nInsertAtLineNo, char **papszNewLines );
313 // CPLStringList &RemoveStrings( int nFirstLineToDelete, int nNumToRemove=1 );
314 
315  int FindString( const char *pszTarget ) const
316  { return CSLFindString( papszList, pszTarget ); }
317  int PartialFindString( const char *pszNeedle ) const
318  { return CSLPartialFindString( papszList, pszNeedle ); }
319 
320  int FindName( const char *pszName ) const;
321  int FetchBoolean( const char *pszKey, int bDefault ) const;
322  const char *FetchNameValue( const char *pszKey ) const;
323  const char *FetchNameValueDef( const char *pszKey, const char *pszDefault ) const;
324  CPLStringList &AddNameValue( const char *pszKey, const char *pszValue );
325  CPLStringList &SetNameValue( const char *pszKey, const char *pszValue );
326 
327  CPLStringList &Assign( char **papszList, int bTakeOwnership=TRUE );
328  CPLStringList &operator=(char **papszListIn) { return Assign( papszListIn, TRUE ); }
329  CPLStringList &operator=(const CPLStringList& oOther);
330 
331  char * operator[](int i);
332  char * operator[](size_t i) { return (*this)[(int)i]; }
333  const char * operator[](int i) const;
334  const char * operator[](size_t i) const { return (*this)[(int)i]; }
335 
336  char **List() { return papszList; }
337  char **StealList();
338 
339  CPLStringList &Sort();
340  int IsSorted() const { return bIsSorted; }
341 
342  operator char**(void) { return List(); }
343 };
344 
345 #endif /* def __cplusplus && !CPL_SUPRESS_CPLUSPLUS */
346 
347 #endif /* _CPL_STRING_H_INCLUDED */

Generated for GDAL by doxygen 1.8.2.