String Formats

While it is possible to use floating point values to get and set the value of an AngularValue or LinearValue, or to specify the position of a GeodeticPoint or ProjectedPoint, it is also possible to do this using formatted strings.  This can be helpful when displaying information to the user or retrieving information from the user, since formatted strings can be more user readable than floating point values, in some cases.

AngularValue

There are many different formats that can be used to express AngularValues.  In order to use these, it is necessary to first set the AngularValue::Format property with the appropriate formatting string.  Formatting strings consist of three parts: reserved characters, special characters, and separator characters.  There are also some special cases that are included for backwards compatibility.

Reserved Characters

Reserved characters are the characters 'D', 'd', 'M', 'm', 'S', and 's'.  These characters are used to represent the locations where numerical values will be located when using the ToString method and will determine how we translate the input string when using the FromString method.  The capital letters denote the whole portion and the lower case letters denote the decimal portion of degrees (D, d), minutes (M, m), and seconds (S,s).  

The behavior of the reserve characters when using the ToString method is quite simple.  The characters will be replaced in their exact locations with the appropriate numerical character based on the value of the AngularValue.  If the whole portion of the number is larger than the space allocated by its reserve character then extra space is allocated so the whole value can be displayed.  However, relying on this is a bad practice since it can cause problems when using the FromString method with packed (unseparated) formats.  The decimal portion of the formatted value will be limited to the space allocated by its reserve characters, which allows control of decimal precision.  When more space is allocated than is needed 0s will be inserted to fill the space without effecting the actual value of the number (leading for whole portions and trailing for decimal portions).

The behavior of the reserve characters becomes slightly more complicated when using the FromString method.  The reserve characters determine how numerical characters are valued when found in the input string, which can affect the value of AngularValue.  When parsing an input string, groupings of numerical characters in the input string will be lined up with groupings of reserve characters in the format string.  Next, if there are any groupings of reserve characters that contain more than one distinct reserve character, then the corresponding grouping of numerical characters will be matched up with the reserve characters going left to right with any extra numerical characters being assigned to the last reserve character value.  If there are more groupings of numerical characters than there are groupings of reserve characters, then the special case of "DD" is used.

Special Characters

Special characters are the characters 'I', 'N', 'E', 'P', and 'o' when preceded by the special character identifier which is the character '$'.  These characters along with the identifier character will be replaced with an appropriate character when the ToString method is called, they will however have no effect when calling the FromString method except to break up reserve characters.

Separator Characters

Separator characters include all characters that are not reserved characters, numerical characters, or special characters.  These will be placed in the formatted string in the appropriate place when using the ToString method.  When parsing a formatted string using the FromString method, the separator characters will be used to break up the blocks of reserved characters.

Special Cases

The following formats are special cases with the AngularValue::FromString method:

The following formats are special cases with the AngularValue::ToString method:

Examples

In Example 1, "123" is assigned to be the whole degrees ('D') value because of the breaks in numerical and reserve characters and "333" is assigned to decimal seconds ('s') because it is the last reserve character present.

In Example 2, "12" is assigned to be the whole degrees ('D') value because there are only two D reserve characters and no breaks in either strings and "5333" is assigned to decimal seconds ('s') because it is the last reserve character present.

In Example 3, "123" is assigned to be the whole degrees ('D') value because there are three 'D' reserve characters and "333" is assigned to decimal seconds ('s') because it is the last reserve character present.

In Example 4, Since there are more breaks in the Input String than the Format String the special case of "DD" is used.

LinearValue

The only supported string format for use with LinearValues is the Military Grid Reference System format.  This can be specified by setting the LinearValue::Format property to "MGRS".  This format has been deprecated in GeoCalc 6.3.  To use MGRS strings in GeoCalc, use the string formatting capabilities on the ProjectedPoint object, which are described below.