tsc_JobArcs

This class represents all arcs within a job.  Basically, an arc is a partial circle defined in the job database via one of the multiple arc creation methods.  Arcs are based on tsc_Points for their locations.

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

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

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

Case-sensitivity in arc 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, an arc and a line 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 arc:

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

The Snapshot functions obtain a snapshot of the job's arcs at the current time.  Use these for iterating through a list of arcs, 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 arcs were added to the database.

tsc_ArcList  Snapshot();
Obtain a list of all arcs in the job.

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

tsc_String NextUniqueName (const char* arcName, int stepSize = 1);
Generates a unique Arc name. 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 (e.g. ARC99 to ARD00). 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_ArcObservation& obs);
Appends an arc to the database.  After calling an Append method, the added arc will appear in lists produced by Snapshot().

x_Code Delete (tsc_Arc& arc);
Deletes an arc from the job.  The arc 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_Arc& arc);
Un-Deletes an arc in the job. A return code of X_NULL indicates success.