cpl_string.h File Reference

#include "cpl_vsi.h"
#include "cpl_error.h"
#include "cpl_conv.h"
#include <string>

Go to the source code of this file.

Classes

class  CPLString

Defines

#define CSLT_HONOURSTRINGS   0x0001
#define CSLT_ALLOWEMPTYTOKENS   0x0002
#define CSLT_PRESERVEQUOTES   0x0004
#define CSLT_PRESERVEESCAPES   0x0008
#define CPLES_BackslashQuotable   0
#define CPLES_XML   1
#define CPLES_URL   2
#define CPLES_SQL   3
#define CPLES_CSV   4
#define MSVC_OLD_STUPID_BEHAVIOUR
#define std_string   string

Functions

char ** CSLAddString (char **papszStrList, const char *pszNewString)
int CSLCount (char **papszStrList)
const char * CSLGetField (char **, int)
void CSLDestroy (char **papszStrList)
char ** CSLDuplicate (char **papszStrList)
char ** CSLMerge (char **papszOrig, char **papszOverride)
 Merge two lists.
char ** CSLTokenizeString (const char *pszString)
char ** CSLTokenizeStringComplex (const char *pszString, const char *pszDelimiter, int bHonourStrings, int bAllowEmptyTokens)
char ** CSLTokenizeString2 (const char *pszString, const char *pszDelimeter, int nCSLTFlags)
int CSLPrint (char **papszStrList, FILE *fpOut)
char ** CSLLoad (const char *pszFname)
int CSLSave (char **papszStrList, const char *pszFname)
char ** CSLInsertStrings (char **papszStrList, int nInsertAtLineNo, char **papszNewLines)
char ** CSLInsertString (char **papszStrList, int nInsertAtLineNo, const char *pszNewLine)
char ** CSLRemoveStrings (char **papszStrList, int nFirstLineToDelete, int nNumToRemove, char ***ppapszRetStrings)
int CSLFindString (char **, const char *)
int CSLTestBoolean (const char *pszValue)
int CSLFetchBoolean (char **papszStrList, const char *pszKey, int bDefault)
const char * CPLSPrintf (const char *fmt,...)
char ** CSLAppendPrintf (char **papszStrList, char *fmt,...)
const char * CPLParseNameValue (const char *pszNameValue, char **ppszKey)
const char * CSLFetchNameValue (char **papszStrList, const char *pszName)
char ** CSLFetchNameValueMultiple (char **papszStrList, const char *pszName)
char ** CSLAddNameValue (char **papszStrList, const char *pszName, const char *pszValue)
char ** CSLSetNameValue (char **papszStrList, const char *pszName, const char *pszValue)
void CSLSetNameValueSeparator (char **papszStrList, const char *pszSeparator)
char * CPLEscapeString (const char *pszString, int nLength, int nScheme)
char * CPLUnescapeString (const char *pszString, int *pnLength, int nScheme)
char * CPLBinaryToHex (int nBytes, const GByte *pabyData)
GByte * CPLHexToBinary (const char *pszHex, int *pnBytes)


Detailed Description

Various convenience functions for working with strings and string lists.

A StringList is just an array of strings with the last pointer being NULL. An empty StringList may be either a NULL pointer, or a pointer to a pointer memory location with a NULL value.

A common convention for StringLists is to use them to store name/value lists. In this case the contents are treated like a dictionary of name/value pairs. The actual data is formatted with each string having the format "<name>:<value>" (though "=" is also an acceptable separator). A number of the functions in the file operate on name/value style string lists (such as CSLSetNameValue(), and CSLFetchNameValue()).


Function Documentation

char* CPLBinaryToHex ( int  nBytes,
const GByte *  pabyData 
)

Binary to hexadecimal translation.

Parameters:
nBytes number of bytes of binary data in pabyData.
pabyData array of data bytes to translate.
Returns:
hexadecimal translation, zero terminated. Free with CPLFree().

char* CPLEscapeString ( const char *  pszInput,
int  nLength,
int  nScheme 
)

Apply escaping to string to preserve special characters.

This function will "escape" a variety of special characters to make the string suitable to embed within a string constant or to write within a text stream but in a form that can be reconstitued to it's original form. The escaping will even preserve zero bytes allowing preservation of raw binary data.

CPLES_BackslashQuotable(0): This scheme turns a binary string into a form suitable to be placed within double quotes as a string constant. The backslash, quote, '' and newline characters are all escaped in the usual C style.

