SDTS_AL
cpl_string.h
Go to the documentation of this file.
1 /**********************************************************************
2  * $Id: cpl_string.h 24556 2012-06-10 09:50:10Z 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 void CPL_DLL CPLClearRecodeWarningFlags();
168 char CPL_DLL *CPLRecode( const char *pszSource,
169  const char *pszSrcEncoding,
170  const char *pszDstEncoding ) CPL_WARN_UNUSED_RESULT;
171 char CPL_DLL *CPLRecodeFromWChar( const wchar_t *pwszSource,
172  const char *pszSrcEncoding,
173  const char *pszDstEncoding ) CPL_WARN_UNUSED_RESULT;
174 wchar_t CPL_DLL *CPLRecodeToWChar( const char *pszSource,
175  const char *pszSrcEncoding,
176  const char *pszDstEncoding ) CPL_WARN_UNUSED_RESULT;
177 int CPL_DLL CPLIsUTF8(const char* pabyData, int nLen);
178 char CPL_DLL *CPLForceToASCII(const char* pabyData, int nLen, char chReplacementChar) CPL_WARN_UNUSED_RESULT;
179 
180 CPL_C_END
181 
182 /************************************************************************/
183 /* CPLString */
184 /************************************************************************/
185 
186 #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
187 
188 #include <string>
189 
190 /*
191  * Simple trick to avoid "using" declaration in header for new compilers
192  * but make it still working with old compilers which throw C2614 errors.
193  *
194  * Define MSVC_OLD_STUPID_BEHAVIOUR
195  * for old compilers: VC++ 5 and 6 as well as eVC++ 3 and 4.
196  */
197 
198 /*
199  * Detect old MSVC++ compiler <= 6.0
200  * 1200 - VC++ 6.0
201  * 1200-1202 - eVC++ 4.0
202  */
203 #if defined(_MSC_VER)
204 # if (_MSC_VER <= 1202)
205 # define MSVC_OLD_STUPID_BEHAVIOUR
206 # endif
207 #endif
208 
209 /* Avoid C2614 errors */
210 #ifdef MSVC_OLD_STUPID_BEHAVIOUR
211  using std::string;
212 # define gdal_std_string string
213 #else
214 # define gdal_std_string std::string
215 #endif
216 
217 /* Remove annoying warnings in Microsoft eVC++ and Microsoft Visual C++ */
218 #if defined(WIN32CE)
219 # pragma warning(disable:4251 4275 4786)
220 #endif
221 
223 class CPL_DLL CPLString : public gdal_std_string
224 {
225 public:
226 
227 
228  CPLString(void) {}
229  CPLString( const std::string &oStr ) : gdal_std_string( oStr ) {}
230  CPLString( const char *pszStr ) : gdal_std_string( pszStr ) {}
231 
232  operator const char* (void) const { return c_str(); }
233 
234  char& operator[](std::string::size_type i)
235  {
236  return gdal_std_string::operator[](i);
237  }
238 
239  const char& operator[](std::string::size_type i) const
240  {
241  return gdal_std_string::operator[](i);
242  }
243 
244  char& operator[](int i)
245  {
246  return gdal_std_string::operator[](static_cast<std::string::size_type>(i));
247  }
248 
249  const char& operator[](int i) const
250  {
251  return gdal_std_string::operator[](static_cast<std::string::size_type>(i));
252  }
253 
254  void Clear() { resize(0); }
255 
256  /* There seems to be a bug in the way the compiler count indices... Should be CPL_PRINT_FUNC_FORMAT (1, 2) */
257  CPLString &Printf( const char *pszFormat, ... ) CPL_PRINT_FUNC_FORMAT (2, 3);
258  CPLString &vPrintf( const char *pszFormat, va_list args );
259  CPLString &FormatC( double dfValue, const char *pszFormat = NULL );
260  CPLString &Trim();
261  CPLString &Recode( const char *pszSrcEncoding, const char *pszDstEncoding );
262 
263  /* case insensitive find alternates */
264  size_t ifind( const std::string & str, size_t pos = 0 ) const;
265  size_t ifind( const char * s, size_t pos = 0 ) const;
266  CPLString &toupper( void );
267  CPLString &tolower( void );
268 };
269 
270 /* -------------------------------------------------------------------- */
271 /* URL processing functions, here since they depend on CPLString. */
272 /* -------------------------------------------------------------------- */
273 CPLString CPL_DLL CPLURLGetValue(const char* pszURL, const char* pszKey);
274 CPLString CPL_DLL CPLURLAddKVP(const char* pszURL, const char* pszKey,
275  const char* pszValue);
276 
277 /************************************************************************/
278 /* CPLStringList */
279 /************************************************************************/
280 
282 class CPL_DLL CPLStringList
283 {
284  char **papszList;
285  mutable int nCount;
286  mutable int nAllocation;
287  int bOwnList;
288  int bIsSorted;
289 
290  void Initialize();
291  void MakeOurOwnCopy();
292  void EnsureAllocation( int nMaxLength );
293  int FindSortedInsertionPoint( const char *pszLine );
294 
295  public:
296  CPLStringList();
297  CPLStringList( char **papszList, int bTakeOwnership=TRUE );
298  CPLStringList( const CPLStringList& oOther );
299  ~CPLStringList();
300 
301  CPLStringList &Clear();
302 
303  int size() const { return Count(); }
304  int Count() const;
305 
306  CPLStringList &AddString( const char *pszNewString );
307  CPLStringList &AddStringDirectly( char *pszNewString );
308 
309  CPLStringList &InsertString( int nInsertAtLineNo, const char *pszNewLine )
310  { return InsertStringDirectly( nInsertAtLineNo, CPLStrdup(pszNewLine) ); }
311  CPLStringList &InsertStringDirectly( int nInsertAtLineNo, char *pszNewLine);
312 
313 // CPLStringList &InsertStrings( int nInsertAtLineNo, char **papszNewLines );
314 // CPLStringList &RemoveStrings( int nFirstLineToDelete, int nNumToRemove=1 );
315 
316  int FindString( const char *pszTarget ) const
317  { return CSLFindString( papszList, pszTarget ); }
318  int PartialFindString( const char *pszNeedle ) const
319  { return CSLPartialFindString( papszList, pszNeedle ); }
320 
321  int FindName( const char *pszName ) const;
322  int FetchBoolean( const char *pszKey, int bDefault ) const;
323  const char *FetchNameValue( const char *pszKey ) const;
324  const char *FetchNameValueDef( const char *pszKey, const char *pszDefault ) const;
325  CPLStringList &AddNameValue( const char *pszKey, const char *pszValue );
326  CPLStringList &SetNameValue( const char *pszKey, const char *pszValue );
327 
328  CPLStringList &Assign( char **papszList, int bTakeOwnership=TRUE );
329  CPLStringList &operator=(char **papszListIn) { return Assign( papszListIn, TRUE ); }
330  CPLStringList &operator=(const CPLStringList& oOther);
331 
332  char * operator[](int i);
333  char * operator[](size_t i) { return (*this)[(int)i]; }
334  const char * operator[](int i) const;
335  const char * operator[](size_t i) const { return (*this)[(int)i]; }
336 
337  char **List() { return papszList; }
338  char **StealList();
339 
340  CPLStringList &Sort();
341  int IsSorted() const { return bIsSorted; }
342 
343  operator char**(void) { return List(); }
344 };
345 
346 #endif /* def __cplusplus && !CPL_SUPRESS_CPLUSPLUS */
347 
348 #endif /* _CPL_STRING_H_INCLUDED */