SDTS_AL
cpl_conv.h
Go to the documentation of this file.
1 /******************************************************************************
2  * $Id: cpl_conv.h 33666 2016-03-07 05:21:07Z goatbar $
3  *
4  * Project: CPL - Common Portability Library
5  * Purpose: Convenience functions declarations.
6  * This is intended to remain light weight.
7  * Author: Frank Warmerdam, warmerdam@pobox.com
8  *
9  ******************************************************************************
10  * Copyright (c) 1998, Frank Warmerdam
11  * Copyright (c) 2007-2013, 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
24  * OR 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_CONV_H_INCLUDED
33 #define CPL_CONV_H_INCLUDED
34 
35 #include "cpl_port.h"
36 #include "cpl_vsi.h"
37 #include "cpl_error.h"
38 
46 /* -------------------------------------------------------------------- */
47 /* Runtime check of various configuration items. */
48 /* -------------------------------------------------------------------- */
49 CPL_C_START
50 
51 void CPL_DLL CPLVerifyConfiguration(void);
52 
53 const char CPL_DLL * CPL_STDCALL
54 CPLGetConfigOption( const char *, const char * ) CPL_WARN_UNUSED_RESULT;
55 const char CPL_DLL * CPL_STDCALL
56 CPLGetThreadLocalConfigOption( const char *, const char * ) CPL_WARN_UNUSED_RESULT;
57 void CPL_DLL CPL_STDCALL CPLSetConfigOption( const char *, const char * );
58 void CPL_DLL CPL_STDCALL CPLSetThreadLocalConfigOption( const char *pszKey,
59  const char *pszValue );
60 void CPL_DLL CPL_STDCALL CPLFreeConfig(void);
61 
62 /* -------------------------------------------------------------------- */
63 /* Safe malloc() API. Thin cover over VSI functions with fatal */
64 /* error reporting if memory allocation fails. */
65 /* -------------------------------------------------------------------- */
66 void CPL_DLL *CPLMalloc( size_t ) CPL_WARN_UNUSED_RESULT;
67 void CPL_DLL *CPLCalloc( size_t, size_t ) CPL_WARN_UNUSED_RESULT;
68 void CPL_DLL *CPLRealloc( void *, size_t ) CPL_WARN_UNUSED_RESULT;
69 char CPL_DLL *CPLStrdup( const char * ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
70 char CPL_DLL *CPLStrlwr( char *);
71 
72 #define CPLFree VSIFree
73 
74 /* -------------------------------------------------------------------- */
75 /* Read a line from a text file, and strip of CR/LF. */
76 /* -------------------------------------------------------------------- */
77 char CPL_DLL *CPLFGets( char *, int, FILE *);
78 const char CPL_DLL *CPLReadLine( FILE * );
79 const char CPL_DLL *CPLReadLineL( VSILFILE * );
80 const char CPL_DLL *CPLReadLine2L( VSILFILE * , int nMaxCols, char** papszOptions);
81 
82 /* -------------------------------------------------------------------- */
83 /* Convert ASCII string to floating point number */
84 /* (THESE FUNCTIONS ARE NOT LOCALE AWARE!). */
85 /* -------------------------------------------------------------------- */
86 double CPL_DLL CPLAtof(const char *);
87 double CPL_DLL CPLAtofDelim(const char *, char);
88 double CPL_DLL CPLStrtod(const char *, char **);
89 double CPL_DLL CPLStrtodDelim(const char *, char **, char);
90 float CPL_DLL CPLStrtof(const char *, char **);
91 float CPL_DLL CPLStrtofDelim(const char *, char **, char);
92 
93 /* -------------------------------------------------------------------- */
94 /* Convert number to string. This function is locale agnostic */
95 /* (i.e. it will support "," or "." regardless of current locale) */
96 /* -------------------------------------------------------------------- */
97 double CPL_DLL CPLAtofM(const char *);
98 
99 /* -------------------------------------------------------------------- */
100 /* Read a numeric value from an ASCII character string. */
101 /* -------------------------------------------------------------------- */
102 char CPL_DLL *CPLScanString( const char *, int, int, int );
103 double CPL_DLL CPLScanDouble( const char *, int );
104 long CPL_DLL CPLScanLong( const char *, int );
105 unsigned long CPL_DLL CPLScanULong( const char *, int );
106 GUIntBig CPL_DLL CPLScanUIntBig( const char *, int );
107 GIntBig CPL_DLL CPLAtoGIntBig( const char* pszString );
108 GIntBig CPL_DLL CPLAtoGIntBigEx( const char* pszString, int bWarn, int *pbOverflow );
109 void CPL_DLL *CPLScanPointer( const char *, int );
110 
111 /* -------------------------------------------------------------------- */
112 /* Print a value to an ASCII character string. */
113 /* -------------------------------------------------------------------- */
114 int CPL_DLL CPLPrintString( char *, const char *, int );
115 int CPL_DLL CPLPrintStringFill( char *, const char *, int );
116 int CPL_DLL CPLPrintInt32( char *, GInt32 , int );
117 int CPL_DLL CPLPrintUIntBig( char *, GUIntBig , int );
118 int CPL_DLL CPLPrintDouble( char *, const char *, double, const char * );
119 int CPL_DLL CPLPrintTime( char *, int , const char *, const struct tm *,
120  const char * );
121 int CPL_DLL CPLPrintPointer( char *, void *, int );
122 
123 /* -------------------------------------------------------------------- */
124 /* Fetch a function from DLL / so. */
125 /* -------------------------------------------------------------------- */
126 
127 void CPL_DLL *CPLGetSymbol( const char *, const char * );
128 
129 /* -------------------------------------------------------------------- */
130 /* Fetch executable path. */
131 /* -------------------------------------------------------------------- */
132 int CPL_DLL CPLGetExecPath( char *pszPathBuf, int nMaxLength );
133 
134 /* -------------------------------------------------------------------- */
135 /* Filename handling functions. */
136 /* -------------------------------------------------------------------- */
137 const char CPL_DLL *CPLGetPath( const char * ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
138 const char CPL_DLL *CPLGetDirname( const char * ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
139 const char CPL_DLL *CPLGetFilename( const char * ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
140 const char CPL_DLL *CPLGetBasename( const char * ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
141 const char CPL_DLL *CPLGetExtension( const char * ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
142 char CPL_DLL *CPLGetCurrentDir(void);
143 const char CPL_DLL *CPLFormFilename( const char *pszPath,
144  const char *pszBasename,
145  const char *pszExtension ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
146 const char CPL_DLL *CPLFormCIFilename( const char *pszPath,
147  const char *pszBasename,
148  const char *pszExtension ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
149 const char CPL_DLL *CPLResetExtension( const char *, const char * ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
150 const char CPL_DLL *CPLProjectRelativeFilename( const char *pszProjectDir,
151  const char *pszSecondaryFilename ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
152 int CPL_DLL CPLIsFilenameRelative( const char *pszFilename );
153 const char CPL_DLL *CPLExtractRelativePath(const char *, const char *, int *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
154 const char CPL_DLL *CPLCleanTrailingSlash( const char * ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
155 char CPL_DLL **CPLCorrespondingPaths( const char *pszOldFilename,
156  const char *pszNewFilename,
157  char **papszFileList ) CPL_WARN_UNUSED_RESULT;
158 int CPL_DLL CPLCheckForFile( char *pszFilename, char **papszSiblingList );
159 
160 const char CPL_DLL *CPLGenerateTempFilename( const char *pszStem ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
161 
162 /* -------------------------------------------------------------------- */
163 /* Find File Function */
164 /* -------------------------------------------------------------------- */
165 typedef const char *(*CPLFileFinder)(const char *, const char *);
166 
167 const char CPL_DLL *CPLFindFile(const char *pszClass,
168  const char *pszBasename);
169 const char CPL_DLL *CPLDefaultFindFile(const char *pszClass,
170  const char *pszBasename);
171 void CPL_DLL CPLPushFileFinder( CPLFileFinder pfnFinder );
172 CPLFileFinder CPL_DLL CPLPopFileFinder(void);
173 void CPL_DLL CPLPushFinderLocation( const char * );
174 void CPL_DLL CPLPopFinderLocation(void);
175 void CPL_DLL CPLFinderClean(void);
176 
177 /* -------------------------------------------------------------------- */
178 /* Safe version of stat() that works properly on stuff like "C:". */
179 /* -------------------------------------------------------------------- */
180 int CPL_DLL CPLStat( const char *, VSIStatBuf * ) CPL_WARN_UNUSED_RESULT;
181 
182 /* -------------------------------------------------------------------- */
183 /* Reference counted file handle manager. Makes sharing file */
184 /* handles more practical. */
185 /* -------------------------------------------------------------------- */
186 typedef struct {
187  FILE *fp;
188  int nRefCount;
189  int bLarge;
190  char *pszFilename;
191  char *pszAccess;
193 
194 FILE CPL_DLL *CPLOpenShared( const char *, const char *, int );
195 void CPL_DLL CPLCloseShared( FILE * );
196 CPLSharedFileInfo CPL_DLL *CPLGetSharedList( int * );
197 void CPL_DLL CPLDumpSharedList( FILE * );
198 void CPL_DLL CPLCleanupSharedFileMutex( void );
199 
200 /* -------------------------------------------------------------------- */
201 /* DMS to Dec to DMS conversion. */
202 /* -------------------------------------------------------------------- */
203 double CPL_DLL CPLDMSToDec( const char *is );
204 const char CPL_DLL *CPLDecToDMS( double dfAngle, const char * pszAxis,
205  int nPrecision );
206 double CPL_DLL CPLPackedDMSToDec( double );
207 double CPL_DLL CPLDecToPackedDMS( double dfDec );
208 
209 void CPL_DLL CPLStringToComplex( const char *pszString,
210  double *pdfReal, double *pdfImag );
211 
212 /* -------------------------------------------------------------------- */
213 /* Misc other functions. */
214 /* -------------------------------------------------------------------- */
215 int CPL_DLL CPLUnlinkTree( const char * );
216 int CPL_DLL CPLCopyFile( const char *pszNewPath, const char *pszOldPath );
217 int CPL_DLL CPLCopyTree( const char *pszNewPath, const char *pszOldPath );
218 int CPL_DLL CPLMoveFile( const char *pszNewPath, const char *pszOldPath );
219 int CPL_DLL CPLSymlink( const char* pszOldPath, const char* pszNewPath, char** papszOptions );
220 
221 /* -------------------------------------------------------------------- */
222 /* ZIP Creation. */
223 /* -------------------------------------------------------------------- */
224 #define CPL_ZIP_API_OFFERED
225 void CPL_DLL *CPLCreateZip( const char *pszZipFilename, char **papszOptions );
226 CPLErr CPL_DLL CPLCreateFileInZip( void *hZip, const char *pszFilename,
227  char **papszOptions );
228 CPLErr CPL_DLL CPLWriteFileInZip( void *hZip, const void *pBuffer, int nBufferSize );
229 CPLErr CPL_DLL CPLCloseFileInZip( void *hZip );
230 CPLErr CPL_DLL CPLCloseZip( void *hZip );
231 
232 /* -------------------------------------------------------------------- */
233 /* ZLib compression */
234 /* -------------------------------------------------------------------- */
235 
236 void CPL_DLL *CPLZLibDeflate( const void* ptr, size_t nBytes, int nLevel,
237  void* outptr, size_t nOutAvailableBytes,
238  size_t* pnOutBytes );
239 void CPL_DLL *CPLZLibInflate( const void* ptr, size_t nBytes,
240  void* outptr, size_t nOutAvailableBytes,
241  size_t* pnOutBytes );
242 
243 /* -------------------------------------------------------------------- */
244 /* XML validation. */
245 /* -------------------------------------------------------------------- */
246 int CPL_DLL CPLValidateXML(const char* pszXMLFilename,
247  const char* pszXSDFilename,
248  char** papszOptions);
249 
250 /* -------------------------------------------------------------------- */
251 /* Locale handling. Prevents parallel executions of setlocale(). */
252 /* -------------------------------------------------------------------- */
253 char* CPLsetlocale (int category, const char* locale);
254 void CPLCleanupSetlocaleMutex(void);
255 
256 CPL_C_END
257 
258 /* -------------------------------------------------------------------- */
259 /* C++ object for temporarily forcing a LC_NUMERIC locale to "C". */
260 /* -------------------------------------------------------------------- */
261 
262 #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
263 
264 class CPL_DLL CPLLocaleC
265 {
266 public:
267  CPLLocaleC();
268  ~CPLLocaleC();
269 
270 private:
271  char *pszOldLocale;
272 
273  /* Make it non-copyable */
274  CPLLocaleC(const CPLLocaleC&);
275  CPLLocaleC& operator=(const CPLLocaleC&);
276 };
277 
278 // Does the same as CPLLocaleC except that, when available, it tries to
279 // only affect the current thread. But code that would be dependent of
280 // setlocale(LC_NUMERIC, NULL) returning "C", such as current proj.4 versions,
281 // will not work depending on the actual implementation
282 class CPL_DLL CPLThreadLocaleC
283 {
284 public:
285  CPLThreadLocaleC();
286  ~CPLThreadLocaleC();
287 
288 private:
289 #ifdef HAVE_USELOCALE
290  locale_t nNewLocale;
291  locale_t nOldLocale;
292 #else
293 #if defined(_MSC_VER)
294  int nOldValConfigThreadLocale;
295 #endif
296  char *pszOldLocale;
297 #endif
298 
299  /* Make it non-copyable */
300  CPLThreadLocaleC(const CPLThreadLocaleC&);
301  CPLThreadLocaleC& operator=(const CPLThreadLocaleC&);
302 };
303 
304 #endif /* def __cplusplus */
305 
306 
307 #endif /* ndef CPL_CONV_H_INCLUDED */
double CPL_DLL CPLAtofM(const char *)
Definition: cpl_strtod.cpp:138
double CPL_DLL CPLStrtod(const char *, char **)
Definition: cpl_strtod.cpp:317
int CPL_DLL CPLPrintString(char *, const char *, int)
Definition: cpl_conv.cpp:1154
GUIntBig CPL_DLL CPLScanUIntBig(const char *, int)
Definition: cpl_conv.cpp:905
const char CPL_DLL * CPLFormFilename(const char *pszPath, const char *pszBasename, const char *pszExtension) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL
Definition: cpl_path.cpp:488
int CPL_DLL CPLPrintInt32(char *, GInt32, int)
Definition: cpl_conv.cpp:1242
const char CPL_DLL * CPLResetExtension(const char *, const char *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL
Definition: cpl_path.cpp:409
int CPL_DLL CPLPrintTime(char *, int, const char *, const struct tm *, const char *)
Definition: cpl_conv.cpp:1439
unsigned long CPL_DLL CPLScanULong(const char *, int)
Definition: cpl_conv.cpp:875
GIntBig CPL_DLL CPLAtoGIntBigEx(const char *pszString, int bWarn, int *pbOverflow)
Definition: cpl_conv.cpp:988
char CPL_DLL * CPLStrdup(const char *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL
Definition: cpl_conv.cpp:261
CPLSharedFileInfo CPL_DLL * CPLGetSharedList(int *)
Definition: cpl_conv.cpp:2280
char * CPLsetlocale(int category, const char *locale)
Definition: cpl_conv.cpp:2717
const char CPL_DLL * CPLReadLine(FILE *)
Definition: cpl_conv.cpp:539
double CPL_DLL CPLDecToPackedDMS(double dfDec)
Definition: cpl_conv.cpp:2043
int CPL_DLL CPLPrintDouble(char *, const char *, double, const char *)
Definition: cpl_conv.cpp:1381
double CPL_DLL CPLScanDouble(const char *, int)
Definition: cpl_conv.cpp:1102
const char CPL_DLL * CPLGetFilename(const char *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL
Definition: cpl_path.cpp:245
void CPL_DLL CPL_STDCALL CPLSetThreadLocalConfigOption(const char *pszKey, const char *pszValue)
Definition: cpl_conv.cpp:1737
GIntBig CPL_DLL CPLAtoGIntBig(const char *pszString)
Definition: cpl_conv.cpp:937
double CPL_DLL CPLAtofDelim(const char *, char)
Definition: cpl_strtod.cpp:71
const char CPL_DLL * CPLReadLineL(VSILFILE *)
Definition: cpl_conv.cpp:604
char CPL_DLL * CPLStrlwr(char *)
Definition: cpl_conv.cpp:294
void CPL_DLL CPL_STDCALL CPLSetConfigOption(const char *, const char *)
Definition: cpl_conv.cpp:1692
FILE CPL_DLL * CPLOpenShared(const char *, const char *, int)
Definition: cpl_conv.cpp:2121
char CPL_DLL * CPLScanString(const char *, int, int, int)
Definition: cpl_conv.cpp:792
const char CPL_DLL * CPLReadLine2L(VSILFILE *, int nMaxCols, char **papszOptions)
Definition: cpl_conv.cpp:629
Definition: cpl_conv.h:186
const char CPL_DLL * CPLGenerateTempFilename(const char *pszStem) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL
Definition: cpl_path.cpp:1054
char CPL_DLL * CPLFGets(char *, int, FILE *)
Definition: cpl_conv.cpp:335
char CPL_DLL ** CPLCorrespondingPaths(const char *pszOldFilename, const char *pszNewFilename, char **papszFileList) CPL_WARN_UNUSED_RESULT
Definition: cpl_path.cpp:946
const char CPL_DLL * CPLCleanTrailingSlash(const char *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL
Definition: cpl_path.cpp:895
char CPL_DLL * CPLGetCurrentDir(void)
Definition: cpl_path.cpp:372
void CPL_DLL * CPLMalloc(size_t) CPL_WARN_UNUSED_RESULT
Definition: cpl_conv.cpp:136
int CPL_DLL CPLPrintUIntBig(char *, GUIntBig, int)
Definition: cpl_conv.cpp:1281
const char CPL_DLL * CPLGetExtension(const char *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL
Definition: cpl_path.cpp:331
double CPL_DLL CPLAtof(const char *)
Definition: cpl_strtod.cpp:113
int CPL_DLL CPLPrintPointer(char *, void *, int)
Definition: cpl_conv.cpp:1332
int CPL_DLL CPLPrintStringFill(char *, const char *, int)
Definition: cpl_conv.cpp:1198
const char CPL_DLL * CPLExtractRelativePath(const char *, const char *, int *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL
Definition: cpl_path.cpp:803
void CPL_DLL CPLDumpSharedList(FILE *)
Definition: cpl_conv.cpp:2302
const char CPL_DLL *CPL_STDCALL CPLGetConfigOption(const char *, const char *) CPL_WARN_UNUSED_RESULT
Definition: cpl_conv.cpp:1604
const char CPL_DLL * CPLGetDirname(const char *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL
Definition: cpl_path.cpp:193
void CPL_DLL * CPLRealloc(void *, size_t) CPL_WARN_UNUSED_RESULT
Definition: cpl_conv.cpp:194
float CPL_DLL CPLStrtofDelim(const char *, char **, char)
Definition: cpl_strtod.cpp:343
const char CPL_DLL * CPLGetBasename(const char *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL
Definition: cpl_path.cpp:277
const char CPL_DLL * CPLProjectRelativeFilename(const char *pszProjectDir, const char *pszSecondaryFilename) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL
Definition: cpl_path.cpp:699
float CPL_DLL CPLStrtof(const char *, char **)
Definition: cpl_strtod.cpp:393
long CPL_DLL CPLScanLong(const char *, int)
Definition: cpl_conv.cpp:846
double CPL_DLL CPLStrtodDelim(const char *, char **, char)
Definition: cpl_strtod.cpp:227
const char CPL_DLL * CPLGetPath(const char *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL
Definition: cpl_path.cpp:138
int CPL_DLL CPLUnlinkTree(const char *)
Definition: cpl_conv.cpp:2339
int CPL_DLL CPLCheckForFile(char *pszFilename, char **papszSiblingList)
Definition: cpl_conv.cpp:2768
void CPL_DLL * CPLCalloc(size_t, size_t) CPL_WARN_UNUSED_RESULT
Definition: cpl_conv.cpp:106
void CPL_DLL * CPLScanPointer(const char *, int)
Definition: cpl_conv.cpp:1039
const char CPL_DLL * CPLFormCIFilename(const char *pszPath, const char *pszBasename, const char *pszExtension) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL
Definition: cpl_path.cpp:605
void CPL_DLL CPLCloseShared(FILE *)
Definition: cpl_conv.cpp:2194
double CPL_DLL CPLPackedDMSToDec(double)
Definition: cpl_conv.cpp:2009
void CPL_DLL * CPLZLibInflate(const void *ptr, size_t nBytes, void *outptr, size_t nOutAvailableBytes, size_t *pnOutBytes)
Uncompress a buffer compressed with ZLib DEFLATE compression.
Definition: cpl_conv.cpp:2848
int CPL_DLL CPLIsFilenameRelative(const char *pszFilename)
Definition: cpl_path.cpp:762
void CPL_DLL * CPLGetSymbol(const char *, const char *)
Definition: cplgetsymbol.cpp:85