tsc_JobPolylines

This class represents all polylines within a job.  A polyline is essentially a list of line and arc segments which, when connected together, form a single object.  

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

Other functions allow the addition of new polylines, deletion, utility functions to help with naming polylines, etc.

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

Case-sensitivity in polyline 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 each entity type (Lines, Points, Arcs, Polylines) has its own namespace, so it is possible to have, for example, a polyline and a point of the same name but remain distinct entities.

The AdjustNameCase function may be used to change a name's case to that of any existing polyline:

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 case-insensitively 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_JobPolylines member functions

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

tsc_PolylineList  Snapshot();
Obtain a list of all polylines in the job.

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

tsc_String NextUniqueName (const char* polylineName, int stepSize = 1);
Generates a unique polyline name. Supply a name containing a numeric segment, and a step size. A polyline 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 (e.g. POLY99 to POLZ00). 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. For example, passing POLY00 into a series of calls will generate POLY00, POLY01, POLY02, etc but passing in the previous name (POLY01 etc) generates the same sequence but quicker.

Note that a polyline name is only considered to be used when a polyline actually exists, so a simple series of calls to NextUniqueName will generate the same name every time if the polyline is not stored.

x_Code Append (class tsc_PolylineObservation& obs);
Appends a polyline to the database.  After calling an Append method, the added polyline will appear in lists produced by subsequent calls to Snapshot(). A return code of X_NULL indicates success.

x_Code Delete (tsc_Polyline& polyline);
Deletes a polyline from the job.  The polyline 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_Polyline& polyline);
Un-Deletes a previously-deleted polyline in the job. A return code of X_NULL indicates success.