1 /******************************************************************************
2  * $Id: cpl_conv.h daf8a2abc014b937ac276c213cf26e843121f6cb 2021-02-24 11:01:06 +0100 Even 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 spatialys.com>
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 
39 /**
40  * \file cpl_conv.h
41  *
42  * Various convenience functions for CPL.
43  *
44  */
45 
46 /* -------------------------------------------------------------------- */
47 /*      Runtime check of various configuration items.                   */
48 /* -------------------------------------------------------------------- */
49 CPL_C_START
50 
51 /*! @cond Doxygen_Suppress */
52 void CPL_DLL CPLVerifyConfiguration(void);
53 /*! @endcond */
54 
55 const char CPL_DLL * CPL_STDCALL
56 CPLGetConfigOption( const char *, const char * ) CPL_WARN_UNUSED_RESULT;
57 const char CPL_DLL * CPL_STDCALL
58 CPLGetThreadLocalConfigOption( const char *, const char * ) CPL_WARN_UNUSED_RESULT;
59 void CPL_DLL CPL_STDCALL CPLSetConfigOption( const char *, const char * );
60 void CPL_DLL CPL_STDCALL CPLSetThreadLocalConfigOption( const char *pszKey,
61                                                         const char *pszValue );
62 /*! @cond Doxygen_Suppress */
63 void CPL_DLL CPL_STDCALL CPLFreeConfig(void);
64 /*! @endcond */
65 char CPL_DLL** CPLGetConfigOptions(void);
66 void CPL_DLL   CPLSetConfigOptions(const char* const * papszConfigOptions);
67 char CPL_DLL** CPLGetThreadLocalConfigOptions(void);
68 void CPL_DLL   CPLSetThreadLocalConfigOptions(const char* const * papszConfigOptions);
69 void CPL_DLL   CPLLoadConfigOptionsFromFile(const char* pszFilename, int bOverrideEnvVars);
70 void CPL_DLL   CPLLoadConfigOptionsFromPredefinedFiles(void);
71 
72 /* -------------------------------------------------------------------- */
73 /*      Safe malloc() API.  Thin cover over VSI functions with fatal    */
74 /*      error reporting if memory allocation fails.                     */
75 /* -------------------------------------------------------------------- */
76 void CPL_DLL *CPLMalloc( size_t ) CPL_WARN_UNUSED_RESULT;
77 void CPL_DLL *CPLCalloc( size_t, size_t ) CPL_WARN_UNUSED_RESULT;
78 void CPL_DLL *CPLRealloc( void *, size_t ) CPL_WARN_UNUSED_RESULT;
79 char CPL_DLL *CPLStrdup( const char * ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
80 char CPL_DLL *CPLStrlwr( char *);
81 
82 /** Alias of VSIFree() */
83 #define CPLFree VSIFree
84 
85 /* -------------------------------------------------------------------- */
86 /*      Read a line from a text file, and strip of CR/LF.               */
87 /* -------------------------------------------------------------------- */
88 char CPL_DLL *CPLFGets( char *, int, FILE *);
89 const char CPL_DLL *CPLReadLine( FILE * );
90 const char CPL_DLL *CPLReadLineL( VSILFILE * );
91 const char CPL_DLL *CPLReadLine2L( VSILFILE *, int, CSLConstList );
92 const char CPL_DLL *CPLReadLine3L( VSILFILE *, int, int *, CSLConstList );
93 
94 /* -------------------------------------------------------------------- */
95 /*      Convert ASCII string to floating point number                  */
96 /*      (THESE FUNCTIONS ARE NOT LOCALE AWARE!).                        */
97 /* -------------------------------------------------------------------- */
98 double CPL_DLL CPLAtof(const char *);
99 double CPL_DLL CPLAtofDelim(const char *, char);
100 double CPL_DLL CPLStrtod(const char *, char **);
101 double CPL_DLL CPLStrtodDelim(const char *, char **, char);
102 float CPL_DLL CPLStrtof(const char *, char **);
103 float CPL_DLL CPLStrtofDelim(const char *, char **, char);
104 
105 /* -------------------------------------------------------------------- */
106 /*      Convert number to string.  This function is locale agnostic     */
107 /*      (i.e. it will support "," or "." regardless of current locale)  */
108 /* -------------------------------------------------------------------- */
109 double CPL_DLL CPLAtofM(const char *);
110 
111 /* -------------------------------------------------------------------- */
112 /*      Read a numeric value from an ASCII character string.            */
113 /* -------------------------------------------------------------------- */
114 char CPL_DLL *CPLScanString( const char *, int, int, int );
115 double CPL_DLL CPLScanDouble( const char *, int );
116 long CPL_DLL CPLScanLong( const char *, int );
117 unsigned long CPL_DLL CPLScanULong( const char *, int );
118 GUIntBig CPL_DLL CPLScanUIntBig( const char *, int );
119 GIntBig CPL_DLL CPLAtoGIntBig( const char* pszString );
120 GIntBig CPL_DLL CPLAtoGIntBigEx( const char* pszString, int bWarn, int *pbOverflow );
121 void CPL_DLL *CPLScanPointer( const char *, int );
122 
123 /* -------------------------------------------------------------------- */
124 /*      Print a value to an ASCII character string.                     */
125 /* -------------------------------------------------------------------- */
126 int CPL_DLL CPLPrintString( char *, const char *, int );
127 int CPL_DLL CPLPrintStringFill( char *, const char *, int );
128 int CPL_DLL CPLPrintInt32( char *, GInt32 , int );
129 int CPL_DLL CPLPrintUIntBig( char *, GUIntBig , int );
130 int CPL_DLL CPLPrintDouble( char *, const char *, double, const char * );
131 int CPL_DLL CPLPrintTime( char *, int , const char *, const struct tm *,
132                           const char * );
133 int CPL_DLL CPLPrintPointer( char *, void *, int );
134 
135 /* -------------------------------------------------------------------- */
136 /*      Fetch a function from DLL / so.                                 */
137 /* -------------------------------------------------------------------- */
138 
139 void CPL_DLL *CPLGetSymbol( const char *, const char * );
140 
141 /* -------------------------------------------------------------------- */
142 /*      Fetch executable path.                                          */
143 /* -------------------------------------------------------------------- */
144 int CPL_DLL CPLGetExecPath( char *pszPathBuf, int nMaxLength );
145 
146 /* -------------------------------------------------------------------- */
147 /*      Filename handling functions.                                    */
148 /* -------------------------------------------------------------------- */
149 const char CPL_DLL *CPLGetPath( const char * ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
150 const char CPL_DLL *CPLGetDirname( const char * ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
151 const char CPL_DLL *CPLGetFilename( const char * ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
152 const char CPL_DLL *CPLGetBasename( const char * ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
153 const char CPL_DLL *CPLGetExtension( const char * ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
154 char       CPL_DLL *CPLGetCurrentDir(void);
155 const char CPL_DLL *CPLFormFilename( const char *pszPath,
156                                      const char *pszBasename,
157                                      const char *pszExtension ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
158 const char CPL_DLL *CPLFormCIFilename( const char *pszPath,
159                                        const char *pszBasename,
160                                        const char *pszExtension ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
161 const char CPL_DLL *CPLResetExtension( const char *, const char * ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
162 const char CPL_DLL *CPLProjectRelativeFilename( const char *pszProjectDir,
163                                             const char *pszSecondaryFilename ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
164 int CPL_DLL CPLIsFilenameRelative( const char *pszFilename );
165 const char CPL_DLL *CPLExtractRelativePath(const char *, const char *, int *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
166 const char CPL_DLL *CPLCleanTrailingSlash( const char * ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
167 char CPL_DLL      **CPLCorrespondingPaths( const char *pszOldFilename,
168                                            const char *pszNewFilename,
169                                            char **papszFileList ) CPL_WARN_UNUSED_RESULT;
170 int CPL_DLL CPLCheckForFile( char *pszFilename, char **papszSiblingList );
171 
172 const char CPL_DLL *CPLGenerateTempFilename( const char *pszStem ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
173 const char CPL_DLL *CPLExpandTilde( const char *pszFilename ) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL;
174 const char CPL_DLL *CPLGetHomeDir(void) CPL_WARN_UNUSED_RESULT;
175 const char CPL_DLL *CPLLaunderForFilename(const char* pszName,
176                                           const char* pszOutputPath ) CPL_WARN_UNUSED_RESULT;
177 
178 /* -------------------------------------------------------------------- */
179 /*      Find File Function                                              */
180 /* -------------------------------------------------------------------- */
181 
182 /** Callback for CPLPushFileFinder */
183 typedef char const *(*CPLFileFinder)(const char *, const char *);
184 
185 const char    CPL_DLL *CPLFindFile(const char *pszClass,
186                                    const char *pszBasename);
187 const char    CPL_DLL *CPLDefaultFindFile(const char *pszClass,
188                                           const char *pszBasename);
189 void          CPL_DLL CPLPushFileFinder( CPLFileFinder pfnFinder );
190 CPLFileFinder CPL_DLL CPLPopFileFinder(void);
191 void          CPL_DLL CPLPushFinderLocation( const char * );
192 void          CPL_DLL CPLPopFinderLocation(void);
193 void          CPL_DLL CPLFinderClean(void);
194 
195 /* -------------------------------------------------------------------- */
196 /*      Safe version of stat() that works properly on stuff like "C:".  */
197 /* -------------------------------------------------------------------- */
198 int CPL_DLL     CPLStat( const char *, VSIStatBuf * ) CPL_WARN_UNUSED_RESULT;
199 
200 /* -------------------------------------------------------------------- */
201 /*      Reference counted file handle manager.  Makes sharing file      */
202 /*      handles more practical.                                         */
203 /* -------------------------------------------------------------------- */
204 
205 /** Information on a shared file */
206 typedef struct {
207     FILE *fp;               /**< File pointer */
208     int   nRefCount;        /**< Reference counter */
209     int   bLarge;           /**< Whether fp must be interpreted as VSIFILE* */
210     char  *pszFilename;     /**< Filename */
211     char  *pszAccess;       /**< Access mode */
212 } CPLSharedFileInfo;
213 
214 FILE CPL_DLL    *CPLOpenShared( const char *, const char *, int );
215 void CPL_DLL     CPLCloseShared( FILE * );
216 CPLSharedFileInfo CPL_DLL *CPLGetSharedList( int * );
217 void CPL_DLL     CPLDumpSharedList( FILE * );
218 /*! @cond Doxygen_Suppress */
219 void CPL_DLL     CPLCleanupSharedFileMutex( void );
220 /*! @endcond */
221 
222 /* -------------------------------------------------------------------- */
223 /*      DMS to Dec to DMS conversion.                                   */
224 /* -------------------------------------------------------------------- */
225 double CPL_DLL CPLDMSToDec( const char *is );
226 const char CPL_DLL *CPLDecToDMS( double dfAngle, const char * pszAxis,
227                                  int nPrecision );
228 double CPL_DLL CPLPackedDMSToDec( double );
229 double CPL_DLL CPLDecToPackedDMS( double dfDec );
230 
231 void CPL_DLL CPLStringToComplex( const char *pszString,
232                                  double *pdfReal, double *pdfImag );
233 
234 /* -------------------------------------------------------------------- */
235 /*      Misc other functions.                                           */
236 /* -------------------------------------------------------------------- */
237 int CPL_DLL CPLUnlinkTree( const char * );
238 int CPL_DLL CPLCopyFile( const char *pszNewPath, const char *pszOldPath );
239 int CPL_DLL CPLCopyTree( const char *pszNewPath, const char *pszOldPath );
240 int CPL_DLL CPLMoveFile( const char *pszNewPath, const char *pszOldPath );
241 int CPL_DLL CPLSymlink( const char* pszOldPath, const char* pszNewPath, CSLConstList papszOptions );
242 
243 /* -------------------------------------------------------------------- */
244 /*      ZIP Creation.                                                   */
245 /* -------------------------------------------------------------------- */
246 
247 /*! @cond Doxygen_Suppress */
248 #define CPL_ZIP_API_OFFERED
249 /*! @endcond */
250 void CPL_DLL  *CPLCreateZip( const char *pszZipFilename, char **papszOptions );
251 CPLErr CPL_DLL CPLCreateFileInZip( void *hZip, const char *pszFilename,
252                                    char **papszOptions );
253 CPLErr CPL_DLL CPLWriteFileInZip( void *hZip, const void *pBuffer, int nBufferSize );
254 CPLErr CPL_DLL CPLCloseFileInZip( void *hZip );
255 CPLErr CPL_DLL CPLCloseZip( void *hZip );
256 
257 /* -------------------------------------------------------------------- */
258 /*      ZLib compression                                                */
259 /* -------------------------------------------------------------------- */
260 
261 void CPL_DLL *CPLZLibDeflate( const void* ptr, size_t nBytes, int nLevel,
262                               void* outptr, size_t nOutAvailableBytes,
263                               size_t* pnOutBytes );
264 void CPL_DLL *CPLZLibInflate( const void* ptr, size_t nBytes,
265                               void* outptr, size_t nOutAvailableBytes,
266                               size_t* pnOutBytes );
267 
268 /* -------------------------------------------------------------------- */
269 /*      XML validation.                                                 */
270 /* -------------------------------------------------------------------- */
271 int CPL_DLL CPLValidateXML(const char* pszXMLFilename,
272                            const char* pszXSDFilename,
273                            CSLConstList papszOptions);
274 
275 /* -------------------------------------------------------------------- */
276 /*      Locale handling. Prevents parallel executions of setlocale().   */
277 /* -------------------------------------------------------------------- */
278 char* CPLsetlocale (int category, const char* locale);
279 /*! @cond Doxygen_Suppress */
280 void CPLCleanupSetlocaleMutex(void);
281 /*! @endcond */
282 
283 /*!
284     CPLIsPowerOfTwo()
285     @param i - tested number
286     @return TRUE if i is power of two otherwise return FALSE
287 */
288 int CPL_DLL CPLIsPowerOfTwo( unsigned int i );
289 
290 CPL_C_END
291 
292 /* -------------------------------------------------------------------- */
293 /*      C++ object for temporarily forcing a LC_NUMERIC locale to "C".  */
294 /* -------------------------------------------------------------------- */
295 
296 //! @cond Doxygen_Suppress
297 #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
298 
299 extern "C++"
300 {
301 class CPL_DLL CPLLocaleC
302 {
303     CPL_DISALLOW_COPY_ASSIGN(CPLLocaleC)
304 public:
305     CPLLocaleC();
306     ~CPLLocaleC();
307 
308 private:
309     char *pszOldLocale;
310 };
311 
312 // Does the same as CPLLocaleC except that, when available, it tries to
313 // only affect the current thread. But code that would be dependent of
314 // setlocale(LC_NUMERIC, NULL) returning "C", such as current proj.4 versions,
315 // will not work depending on the actual implementation
316 class CPLThreadLocaleCPrivate;
317 class CPL_DLL CPLThreadLocaleC
318 {
319     CPL_DISALLOW_COPY_ASSIGN(CPLThreadLocaleC)
320 
321 public:
322     CPLThreadLocaleC();
323     ~CPLThreadLocaleC();
324 
325 private:
326     CPLThreadLocaleCPrivate* m_private;
327 };
328 }
329 
330 #endif /* def __cplusplus */
331 //! @endcond
332 
333 
334 
335 /* -------------------------------------------------------------------- */
336 /*      C++ object for temporarily forcing a config option              */
337 /* -------------------------------------------------------------------- */
338 
339 //! @cond Doxygen_Suppress
340 #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
341 
342 extern "C++"
343 {
344 class CPL_DLL CPLConfigOptionSetter
345 {
346     CPL_DISALLOW_COPY_ASSIGN(CPLConfigOptionSetter)
347 public:
348     CPLConfigOptionSetter(const char* pszKey, const char* pszValue,
349                           bool bSetOnlyIfUndefined);
350     ~CPLConfigOptionSetter();
351 
352 private:
353     char* m_pszKey;
354     char *m_pszOldValue;
355     bool m_bRestoreOldValue;
356 };
357 }
358 
359 #endif /* def __cplusplus */
360 //! @endcond
361 
362 #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
363 
364 extern "C++"
365 {
366 
367 #ifndef DOXYGEN_SKIP
368 #include <type_traits> // for std::is_base_of
369 #endif
370 
371 namespace cpl
372 {
373     /** Use cpl::down_cast<Derived*>(pointer_to_base) as equivalent of
374      * static_cast<Derived*>(pointer_to_base) with safe checking in debug
375      * mode.
376      *
377      * Only works if no virtual inheritance is involved.
378      *
379      * @param f pointer to a base class
380      * @return pointer to a derived class
381      */
down_cast(From * f)382     template<typename To, typename From> inline To down_cast(From* f)
383     {
384         static_assert(
385             (std::is_base_of<From,
386                             typename std::remove_pointer<To>::type>::value),
387             "target type not derived from source type");
388         CPLAssert(f == nullptr || dynamic_cast<To>(f) != nullptr);
389         return static_cast<To>(f);
390     }
391 }
392 } // extern "C++"
393 
394 #endif /* def __cplusplus */
395 
396 #endif /* ndef CPL_CONV_H_INCLUDED */
397