SDTS_AL
cpl_conv.h
Go to the documentation of this file.
1 /******************************************************************************
2  * $Id: cpl_conv.h 28601 2015-03-03 11:06:40Z rouault $
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 void CPL_DLL CPL_STDCALL CPLSetConfigOption( const char *, const char * );
56 void CPL_DLL CPL_STDCALL CPLSetThreadLocalConfigOption( const char *pszKey,
57  const char *pszValue );
58 void CPL_DLL CPL_STDCALL CPLFreeConfig(void);
59 
60 /* -------------------------------------------------------------------- */
61 /* Safe malloc() API. Thin cover over VSI functions with fatal */
62 /* error reporting if memory allocation fails. */
63 /* -------------------------------------------------------------------- */
64 void CPL_DLL *CPLMalloc( size_t ) CPL_WARN_UNUSED_RESULT;
65 void CPL_DLL *CPLCalloc( size_t, size_t ) CPL_WARN_UNUSED_RESULT;
66 void CPL_DLL *CPLRealloc( void *, size_t ) CPL_WARN_UNUSED_RESULT;
67 char CPL_DLL *CPLStrdup( const char * ) CPL_WARN_UNUSED_RESULT;
68 char CPL_DLL *CPLStrlwr( char *);
69 
70 #define CPLFree VSIFree
71 
72 /* -------------------------------------------------------------------- */
73 /* Read a line from a text file, and strip of CR/LF. */
74 /* -------------------------------------------------------------------- */
75 char CPL_DLL *CPLFGets( char *, int, FILE *);
76 const char CPL_DLL *CPLReadLine( FILE * );
77 const char CPL_DLL *CPLReadLineL( VSILFILE * );
78 const char CPL_DLL *CPLReadLine2L( VSILFILE * , int nMaxCols, char** papszOptions);
79 
80 /* -------------------------------------------------------------------- */
81 /* Convert ASCII string to floationg point number */
82 /* (THESE FUNCTIONS ARE NOT LOCALE AWARE!). */
83 /* -------------------------------------------------------------------- */
84 double CPL_DLL CPLAtof(const char *);
85 double CPL_DLL CPLAtofDelim(const char *, char);
86 double CPL_DLL CPLStrtod(const char *, char **);
87 double CPL_DLL CPLStrtodDelim(const char *, char **, char);
88 float CPL_DLL CPLStrtof(const char *, char **);
89 float CPL_DLL CPLStrtofDelim(const char *, char **, char);
90 
91 /* -------------------------------------------------------------------- */
92 /* Convert number to string. This function is locale agnostic */
93 /* (ie. it will support "," or "." regardless of current locale) */
94 /* -------------------------------------------------------------------- */
95 double CPL_DLL CPLAtofM(const char *);
96 
97 /* -------------------------------------------------------------------- */
98 /* Read a numeric value from an ASCII character string. */
99 /* -------------------------------------------------------------------- */
100 char CPL_DLL *CPLScanString( const char *, int, int, int );
101 double CPL_DLL CPLScanDouble( const char *, int );
102 long CPL_DLL CPLScanLong( const char *, int );
103 unsigned long CPL_DLL CPLScanULong( const char *, int );
104 GUIntBig CPL_DLL CPLScanUIntBig( const char *, int );
105 GIntBig CPL_DLL CPLAtoGIntBig( const char* pszString );
106 GIntBig CPL_DLL CPLAtoGIntBigEx( const char* pszString, int bWarn, int *pbOverflow );
107 void CPL_DLL *CPLScanPointer( const char *, int );
108 
109 /* -------------------------------------------------------------------- */
110 /* Print a value to an ASCII character string. */
111 /* -------------------------------------------------------------------- */
112 int CPL_DLL CPLPrintString( char *, const char *, int );
113 int CPL_DLL CPLPrintStringFill( char *, const char *, int );
114 int CPL_DLL CPLPrintInt32( char *, GInt32 , int );
115 int CPL_DLL CPLPrintUIntBig( char *, GUIntBig , int );
116 int CPL_DLL CPLPrintDouble( char *, const char *, double, const char * );
117 int CPL_DLL CPLPrintTime( char *, int , const char *, const struct tm *,
118  const char * );
119 int CPL_DLL CPLPrintPointer( char *, void *, int );
120 
121 /* -------------------------------------------------------------------- */
122 /* Fetch a function from DLL / so. */
123 /* -------------------------------------------------------------------- */
124 
125 void CPL_DLL *CPLGetSymbol( const char *, const char * );
126 
127 /* -------------------------------------------------------------------- */
128 /* Fetch executable path. */
129 /* -------------------------------------------------------------------- */
130 int CPL_DLL CPLGetExecPath( char *pszPathBuf, int nMaxLength );
131 
132 /* -------------------------------------------------------------------- */
133 /* Filename handling functions. */
134 /* -------------------------------------------------------------------- */
135 const char CPL_DLL *CPLGetPath( const char * );
136 const char CPL_DLL *CPLGetDirname( const char * );
137 const char CPL_DLL *CPLGetFilename( const char * );
138 const char CPL_DLL *CPLGetBasename( const char * );
139 const char CPL_DLL *CPLGetExtension( const char * );
140 char CPL_DLL *CPLGetCurrentDir(void);
141 const char CPL_DLL *CPLFormFilename( const char *pszPath,
142  const char *pszBasename,
143  const char *pszExtension );
144 const char CPL_DLL *CPLFormCIFilename( const char *pszPath,
145  const char *pszBasename,
146  const char *pszExtension );
147 const char CPL_DLL *CPLResetExtension( const char *, const char * );
148 const char CPL_DLL *CPLProjectRelativeFilename( const char *pszProjectDir,
149  const char *pszSecondaryFilename );
150 int CPL_DLL CPLIsFilenameRelative( const char *pszFilename );
151 const char CPL_DLL *CPLExtractRelativePath(const char *, const char *, int *);
152 const char CPL_DLL *CPLCleanTrailingSlash( const char * );
153 char CPL_DLL **CPLCorrespondingPaths( const char *pszOldFilename,
154  const char *pszNewFilename,
155  char **papszFileList );
156 int CPL_DLL CPLCheckForFile( char *pszFilename, char **papszSiblingList );
157 
158 const char CPL_DLL *CPLGenerateTempFilename( const char *pszStem );
159 
160 /* -------------------------------------------------------------------- */
161 /* Find File Function */
162 /* -------------------------------------------------------------------- */
163 typedef const char *(*CPLFileFinder)(const char *, const char *);
164 
165 const char CPL_DLL *CPLFindFile(const char *pszClass,
166  const char *pszBasename);
167 const char CPL_DLL *CPLDefaultFindFile(const char *pszClass,
168  const char *pszBasename);
169 void CPL_DLL CPLPushFileFinder( CPLFileFinder pfnFinder );
170 CPLFileFinder CPL_DLL CPLPopFileFinder(void);
171 void CPL_DLL CPLPushFinderLocation( const char * );
172 void CPL_DLL CPLPopFinderLocation(void);
173 void CPL_DLL CPLFinderClean(void);
174 
175 /* -------------------------------------------------------------------- */
176 /* Safe version of stat() that works properly on stuff like "C:". */
177 /* -------------------------------------------------------------------- */
178 int CPL_DLL CPLStat( const char *, VSIStatBuf * );
179 
180 /* -------------------------------------------------------------------- */
181 /* Reference counted file handle manager. Makes sharing file */
182 /* handles more practical. */
183 /* -------------------------------------------------------------------- */
184 typedef struct {
185  FILE *fp;
186  int nRefCount;
187  int bLarge;
188  char *pszFilename;
189  char *pszAccess;
191 
192 FILE CPL_DLL *CPLOpenShared( const char *, const char *, int );
193 void CPL_DLL CPLCloseShared( FILE * );
194 CPLSharedFileInfo CPL_DLL *CPLGetSharedList( int * );
195 void CPL_DLL CPLDumpSharedList( FILE * );
196 void CPL_DLL CPLCleanupSharedFileMutex( void );
197 
198 /* -------------------------------------------------------------------- */
199 /* DMS to Dec to DMS conversion. */
200 /* -------------------------------------------------------------------- */
201 double CPL_DLL CPLDMSToDec( const char *is );
202 const char CPL_DLL *CPLDecToDMS( double dfAngle, const char * pszAxis,
203  int nPrecision );
204 double CPL_DLL CPLPackedDMSToDec( double );
205 double CPL_DLL CPLDecToPackedDMS( double dfDec );
206 
207 void CPL_DLL CPLStringToComplex( const char *pszString,
208  double *pdfReal, double *pdfImag );
209 
210 /* -------------------------------------------------------------------- */
211 /* Misc other functions. */
212 /* -------------------------------------------------------------------- */
213 int CPL_DLL CPLUnlinkTree( const char * );
214 int CPL_DLL CPLCopyFile( const char *pszNewPath, const char *pszOldPath );
215 int CPL_DLL CPLCopyTree( const char *pszNewPath, const char *pszOldPath );
216 int CPL_DLL CPLMoveFile( const char *pszNewPath, const char *pszOldPath );
217 
218 /* -------------------------------------------------------------------- */
219 /* ZIP Creation. */
220 /* -------------------------------------------------------------------- */
221 #define CPL_ZIP_API_OFFERED
222 void CPL_DLL *CPLCreateZip( const char *pszZipFilename, char **papszOptions );
223 CPLErr CPL_DLL CPLCreateFileInZip( void *hZip, const char *pszFilename,
224  char **papszOptions );
225 CPLErr CPL_DLL CPLWriteFileInZip( void *hZip, const void *pBuffer, int nBufferSize );
226 CPLErr CPL_DLL CPLCloseFileInZip( void *hZip );
227 CPLErr CPL_DLL CPLCloseZip( void *hZip );
228 
229 /* -------------------------------------------------------------------- */
230 /* ZLib compression */
231 /* -------------------------------------------------------------------- */
232 
233 void CPL_DLL *CPLZLibDeflate( const void* ptr, size_t nBytes, int nLevel,
234  void* outptr, size_t nOutAvailableBytes,
235  size_t* pnOutBytes );
236 void CPL_DLL *CPLZLibInflate( const void* ptr, size_t nBytes,
237  void* outptr, size_t nOutAvailableBytes,
238  size_t* pnOutBytes );
239 
240 /* -------------------------------------------------------------------- */
241 /* XML validation. */
242 /* -------------------------------------------------------------------- */
243 int CPL_DLL CPLValidateXML(const char* pszXMLFilename,
244  const char* pszXSDFilename,
245  char** papszOptions);
246 
247 /* -------------------------------------------------------------------- */
248 /* Locale handling. Prevents parallel executions of setlocale(). */
249 /* -------------------------------------------------------------------- */
250 char* CPLsetlocale (int category, const char* locale);
251 void CPLCleanupSetlocaleMutex(void);
252 
253 CPL_C_END
254 
255 /* -------------------------------------------------------------------- */
256 /* C++ object for temporariliy forcing a LC_NUMERIC locale to "C". */
257 /* -------------------------------------------------------------------- */
258 
259 #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
260 
261 class CPL_DLL CPLLocaleC
262 {
263 public:
264  CPLLocaleC();
265  ~CPLLocaleC();
266 
267 private:
268  char *pszOldLocale;
269 
270  /* Make it non-copyable */
271  CPLLocaleC(CPLLocaleC&);
272  CPLLocaleC& operator=(CPLLocaleC&);
273 };
274 
275 #endif /* def __cplusplus */
276 
277 
278 #endif /* ndef CPL_CONV_H_INCLUDED */
double CPL_DLL CPLAtofM(const char *)
Definition: cpl_strtod.cpp:170
double CPL_DLL CPLStrtod(const char *, char **)
Definition: cpl_strtod.cpp:349
int CPL_DLL CPLPrintString(char *, const char *, int)
Definition: cpl_conv.cpp:1153
GUIntBig CPL_DLL CPLScanUIntBig(const char *, int)
Definition: cpl_conv.cpp:905
const char CPL_DLL * CPLProjectRelativeFilename(const char *pszProjectDir, const char *pszSecondaryFilename)
Definition: cpl_path.cpp:630
int CPL_DLL CPLPrintInt32(char *, GInt32, int)
Definition: cpl_conv.cpp:1242
int CPL_DLL CPLPrintTime(char *, int, const char *, const struct tm *, const char *)
Definition: cpl_conv.cpp:1436
const char CPL_DLL * CPLGetPath(const char *)
Definition: cpl_path.cpp:129
const char CPL_DLL * CPLFormCIFilename(const char *pszPath, const char *pszBasename, const char *pszExtension)
Definition: cpl_path.cpp:535
unsigned long CPL_DLL CPLScanULong(const char *, int)
Definition: cpl_conv.cpp:865
GIntBig CPL_DLL CPLAtoGIntBigEx(const char *pszString, int bWarn, int *pbOverflow)
Definition: cpl_conv.cpp:986
const char CPL_DLL * CPLGetDirname(const char *)
Definition: cpl_path.cpp:182
CPLSharedFileInfo CPL_DLL * CPLGetSharedList(int *)
Definition: cpl_conv.cpp:2244
char * CPLsetlocale(int category, const char *locale)
Definition: cpl_conv.cpp:2615
const char CPL_DLL * CPLGetBasename(const char *)
Definition: cpl_path.cpp:263
const char CPL_DLL * CPLReadLine(FILE *)
Definition: cpl_conv.cpp:519
double CPL_DLL CPLDecToPackedDMS(double dfDec)
Definition: cpl_conv.cpp:2011
double CPL_DLL CPLScanDouble(const char *, int)
Definition: cpl_conv.cpp:1106
void CPL_DLL CPL_STDCALL CPLSetThreadLocalConfigOption(const char *pszKey, const char *pszValue)
Definition: cpl_conv.cpp:1716
GIntBig CPL_DLL CPLAtoGIntBig(const char *pszString)
Definition: cpl_conv.cpp:943
char CPL_DLL * CPLStrdup(const char *) CPL_WARN_UNUSED_RESULT
Definition: cpl_conv.cpp:248
double CPL_DLL CPLAtofDelim(const char *, char)
Definition: cpl_strtod.cpp:103
const char CPL_DLL * CPLReadLineL(VSILFILE *)
Definition: cpl_conv.cpp:584
char CPL_DLL * CPLStrlwr(char *)
Definition: cpl_conv.cpp:283
const char CPL_DLL * CPLFormFilename(const char *pszPath, const char *pszBasename, const char *pszExtension)
Definition: cpl_path.cpp:460
void CPL_DLL CPL_STDCALL CPLSetConfigOption(const char *, const char *)
Definition: cpl_conv.cpp:1671
FILE CPL_DLL * CPLOpenShared(const char *, const char *, int)
Definition: cpl_conv.cpp:2089
const char CPL_DLL * CPLGenerateTempFilename(const char *pszStem)
Definition: cpl_path.cpp:980
char CPL_DLL * CPLScanString(const char *, int, int, int)
Definition: cpl_conv.cpp:770
const char CPL_DLL * CPLReadLine2L(VSILFILE *, int nMaxCols, char **papszOptions)
Definition: cpl_conv.cpp:609
Definition: cpl_conv.h:184
char CPL_DLL * CPLFGets(char *, int, FILE *)
Definition: cpl_conv.cpp:324
char CPL_DLL * CPLGetCurrentDir(void)
Definition: cpl_path.cpp:348
void CPL_DLL * CPLMalloc(size_t) CPL_WARN_UNUSED_RESULT
Definition: cpl_conv.cpp:119
int CPL_DLL CPLPrintUIntBig(char *, GUIntBig, int)
Definition: cpl_conv.cpp:1281
const char CPL_DLL * CPLGetExtension(const char *)
Definition: cpl_path.cpp:313
double CPL_DLL CPLAtof(const char *)
Definition: cpl_strtod.cpp:145
int CPL_DLL CPLPrintPointer(char *, void *, int)
Definition: cpl_conv.cpp:1323
int CPL_DLL CPLPrintStringFill(char *, const char *, int)
Definition: cpl_conv.cpp:1197
char CPL_DLL ** CPLCorrespondingPaths(const char *pszOldFilename, const char *pszNewFilename, char **papszFileList)
Definition: cpl_path.cpp:870
void CPL_DLL CPLDumpSharedList(FILE *)
Definition: cpl_conv.cpp:2266
const char CPL_DLL *CPL_STDCALL CPLGetConfigOption(const char *, const char *) CPL_WARN_UNUSED_RESULT
Definition: cpl_conv.cpp:1609
void CPL_DLL * CPLRealloc(void *, size_t) CPL_WARN_UNUSED_RESULT
Definition: cpl_conv.cpp:182
const char CPL_DLL * CPLExtractRelativePath(const char *, const char *, int *)
Definition: cpl_path.cpp:727
const char CPL_DLL * CPLGetFilename(const char *)
Definition: cpl_path.cpp:231
float CPL_DLL CPLStrtofDelim(const char *, char **, char)
Definition: cpl_strtod.cpp:375
const char CPL_DLL * CPLCleanTrailingSlash(const char *)
Definition: cpl_path.cpp:821
float CPL_DLL CPLStrtof(const char *, char **)
Definition: cpl_strtod.cpp:430
long CPL_DLL CPLScanLong(const char *, int)
Definition: cpl_conv.cpp:826
double CPL_DLL CPLStrtodDelim(const char *, char **, char)
Definition: cpl_strtod.cpp:259
int CPL_DLL CPLUnlinkTree(const char *)
Definition: cpl_conv.cpp:2305
int CPL_DLL CPLCheckForFile(char *pszFilename, char **papszSiblingList)
Definition: cpl_conv.cpp:2663
void CPL_DLL * CPLCalloc(size_t, size_t) CPL_WARN_UNUSED_RESULT
Definition: cpl_conv.cpp:87
void CPL_DLL * CPLScanPointer(const char *, int)
Definition: cpl_conv.cpp:1038
void CPL_DLL CPLCloseShared(FILE *)
Definition: cpl_conv.cpp:2164
double CPL_DLL CPLPackedDMSToDec(double)
Definition: cpl_conv.cpp:1975
const char CPL_DLL * CPLResetExtension(const char *, const char *)
Definition: cpl_path.cpp:388
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:2744
int CPL_DLL CPLIsFilenameRelative(const char *pszFilename)
Definition: cpl_path.cpp:687
void CPL_DLL * CPLGetSymbol(const char *, const char *)
Definition: cplgetsymbol.cpp:84