---

cpl_conv.h File Reference

#include "cpl_port.h"
#include "cpl_vsi.h"
#include "cpl_error.h"

Go to the source code of this file.

Functions
void CPL_DLL *	CPLMalloc (size_t)
void CPL_DLL *	CPLCalloc (size_t, size_t)
void CPL_DLL *	CPLRealloc (void *, size_t)
char CPL_DLL *	CPLStrdup (const char *)
char CPL_DLL *	CPLFGets (char *, int, FILE *)
const char CPL_DLL *	CPLReadLine (FILE *)
double CPL_DLL	CPLScanDouble (char *, int)
long CPL_DLL	CPLScanLong (char *, int)
char CPL_DLL *	CPLPrintString (char *, const char *, int)
char CPL_DLL *	CPLPrintStringFill (char *, const char *, int)
char CPL_DLL *	CPLPrintInt32 (char *, GInt32, int)
char CPL_DLL *	CPLPrintUIntBig (char *, GUIntBig, int)
char CPL_DLL *	CPLPrintDouble (char *, const char *, double)
char CPL_DLL *	CPLPrintTime (char *, int, const char *, const struct tm *, char *)
void CPL_DLL *	CPLGetSymbol (const char *, const char *)
char CPL_DLL **	CPLReadDir (const char *pszPath)
const char CPL_DLL *	CPLGetPath (const char *)
const char CPL_DLL *	CPLGetDirname (const char *)
const char CPL_DLL *	CPLGetFilename (const char *)
const char CPL_DLL *	CPLGetBasename (const char *)
const char CPL_DLL *	CPLGetExtension (const char *)
const char CPL_DLL *	CPLFormFilename (const char *pszPath, const char *pszBasename, const char *pszExtension)
const char CPL_DLL *	CPLFormCIFilename (const char *pszPath, const char *pszBasename, const char *pszExtension)
const char CPL_DLL *	CPLResetExtension (const char *, const char *)
const char CPL_DLL *	CPLProjectRelativeFilename (const char *pszProjectDir, const char *pszSecondaryFilename)
int CPL_DLL	CPLIsFilenameRelative (const char *pszFilename)

---

Detailed Description

Various convenience functions for CPL.

---

Function Documentation

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(). Parameters: nCount  number of objects to allocate. nSize  size (in bytes) of object to allocate. Returns: pointer to newly allocated memory, only NULL if nSize * nCount is NULL.

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 ' ' and '\r ' combination. Parameters: pszBuffer  pointer to the targeting character buffer. nBufferSize  maximum size of the string to read (not including termonating '\0'). fp  file pointer to read from. Returns: pointer to the pszBuffer containing a string read from the file or NULL if the error or end of file was encountered.

const char CPL_DLL* CPLFormCIFilename (  const char *    pszPath, const char *    pszBasename, const char *    pszExtension )

Case insensitive file searching, returing 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 equivelent to CPLFormFilename() on case insensitive file systems (like Windows). Parameters: 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. Returns: a fully formed filename in an internal static string. Do not modify or free the returned string. The string may be destroyed by the next CPL call.

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" Parameters: 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. Returns: a fully formed filename in an internal static string. Do not modify or free the returned string. The string may be destroyed by the next CPL call.

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/" ) == "" Parameters: pszFullFilename  the full filename potentially including a path. Returns: just the non-directory, non-extension portion of the path in an internal string which must not be freed. The string may be destroyed by the next CPL filename handling call.

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" ) == "." Parameters: pszFilename  the filename potentially including a path. Returns: Path in an internal string which must not be freed. The string may be destroyed by the next CPL filename handling call. The returned will generally not contain a trailing path separator.

const char CPL_DLL* CPLGetExtension (  const char *    pszFullFilename )

Extract filename extension from full filename. Returns a string containing the extention 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" ) == "" Parameters: pszFullFilename  the full filename potentially including a path. Returns: just the extension portion of the path in an internal string which must not be freed. The string may be destroyed by the next CPL filename handling call.

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" Parameters: pszFullFilename  the full filename potentially including a path. Returns: just the non-directory portion of the path in an internal string which must not be freed. The string may be destroyed by the next CPL filename handling call.

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" ) == "" Parameters: pszFilename  the filename potentially including a path. Returns: Path in an internal string which must not be freed. The string may be destroyed by the next CPL filename handling call. The returned will generally not contain a trailing path separator.

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: prevent the reference count on the library from going up for every request, or given any opportunity to unload the library. Attempt to look for the library in non-standard locations. Attempt to try variations on the symbol name, like pre-prending or post-pending an underscore. Some of these issues may be worked on in the future. Parameters: 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. Returns: A pointer to the function if found, or NULL if the function isn't found, or the shared library can't be loaded.

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. Parameters: pszFilename  the filename with path to test. Returns: TRUE if the filename is relative or FALSE if it is absolute.

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(). Parameters: nSize  size (in bytes) of memory block to allocate. Returns: pointer to newly allocated memory, only NULL if nSize is zero.

