VkNameList(3x)
VkNameList - A class that supports and manipulates lists of strings
As shipped in IRIX 6.5.22. Unchanged since IRIX 6.5.
NAME VkNameList - 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); 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 DESCRIPTION VkNameList 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 DESCRIPTIONS VkNameList() VkNameList(void); VkNameList(char* name); VkNameList(const VkNameList& givenList); 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); 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. 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 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) 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 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