CPLStringList Class Reference

String list class designed around our use of C "char**" string lists. More...

#include <cpl_string.h>

Public Member Functions
	CPLStringList (char **papszList, int bTakeOwnership=TRUE)
	CPLStringList constructor. More...
	CPLStringList (CSLConstList papszList)
	CPLStringList constructor. More...
	CPLStringList (const std::vector< std::string > &aosList)
	CPLStringList constructor. More...
	CPLStringList (std::initializer_list< const char * > oInitList)
	CPLStringList constructor. More...
	CPLStringList (const CPLStringList &oOther)
	Copy constructor.
	CPLStringList (CPLStringList &&oOther)
	Move constructor.
CPLStringList &	Clear ()
	Clear the string list.
void	clear ()
	Clear the list.
int	size () const
	Return size of list.
int	Count () const
bool	empty () const
	Return whether the list is empty.
CPLStringList &	AddString (const char *pszNewString)
	Add a string to the list. More...
CPLStringList &	AddStringDirectly (char *pszNewString)
	Add a string to the list. More...
CPLStringList &	InsertString (int nInsertAtLineNo, const char *pszNewLine)
	Insert into the list at identified location. More...
CPLStringList &	InsertStringDirectly (int nInsertAtLineNo, char *pszNewLine)
	Insert into the list at identified location. More...
int	FindString (const char *pszTarget) const
	Return index of pszTarget in the list, or -1.
int	PartialFindString (const char *pszNeedle) const
	Return index of pszTarget in the list (using partial search), or -1.
int	FindName (const char *pszName) const
	Get index of given name/value keyword. More...
bool	FetchBool (const char *pszKey, bool bDefault) const
	Check for boolean key value. More...
int	FetchBoolean (const char *pszKey, int bDefault) const
	DEPRECATED: Check for boolean key value. More...
const char *	FetchNameValue (const char *pszKey) const
	Fetch value associated with this key name. More...
const char *	FetchNameValueDef (const char *pszKey, const char *pszDefault) const
	Fetch value associated with this key name. More...
CPLStringList &	AddNameValue (const char *pszKey, const char *pszValue)
	Add a name=value entry to the list. More...
CPLStringList &	SetNameValue (const char *pszKey, const char *pszValue)
	Set name=value entry in the list. More...
CPLStringList &	Assign (char **papszListIn, int bTakeOwnership=TRUE)
	Assign a list of strings. More...
CPLStringList &	operator= (char **papszListIn)
	Assignment operator.
CPLStringList &	operator= (const CPLStringList &oOther)
	Assignment operator.
CPLStringList &	operator= (CSLConstList papszListIn)
	Assignment operator.
CPLStringList &	operator= (CPLStringList &&oOther)
	Move assignment operator.
char *	operator[] (int i)
	Return string at specified index. More...
char *	operator[] (size_t i)
	Return string at specified index.
const char *	operator[] (int i) const
	Return string at specified index.
const char *	operator[] (size_t i) const
	Return string at specified index.
const char *	operator[] (const char *pszKey) const
	Return value corresponding to pszKey, or nullptr.
const char *	front () const
	Return first element.
const char *	back () const
	Return last element.
const char *const *	begin () const
	begin() implementation
const char *const *	end () const
	end() implementation
char **	List ()
	Return list. More...
CSLConstList	List () const
	Return list. More...
char **	StealList ()
	Seize ownership of underlying string array. More...
CPLStringList &	Sort ()
	Sort the entries in the list and mark list sorted. More...
int	IsSorted () const
	Returns whether the list is sorted.
	operator char ** (void)
	Return lists.
	operator CSLConstList (void) const
	Return lists.
	operator std::vector< std::string > (void) const
	Return the list as a vector of strings.

Static Public Member Functions
static const CPLStringList	BoundToConstList (CSLConstList papszList)
	Return a CPLStringList that wraps the passed list. More...

Detailed Description

String list class designed around our use of C "char**" string lists.

