SDTS_AL
|
Go to the source code of this file.
Classes | |
struct | CPLSharedFileInfo |
Macros | |
#define | CPLFree VSIFree |
Typedefs | |
typedef const char *(* | CPLFileFinder) (const char *, const char *) |
Functions | |
CPL_C_START const char CPL_DLL *CPL_STDCALL | CPLGetConfigOption (const char *, const char *) CPL_WARN_UNUSED_RESULT |
const char CPL_DLL *CPL_STDCALL | CPLGetThreadLocalConfigOption (const char *, const char *) CPL_WARN_UNUSED_RESULT |
void CPL_DLL CPL_STDCALL | CPLSetConfigOption (const char *, const char *) |
void CPL_DLL CPL_STDCALL | CPLSetThreadLocalConfigOption (const char *pszKey, const char *pszValue) |
char CPL_DLL ** | CPLGetConfigOptions (void) |
void CPL_DLL | CPLSetConfigOptions (const char *const *papszConfigOptions) |
char CPL_DLL ** | CPLGetThreadLocalConfigOptions (void) |
void CPL_DLL | CPLSetThreadLocalConfigOptions (const char *const *papszConfigOptions) |
void CPL_DLL * | CPLMalloc (size_t) CPL_WARN_UNUSED_RESULT |
void CPL_DLL * | CPLCalloc (size_t, size_t) CPL_WARN_UNUSED_RESULT |
void CPL_DLL * | CPLRealloc (void *, size_t) CPL_WARN_UNUSED_RESULT |
char CPL_DLL * | CPLStrdup (const char *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL |
char CPL_DLL * | CPLStrlwr (char *) |
char CPL_DLL * | CPLFGets (char *, int, FILE *) |
const char CPL_DLL * | CPLReadLine (FILE *) |
const char CPL_DLL * | CPLReadLineL (VSILFILE *) |
double CPL_DLL | CPLAtof (const char *) |
double CPL_DLL | CPLAtofDelim (const char *, char) |
double CPL_DLL | CPLStrtod (const char *, char **) |
double CPL_DLL | CPLStrtodDelim (const char *, char **, char) |
float CPL_DLL | CPLStrtof (const char *, char **) |
float CPL_DLL | CPLStrtofDelim (const char *, char **, char) |
double CPL_DLL | CPLAtofM (const char *) |
char CPL_DLL * | CPLScanString (const char *, int, int, int) |
double CPL_DLL | CPLScanDouble (const char *, int) |
long CPL_DLL | CPLScanLong (const char *, int) |
unsigned long CPL_DLL | CPLScanULong (const char *, int) |
GUIntBig CPL_DLL | CPLScanUIntBig (const char *, int) |
GIntBig CPL_DLL | CPLAtoGIntBig (const char *pszString) |
GIntBig CPL_DLL | CPLAtoGIntBigEx (const char *pszString, int bWarn, int *pbOverflow) |
void CPL_DLL * | CPLScanPointer (const char *, int) |
int CPL_DLL | CPLPrintString (char *, const char *, int) |
int CPL_DLL | CPLPrintStringFill (char *, const char *, int) |
int CPL_DLL | CPLPrintInt32 (char *, GInt32, int) |
int CPL_DLL | CPLPrintUIntBig (char *, GUIntBig, int) |
int CPL_DLL | CPLPrintTime (char *, int, const char *, const struct tm *, const char *) |
int CPL_DLL | CPLPrintPointer (char *, void *, int) |
void CPL_DLL * | CPLGetSymbol (const char *, const char *) |
const char CPL_DLL * | CPLGetPath (const char *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL |
const char CPL_DLL * | CPLGetDirname (const char *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL |
const char CPL_DLL * | CPLGetFilename (const char *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL |
const char CPL_DLL * | CPLGetBasename (const char *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL |
const char CPL_DLL * | CPLGetExtension (const char *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL |
char CPL_DLL * | CPLGetCurrentDir (void) |
const char CPL_DLL * | CPLFormFilename (const char *pszPath, const char *pszBasename, const char *pszExtension) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL |
const char CPL_DLL * | CPLFormCIFilename (const char *pszPath, const char *pszBasename, const char *pszExtension) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL |
const char CPL_DLL * | CPLResetExtension (const char *, const char *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL |
const char CPL_DLL * | CPLProjectRelativeFilename (const char *pszProjectDir, const char *pszSecondaryFilename) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL |
int CPL_DLL | CPLIsFilenameRelative (const char *pszFilename) |
const char CPL_DLL * | CPLExtractRelativePath (const char *, const char *, int *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL |
const char CPL_DLL * | CPLCleanTrailingSlash (const char *) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL |
char CPL_DLL ** | CPLCorrespondingPaths (const char *pszOldFilename, const char *pszNewFilename, char **papszFileList) CPL_WARN_UNUSED_RESULT |
int CPL_DLL | CPLCheckForFile (char *pszFilename, char **papszSiblingList) |
const char CPL_DLL * | CPLGenerateTempFilename (const char *pszStem) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL |
const char CPL_DLL * | CPLExpandTilde (const char *pszFilename) CPL_WARN_UNUSED_RESULT CPL_RETURNS_NONNULL |
const char CPL_DLL * | CPLFindFile (const char *pszClass, const char *pszBasename) |
const char CPL_DLL * | CPLDefaultFindFile (const char *pszClass, const char *pszBasename) |
void CPL_DLL | CPLPushFileFinder (CPLFileFinder pfnFinder) |
CPLFileFinder CPL_DLL | CPLPopFileFinder (void) |
void CPL_DLL | CPLPushFinderLocation (const char *) |
void CPL_DLL | CPLPopFinderLocation (void) |
void CPL_DLL | CPLFinderClean (void) |
int CPL_DLL | CPLStat (const char *, VSIStatBuf *) CPL_WARN_UNUSED_RESULT |
FILE CPL_DLL * | CPLOpenShared (const char *, const char *, int) |
void CPL_DLL | CPLCloseShared (FILE *) |
CPLSharedFileInfo CPL_DLL * | CPLGetSharedList (int *) |
void CPL_DLL | CPLDumpSharedList (FILE *) |
double CPL_DLL | CPLDMSToDec (const char *is) |
const char CPL_DLL * | CPLDecToDMS (double dfAngle, const char *pszAxis, int nPrecision) |
double CPL_DLL | CPLPackedDMSToDec (double) |
double CPL_DLL | CPLDecToPackedDMS (double dfDec) |
void CPL_DLL | CPLStringToComplex (const char *pszString, double *pdfReal, double *pdfImag) |
int CPL_DLL | CPLUnlinkTree (const char *) |
int CPL_DLL | CPLCopyFile (const char *pszNewPath, const char *pszOldPath) |
int CPL_DLL | CPLCopyTree (const char *pszNewPath, const char *pszOldPath) |
int CPL_DLL | CPLMoveFile (const char *pszNewPath, const char *pszOldPath) |
int CPL_DLL | CPLSymlink (const char *pszOldPath, const char *pszNewPath, char **papszOptions) |
void CPL_DLL * | CPLCreateZip (const char *pszZipFilename, char **papszOptions) |
CPLErr CPL_DLL | CPLCreateFileInZip (void *hZip, const char *pszFilename, char **papszOptions) |
CPLErr CPL_DLL | CPLWriteFileInZip (void *hZip, const void *pBuffer, int nBufferSize) |
CPLErr CPL_DLL | CPLCloseFileInZip (void *hZip) |
CPLErr CPL_DLL | CPLCloseZip (void *hZip) |
void CPL_DLL * | CPLZLibInflate (const void *ptr, size_t nBytes, void *outptr, size_t nOutAvailableBytes, size_t *pnOutBytes) |
Uncompress a buffer compressed with ZLib DEFLATE compression. More... | |
char * | CPLsetlocale (int category, const char *locale) |
Various convenience functions for CPL.
typedef const char*(* CPLFileFinder) (const char *, const char *) |
Callback for CPLPushFileFinder
double CPL_DLL CPLAtof | ( | const char * | nptr | ) |
Converts ASCII string to floating point number.
This function converts the initial portion of the string pointed to by nptr to double floating point representation. The behaviour is the same as
CPLStrtod(nptr, (char **)NULL);
This function does the same as standard atof(3), but does not take locale in account. That means, the decimal delimiter is always '.' (decimal point). Use CPLAtofDelim() function if you want to specify custom delimiter.
IMPORTANT NOTE:
Existence of this function does not mean you should always use it. Sometimes you should use standard locale aware atof(3) and its family. When you need to process the user's input (for example, command line parameters) use atof(3), because the user works in a localized environment and the user's input will be done according to the locale set. In particular that means we should not make assumptions about character used as decimal delimiter, it can be either "." or ",".
But when you are parsing some ASCII file in predefined format, you most likely need CPLAtof(), because such files distributed across the systems with different locales and floating point representation should be considered as a part of file format. If the format uses "." as a delimiter the same character must be used when parsing number regardless of actual locale setting.
nptr | Pointer to string to convert. |
double CPL_DLL CPLAtofDelim | ( | const char * | nptr, |
char | point | ||
) |
Converts ASCII string to floating point number.
This function converts the initial portion of the string pointed to by nptr to double floating point representation. The behaviour is the same as
CPLStrtodDelim(nptr, (char **)NULL, point);
This function does the same as standard atof(3), but does not take locale in account. Instead of locale defined decimal delimiter you can specify your own one. Also see notes for CPLAtof() function.
nptr | Pointer to string to convert. |
point | Decimal delimiter. |
double CPL_DLL CPLAtofM | ( | const char * | nptr | ) |
Converts ASCII string to floating point number using any numeric locale.
This function converts the initial portion of the string pointed to by nptr to double floating point representation. This function does the same as standard atof(), but it allows a variety of locale representations. That is it supports numeric values with either a comma or a period for the decimal delimiter.
PS. The M stands for Multi-lingual.
nptr | The string to convert. |
GIntBig CPL_DLL CPLAtoGIntBig | ( | const char * | pszString | ) |
Convert a string to a 64 bit signed integer.
pszString | String containing 64 bit signed integer. |
GIntBig CPL_DLL CPLAtoGIntBigEx | ( | const char * | pszString, |
int | bWarn, | ||
int * | pbOverflow | ||
) |
Convert a string to a 64 bit signed integer.
pszString | String containing 64 bit signed integer. |
bWarn | Issue a warning if an overflow occurs during conversion |
pbOverflow | Pointer to an integer to store if an overflow occurred, or NULL |
void CPL_DLL* CPLCalloc | ( | size_t | nCount, |
size_t | nSize | ||
) |
Safe version of calloc().
This function is like the C library calloc(), but raises a CE_Fatal error with CPLError() if it fails to allocate the desired memory. It should be used for small memory allocations that are unlikely to fail and for which the application is unwilling to test for out of memory conditions. It uses VSICalloc() to get the memory, so any hooking of VSICalloc() will apply to CPLCalloc() as well. CPLFree() or VSIFree() can be used free memory allocated by CPLCalloc().
nCount | number of objects to allocate. |
nSize | size (in bytes) of object to allocate. |
int CPL_DLL CPLCheckForFile | ( | char * | pszFilename, |
char ** | papszSiblingFiles | ||
) |
Check for file existence.
The function checks if a named file exists in the filesystem, hopefully in an efficient fashion if a sibling file list is available. It exists primarily to do faster file checking for functions like GDAL open methods that get a list of files from the target directory.
If the sibling file list exists (is not NULL) it is assumed to be a list of files in the same directory as the target file, and it will be checked (case insensitively) for a match. If a match is found, pszFilename is updated with the correct case and TRUE is returned.
If papszSiblingFiles is NULL, a VSIStatL() is used to test for the files existence, and no case insensitive testing is done.
pszFilename | name of file to check for - filename case updated in some cases. |
papszSiblingFiles | a list of files in the same directory as pszFilename if available, or NULL. This list should have no path components. |
const char CPL_DLL* CPLCleanTrailingSlash | ( | const char * | pszPath | ) |
Remove trailing forward/backward slash from the path for UNIX/Windows resp.
Returns a string containing the portion of the passed path string with trailing slash removed. If there is no path in the passed filename an empty string will be returned (not NULL).
CPLCleanTrailingSlash( "abc/def/" ) == "abc/def" CPLCleanTrailingSlash( "abc/def" ) == "abc/def" CPLCleanTrailingSlash( "c:\abc\def\" ) == "c:\abc\def" CPLCleanTrailingSlash( "c:\abc\def" ) == "c:\abc\def" CPLCleanTrailingSlash( "abc" ) == "abc"
pszPath | the path to be cleaned up |
CPLErr CPL_DLL CPLCloseFileInZip | ( | void * | hZip | ) |
Close current file inside ZIP file
void CPL_DLL CPLCloseShared | ( | FILE * | fp | ) |
Close shared file.
Dereferences the indicated file handle, and closes it if the reference count has dropped to zero. A CPLError() is issued if the file is not in the shared file list.
fp | file handle from CPLOpenShared() to deaccess. |
CPLErr CPL_DLL CPLCloseZip | ( | void * | hZip | ) |
Close ZIP file
int CPL_DLL CPLCopyFile | ( | const char * | pszNewPath, |
const char * | pszOldPath | ||
) |
Copy a file
int CPL_DLL CPLCopyTree | ( | const char * | pszNewPath, |
const char * | pszOldPath | ||
) |
Recursively copy a tree
char CPL_DLL** CPLCorrespondingPaths | ( | const char * | pszOldFilename, |
const char * | pszNewFilename, | ||
char ** | papszFileList | ||
) |
Identify corresponding paths.
Given a prototype old and new filename this function will attempt to determine corresponding names for a set of other old filenames that will rename them in a similar manner. This correspondence assumes there are two possibly kinds of renaming going on. A change of path, and a change of filename stem.
If a consistent renaming cannot be established for all the files this function will return indicating an error.
The returned file list becomes owned by the caller and should be destroyed with CSLDestroy().
pszOldFilename | path to old prototype file. |
pszNewFilename | path to new prototype file. |
papszFileList | list of other files associated with pszOldFilename to rename similarly. |
CPLErr CPL_DLL CPLCreateFileInZip | ( | void * | hZip, |
const char * | pszFilename, | ||
char ** | papszOptions | ||
) |
Create a file in a ZIP file
void CPL_DLL* CPLCreateZip | ( | const char * | pszZipFilename, |
char ** | papszOptions | ||
) |
Create ZIP file
const char CPL_DLL* CPLDecToDMS | ( | double | dfAngle, |
const char * | pszAxis, | ||
int | nPrecision | ||
) |
Translate a decimal degrees value to a DMS string with hemisphere.
double CPL_DLL CPLDecToPackedDMS | ( | double | dfDec | ) |
Convert decimal degrees into packed DMS value (DDDMMMSSS.SS).
This function converts a value, specified in decimal degrees into packed DMS angle. The standard packed DMS format is:
degrees * 1000000 + minutes * 1000 + seconds
See also CPLPackedDMSToDec().
dfDec | Angle in decimal degrees. |
const char CPL_DLL* CPLDefaultFindFile | ( | const char * | , |
const char * | pszBasename | ||
) |
CPLDefaultFindFile
double CPL_DLL CPLDMSToDec | ( | const char * | is | ) |
CPLDMSToDec
void CPL_DLL CPLDumpSharedList | ( | FILE * | fp | ) |
Report open shared files.
Dumps all open shared files to the indicated file handle. If the file handle is NULL information is sent via the CPLDebug() call.
fp | File handle to write to. |
const char CPL_DLL* CPLExpandTilde | ( | const char * | pszFilename | ) |
Expands ~/ at start of filename.
Assumes that the HOME configuration option is defined.
pszFilename | filename potentially starting with ~/ |
const char CPL_DLL* CPLExtractRelativePath | ( | const char * | pszBaseDir, |
const char * | pszTarget, | ||
int * | pbGotRelative | ||
) |
Get relative path from directory to target file.
Computes a relative path for pszTarget relative to pszBaseDir. Currently this only works if they share a common base path. The returned path is normally into the pszTarget string. It should only be considered valid as long as pszTarget is valid or till the next call to this function, whichever comes first.
pszBaseDir | the name of the directory relative to which the path should be computed. pszBaseDir may be NULL in which case the original target is returned without relativizing. |
pszTarget | the filename to be changed to be relative to pszBaseDir. |
pbGotRelative | Pointer to location in which a flag is placed indicating that the returned path is relative to the basename (TRUE) or not (FALSE). This pointer may be NULL if flag is not desired. |
char CPL_DLL* CPLFGets | ( | char * | pszBuffer, |
int | nBufferSize, | ||
FILE * | fp | ||
) |
Reads in at most one less than nBufferSize characters from the fp stream and stores them into the buffer pointed to by pszBuffer. Reading stops after an EOF or a newline. If a newline is read, it is not stored into the buffer. A '\0' is stored after the last character in the buffer. All three types of newline terminators recognized by the CPLFGets(): single '\r' and '\n' and '\r\n' combination.
pszBuffer | pointer to the targeting character buffer. |
nBufferSize | maximum size of the string to read (not including terminating '\0'). |
fp | file pointer to read from. |
void CPL_DLL CPLFinderClean | ( | void | ) |
CPLFinderClean
const char CPL_DLL* CPLFindFile | ( | const char * | pszClass, |
const char * | pszBasename | ||
) |
CPLFindFile
const char CPL_DLL* CPLFormCIFilename | ( | const char * | pszPath, |
const char * | pszBasename, | ||
const char * | pszExtension | ||
) |
Case insensitive file searching, returning full path.
This function tries to return the path to a file regardless of whether the file exactly matches the basename, and extension case, or is all upper case, or all lower case. The path is treated as case sensitive. This function is equivalent to CPLFormFilename() on case insensitive file systems (like Windows).
pszPath | directory path to the directory containing the file. This may be relative or absolute, and may have a trailing path separator or not. May be NULL. |
pszBasename | file basename. May optionally have path and/or extension. May not be NULL. |
pszExtension | file extension, optionally including the period. May be NULL. |
const char CPL_DLL* CPLFormFilename | ( | const char * | pszPath, |
const char * | pszBasename, | ||
const char * | pszExtension | ||
) |
Build a full file path from a passed path, file basename and extension.
The path, and extension are optional. The basename may in fact contain an extension if desired.
CPLFormFilename("abc/xyz", "def", ".dat" ) == "abc/xyz/def.dat" CPLFormFilename(NULL,"def", NULL ) == "def" CPLFormFilename(NULL, "abc/def.dat", NULL ) == "abc/def.dat" CPLFormFilename("/abc/xyz/", "def.dat", NULL ) == "/abc/xyz/def.dat"
pszPath | directory path to the directory containing the file. This may be relative or absolute, and may have a trailing path separator or not. May be NULL. |
pszBasename | file basename. May optionally have path and/or extension. Must NOT be NULL. |
pszExtension | file extension, optionally including the period. May be NULL. |
const char CPL_DLL* CPLGenerateTempFilename | ( | const char * | pszStem | ) |
Generate temporary file name.
Returns a filename that may be used for a temporary file. The location of the file tries to follow operating system semantics but may be forced via the CPL_TMPDIR configuration option.
pszStem | if non-NULL this will be part of the filename. |
const char CPL_DLL* CPLGetBasename | ( | const char * | pszFullFilename | ) |
Extract basename (non-directory, non-extension) portion of filename.
Returns a string containing the file basename portion of the passed name. If there is no basename (passed value ends in trailing directory separator, or filename starts with a dot) an empty string is returned.
CPLGetBasename( "abc/def.xyz" ) == "def" CPLGetBasename( "abc/def" ) == "def" CPLGetBasename( "abc/def/" ) == ""
pszFullFilename | the full filename potentially including a path. |
CPL_C_START const char CPL_DLL* CPL_STDCALL CPLGetConfigOption | ( | const char * | pszKey, |
const char * | pszDefault | ||
) |
Get the value of a configuration option.
The value is the value of a (key, value) option set with CPLSetConfigOption(), or CPLSetThreadLocalConfigOption() of the same thread. If the given option was no defined with CPLSetConfigOption(), it tries to find it in environment variables.
Note: the string returned by CPLGetConfigOption() might be short-lived, and in particular it will become invalid after a call to CPLSetConfigOption() with the same key.
To override temporary a potentially existing option with a new value, you can use the following snippet :
// backup old value const char* pszOldValTmp = CPLGetConfigOption(pszKey, NULL); char* pszOldVal = pszOldValTmp ? CPLStrdup(pszOldValTmp) : NULL; // override with new value CPLSetConfigOption(pszKey, pszNewVal); // do something useful // restore old value CPLSetConfigOption(pszKey, pszOldVal); CPLFree(pszOldVal);
pszKey | the key of the option to retrieve |
pszDefault | a default value if the key does not match existing defined options (may be NULL) |
char CPL_DLL** CPLGetConfigOptions | ( | void | ) |
Return the list of configuration options as KEY=VALUE pairs.
The list is the one set through the CPLSetConfigOption() API.
Options that through environment variables or with CPLSetThreadLocalConfigOption() will not be listed.
char CPL_DLL* CPLGetCurrentDir | ( | void | ) |
Get the current working directory name.
const char CPL_DLL* CPLGetDirname | ( | const char * | pszFilename | ) |
Extract directory path portion of filename.
Returns a string containing the directory path portion of the passed filename. If there is no path in the passed filename the dot will be returned. It is the only difference from CPLGetPath().
CPLGetDirname( "abc/def.xyz" ) == "abc" CPLGetDirname( "/abc/def/" ) == "/abc/def" CPLGetDirname( "/" ) == "/" CPLGetDirname( "/abc/def" ) == "/abc" CPLGetDirname( "abc" ) == "."
pszFilename | the filename potentially including a path. |
const char CPL_DLL* CPLGetExtension | ( | const char * | pszFullFilename | ) |
Extract filename extension from full filename.
Returns a string containing the extension portion of the passed name. If there is no extension (the filename has no dot) an empty string is returned. The returned extension will not include the period.
CPLGetExtension( "abc/def.xyz" ) == "xyz" CPLGetExtension( "abc/def" ) == ""
pszFullFilename | the full filename potentially including a path. |
const char CPL_DLL* CPLGetFilename | ( | const char * | pszFullFilename | ) |
Extract non-directory portion of filename.
Returns a string containing the bare filename portion of the passed filename. If there is no filename (passed value ends in trailing directory separator) an empty string is returned.
CPLGetFilename( "abc/def.xyz" ) == "def.xyz" CPLGetFilename( "/abc/def/" ) == "" CPLGetFilename( "abc/def" ) == "def"
pszFullFilename | the full filename potentially including a path. |
const char CPL_DLL* CPLGetPath | ( | const char * | pszFilename | ) |
Extract directory path portion of filename.
Returns a string containing the directory path portion of the passed filename. If there is no path in the passed filename an empty string will be returned (not NULL).
CPLGetPath( "abc/def.xyz" ) == "abc" CPLGetPath( "/abc/def/" ) == "/abc/def" CPLGetPath( "/" ) == "/" CPLGetPath( "/abc/def" ) == "/abc" CPLGetPath( "abc" ) == ""
pszFilename | the filename potentially including a path. |
CPLSharedFileInfo CPL_DLL* CPLGetSharedList | ( | int * | pnCount | ) |
Fetch list of open shared files.
pnCount | place to put the count of entries. |
void CPL_DLL* CPLGetSymbol | ( | const char * | pszLibrary, |
const char * | pszSymbolName | ||
) |
Fetch a function pointer from a shared library / DLL.
This function is meant to abstract access to shared libraries and DLLs and performs functions similar to dlopen()/dlsym() on Unix and LoadLibrary() / GetProcAddress() on Windows.
If no support for loading entry points from a shared library is available this function will always return NULL. Rules on when this function issues a CPLError() or not are not currently well defined, and will have to be resolved in the future.
Currently CPLGetSymbol() doesn't try to:
Some of these issues may be worked on in the future.
pszLibrary | the name of the shared library or DLL containing the function. May contain path to file. If not system supplies search paths will be used. |
pszSymbolName | the name of the function to fetch a pointer to. |
const char CPL_DLL* CPL_STDCALL CPLGetThreadLocalConfigOption | ( | const char * | pszKey, |
const char * | pszDefault | ||
) |
Same as CPLGetConfigOption() but only with options set with CPLSetThreadLocalConfigOption()
char CPL_DLL** CPLGetThreadLocalConfigOptions | ( | void | ) |
Return the list of thread local configuration options as KEY=VALUE pairs.
Options that through environment variables or with CPLSetConfigOption() will not be listed.
int CPL_DLL CPLIsFilenameRelative | ( | const char * | pszFilename | ) |
Is filename relative or absolute?
The test is filesystem convention agnostic. That is it will test for Unix style and windows style path conventions regardless of the actual system in use.
pszFilename | the filename with path to test. |
void CPL_DLL* CPLMalloc | ( | size_t | nSize | ) |
Safe version of malloc().
This function is like the C library malloc(), but raises a CE_Fatal error with CPLError() if it fails to allocate the desired memory. It should be used for small memory allocations that are unlikely to fail and for which the application is unwilling to test for out of memory conditions. It uses VSIMalloc() to get the memory, so any hooking of VSIMalloc() will apply to CPLMalloc() as well. CPLFree() or VSIFree() can be used free memory allocated by CPLMalloc().
nSize | size (in bytes) of memory block to allocate. |
int CPL_DLL CPLMoveFile | ( | const char * | pszNewPath, |
const char * | pszOldPath | ||
) |
Move a file
FILE CPL_DLL* CPLOpenShared | ( | const char * | pszFilename, |
const char * | pszAccess, | ||
int | bLargeIn | ||
) |
Open a shared file handle.
Some operating systems have limits on the number of file handles that can be open at one time. This function attempts to maintain a registry of already open file handles, and reuse existing ones if the same file is requested by another part of the application.
Note that access is only shared for access types "r", "rb", "r+" and "rb+". All others will just result in direct VSIOpen() calls. Keep in mind that a file is only reused if the file name is exactly the same. Different names referring to the same file will result in different handles.
The VSIFOpen() or VSIFOpenL() function is used to actually open the file, when an existing file handle can't be shared.
pszFilename | the name of the file to open. |
pszAccess | the normal fopen()/VSIFOpen() style access string. |
bLargeIn | If TRUE VSIFOpenL() (for large files) will be used instead of VSIFOpen(). |
double CPL_DLL CPLPackedDMSToDec | ( | double | dfPacked | ) |
Convert a packed DMS value (DDDMMMSSS.SS) into decimal degrees.
This function converts a packed DMS angle to seconds. The standard packed DMS format is:
degrees * 1000000 + minutes * 1000 + seconds
Example: angle = 120025045.25 yields deg = 120 min = 25 sec = 45.25
The algorithm used for the conversion is as follows:
Packed DMS values used by the USGS GCTP package and probably by other software.
NOTE: This code does not validate input value. If you give the wrong value, you will get the wrong result.
dfPacked | Angle in packed DMS format. |
CPLFileFinder CPL_DLL CPLPopFileFinder | ( | void | ) |
CPLPopFileFinder
void CPL_DLL CPLPopFinderLocation | ( | void | ) |
CPLPopFinderLocation
int CPL_DLL CPLPrintInt32 | ( | char * | pszBuffer, |
GInt32 | iValue, | ||
int | nMaxLen | ||
) |
Print GInt32 value into specified string buffer. This string will not be NULL-terminated.
pszBuffer | Pointer to the destination string buffer. Should be large enough to hold the resulting string. Note, that the string will not be NULL-terminated, so user should do this himself, if needed. |
iValue | Numerical value to print. |
nMaxLen | Maximum length of the resulting string. If string length is greater than nMaxLen, it will be truncated. |
int CPL_DLL CPLPrintPointer | ( | char * | pszBuffer, |
void * | pValue, | ||
int | nMaxLen | ||
) |
Print pointer value into specified string buffer. This string will not be NULL-terminated.
pszBuffer | Pointer to the destination string buffer. Should be large enough to hold the resulting string. Note, that the string will not be NULL-terminated, so user should do this himself, if needed. |
pValue | Pointer to ASCII encode. |
nMaxLen | Maximum length of the resulting string. If string length is greater than nMaxLen, it will be truncated. |
int CPL_DLL CPLPrintString | ( | char * | pszDest, |
const char * | pszSrc, | ||
int | nMaxLen | ||
) |
Copy the string pointed to by pszSrc, NOT including the terminating ‘\0’ character, to the array pointed to by pszDest.
pszDest | Pointer to the destination string buffer. Should be large enough to hold the resulting string. |
pszSrc | Pointer to the source buffer. |
nMaxLen | Maximum length of the resulting string. If string length is greater than nMaxLen, it will be truncated. |
int CPL_DLL CPLPrintStringFill | ( | char * | pszDest, |
const char * | pszSrc, | ||
int | nMaxLen | ||
) |
Copy the string pointed to by pszSrc, NOT including the terminating ‘\0’ character, to the array pointed to by pszDest. Remainder of the destination string will be filled with space characters. This is only difference from the PrintString().
pszDest | Pointer to the destination string buffer. Should be large enough to hold the resulting string. |
pszSrc | Pointer to the source buffer. |
nMaxLen | Maximum length of the resulting string. If string length is greater than nMaxLen, it will be truncated. |
int CPL_DLL CPLPrintTime | ( | char * | pszBuffer, |
int | nMaxLen, | ||
const char * | pszFormat, | ||
const struct tm * | poBrokenTime, | ||
const char * | pszLocale | ||
) |
Print specified time value accordingly to the format options and specified locale name. This function does following:
pszBuffer | Pointer to the destination string buffer. Should be large enough to hold the resulting string. Note, that the string will not be NULL-terminated, so user should do this himself, if needed. |
nMaxLen | Maximum length of the resulting string. If string length is greater than nMaxLen, it will be truncated. |
pszFormat | Controls the output format. Options are the same as for strftime(3) function. |
poBrokenTime | Pointer to the broken-down time structure. May be requested with the VSIGMTime() and VSILocalTime() functions. |
pszLocale | Pointer to a character string containing locale name ("C", "POSIX", "us_US", "ru_RU.KOI8-R" etc.). If NULL we will not manipulate with locale settings and current process locale will be used for printing. Be aware that it may be unsuitable to use current locale for printing time, because all names will be printed in your native language, as well as time format settings also may be adjusted differently from the C/POSIX defaults. To solve these problems this option was introduced. |
int CPL_DLL CPLPrintUIntBig | ( | char * | pszBuffer, |
GUIntBig | iValue, | ||
int | nMaxLen | ||
) |
Print GUIntBig value into specified string buffer. This string will not be NULL-terminated.
pszBuffer | Pointer to the destination string buffer. Should be large enough to hold the resulting string. Note, that the string will not be NULL-terminated, so user should do this himself, if needed. |
iValue | Numerical value to print. |
nMaxLen | Maximum length of the resulting string. If string length is greater than nMaxLen, it will be truncated. |
const char CPL_DLL* CPLProjectRelativeFilename | ( | const char * | pszProjectDir, |
const char * | pszSecondaryFilename | ||
) |
Find a file relative to a project file.
Given the path to a "project" directory, and a path to a secondary file referenced from that project, build a path to the secondary file that the current application can use. If the secondary path is already absolute, rather than relative, then it will be returned unaltered.
Examples:
CPLProjectRelativeFilename("abc/def", "tmp/abc.gif") == "abc/def/tmp/abc.gif" CPLProjectRelativeFilename("abc/def", "/tmp/abc.gif") == "/tmp/abc.gif" CPLProjectRelativeFilename("/xy", "abc.gif") == "/xy/abc.gif" CPLProjectRelativeFilename("/abc/def", "../abc.gif") == "/abc/def/../abc.gif" CPLProjectRelativeFilename("C:\WIN", "abc.gif") == "C:\WIN\abc.gif"
pszProjectDir | the directory relative to which the secondary files path should be interpreted. |
pszSecondaryFilename | the filename (potentially with path) that is to be interpreted relative to the project directory. |
void CPL_DLL CPLPushFileFinder | ( | CPLFileFinder | pfnFinder | ) |
CPLPushFileFinder
void CPL_DLL CPLPushFinderLocation | ( | const char * | pszLocation | ) |
CPLPushFinderLocation
const char CPL_DLL* CPLReadLine | ( | FILE * | fp | ) |
Simplified line reading from text file.
Read a line of text from the given file handle, taking care to capture CR and/or LF and strip off ... equivalent of DKReadLine(). Pointer to an internal buffer is returned. The application shouldn't free it, or depend on its value past the next call to CPLReadLine().
Note that CPLReadLine() uses VSIFGets(), so any hooking of VSI file services should apply to CPLReadLine() as well.
CPLReadLine() maintains an internal buffer, which will appear as a single block memory leak in some circumstances. CPLReadLine() may be called with a NULL FILE * at any time to free this working buffer.
fp | file pointer opened with VSIFOpen(). |
const char CPL_DLL* CPLReadLineL | ( | VSILFILE * | fp | ) |
Simplified line reading from text file.
Similar to CPLReadLine(), but reading from a large file API handle.
fp | file pointer opened with VSIFOpenL(). |
void CPL_DLL* CPLRealloc | ( | void * | pData, |
size_t | nNewSize | ||
) |
Safe version of realloc().
This function is like the C library realloc(), but raises a CE_Fatal error with CPLError() if it fails to allocate the desired memory. It should be used for small memory allocations that are unlikely to fail and for which the application is unwilling to test for out of memory conditions. It uses VSIRealloc() to get the memory, so any hooking of VSIRealloc() will apply to CPLRealloc() as well. CPLFree() or VSIFree() can be used free memory allocated by CPLRealloc().
It is also safe to pass NULL in as the existing memory block for CPLRealloc(), in which case it uses VSIMalloc() to allocate a new block.
pData | existing memory block which should be copied to the new block. |
nNewSize | new size (in bytes) of memory block to allocate. |
const char CPL_DLL* CPLResetExtension | ( | const char * | pszPath, |
const char * | pszExt | ||
) |
Replace the extension with the provided one.
pszPath | the input path, this string is not altered. |
pszExt | the new extension to apply to the given path. |
double CPL_DLL CPLScanDouble | ( | const char * | pszString, |
int | nMaxLength | ||
) |
Extract double from string.
Scan up to a maximum number of characters from a string and convert the result to a double. This function uses CPLAtof() to convert string to double value, so it uses a comma as a decimal delimiter.
pszString | String containing characters to be scanned. It may be terminated with a null character. |
nMaxLength | The maximum number of character to consider as part of the number. Less characters will be considered if a null character is encountered. |
long CPL_DLL CPLScanLong | ( | const char * | pszString, |
int | nMaxLength | ||
) |
Scan up to a maximum number of characters from a string and convert the result to a long.
pszString | String containing characters to be scanned. It may be terminated with a null character. |
nMaxLength | The maximum number of character to consider as part of the number. Less characters will be considered if a null character is encountered. |
void CPL_DLL* CPLScanPointer | ( | const char * | pszString, |
int | nMaxLength | ||
) |
Extract pointer from string.
Scan up to a maximum number of characters from a string and convert the result to a pointer.
pszString | String containing characters to be scanned. It may be terminated with a null character. |
nMaxLength | The maximum number of character to consider as part of the number. Less characters will be considered if a null character is encountered. |
char CPL_DLL* CPLScanString | ( | const char * | pszString, |
int | nMaxLength, | ||
int | bTrimSpaces, | ||
int | bNormalize | ||
) |
Scan up to a maximum number of characters from a given string, allocate a buffer for a new string and fill it with scanned characters.
pszString | String containing characters to be scanned. It may be terminated with a null character. |
nMaxLength | The maximum number of character to read. Less characters will be read if a null character is encountered. |
bTrimSpaces | If TRUE, trim ending spaces from the input string. Character considered as empty using isspace(3) function. |
bNormalize | If TRUE, replace ':' symbol with the '_'. It is needed if resulting string will be used in CPL dictionaries. |
GUIntBig CPL_DLL CPLScanUIntBig | ( | const char * | pszString, |
int | nMaxLength | ||
) |
Extract big integer from string.
Scan up to a maximum number of characters from a string and convert the result to a GUIntBig.
pszString | String containing characters to be scanned. It may be terminated with a null character. |
nMaxLength | The maximum number of character to consider as part of the number. Less characters will be considered if a null character is encountered. |
unsigned long CPL_DLL CPLScanULong | ( | const char * | pszString, |
int | nMaxLength | ||
) |
Scan up to a maximum number of characters from a string and convert the result to a unsigned long.
pszString | String containing characters to be scanned. It may be terminated with a null character. |
nMaxLength | The maximum number of character to consider as part of the number. Less characters will be considered if a null character is encountered. |
void CPL_DLL CPL_STDCALL CPLSetConfigOption | ( | const char * | pszKey, |
const char * | pszValue | ||
) |
Set a configuration option for GDAL/OGR use.
Those options are defined as a (key, value) couple. The value corresponding to a key can be got later with the CPLGetConfigOption() method.
This mechanism is similar to environment variables, but options set with CPLSetConfigOption() overrides, for CPLGetConfigOption() point of view, values defined in the environment.
If CPLSetConfigOption() is called several times with the same key, the value provided during the last call will be used.
Options can also be passed on the command line of most GDAL utilities with the with '–config KEY VALUE'. For example, ogrinfo –config CPL_DEBUG ON ~/data/test/point.shp
This function can also be used to clear a setting by passing NULL as the value (note: passing NULL will not unset an existing environment variable; it will just unset a value previously set by CPLSetConfigOption()).
pszKey | the key of the option |
pszValue | the value of the option, or NULL to clear a setting. |
void CPL_DLL CPLSetConfigOptions | ( | const char *const * | papszConfigOptions | ) |
Replace the full list of configuration options with the passed list of KEY=VALUE pairs.
This has the same effect of clearing the existing list, and setting individually each pair with the CPLSetConfigOption() API.
This does not affect options set through environment variables or with CPLSetThreadLocalConfigOption().
The passed list is copied by the function.
papszConfigOptions | the new list (or NULL). |
char* CPLsetlocale | ( | int | category, |
const char * | locale | ||
) |
Prevents parallel executions of setlocale().
Calling setlocale() concurrently from two or more threads is a potential data race. A mutex is used to provide a critical region so that only one thread at a time can be executing setlocale().
The return should not be freed, and copied quickly as it may be invalidated by a following next call to CPLsetlocale().
category | See your compiler's documentation on setlocale. |
locale | See your compiler's documentation on setlocale. |
void CPL_DLL CPL_STDCALL CPLSetThreadLocalConfigOption | ( | const char * | pszKey, |
const char * | pszValue | ||
) |
Set a configuration option for GDAL/OGR use.
Those options are defined as a (key, value) couple. The value corresponding to a key can be got later with the CPLGetConfigOption() method.
This function sets the configuration option that only applies in the current thread, as opposed to CPLSetConfigOption() which sets an option that applies on all threads. CPLSetThreadLocalConfigOption() will override the effect of CPLSetConfigOption) for the current thread.
This function can also be used to clear a setting by passing NULL as the value (note: passing NULL will not unset an existing environment variable or a value set through CPLSetConfigOption(); it will just unset a value previously set by CPLSetThreadLocalConfigOption()).
pszKey | the key of the option |
pszValue | the value of the option, or NULL to clear a setting. |
void CPL_DLL CPLSetThreadLocalConfigOptions | ( | const char *const * | papszConfigOptions | ) |
Replace the full list of thread local configuration options with the passed list of KEY=VALUE pairs.
This has the same effect of clearing the existing list, and setting individually each pair with the CPLSetThreadLocalConfigOption() API.
This does not affect options set through environment variables or with CPLSetConfigOption().
The passed list is copied by the function.
papszConfigOptions | the new list (or NULL). |
int CPL_DLL CPLStat | ( | const char * | pszPath, |
VSIStatBuf * | psStatBuf | ||
) |
Same as VSIStat() except it works on "C:" as if it were "C:\".
char CPL_DLL* CPLStrdup | ( | const char * | pszString | ) |
Safe version of strdup() function.
This function is similar to the C library strdup() function, but if the memory allocation fails it will issue a CE_Fatal error with CPLError() instead of returning NULL. It uses VSIStrdup(), so any hooking of that function will apply to CPLStrdup() as well. Memory allocated with CPLStrdup() can be freed with CPLFree() or VSIFree().
It is also safe to pass a NULL string into CPLStrdup(). CPLStrdup() will allocate and return a zero length string (as opposed to a NULL string).
pszString | input string to be duplicated. May be NULL. |
void CPL_DLL CPLStringToComplex | ( | const char * | pszString, |
double * | pdfReal, | ||
double * | pdfImag | ||
) |
Fetch the real and imaginary part of a serialized complex number
char CPL_DLL* CPLStrlwr | ( | char * | pszString | ) |
Convert each characters of the string to lower case.
For example, "ABcdE" will be converted to "abcde". This function is locale dependent.
pszString | input string to be converted. |
double CPL_DLL CPLStrtod | ( | const char * | nptr, |
char ** | endptr | ||
) |
Converts ASCII string to floating point number.
This function converts the initial portion of the string pointed to by nptr to double floating point representation. This function does the same as standard strtod(3), but does not take locale in account. That means, the decimal delimiter is always '.' (decimal point). Use CPLStrtodDelim() function if you want to specify custom delimiter. Also see notes for CPLAtof() function.
nptr | Pointer to string to convert. |
endptr | If is not NULL, a pointer to the character after the last character used in the conversion is stored in the location referenced by endptr. |
double CPL_DLL CPLStrtodDelim | ( | const char * | nptr, |
char ** | endptr, | ||
char | point | ||
) |
Converts ASCII string to floating point number using specified delimiter.
This function converts the initial portion of the string pointed to by nptr to double floating point representation. This function does the same as standard strtod(3), but does not take locale in account. Instead of locale defined decimal delimiter you can specify your own one. Also see notes for CPLAtof() function.
nptr | Pointer to string to convert. |
endptr | If is not NULL, a pointer to the character after the last character used in the conversion is stored in the location referenced by endptr. |
point | Decimal delimiter. |
float CPL_DLL CPLStrtof | ( | const char * | nptr, |
char ** | endptr | ||
) |
Converts ASCII string to floating point number.
This function converts the initial portion of the string pointed to by nptr to single floating point representation. This function does the same as standard strtof(3), but does not take locale in account. That means, the decimal delimiter is always '.' (decimal point). Use CPLStrtofDelim() function if you want to specify custom delimiter. Also see notes for CPLAtof() function.
nptr | Pointer to string to convert. |
endptr | If is not NULL, a pointer to the character after the last character used in the conversion is stored in the location referenced by endptr. |
float CPL_DLL CPLStrtofDelim | ( | const char * | nptr, |
char ** | endptr, | ||
char | point | ||
) |
Converts ASCII string to floating point number using specified delimiter.
This function converts the initial portion of the string pointed to by nptr to single floating point representation. This function does the same as standard strtof(3), but does not take locale in account. Instead of locale defined decimal delimiter you can specify your own one. Also see notes for CPLAtof() function.
nptr | Pointer to string to convert. |
endptr | If is not NULL, a pointer to the character after the last character used in the conversion is stored in the location referenced by endptr. |
point | Decimal delimiter. |
int CPL_DLL CPLSymlink | ( | const char * | pszOldPath, |
const char * | pszNewPath, | ||
char ** | |||
) |
Create a symbolic link
int CPL_DLL CPLUnlinkTree | ( | const char * | pszPath | ) |
Recursively unlink a directory.
CPLErr CPL_DLL CPLWriteFileInZip | ( | void * | hZip, |
const void * | pBuffer, | ||
int | nBufferSize | ||
) |
Write in current file inside a ZIP file
void CPL_DLL* CPLZLibInflate | ( | const void * | ptr, |
size_t | nBytes, | ||
void * | outptr, | ||
size_t | nOutAvailableBytes, | ||
size_t * | pnOutBytes | ||
) |
Uncompress a buffer compressed with ZLib DEFLATE compression.
ptr | input buffer. |
nBytes | size of input buffer in bytes. |
outptr | output buffer, or NULL to let the function allocate it. |
nOutAvailableBytes | size of output buffer if provided, or ignored. |
pnOutBytes | pointer to a size_t, where to store the size of the output buffer. |