tsc_LineList

This class is a list of line objects.  It is generally a snapshot of the lines at the time it was constructed from the job, empty line lists can be created however.  A LineList can be filtered in various ways to reduce it to some desired subset of all lines in the job.

A line list does not represent the actual line entities in the database, it is simply a read-only access to them.  Functions that change the list such as Remove modify only the list, not the database.

The list can be indexed by using the zero-based [] operator on the class to obtain a tsc_Line object. Line objects in an unmodified list obtained from tsc_Database are in database (time) sequence.

Constructor

tsc_LineList (const tsc_LineList& copy);
Generally a line list is constructed by calling a function on tsc_JobLines that returns a list.  The copy constructor simply makes a reference to the same list, so that changes made to either copy will be reflected in the other.

tsc_LineList ();
Creates an empty list.

tsc_LineList Clone();
Clone makes a shallow copy of the list.  The list itself is copied but all references are to the same line objects.  Changes made to the copy list will not affect the original.

Public methods

tsc_Line operator[] (int item);
The [] operator will access any line in the list by index, which starts at zero and ends at Count() - 1.

tsc_StringList ToStringList();
Returns a string list containing the names of all the lines in the tsc_LineList.

int Count () const;
The number of lines in the list is returned.

 bool IsEmpty() const;
Returns true if the list is empty.

void Append (const tsc_Line& line);
Add a line object to the end of the list.  This action affects only the list, not the job.

void Remove (const tsc_Line& line);
Remove a line from the list.  If the same line exists more than once in the list, only the first is removed.  Note: The list is searched sequentially for the object, and then compacted; avoid using this repetitively on potentially large lists.  Consider using SelectBy instead.

void Remove (int index);
Removes the line from the list at the given index, counting from zero.  Note: The list is compacted after the item is removed; avoid use on large lists or looping to remove many items.  Consider using SelectBy instead.

void Clear();
Removes all items.

void Find (tsc_IEntityFilter match, int startIndex = 0);
To find a line in a list, this function may be used; it is faster than looping through the list yourself.  Construct a subclass of tsc_IEntityFilter and implement your search function there. See the documentation for tsc_IEntityFilter for details.

Filtering the list

These functions remove all but the selected items from an existing list.  They are significantly faster than iterating through the list to access and remove individual line objects.  It is also more efficient to first select for uncommon conditions.  For instance, to find all 3D gridable lines with names between L1 and L20, select the name range first and the gridable 3D second, since many if not all lines will be gridable and testing for being gridable may involve a coordinate transformation.

void SelectGridable (int dimensions);
Use this to select lines that are convertible to grid coordinates with the given number of dimensions - 1, 2, or 3.  A dimension of 1 selects all lines with a height, 2 selects lines with both horizontal dimensions, and 3 selects only lines with all three.

void SelectCollatingNameRange (const char* from, const char* to);
This function selects all lines within a name range.  The names are sorted such that numeric segments within the name are collated in a more intuitive sequence.  For instance, a normally sorted list of lines might contain the sequence of names [L1,L10,L2,L20,L3], whereas this function sorts them as [L1,L2,L3,L10,L20].  The resulting line list will have been sorted by name in this manner.

void RemoveDeleted();
Deleted items are normally included in line lists; this function removes them.

This function allows any line to be tested by a callback function and kept or removed as determined by the callback.    See the documentation for tsc_IEntityFilter for details and an example.  Using this function is very much faster than individually testing and removing lines in a list.

A NULL filter will result in no filtering - all objects will be retained.

void SelectBy (tsc_IEntityFilter* keep);