Main Page Class Hierarchy Compound List File List Compound Members File Members Related Pages

# cpl_conv.h File Reference

Various convenience functions for CPL. More...

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

## Functions
|  | void | CPLVerifyConfiguration ()
|  | CPL_C_START void CPL_DLL* | CPLMalloc ( size_t )
|  |  | Safe version of malloc(). More...

|  | void CPL_DLL* | CPLCalloc ( size_t, size_t )
|  |  | Safe version of calloc(). More...

|  | void CPL_DLL* | CPLRealloc ( void *, size_t )
|  |  | Safe version of realloc(). More...

|  | char CPL_DLL* | CPLStrdup ( const char * )
|  |  | Safe version of strdup() function. More...

|  | const char* | CPLReadLine ( FILE * )
|  |  | Simplified line reading from text file. More...

|  | void CPL_DLL* | CPLGetSymbol ( const char *, const char * )
|  | char CPL_DLL** | CPLReadDir ( const char *pszPath )
|  | const char CPL_DLL* | CPLGetPath ( const char * )
|  |  | Extract directory path portion of filename. More...

|  | const char CPL_DLL* | CPLGetFilename ( const char * )
|  |  | Extract non-directory portion of filename. More...

|  | const char CPL_DLL* | CPLGetBasename ( const char * )
|  |  | Extract basename (non-directory, non-extension) portion of filename. More...

|  | const char CPL_DLL* | CPLGetExtension ( const char * )
|  |  | Extract filename extension from full filename. More...

|  | 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. More...

## Detailed Description

Various convenience functions for CPL.

## Function Documentation

void * 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.

const char * 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.

Parameters:

  pszBasename | file basename. May optionally have path and/or extension. May not be NULL.

Parameters:

  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 * 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 * 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 always 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 * 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 * 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"

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 * 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.

const char * 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.

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 * 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.

char * 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().