tsc_JobPoints

This class represents all points within a job and its attached files.  Basically, a point is anything in the job database with a single position, as opposed to arcs, lines, etc.  A station, represented in the tsc_Station class, is a special kind of point and appears in both the point and the station lists.

Member functions are provided to obtain lists of points (see class tsc_PointList) filtered in various ways.  A tsc_PointList also contains member functions to further filter the list down to the required set.

A reference to the tsc_JobPoints is obtained from the Points() method in tsc_Database.  The reference is valid until the job is closed.

Case-sensitivity in point names

Names within Survey Core are case-sensitive, but to the outside world (ie, the user) they are not.  To make this work, every name obtained from an external source, which also exists in the job, must be altered to the correct case before it is used internally.  In practise there are only a small number of cases where this is necessary. 

Note that other entity types (Lines, Arcs, etc) have their own namespaces, and it is possible to have a point and (eg) a line of the same name but remain distinct entities.  Stations and points share the same namespace, since the station name is the name of the point where it is located.

tsc_String AdjustNameCase (const char* name);
Any name that the plugin obtains externally to SC (a file, a form field, etc) must be run through this function before use.  If the name does not exist in the current job, then no change is made to the name.  The name, adjusted or not, is returned.  This function has a lower performance for names that do not exist in the database, or whose case is incorrect. 

tsc_JobPoints member functions

The Snapshot functions obtain a snapshot of the job's points at the current time.  Use these for iterating through a list of points, when a copy is required for filtering or other modification, and any other time that point information is required.  The list is in the sequence that the points were added to the database, followed by points from linked files (CSV, job).

tsc_PointList  Snapshot();
Obtain a list of all points in the job and attached files.

tsc_PointList  Snapshot (const char* name);
Obtain a list of all points with the given name.  Only one of these will be the 'best' point - the one that is used in calculations throughout SC.

tsc_Point BestPoint (const char* name);
This function returns a reference to the best or only point of a given name.  For information about what a "best point" is, see the description in tsc_Point.  The name must have the correct case - if it hasn't, fix it with the AdjustNameCase member of the tsc_JobPoints class.  If no points of the given name are found, the returned object will be empty, and its Exists() function will return false.

tsc_String NextUniqueName (const char* pointName, int stepSize = 1);
Point name generation - supply a name containing a numeric segment, and a step size. A point name that is unique within the database will be generated by incrementing the numeric segment by the step size until a unique name is found.   Alphabetic characters may also be incremented when there is no suitable numeric part.  When many names must be generated, it is more efficient to remember the output name from each call, and pass it back in when generating the next name.

x_Code Append (class tsc_Observation& obs);
Use this method to add a point to the database.  This method is generally used for storing computed or measured results.

After calling an Append method, the added point will appear in lists produced by Snapshot().

x_Code Delete (tsc_Point& point);
Deletes a point from the job.  The point will still appear as an item in the list produced by a subsequent Snapshot() but will be marked as deleted.

A return code of X_NULL indicates success.

Please take care to only delete the appropriate points for your purposes.  Removing points can change the BestPoint status and subtly (or grossly) shift coordinate values.  Some stored results will not be recalculated to account for the change in input data (e.g. points used to calculate areas).  If you interfere with a station setup or backsight coordinate all observations from that station will shift or become unavailable.

x_Code UnDelete (tsc_Point& point);
Un-Deletes a previously-deleted point in the job.

A return code of X_NULL indicates success.