Top: Basic types: Lists: tstrlist

template <class X> class tstrlist {
    tstrlist(int flags = 0);
    ~tstrlist();

    int    get/set_count(int);
    int    get/set_capacity(int);
    bool   get/set_ownobjects(bool);
    void   clear();
    void   pack();

    bool   get_sorted() const;
    bool   get_duplicates() const;
    bool   get_casesens() const;

    // methods that work both on sorted and unsorted lists
    void   ins(int index, string key, X* obj);
    void   put(int index, string key, X* obj);
    void   put(int index, X* obj);
    int    add(string key, X* obj);
    X*     operator [](int index) const;
    string getkey(int index) const;
    void   del(int index);
    int    indexof(string key) const;
    int    indexof(void* obj) const;

    // these methods are allowed only on sorted lists
    int    put(string key, X* obj);
    X*     operator [](string key) const;
    void   del(string key);
    bool   search(string key, int& index) const;
}

The tstrlist template is similar to tobjlist in many ways, except that it maintains pairs of strings and objects of type X, and defines some additional methods described below. Tstrlist can optionally be sorted by string keys, which allows to use it as an associative array of objects. Thus, tstrlist combines functionality of an indexed dynamic array and an associative array at the same time. Like tobjlist, tstrlist can 'own objects', which means it can automatically free objects whenever they are removed from a list.

The methods get/set_count(), get/set_capacity(), get/set_ownobjects(), clear() and pack() work as for tobjlist and are not described in this section.

tstrlist::tstrlist(int flags = 0) constructs a tstrlist object. The parameter flags can be a combination of the following constants:

• SL_OWNOBJECTS - this tstrlist object will be responsible for freeing objects.
• SL_SORTED - create a sorted list; the items are kept in an alphabetically sorted order. This allows to use a tstrlist object as an associative array.
• SL_DUPLICATES - allow duplicate keys. Must be combined with SL_SORTED.
• SL_CASESENS - perform case-sensitive search. By default the search is case-insensitive.

void tstrlist::ins(int index, string key, X* obj) inserts a key/object pair into a list at the position index. For sorted lists index must be equal to the value returned by search() for the given key. A common pattern of using ins() on sorted lists is to call search() for a key to determine whether an object associated with a given key exists, then either insert a new object at the position pointed to by search() or to get the existing object at that position.

void tstrlist::put(int index, string key, X* obj) puts (replaces) the key/object pair at the position index.

void tstrlist::put(int index, X* obj) puts obj at the position index. The key at this position remains unchanged.

int tstrlist::add(string key, X* obj) on sorted lists this method performs search and inserts the key/object pair at a proper position to keep the list in a sorted order. For ordinary (unsorted) lists this method adds the key/object pair at the end of a list.

X* tstrlist::operator [](int index) returns an object at the position index.

string tstrlist::getkey(int index) returns the key value at the position index.

void tstrlist::del(int index) deletes the key/object pair at the position index.

int tstrlist::indexof(string key) determines the index of a given key. This function performs binary search on sorted lists, or otherwise linear search on unsorted lists. Returns -1 if key is not found.

int tstrlist::indexof(void* obj) determines the index of a given object. Always uses linear search. Returns -1 if obj is not found.

int tstrlist::put(string key, X* obj) is a universal method of adding, replacing and removing objects in a sorted list. Put() performs search by a given key and inserts obj if the key doesn't exist in a list, replaces the old object with obj if the key was found in a list, or deletes the key/object pair if the parameter obj was NULL.

X* tstrlist::operator [](string key) returns an object associated with a given key. Works only on sorted lists. Returns NULL if key is not found.

void tstrlist::del(string key) deletes the key/object pair for a given key. Works only on sorted lists.

bool tstrlist::search(string key, int& index) performs binary search on a list. Returns true if key is present in a list. The output parameter index contains either the position at which key was found, or otherwise the position where key must be inserted to preserve the sorted order.

See also: tobjlist, textmap