char CPL_DLL* CPLPrintDouble (  char *    pszBuffer, const char *    pszFormat, double    dfValue )

Print double value into specified string buffer. Exponential character flag 'E' (or 'e') will be replaced with 'D', as in Fortran. Resulting string will not to be NULL-terminated. Parameters: 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. Format  specifier (for example, "%16.9E"). dfValue  Numerical value to print. Returns: Pointer to the destination string buffer.

char CPL_DLL* CPLPrintInt32 (  char *    pszBuffer, GInt32    iValue, int    nMaxLen )

Print GInt32 value into specified string buffer. This string will not be NULL-terminated. Parameters: 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. Returns: Pointer to the destination string buffer.

char 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. Parameters: pszDest  Pointer to the destination string buffer. Should be large enough to hold the resulting string. pszDest  Pointer to the source buffer. nMaxLen  Maximum length of the resulting string. If string length is greater than nMaxLen, it will be truncated. Returns: Pointer to the destination string pszDest.

char 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(). Parameters: pszDest  Pointer to the destination string buffer. Should be large enough to hold the resulting string. pszDest  Pointer to the source buffer. nMaxLen  Maximum length of the resulting string. If string length is greater than nMaxLen, it will be truncated. Returns: Pointer to the destination string pszDest.

char CPL_DLL* CPLPrintTime (  char *    pszBuffer, int    nMaxLen, const char *    pszFormat, const struct tm *    poBrokenTime, char *    pszLocale )

Print specified time value accordingly to the format options and specified locale name. This function does following: if locale parameter is not NULL, the current locale setting will be stored and replaced with the specified one; format time value with the strftime(3) function; restore back current locale, if was saved. Parameters: 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.). Returns: Pointer to the destination not NULL terminated buffer.

char CPL_DLL* CPLPrintUIntBig (  char *    pszBuffer, GUIntBig    iValue, int    nMaxLen )

Print GUIntBig value into specified string buffer. This string will not be NULL-terminated. Parameters: 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. Returns: Pointer to the destination string buffer.

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" Parameters: 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. Returns: a composed path to the secondary file. The returned string is internal and should not be altered, freed, or depending on past the next CPL call.

char CPL_DLL** CPLReadDir (  const char *    pszPath )

Read names in a directory. This function abstracts access to directory contains. It returns a list of strings containing the names of files, and directories in this directory. The resulting string list becomes the responsibility of the application and should be freed with CSLDestroy() when no longer needed. Note that no error is issued via CPLError() if the directory path is invalid, though NULL is returned. Parameters: pszPath  the relative, or absolute path of a directory to read. Returns: The list of entries in the directory, or NULL if the directory doesn't exist.

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 ... equivelent of DKReadLine(). Pointer to an internal buffer is returned. The application shouldn't free it, or depend on it's 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. Parameters: fp  file pointer opened with VSIFOpen(). Returns: pointer to an internal buffer containing a line of text read from the file or NULL if the end of file was encountered.

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. Parameters: pData  existing memory block which should be copied to the new block. nNewSize  new size (in bytes) of memory block to allocate. Returns: pointer to allocated memory, only NULL if nNewSize is zero.

const char CPL_DLL* CPLResetExtension (  const char *    pszPath, const char *    pszExt )

Replace the extension with the provided one. Parameters: pszPath  the input path, this string is not altered. pszExt  the new extension to apply to the given path. Returns: an altered filename with the new extension. Do not modify or free the returned string. The string may be destroyed by the next CPL call.

double CPL_DLL CPLScanDouble (  char *    pszString, int    nMaxLength )

Scan up to a maximum number of characters from a string and convert the result to a double. Parameters: 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. Returns: Double value, converted from its ASCII form.

long CPL_DLL CPLScanLong (  char *    pszString, int    nMaxLength )

Scan up to a maximum number of characters from a string and convert the result to a long. Parameters: 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. Returns: Long value, converted from its ASCII form.

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). Parameters: pszString  input string to be duplicated. May be NULL. Returns: pointer to a newly allocated copy of the string. Free with CPLFree() or VSIFree().

---