GDAL
cpl_conv.h
Go to the documentation of this file.
1 /******************************************************************************
2  * $Id: cpl_conv.h 25627 2013-02-10 10:17:19Z 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  *
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
23  * OR 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_CONV_H_INCLUDED
32 #define CPL_CONV_H_INCLUDED
33 
34 #include "cpl_port.h"
35 #include "cpl_vsi.h"
36 #include "cpl_error.h"
37 
45 /* -------------------------------------------------------------------- */
46 /* Runtime check of various configuration items. */
47 /* -------------------------------------------------------------------- */
48 CPL_C_START
49 
50 void CPL_DLL CPLVerifyConfiguration(void);
51 
52 const char CPL_DLL * CPL_STDCALL
53 CPLGetConfigOption( const char *, const char * ) CPL_WARN_UNUSED_RESULT;
54 void CPL_DLL CPL_STDCALL CPLSetConfigOption( const char *, const char * );
55 void CPL_DLL CPL_STDCALL CPLSetThreadLocalConfigOption( const char *pszKey,
56  const char *pszValue );
57 void CPL_DLL CPL_STDCALL CPLFreeConfig(void);
58 
59 /* -------------------------------------------------------------------- */
60 /* Safe malloc() API. Thin cover over VSI functions with fatal */
61 /* error reporting if memory allocation fails. */
62 /* -------------------------------------------------------------------- */
63 void CPL_DLL *CPLMalloc( size_t ) CPL_WARN_UNUSED_RESULT;
64 void CPL_DLL *CPLCalloc( size_t, size_t ) CPL_WARN_UNUSED_RESULT;
65 void CPL_DLL *CPLRealloc( void *, size_t ) CPL_WARN_UNUSED_RESULT;
66 char CPL_DLL *CPLStrdup( const char * ) CPL_WARN_UNUSED_RESULT;
67 char CPL_DLL *CPLStrlwr( char *);
68 
69 #define CPLFree VSIFree
70 
71 /* -------------------------------------------------------------------- */
72 /* Read a line from a text file, and strip of CR/LF. */
73 /* -------------------------------------------------------------------- */
74 char CPL_DLL *CPLFGets( char *, int, FILE *);
75 const char CPL_DLL *CPLReadLine( FILE * );
76 const char CPL_DLL *CPLReadLineL( VSILFILE * );
77 const char CPL_DLL *CPLReadLine2L( VSILFILE * , int nMaxCols, char** papszOptions);
78 
79 /* -------------------------------------------------------------------- */
80 /* Convert ASCII string to floationg point number */
81 /* (THESE FUNCTIONS ARE NOT LOCALE AWARE!). */
82 /* -------------------------------------------------------------------- */
83 double CPL_DLL CPLAtof(const char *);
84 double CPL_DLL CPLAtofDelim(const char *, char);
85 double CPL_DLL CPLStrtod(const char *, char **);
86 double CPL_DLL CPLStrtodDelim(const char *, char **, char);
87 float CPL_DLL CPLStrtof(const char *, char **);
88 float CPL_DLL CPLStrtofDelim(const char *, char **, char);
89 
90 /* -------------------------------------------------------------------- */
91 /* Convert number to string. This function is locale agnostic */
92 /* (ie. it will support "," or "." regardless of current locale) */
93 /* -------------------------------------------------------------------- */
94 double CPL_DLL CPLAtofM(const char *);
95 
96 /* -------------------------------------------------------------------- */
97 /* Read a numeric value from an ASCII character string. */
98 /* -------------------------------------------------------------------- */
99 char CPL_DLL *CPLScanString( const char *, int, int, int );
100 double CPL_DLL CPLScanDouble( const char *, int );
101 long CPL_DLL CPLScanLong( const char *, int );
102 unsigned long CPL_DLL CPLScanULong( const char *, int );
103 GUIntBig CPL_DLL CPLScanUIntBig( const char *, int );
104 void CPL_DLL *CPLScanPointer( const char *, int );
105 
106 /* -------------------------------------------------------------------- */
107 /* Print a value to an ASCII character string. */
108 /* -------------------------------------------------------------------- */
109 int CPL_DLL CPLPrintString( char *, const char *, int );
110 int CPL_DLL CPLPrintStringFill( char *, const char *, int );
111 int CPL_DLL CPLPrintInt32( char *, GInt32 , int );
112 int CPL_DLL CPLPrintUIntBig( char *, GUIntBig , int );
113 int CPL_DLL CPLPrintDouble( char *, const char *, double, const char * );
114 int CPL_DLL CPLPrintTime( char *, int , const char *, const struct tm *,
115  const char * );
116 int CPL_DLL CPLPrintPointer( char *, void *, int );
117 
118 /* -------------------------------------------------------------------- */
119 /* Fetch a function from DLL / so. */
120 /* -------------------------------------------------------------------- */
121 
122 void CPL_DLL *CPLGetSymbol( const char *, const char * );
123 
124 /* -------------------------------------------------------------------- */
125 /* Fetch executable path. */
126 /* -------------------------------------------------------------------- */
127 int CPL_DLL CPLGetExecPath( char *pszPathBuf, int nMaxLength );
128 
129 /* -------------------------------------------------------------------- */
130 /* Filename handling functions. */
131 /* -------------------------------------------------------------------- */
132 const char CPL_DLL *CPLGetPath( const char * );
133 const char CPL_DLL *CPLGetDirname( const char * );
134 const char CPL_DLL *CPLGetFilename( const char * );
135 const char CPL_DLL *CPLGetBasename( const char * );
136 const char CPL_DLL *CPLGetExtension( const char * );
137 char CPL_DLL *CPLGetCurrentDir(void);
138 const char CPL_DLL *CPLFormFilename( const char *pszPath,
139  const char *pszBasename,
140  const char *pszExtension );
141 const char CPL_DLL *CPLFormCIFilename( const char *pszPath,
142  const char *pszBasename,
143  const char *pszExtension );
144 const char CPL_DLL *CPLResetExtension( const char *, const char * );
145 const char CPL_DLL *CPLProjectRelativeFilename( const char *pszProjectDir,
146  const char *pszSecondaryFilename );
147 int CPL_DLL CPLIsFilenameRelative( const char *pszFilename );
148 const char CPL_DLL *CPLExtractRelativePath(const char *, const char *, int *);
149 const char CPL_DLL *CPLCleanTrailingSlash( const char * );
150 char CPL_DLL **CPLCorrespondingPaths( const char *pszOldFilename,
151  const char *pszNewFilename,
152  char **papszFileList );
153 int CPL_DLL CPLCheckForFile( char *pszFilename, char **papszSiblingList );
154 
155 const char CPL_DLL *CPLGenerateTempFilename( const char *pszStem );
156 
157 /* -------------------------------------------------------------------- */
158 /* Find File Function */
159 /* -------------------------------------------------------------------- */
160 typedef const char *(*CPLFileFinder)(const char *, const char *);
161 
162 const char CPL_DLL *CPLFindFile(const char *pszClass,
163  const char *pszBasename);
164 const char CPL_DLL *CPLDefaultFindFile(const char *pszClass,
165  const char *pszBasename);
166 void CPL_DLL CPLPushFileFinder( CPLFileFinder pfnFinder );
167 CPLFileFinder CPL_DLL CPLPopFileFinder(void);
168 void CPL_DLL CPLPushFinderLocation( const char * );
169 void CPL_DLL CPLPopFinderLocation(void);
170 void CPL_DLL CPLFinderClean(void);
171 
172 /* -------------------------------------------------------------------- */
173 /* Safe version of stat() that works properly on stuff like "C:". */
174 /* -------------------------------------------------------------------- */
175 int CPL_DLL CPLStat( const char *, VSIStatBuf * );
176 
177 /* -------------------------------------------------------------------- */
178 /* Reference counted file handle manager. Makes sharing file */
179 /* handles more practical. */
180 /* -------------------------------------------------------------------- */
181 typedef struct {
182  FILE *fp;
183  int nRefCount;
184  int bLarge;
185  char *pszFilename;
186  char *pszAccess;
188 
189 FILE CPL_DLL *CPLOpenShared( const char *, const char *, int );
190 void CPL_DLL CPLCloseShared( FILE * );
191 CPLSharedFileInfo CPL_DLL *CPLGetSharedList( int * );
192 void CPL_DLL CPLDumpSharedList( FILE * );
193 void CPL_DLL CPLCleanupSharedFileMutex();
194 
195 /* -------------------------------------------------------------------- */
196 /* DMS to Dec to DMS conversion. */
197 /* -------------------------------------------------------------------- */
198 double CPL_DLL CPLDMSToDec( const char *is );
199 const char CPL_DLL *CPLDecToDMS( double dfAngle, const char * pszAxis,
200  int nPrecision );
201 double CPL_DLL CPLPackedDMSToDec( double );
202 double CPL_DLL CPLDecToPackedDMS( double dfDec );
203 
204 void CPL_DLL CPLStringToComplex( const char *pszString,
205  double *pdfReal, double *pdfImag );
206 
207 /* -------------------------------------------------------------------- */
208 /* Misc other functions. */
209 /* -------------------------------------------------------------------- */
210 int CPL_DLL CPLUnlinkTree( const char * );
211 int CPL_DLL CPLCopyFile( const char *pszNewPath, const char *pszOldPath );
212 int CPL_DLL CPLMoveFile( const char *pszNewPath, const char *pszOldPath );
213 
214 /* -------------------------------------------------------------------- */
215 /* ZIP Creation. */
216 /* -------------------------------------------------------------------- */
217 #define CPL_ZIP_API_OFFERED
218 void CPL_DLL *CPLCreateZip( const char *pszZipFilename, char **papszOptions );
219 CPLErr CPL_DLL CPLCreateFileInZip( void *hZip, const char *pszFilename,
220  char **papszOptions );
221 CPLErr CPL_DLL CPLWriteFileInZip( void *hZip, const void *pBuffer, int nBufferSize );
222 CPLErr CPL_DLL CPLCloseFileInZip( void *hZip );
223 CPLErr CPL_DLL CPLCloseZip( void *hZip );
224 
225 /* -------------------------------------------------------------------- */
226 /* ZLib compression */
227 /* -------------------------------------------------------------------- */
228 
229 void CPL_DLL *CPLZLibDeflate( const void* ptr, size_t nBytes, int nLevel,
230  void* outptr, size_t nOutAvailableBytes,
231  size_t* pnOutBytes );
232 void CPL_DLL *CPLZLibInflate( const void* ptr, size_t nBytes,
233  void* outptr, size_t nOutAvailableBytes,
234  size_t* pnOutBytes );
235 
236 /* -------------------------------------------------------------------- */
237 /* XML validation. */
238 /* -------------------------------------------------------------------- */
239 int CPL_DLL CPLValidateXML(const char* pszXMLFilename,
240  const char* pszXSDFilename,
241  char** papszOptions);
242 
243 CPL_C_END
244 
245 /* -------------------------------------------------------------------- */
246 /* C++ object for temporariliy forcing a LC_NUMERIC locale to "C". */
247 /* -------------------------------------------------------------------- */
248 
249 #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
250 
251 class CPL_DLL CPLLocaleC
252 {
253 public:
254  CPLLocaleC();
255  ~CPLLocaleC();
256 
257 private:
258  char *pszOldLocale;
259 
260  /* Make it non-copyable */
262  CPLLocaleC& operator=(CPLLocaleC&);
263 };
264 
265 #endif /* def __cplusplus */
266 
267 
268 #endif /* ndef CPL_CONV_H_INCLUDED */
int CPLIsFilenameRelative(const char *pszFilename)
Is filename relative or absolute?
Definition: cpl_path.cpp:683
const char * CPLProjectRelativeFilename(const char *pszProjectDir, const char *pszSecondaryFilename)
Find a file relative to a project file.
Definition: cpl_path.cpp:626
int CPLPrintString(char *, const char *, int)
Copy the string pointed to by pszSrc, NOT including the terminating `\0' character, to the array pointed to by pszDest.
Definition: cpl_conv.cpp:1061
const char * CPLFormFilename(const char *pszPath, const char *pszBasename, const char *pszExtension)
Build a full file path from a passed path, file basename and extension.
Definition: cpl_path.cpp:459
void * CPLRealloc(void *, size_t) CPL_WARN_UNUSED_RESULT
Safe version of realloc().
Definition: cpl_conv.cpp:177
double CPLDecToPackedDMS(double dfDec)
Convert decimal degrees into packed DMS value (DDDMMMSSS.SS).
Definition: cpl_conv.cpp:1934
const char * CPLExtractRelativePath(const char *, const char *, int *)
Get relative path from directory to target file.
Definition: cpl_path.cpp:723
Standard C Covers.
char * CPLStrdup(const char *) CPL_WARN_UNUSED_RESULT
Safe version of strdup() function.
Definition: cpl_conv.cpp:243
int CPLPrintDouble(char *, const char *, double, const char *)
Print double value into specified string buffer.
Definition: cpl_conv.cpp:1280
const char * CPLGetConfigOption(const char *, const char *) CPL_WARN_UNUSED_RESULT
Get the value of a configuration option.
Definition: cpl_conv.cpp:1543
const char * CPLFormCIFilename(const char *pszPath, const char *pszBasename, const char *pszExtension)
Case insensitive file searching, returing full path.
Definition: cpl_path.cpp:531
Core portability definitions for CPL.
const char * CPLResetExtension(const char *, const char *)
Replace the extension with the provided one.
Definition: cpl_path.cpp:387
void * CPLMalloc(size_t) CPL_WARN_UNUSED_RESULT
Safe version of malloc().
Definition: cpl_conv.cpp:114
int CPLPrintStringFill(char *, const char *, int)
Copy the string pointed to by pszSrc, NOT including the terminating `\0' character, to the array pointed to by pszDest.
Definition: cpl_conv.cpp:1105
int CPLPrintPointer(char *, void *, int)
Print pointer value into specified string buffer.
Definition: cpl_conv.cpp:1231
double CPLAtof(const char *)
Converts ASCII string to floating point number.
Definition: cpl_strtod.cpp:136
void * CPLGetSymbol(const char *, const char *)
Fetch a function pointer from a shared library / DLL.
Definition: cplgetsymbol.cpp:83
int CPLGetExecPath(char *pszPathBuf, int nMaxLength)
Fetch path of executable.
Definition: cpl_getexecpath.cpp:138
const char * CPLReadLine(FILE *)
Simplified line reading from text file.
Definition: cpl_conv.cpp:514
void * 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:2537
float CPLStrtof(const char *, char **)
Converts ASCII string to floating point number.
Definition: cpl_strtod.cpp:399
char * CPLStrlwr(char *)
Convert each characters of the string to lower case.
Definition: cpl_conv.cpp:278
void CPLSetThreadLocalConfigOption(const char *pszKey, const char *pszValue)
Set a configuration option for GDAL/OGR use.
Definition: cpl_conv.cpp:1640
double CPLStrtodDelim(const char *, char **, char)
Converts ASCII string to floating point number using specified delimiter.
Definition: cpl_strtod.cpp:246
int CPLUnlinkTree(const char *)
Definition: cpl_conv.cpp:2228
const char * CPLReadLineL(VSILFILE *)
Simplified line reading from text file.
Definition: cpl_conv.cpp:579
CPLSharedFileInfo * CPLGetSharedList(int *)
Fetch list of open shared files.
Definition: cpl_conv.cpp:2167
const char * CPLGetDirname(const char *)
Extract directory path portion of filename.
Definition: cpl_path.cpp:181
float CPLStrtofDelim(const char *, char **, char)
Converts ASCII string to floating point number using specified delimiter.
Definition: cpl_strtod.cpp:344
int CPLPrintTime(char *, int, const char *, const struct tm *, const char *)
Print specified time value accordingly to the format options and specified locale name...
Definition: cpl_conv.cpp:1370
Definition: cpl_conv.h:181
FILE * CPLOpenShared(const char *, const char *, int)
Open a shared file handle.
Definition: cpl_conv.cpp:2012
char * CPLFGets(char *, int, FILE *)
Reads in at most one less than nBufferSize characters from the fp stream and stores them into the buf...
Definition: cpl_conv.cpp:319
int CPLCheckForFile(char *pszFilename, char **papszSiblingList)
Check for file existance.
Definition: cpl_conv.cpp:2456
CPL error handling services.
void CPLDumpSharedList(FILE *)
Report open shared files.
Definition: cpl_conv.cpp:2189
Definition: cpl_conv.h:251
unsigned long CPLScanULong(const char *, int)
Scan up to a maximum number of characters from a string and convert the result to a unsigned long...
Definition: cpl_conv.cpp:860
const char * CPLReadLine2L(VSILFILE *, int nMaxCols, char **papszOptions)
Simplified line reading from text file.
Definition: cpl_conv.cpp:604
const char * CPLGetPath(const char *)
Extract directory path portion of filename.
Definition: cpl_path.cpp:128
void * CPLScanPointer(const char *, int)
Extract pointer from string.
Definition: cpl_conv.cpp:946
double CPLStrtod(const char *, char **)
Converts ASCII string to floating point number.
Definition: cpl_strtod.cpp:318
const char * CPLGenerateTempFilename(const char *pszStem)
Generate temporary file name.
Definition: cpl_path.cpp:976
GUIntBig CPLScanUIntBig(const char *, int)
Extract big integer from string.
Definition: cpl_conv.cpp:900
char * CPLGetCurrentDir(void)
Get the current working directory name.
Definition: cpl_path.cpp:347
int CPLPrintInt32(char *, GInt32, int)
Print GInt32 value into specified string buffer.
Definition: cpl_conv.cpp:1150
void CPLSetConfigOption(const char *, const char *)
Set a configuration option for GDAL/OGR use.
Definition: cpl_conv.cpp:1605
double CPLScanDouble(const char *, int)
Extract double from string.
Definition: cpl_conv.cpp:1014
long CPLScanLong(const char *, int)
Scan up to a maximum number of characters from a string and convert the result to a long...
Definition: cpl_conv.cpp:821
const char * CPLGetBasename(const char *)
Extract basename (non-directory, non-extension) portion of filename.
Definition: cpl_path.cpp:262
void * CPLCalloc(size_t, size_t) CPL_WARN_UNUSED_RESULT
Safe version of calloc().
Definition: cpl_conv.cpp:82
double CPLAtofM(const char *)
Converts ASCII string to floating point number using any numeric locale.
Definition: cpl_strtod.cpp:161
double CPLAtofDelim(const char *, char)
Converts ASCII string to floating point number.
Definition: cpl_strtod.cpp:94
const char * CPLGetExtension(const char *)
Extract filename extension from full filename.
Definition: cpl_path.cpp:312
const char * CPLGetFilename(const char *)
Extract non-directory portion of filename.
Definition: cpl_path.cpp:230
int CPLPrintUIntBig(char *, GUIntBig, int)
Print GUIntBig value into specified string buffer.
Definition: cpl_conv.cpp:1189
double CPLPackedDMSToDec(double)
Convert a packed DMS value (DDDMMMSSS.SS) into decimal degrees.
Definition: cpl_conv.cpp:1898
void * CPLZLibDeflate(const void *ptr, size_t nBytes, int nLevel, void *outptr, size_t nOutAvailableBytes, size_t *pnOutBytes)
Compress a buffer with ZLib DEFLATE compression.
Definition: cpl_conv.cpp:2528
char * CPLScanString(const char *, int, int, int)
Scan up to a maximum number of characters from a given string, allocate a buffer for a new string and...
Definition: cpl_conv.cpp:765
char ** CPLCorrespondingPaths(const char *pszOldFilename, const char *pszNewFilename, char **papszFileList)
Identify corresponding paths.
Definition: cpl_path.cpp:866
void CPLCloseShared(FILE *)
Close shared file.
Definition: cpl_conv.cpp:2087
const char * CPLCleanTrailingSlash(const char *)
Remove trailing forward/backward slash from the path for unix/windows resp.
Definition: cpl_path.cpp:817

Generated for GDAL by doxygen 1.8.6.