tsc_PointList

This class is a container for point objects.  A PointList is useful as a snapshot of the points at the time it was constructed from the job. Empty PointLists can be created also.  A PointList can be filtered in various ways to reduce it to some desired subset of the points in the job, and this is the usual way to extract a filtered list.

The list does not represent the actual point objects in the database, it is simply a read-only way to access the information.  Modifying the list affects only the list; the database remains unchanged.

The list can be indexed by using the zero-based [] operator on the class to obtain a tsc_Point object.  Point objects obtained like this do not necessarily exist, because the user may unlink a linked job or csv file at any time, which causes all points from that file to cease to exist.  Non-existent points remain in the list but are empty and their Exists property is false.  Many filters remove non-existent points from a list, or they can be explicitly removed by calling RemoveNonexistent().

Public constructors

tsc_PointList (const tsc_PointList& copy);
Generally a point list is constructed by calling a function on tsc_JobPoints 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_PointList ();
Creates an empty list.

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

Public methods

tsc_Point operator[] (int item);
The [] operator will access any point in the list by index, which starts at zero and ends at Count() - 1.
Point objects in an unmodified list obtained from tsc_Database are in database (time) sequence.

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

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

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

void Append (const tsc_Point& point);
Adds a point object to the end of the list.  This action affects only the list, not the job.

void Remove (const tsc_Point& point);
Removes a point from the list.  If the same point 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 point 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.  Consider using SelectBy instead.

void Clear();
Removes all items.

void Find (tsc_IEntityFilter match, int startIndex = 0);
This function may be used to find a point in the list; it is somewhat faster than looping through the list yourself, if the list can be big.  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 point objects.  It is also more efficient to first select for uncommon conditions.  For instance, to find all 3D gridable points with names between P1 and P20, select the name range first and the gridable 3D second, since many if not all points will be gridable and testing for being gridable may involve a coordinate transformation.

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

void SelectCollatingNameRange (const char* from, const char* to);
This function selects all points within a name range.  The names are first sorted such that numeric segments within the name are collated in a more intuitive sequence.  For instance, a normally sorted list of points might contain the sequence of names [P1,P10,P2,P20,P3], whereas this function sorts them as [P1,P2,P3,P10,P20].  The resulting point list will have been sorted by name in this manner.

void RemoveDuplicatesByName ();
Removes items with names seen previously (at a lower index) in the list.  The best point status is not considered; the first item found is retained and subsequent items are removed.

void RemoveDeleted();
Deleted items are normally included in point lists.  To remove them, call this method.

void SelectBy (tsc_IEntityFilter* keep);
This function allows any point to be tested by a callback function and either 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 points in a list.

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