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