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