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