tsc_JobLines

This class represents all lines within a job.  Basically, a line is constructed between two points, or from a single point with a bearing and distance.  They are defined in the job database via one of the multiple line creation methods.  Lines are based on tsc_Points for their locations.

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

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

Case-sensitivity in line names

tsc_String AdjustNameCase (const char* name);
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 (Arcs, Points, etc) have their own namespaces, and it is possible to have an line and (eg) a point of the same name but remain distinct entities.

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_JobLines member functions

The Snapshot functions obtain a snapshot of the job's lines at the current time.  Use these for iterating through a list of lines, when a copy is required for filtering or other modification, and any other time that line information is required.  The list is in the sequence that the lines were added to the database.

tsc_LineList  Snapshot();
Obtain a list of all lines in the job.

tsc_Line GetLine(const char* name);
This function returns a reference to the line of a given name.  The name must have the correct case - if it hasn't, fix it with the AdjustNameCase member of the tsc_JobLines class.  If no line with the given name is found, the returned object will be empty, and its Exists() function will return false.

tsc_String NextUniqueName (const char* lineName, int stepSize = 1);
Line name generation - supply a name containing a numeric segment, and a step size. An arc 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_LineObservation& obs);
To append a line to the database, use the Append method.  After calling an Append method, the added line will appear in lists produced by Snapshot().

x_Code Delete (tsc_Line& line);
Deletes a line from the job.  The line 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.

x_Code UnDelete (tsc_Line& line);
Un-Deletes a line in the job.
A return code of X_NULL indicates success.