VkNameList(3x)VkNameList(3x)NAMEVkNameList - A class that supports and manipulates lists of strings
HEADER FILE
#include <Vk/VkNameList.h>
PUBLIC PROTOCOL SUMMARY
Constructor/Destructor
VkNameList(void);
VkNameList(const VkNameList& givenList);
VkNameList(char* name);
void ~VkNameList(void);
Adding and Removing Items
void add(char* name);
void add(const VkNameList& givenList);
void getIndex(const char* name);
void remove(char* name);
void remove(int index, int count=1);
VkNameList& operator=(const VkNameList& givenList);
Manipulating The List
void sort(void);
void reverse(void);
void removeDuplicates(void);
Access Functions
int size(void);
int exists(char* name);
char* operator[](int index);
VkNameList operator[](char* subString);
int operator==(const VkNameList& givenList);
Page 1
VkNameList(3x)VkNameList(3x)
char* mostCommonString(void);
VkNameList* completeName(char* name,
char&* completedName,
int& nMatching);
char** operator char **(void);
XmStringTable operator unsigned char **(void);
char* getString(int index);
char* getSubStrings(char *subString);
char** getStringTable();
XmStringTable getXmStringTable();
static void freeXmStringTable (XmStringTable);
CLASS DESCRIPTIONVkNameList provides a convenient way to maintain a list of character
strings. Strings can be added or removed individually, the list can
be sorted or reversed, duplications can be removed, the best
completion of a substring can be found, the most common occurrence
can be computed, and so on. The list can also be automatically
converted to a XmStringTable, making this a useful class for use
with Motif widgets that require a list of compound strings.
Some of the VkNameList operators allocate memory that must later be
freed by the caller. This can be counter-intuitive, and a source of
memory leaks. To avoid that, alternate conventional functions are
also provided. The conventional functions make it more clear that
there is something to be freed. In one case (getSubStrings()), the
conventional function is also considerably more efficient.
The operators to be careful of are: operator[](int) (prefer
getString(int)); operator[](char*) (prefer getSubStrings(char*));
operator char**() (prefer getStringTable()); operator
XmStringTable() (prefer getXmStringTable());
FUNCTION DESCRIPTIONSVkNameList()VkNameList(void);
VkNameList(char* name);
VkNameList(const VkNameList& givenList);
Page 2
VkNameList(3x)VkNameList(3x)
Initialize a VkNameList object. The first form initializes an empty
list, while the second allows allows an initial member of the list
to be specified. The copy constructor produces a clone of an
existing VkNameList object.
~VkNameList()
void ~VkNameList(void);
Free all memory allocated by a VkNameList object.
add()
void add(char *item);
void add(const VkNameList& list);
Add an item or a VkNameList to the list.
getIndex()
int getIndex(const char *item) const;
Gets the index of the first occurrence of the given item from the
list. If the item does not exist, the index returned is -1.
remove()
void remove(char *item);
Remove the first occurrence, if any, of the given item from the
list.
remove()
void remove(int index, count=1);
Remove the items index through index+count-1 from the list. Count
items, beginning with a named item, can be removed with the idiom
remove(getIndex(item),count);
sort()
void sort(void);
Page 3
VkNameList(3x)VkNameList(3x)
Sort the items on the list alphanumerically.
reverse()
void reverse(void);
Reverse the order of the items on the list.
removeDuplicates()
void removeDuplicates(void);
Remove all exact duplicates from the list.
size()
int size(void);
Returns the number of elements in the list.
exists()
int exists(char *item);
Returns non-zero if the specified string is a member of the list.
operator=()
VkNameList& operator=(const VkNameList&);
Assign the members of one list to another. Note that this frees any
strings that were in the old object. Any references to them, such
as those returned by a previous call to operator char **(), now
point to free'd memory.
operator[]()
char* operator[](int index);
Retrieve a copy of an item from the list by index. The returned
string must be freed by the caller.
For clarity in the application code, getString(int index) is
preferred.
Page 4
VkNameList(3x)VkNameList(3x)getString()
char* getString(int index);
Retrieve a copy of an item from the list by index.
The returned string must be freed by the caller.
operator[]()
VkNameList operator[](char* substring);
Return a list of items that match the given substring. The returned
object must be delete'd by the caller.
Both for clarity in the application code, and for efficiency,
getSubStrings(char *) is preferred.
getSubStrings()
VkNameList* getSubStrings(char* substring);
Return a pointer to a list of items that match the given substring.
The returned VkNameList must be delete'd by the caller.
operator==()
int operator==(const VkNameList&);
Text for equivalence of two VkNameList objects. The lists must have
identical contents in the same order for the test to return success.
mostCommonString()
char* mostCommonString(void);
Return a copy of the most common string in a list. The returned
string must be freed by the caller.
completeName()
VkNameList* completeName(char *name,
char &*completed name,
int& numMatching);
Given a string, this function returns a VkNameList object containing
all strings in the original list that could be completions of the
given string. Upon returning, the completedName argument contains
Page 5
VkNameList(3x)VkNameList(3x)
the matched substring common to all members of the returned list.
Finally, the numMatching reports the number of matched elements.
operator()
char** operator char **(void);
This operator returns a pointer to the members of a VkNameList
object as as an array of strings. The strings in the returned array
MUST NOT be freed by the caller. The array itself must be freed by
the caller.
For clarity in the application code, getStringTable() is preferred.
getStringTable()
char** getStringTable(void);
This operator returns a pointer to the members of a VkNameList
object as as an array of strings. The strings in the returned array
MUST NOT be freed by the caller. The array itself must be freed by
the caller.
operator()
XmStringTable operator unsigned char **(void);
This operator provides access to the members of a VkNameList object
as as an array of compound strings. The returned XmStringTable must
be freed by the caller. (See freeXmStringTable).
For clarity in the application code, getXmStringTable() is
preferred.
getXmStringTable()
XmStringTable getXmStringTable(void);
This operator provides access to the members of a VkNameList object
as as an array of compound strings. The returned XmStringTable must
be freed by the caller. (See freeXmStringTable).
freeXmStringTable
static void freeXmStringTable (XmStringTable)
Page 6
VkNameList(3x)VkNameList(3x)
This function frees the memory returned by XmStringTable operator
(), or by getXmStringTable().
EXAMPLES
The following example uses a VkNameList to construct a list
incrementally, and display the resulting list in reverse sorted order in
a Motif XmList widget.
#include <Vk/VkApp.h>
#include <Vk/VkSimpleWindow.h>
#include <Xm/List.h>
#include <Vk/VkNameList.h>
// Define a top-level window class
class MyWindow: public VkSimpleWindow {
protected:
Widget _list; // Hang on to widget as a data member
public:
MyWindow ( const char *name );
~MyWindow();
virtual const char* className(); // Identify this class
};
// The MyWindow constructor provides a place in which
// to create a widget tree to be installed as a
// "view" in the window.
MyWindow::MyWindow ( const char *name ) :
VkSimpleWindow ( name )
{
_list = XmCreateList ( mainWindowWidget(),
"list", NULL, 0 );
// Create a name list object
VkNameList *items = new VkNameList();
// Add some items
items->add("One");
items->add("Two");
items->add("Three");
items->add("Four");
items->add("One");
items->removeDuplicates(); // Get rid of duplications
Page 7
VkNameList(3x)VkNameList(3x)
items->sort(); // sort the list
items->reverse(); // Now reverse it
// Display the items in the list widget
XtVaSetValues(_list,
XmNitems, (XmStringTable) (*items),
XmNitemCount, items->size(),
NULL);
addView(_list);
}
const char * MyWindow::className()
{
return "MyWindow";
}
MyWindow::~MyWindow()
{
// Empty
}
// Main driver. Just instantiate a VkApp and a
// top-level window, "show" the window and then
// "run" the application.
void main ( int argc, char **argv )
{
VkApp *app = new VkApp("Hello", &argc, argv);
MyWindow *win = new MyWindow("hello");
win->show();
app->run();
}
KNOWN CLASSES THAT USE THIS CLASS
VkCompletionField
SEE ALSO
VkCompletionField
ViewKit Programmer's Guide
The X Window System, DEC Press, Bob Sheifler and Jim Gettys
The X Window System Toolkit, DEC Press, Paul Asente and Ralph Swick
The OSF/Motif Programmers Reference, Prentice Hall, OSF
Page 8