CPLES_XML(1): This scheme converts the '<', '<' and '&' characters into their XML/HTML equivelent (>, < and &) making a string safe to embed as CDATA within an XML element. The '' is not escaped and should not be included in the input.

CPLES_URL(2): Everything except alphanumerics and the underscore are converted to a percent followed by a two digit hex encoding of the character (leading zero supplied if needed). This is the mechanism used for encoding values to be passed in URLs.

CPLES_SQL(3): All single quotes are replaced with two single quotes. Suitable for use when constructing literal values for SQL commands where the literal will be enclosed in single quotes.

CPLES_CSV(4): If the values contains commas, double quotes, or newlines it placed in double quotes, and double quotes in the value are doubled. Suitable for use when constructing field values for .csv files. Note that CPLUnescapeString() currently does not support this format, only CPLEscapeString(). See cpl_csv.cpp for csv parsing support.

Parameters:
pszInput the string to escape.
nLength The number of bytes of data to preserve. If this is -1 the strlen(pszString) function will be used to compute the length.
nScheme the encoding scheme to use.
Returns:
an escaped, zero terminated string that should be freed with CPLFree() when no longer needed.

GByte* CPLHexToBinary ( const char *  pszHex,
int *  pnBytes 
)

Hexadecimal to binary translation

Parameters:
 

const char* CPLParseNameValue ( const char *  pszNameValue,
char **  ppszKey 
)

Parse NAME=VALUE string into name and value components.

Note that if ppszKey is non-NULL, the key (or name) portion will be allocated using VSIMalloc(), and returned in that pointer. It is the applications responsibility to free this string, but the application should not modify or free the returned value portion.

This function also support "NAME:VALUE" strings and will strip white space from around the delimeter when forming name and value strings.

Eventually CSLFetchNameValue() and friends may be modified to use CPLParseNameValue().

Parameters:
pszNameValue string in "NAME=VALUE" format.
ppszKey optional pointer though which to return the name portion.
Returns:
the value portion (pointing into original string).

char* CPLUnescapeString ( const char *  pszInput,
int *  pnLength,
int  nScheme 
)

Unescape a string.

This function does the opposite of CPLEscapeString(). Given a string with special values escaped according to some scheme, it will return a new copy of the string returned to it's original form.

Parameters:
pszInput the input string. This is a zero terminated string.
pnLength location to return the length of the unescaped string, which may in some cases include embedded '' characters.
nScheme the escaped scheme to undo (see CPLEscapeString() for a list).
Returns:
a copy of the unescaped string that should be freed by the application using CPLFree() when no longer needed.

char** CSLMerge ( char **  papszOrig,
char **  papszOverride 
)

Merge two lists.

The two lists are merged, ensuring that if any keys appear in both that the value from the second (papszOverride) list take precidence.

Parameters:
papszOrig the original list, being modified.
papszOverride the list of items being merged in. This list is unaltered and remains owned by the caller.
Returns:
updated list.

char** CSLSetNameValue ( char **  papszList,
const char *  pszName,
const char *  pszValue 
)

Assign value to name in StringList.

Set the value for a given name in a StringList of "Name=Value" pairs ("Name:Value" pairs are also supported for backward compatibility with older stuff.)

If there is already a value for that name in the list then the value is changed, otherwise a new "Name=Value" pair is added.

Parameters:
papszList the original list, the modified version is returned.
pszName the name to be assigned a value. This should be a well formed token (no spaces or very special characters).
pszValue the value to assign to the name. This should not contain any newlines (CR or LF) but is otherwise pretty much unconstrained. If NULL any corresponding value will be removed.
Returns:
modified stringlist.

void CSLSetNameValueSeparator ( char **  papszList,
const char *  pszSeparator 
)

Replace the default separator (":" or "=") with the passed separator in the given name/value list.

Note that if a separator other than ":" or "=" is used, the resulting list will not be manipulatable by the CSL name/value functions any more.

The CPLParseNameValue() function is used to break the existing lines, and it also strips white space from around the existing delimiter, thus the old separator, and any white space will be replaced by the new separator. For formatting purposes it may be desireable to include some white space in the new separator. eg. ": " or " = ".

Parameters:
papszList the list to update. Component strings may be freed but the list array will remain at the same location.
pszSeparator the new separator string to insert.

int CSLTestBoolean ( const char *  pszValue  ) 

Test what boolean value contained in the string.

If pszValue is "NO", "FALSE", "OFF" or "0" will be returned FALSE. Otherwise, TRUE will be returned.

Parameters:
pszValue the string should be tested.
Returns:
TRUE or FALSE.


Generated for GDAL by doxygen 1.5.2.