StringArray C Library Reference
StringArray
* This is a freeware class/C library/library.
C Library for managing and manipulating collections of strings.
Create/Dispose
HCkStringArray CkStringArray_Create(void);
Creates an instance of the CkStringArray object and returns a handle (i.e. a "void *" pointer). The handle is passed in the 1st argument for the functions listed on this page.
void CkStringArray_Dispose(HCkStringArray handle);
Objects created by calling CkStringArray_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function.
C "Properties"
long CkStringArray_getCount(HCkStringArray cHandle);
The number of strings in the array.
BOOL CkStringArray_getCrlf(HCkStringArray cHandle);
void CkStringArray_putCrlf(HCkStringArray cHandle, BOOL newVal);
If true, strings are always automatically converted to use CRLF line endings. If false, strings are automatically converted to use bare LF line endings.
BOOL CkStringArray_getTrim(HCkStringArray cHandle);
void CkStringArray_putTrim(HCkStringArray cHandle, BOOL newVal);
If true, whitespace, including carriage-returns and linefeeds, are automatically removed from the beginning and end of a string when added to the array.
BOOL CkStringArray_getUnique(HCkStringArray cHandle);
void CkStringArray_putUnique(HCkStringArray cHandle, BOOL newVal);
If true, the array does not allow duplicates. When an attempt is made to insert a string that already exists in the array, the insertion simply doesn't happen and no error is returned.
BOOL CkStringArray_getUtf8(HCkStringArray cHandle);
void CkStringArray_putUtf8(HCkStringArray cHandle, BOOL newVal);
When set to true, all "const char *" arguments are expected to be utf-8 strings. If set to false, the "const char *" arguments are expected to be ANSI strings.
C "Methods"
void CkStringArray_Append(HCkStringArray cHandle, const char *str);
Appends a string to the end of the array.
BOOL CkStringArray_AppendSerialized(HCkStringArray cHandle, const char *encodedStr);
Appends multiple strings to the end of the array. The encodedStrings argument is what is returned from the Serialize method (see below).
void CkStringArray_Clear(HCkStringArray cHandle);
Remove all strings from the array.
BOOL CkStringArray_Contains(HCkStringArray cHandle, const char *str);
Returns true if the string is present in the array. The string comparisons are case sensitive.
long CkStringArray_Find(HCkStringArray cHandle, const char *str, long firstIndex);
Finds the index of the first string equal to the string passed. The search begins at beginIndex. If the string is not found, -1 is returned. The first string in the array is at index 0.
int CkStringArray_FindFirstMatch(HCkStringArray cHandle, const char *str, int firstIndex);
To be documented soon...
BOOL CkStringArray_GetString(HCkStringArray cHandle, long index, HCkString str);
Returns the string at a location in the array. The first string is at index 0.
const char *CkStringArray_GetString(HCkStringArray cHandle, long index);
Returns the string at a location in the array. The first string is at index 0.
int CkStringArray_GetStringLen(HCkStringArray cHandle, int index);
Returns Nth's string length, in characters. The first string is at index 0.
void CkStringArray_InsertAt(HCkStringArray cHandle, long index, const char *str);
Insert a string into the array at a particular index. Using index 0 will insert at the beginning.
BOOL CkStringArray_LastString(HCkStringArray cHandle, HCkString str);
Returns the last string in the array.
BOOL CkStringArray_LoadFromFile(HCkStringArray cHandle, const char *filename);
Adds strings from a file (one per line) into the string array. Returns TRUE for success, FALSE for failure.
void CkStringArray_LoadFromText(HCkStringArray cHandle, const char *str);
Adds strings from an in-memory string (one per line) into the string array.
BOOL CkStringArray_Pop(HCkStringArray cHandle, HCkString str);
Returns the last string and removes it from the array.
void CkStringArray_Prepend(HCkStringArray cHandle, const char *str);
Adds a string to the beginning of the array.
void CkStringArray_Remove(HCkStringArray cHandle, const char *str);
Removes all strings equal to the string argument from the array.
BOOL CkStringArray_RemoveAt(HCkStringArray cHandle, long index);
Removes the string at a particular index.
BOOL CkStringArray_SaveNthToFile(HCkStringArray cHandle, int index, const char *filename);
Saves the Nth string in the StringArray object to a file. Returns TRUE for success, FALSE for failure.
BOOL CkStringArray_SaveToFile(HCkStringArray cHandle, const char *filename);
Saves the array of strings to a file, one string per line. Returns TRUE for success, FALSE for failure.
void CkStringArray_SaveToText(HCkStringArray cHandle, HCkString outStr);
Saves the array of strings to a single string, one string per line (separated by CRLF line endings).
void CkStringArray_Serialize(HCkStringArray cHandle, HCkString encodedStr);
Returns an string which is an encoded representation of all the strings in the array. The StringArray can be re-created by calling the AppendSerialized method. One reason this method exists is to make it easy to pass entire string arrays as a form parameter in a Web page.
void CkStringArray_Sort(HCkStringArray cHandle, BOOL ascending);
Sorts the string array in ascending or descending order.
void CkStringArray_SplitAndAppend(HCkStringArray cHandle, const char *str, const char *boundary);
Splits a string at a character or substring boundary and adds each resulting string to the StringArray object.
void CkStringArray_Union(HCkStringArray cHandle, HCkStringArray array);
Performs the union set-operator. The caller will contain the union of two string arrays.
const char *CkStringArray_getString(HCkStringArray cHandle, long index);
Returns the string at a location in the array. The first string is at index 0.
const char *CkStringArray_lastStr(HCkStringArray cHandle);
To be documented soon...
const char *CkStringArray_pop(HCkStringArray cHandle);
Returns the last string and removes it from the array.
const char *CkStringArray_saveToText(HCkStringArray cHandle);
Saves the array of strings to a single string, one string per line (separated by CRLF line endings).
const char *CkStringArray_serialize(HCkStringArray cHandle);
Returns an string which is an encoded representation of all the strings in the array. The StringArray can be re-created by calling the AppendSerialized method. One reason this method exists is to make it easy to pass entire string arrays as a form parameter in a Web page.
const char *CkStringArray_strAt(HCkStringArray cHandle, long index);
To be documented soon...
|