StringList -- Utility Functions for Lists Of Strings

A StringList is the PCI name for an array of string pointers (char **) which has a few properties.

The array is terminated with a NULL pointer.
Each string is allocated with HMalloc() or HString().
The array itself is allocated with HMalloc().

The StringList API can be used to manipulate these lists of strings in a manner that can simplify many operation. StringLists are also used by a number of other APIs.

DuplicateStringList()

DuplicateStringList() is used to create a new copy of an existing StringList. HMalloc() is used to allocate memory for the new array of pointers, and for the new copy of the strings themselves.

A StringList is an array of pointers to strings. The last element is in the pointer is array is NULL. The array, and the strings pointed to are all allocated with HMalloc().

char    **DuplicateStringList( list );

char    **list;
           The string list to be duplicated.

A new StringList is returned.

CountStringList()

CountStringList() is used to count the number of strings in a StringList.

A StringList is an array of pointers to strings. The last element is in the pointer is array is NULL. The array, and the strings pointed to are all allocated with HMalloc().

int     CountStringList( list );

char    **list;
           The string list for which the string entries are 
           to be counted

A count of the number of strings in the passed string list is returned.

StringListsEqual()

StringListsEqual() is a function used to compare two string lists for equality. A string by string case insensitive comparison is done, and TRUE is returned as long as all the corresponding strings are equal and if there are an equal number of strings in both lists.

int     StringListsEqual( list1, list2 );

char    **list1;
           The first string lists to compare.

char    **list2;
           The second string list to compare.

TRUE is returned if the lists are equivelent.

DestroyStringList()

DestroyStringList() is used to free all the components of a StringList.

A StringList is an array of pointers to strings. The last element is in the pointer is array is NULL. The array, and the strings pointed to are all allocated with HMalloc().

void    DestroyStringList( list );

char    **list;
           The string list to be destroyed.

AddStringList()

The AddStringList() function is used to add the contents of one StringList to another StringList. The StringList being added to is returned with the second StringList added to the end. The second string list is unaffected.

char    **AddStringList( target_list, source_list );

char    **target_list;
           The StringList to which the source_list will
           be added.

char    **source_list;
           The StringList to be added to the target_list.

The modified target_list is returned.

AddStringToList()

The AddStringToList() function is used to add a single string to an existing StringList. The StringList is realloced bigger, and a copy of the passed string is made for the StringList. This function is somewhat expensive for long StringLists.

char    **AddStringToList( target_list, new_string );

char    **target_list;
           The StringList to which the new_string will
           be added.  A new string list will be created
           when target_list == NULL.

char    *new_string;
           The new string to duplicate and add to the StringList.

The modified target_list is returned.

DeleteStringListEntry()

The DeleteStringListEntry() function is used to remove one entry (string) from a String List. The order of other elements is guaranteed to be unaffected.

char ** DeleteStringListEntry( papszStringList, int nEntry );

char ** papszStringList;
           The string list from which the entry should be removed.

int     nEntry;
           The entry in the string list array to be removed.

The return result is the modified string list.

FindEntryInStringList()

The FindEntryInStringList() function is used to find the index of a given string inside a StringList. To search for subsequent occurances of the same string call FindEntryInStringList() again but add the index+1 of the previously found entry to papszStringList pointer.

int     FindEntryInStringList( papszStringList, pszTarget );

char    **papszStringList;
           The StringList to search through.

const char      *pszTarget;
           The string to search for.

The index of the string is returned if it was found. Otherwise -1 is returned.

FindRegexInStringList()

The FindRegexInStringList() function is used to find the index of the first string in the given StringList that matches the provided regular expression. The regular expressions are in a form suitable for use with IMPRegex(), and are evaluated without case sensitivity.

To search for subsequent occurances of the same string call FindRegexInStringList() again but add the index+1 of the previously found entry to papszStringList pointer.

int     FindRegexInStringList( papszStringList, pszRegex );

char    **papszStringList;
           The StringList to search through.

const char      *pszRegex;
           A regular expression for the list entry being searched for.

The index of the matching string is returned if it was found. Otherwise -1 is returned.

ReplaceStringInList()

The ReplaceStringInList() function is used to replace a string at a known index in the StringList. The string at the known index is first freed and then a new string is allocated at the specified index.

int     ReplaceStringInList(char **target_list, const char *new_string,
                           int index);

char    **target_list;
           The StringList that need to be updated.

char    *new_string;
           The new string to add.

int     index;
           The index at which the new string will be added.

For a successful replacement, 0 is returned, else -1 is returned.

FileToStringList()

The FileToStringList() function will read the contents of a text file and return them as a StringList. The file is read using the DKReadLine() function, so the returned StringList entries will have the newline character stripped off.

char    **FileToStringList( pszFilename );

const char *pszFilename;
           The name of the text file to read.

The return result of this function is a StringList, or NULL if the file doesn't exist or can't be opened.

StringListToFile()

The StringListToFile() function will write a new text file with the contents of the passed StringList. A newline character is added to each line in the StringList as the file is written out.

TBool   StringListToFile( papszStringList, pszFilename );

char    **papszStringList;
           The list of strings to write to the file.

const char *pszFilename;
           The file to write them to.

The function returns FALSE if it fails, or TRUE if it succeeds. The file should not already exist, but if it does the function will fail without altering the existing file.

InsertStringInList()

The InsertStringInList() function is used to insert a string before or after a known index in the StringList. Inserting a string after the last item in the string list is the same as calling AddStringToList.

int     InsertStringInList(char **target_list, const char *new_string,
                           int index, TBool bAfter);

char    **target_list;
           The StringList that need to be updated.

char    *new_string;
           The new string to add.

int     index;
           The index at which the new string will be added.

TBool   bAfter;
           If TRUE, the string will be added after the specified item,
           or if FALSE, the string will be added before the sprecified item.

About PCI Help Gateway