Constructor & Destructor Documentation

CPLStringList() [1/4]

CPLStringList::CPLStringList ( char **  papszListIn, int  bTakeOwnership = TRUE  )

explicit

CPLStringList constructor.

Parameters

papszListIn	the NULL terminated list of strings to consume.
bTakeOwnership	TRUE if the CPLStringList should take ownership of the list of strings which implies responsibility to free them.

CPLStringList() [2/4]

CPLStringList::CPLStringList ( CSLConstList  papszListIn )

explicit

CPLStringList constructor.

The input list is copied.

Parameters

papszListIn

the NULL terminated list of strings to ingest.

CPLStringList() [3/4]

CPLStringList::CPLStringList ( const std::vector< std::string > &  aosList )

explicit

CPLStringList constructor.

The input list is copied.

Parameters

aosList

input list.

Since

GDAL 3.9

CPLStringList() [4/4]

CPLStringList::CPLStringList ( std::initializer_list< const char * >  oInitList )

explicit

CPLStringList constructor.

The input list is copied.

Parameters

oInitList

input list.

Since

GDAL 3.9

Member Function Documentation

AddNameValue()

CPLStringList & CPLStringList::AddNameValue	(	const char *	pszKey,
		const char *	pszValue
	)

Add a name=value entry to the list.

A key=value string is prepared and appended to the list. There is no check for other values for the same key in the list.

Parameters

pszKey	the key name to add.
pszValue	the key value to add.

AddString()

CPLStringList & CPLStringList::AddString

(

const char *

pszNewString

)

Add a string to the list.

A copy of the passed in string is made and inserted in the list.

Parameters

pszNewString

the string to add to the list.

AddStringDirectly()

CPLStringList & CPLStringList::AddStringDirectly

(

char *

pszNewString

)

Add a string to the list.

This method is similar to AddString(), but ownership of the pszNewString is transferred to the CPLStringList class.

Parameters

pszNewString

the string to add to the list.

Assign()

CPLStringList & CPLStringList::Assign	(	char **	papszListIn,
		int	bTakeOwnership = TRUE
	)

Assign a list of strings.

Parameters

papszListIn	the NULL terminated list of strings to consume.
bTakeOwnership	TRUE if the CPLStringList should take ownership of the list of strings which implies responsibility to free them.

Returns

a reference to the CPLStringList on which it was invoked.

BoundToConstList()

const CPLStringList CPLStringList::BoundToConstList ( CSLConstList  papszListIn )

static

Return a CPLStringList that wraps the passed list.

The input list is NOT copied and must be kept alive while the return CPLStringList is used.

Parameters

papszListIn

a NULL terminated list of strings to wrap into the CPLStringList

Since

GDAL 3.9

Count()

int CPLStringList::Count

(

)

const

Returns

count of strings in the list, zero if empty.

FetchBool()

bool CPLStringList::FetchBool	(	const char *	pszKey,
		bool	bDefault
	)		const

Check for boolean key value.

In a CPLStringList of "Name=Value" pairs, look to see if there is a key with the given name, and if it can be interpreted as being TRUE. If the key appears without any "=Value" portion it will be considered true. If the value is NO, FALSE or 0 it will be considered FALSE otherwise if the key appears in the list it will be considered TRUE. If the key doesn't appear at all, the indicated default value will be returned.

Parameters

pszKey	the key value to look for (case insensitive).
bDefault	the value to return if the key isn't found at all.

Returns

true or false

FetchBoolean()

int CPLStringList::FetchBoolean	(	const char *	pszKey,
		int	bDefault
	)		const

DEPRECATED: Check for boolean key value.

In a CPLStringList of "Name=Value" pairs, look to see if there is a key with the given name, and if it can be interpreted as being TRUE. If the key appears without any "=Value" portion it will be considered true. If the value is NO, FALSE or 0 it will be considered FALSE otherwise if the key appears in the list it will be considered TRUE. If the key doesn't appear at all, the indicated default value will be returned.

Parameters

pszKey	the key value to look for (case insensitive).
bDefault	the value to return if the key isn't found at all.

Returns

TRUE or FALSE

FetchNameValue()

const char * CPLStringList::FetchNameValue

(

const char *

pszName

)

const

Fetch value associated with this key name.

If this list sorted, a fast binary search is done, otherwise a linear scan is done. Name lookup is case insensitive.

Parameters

pszName

the key name to search for.

Returns

the corresponding value or NULL if not found. The returned string should not be modified and points into internal object state that may change on future calls.

FetchNameValueDef()

const char * CPLStringList::FetchNameValueDef	(	const char *	pszName,
		const char *	pszDefault
	)		const

Fetch value associated with this key name.

If this list sorted, a fast binary search is done, otherwise a linear scan is done. Name lookup is case insensitive.

Parameters

pszName	the key name to search for.
pszDefault	the default value returned if the named entry isn't found.

Returns

the corresponding value or the passed default if not found.

FindName()

int CPLStringList::FindName

(

const char *

pszKey

)

const

Get index of given name/value keyword.

Note that this search is for a line in the form name=value or name:value. Use FindString() or PartialFindString() for searches not based on name=value pairs.

Parameters

pszKey

the name to search for.

Returns

the string list index of this name, or -1 on failure.

InsertString()

CPLStringList * CPLStringList::InsertString ( int  nInsertAtLineNo, const char *  pszNewLine  )

inline

Insert into the list at identified location.

This method will insert a string into the list at the identified location. The insertion point must be within or at the end of the list. The following entries are pushed down to make space.

Parameters

nInsertAtLineNo	the line to insert at, zero to insert at front.
pszNewLine	to the line to insert. This string will be copied.

InsertStringDirectly()

CPLStringList & CPLStringList::InsertStringDirectly	(	int	nInsertAtLineNo,
		char *	pszNewLine
	)

Insert into the list at identified location.

This method will insert a string into the list at the identified location. The insertion point must be within or at the end of the list. The following entries are pushed down to make space.

Parameters

nInsertAtLineNo	the line to insert at, zero to insert at front.
pszNewLine	to the line to insert, the ownership of this string will be taken over the by the object. It must have been allocated on the heap.

List() [1/2]

char ** CPLStringList::List ( )

inline

Return list.

Ownership remains to the object

List() [2/2]

CSLConstList CPLStringList::List ( ) const

inline

Return list.

Ownership remains to the object

operator[]()

char * CPLStringList::operator[]

(

int

i

)

Return string at specified index.

Fetch entry "i".

Fetches the requested item in the list. Note that the returned string remains owned by the CPLStringList. If "i" is out of range NULL is returned.

Parameters

i	the index of the list item to return.

Returns

selected entry in the list.

SetNameValue()

CPLStringList & CPLStringList::SetNameValue	(	const char *	pszKey,
		const char *	pszValue
	)

Set name=value entry in the list.

Similar to AddNameValue(), except if there is already a value for the key in the list it is replaced instead of adding a new entry to the list. If pszValue is NULL any existing key entry is removed.

Parameters

pszKey	the key name to add.
pszValue	the key value to add.

Sort()

CPLStringList & CPLStringList::Sort

(

)

Sort the entries in the list and mark list sorted.

Note that once put into "sorted" mode, the CPLStringList will attempt to keep things in sorted order through calls to AddString(), AddStringDirectly(), AddNameValue(), SetNameValue(). Complete list assignments (via Assign() and operator= will clear the sorting state. When in sorted order FindName(), FetchNameValue() and FetchNameValueDef() will do a binary search to find the key, substantially improve lookup performance in large lists.

StealList()

char ** CPLStringList::StealList

(

)

Seize ownership of underlying string array.

This method is similar to List(), except that the returned list is now owned by the caller and the CPLStringList is emptied.

Returns

the C style string list.

---

The documentation for this class was generated from the following files:

• cpl_string.h
• cplstringlist.cpp