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 readable than floating point values, in some cases.

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

Note that String-based Coordinates such as MGRS are handled in their own separate StringPoint and StringCoordSys.

Reserved Characters

Reserved characters are the characters 'D', 'd', 'M', 'm', 'S', and 's' for angular values, and 'X' and 'x' for linear values. 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 angular units (D, d) and linear units (X,x). When the angular units are degrees (as opposed to radians, etc.), reserve characters for minutes (M, m) and seconds (S,s) may also be used.

Special Characters

Special characters are the characters 'N', 'E', 'P', and (for Angular Values in degrees only) 'o'. All special characters must be preceded the '$' character. These characters will be replaced with an appropriate character when the ToString method is called. They will have no effect when calling the FromString method.

Special Cases

The following formats are special cases that are included for backward compatibility. These format strings may be applied to an Angular Value, and will be "translated" into the actual format specified in the table below. Note that these formats are only valid when units are degrees.

Rules for AngularValue Format Strings

• Format strings may not have breaks in the sequence of reserve characters.
  • Example of bad format: "D D.ddd"
• Numerical values are not allowed in the format string.
  • Example of bad format: "12 DD.d"
• Format strings may not contain more than one decimal.
  • Example of bad format: "DD.d MM.m"
• D must be the first reserve character.
• There must be at least one D in the format string.
• The reserve character before d must be D.
• The reserve character before M must be D.
• The reserve character before m must be M.
• The reserve character before S must be M.
• The reserve character before s must be S.
• $ must be followed by N, E, o, P.
• S, W, n, e, s, and w are not allowed in the format string.
• N and E are only allowed in the format string when prefaced by the $ as described above.
• If the format string contains $o (°), ', " they must be in that order.
• If there is no format set, the format will default to "DDD.ddddddddddddddd"

Rules for AngularValue::FromString

• Any minute or second values >= 60 will always throw an exception.
• The +/- indicator does not need to match the format string. We will always check for a leading or tailing N, W, S, E, n, w, s, e, + or - and assign the sign accordingly. We will throw an exception if there is more than one sign indicator present.
• Leading spaces are ignored unless needed for Packed formats to make them the right size.
• Internal spaces are allowed if they are before or after a separator or if they are in the format string.
• If the format uses some sort of separator (symbols, space, dash, underscore, some other specified set of characters) and the string read in uses a different separator, the value should still be interpreted. Note however that if symbols are used they have to occur in the proper order (degree, min, sec).
• Any non-numerical characters other than those described above will cause exceptions unless they are in the format string. If they are in the format string, however, and are NOT in the string being read in, no error will be thrown (we assume they are only present for ToString, not FromString).
• Additional decimal precision beyond what is specified by the format string is read in, when possible.
  • For "Packed" formats without a trailing decimal, in the case where we are on the last type of character to be processed (ie M if there are no m or S, or S if there are no s) and it is one of the non-decimal characters (D, M or S, but not d, m, s), and there is no decimal in the format string, we assume any additional digits beyond those used for the D, M or S are decimal digits. So, if the format is "DDMMSS" and we are reading in "012345678", we interpret it as 1 degree, 23 minutes, 45.678 seconds. Note however that if the format had been "DDMMSS." it would have thrown an exception.
  • For the special case of "DD.MM", we interpret both "11.2233" and "11.22.33" as 11 deg, 22 min, 33 seconds.
  • For non-Packed formats we will not add missing decimals. So if the format is "DD MM" we interpret "1 2345" as 1 degree, 2345 minutes (and thus it throws an exception).
• If we can't interpret the string provided using our specified format, or if there is no specified format, we do our best to try. For example, if the format is DD, and we get "11 22 33" or "11-22-33", we should interpret those as 11 deg, 22 min, 33 seconds.

Rules for AngularValue::ToString

• The entire whole number portion of the value will be used in the string, even if the number of digits exceeds the number of Ds in the format string.
• The decimal portion of the value will be rounded up to the precision specified by the number of d, m or s terms in the format string.

Rules for LinearValue Format Strings

• Format strings may not have breaks in the sequence of reserve characters
  • Example of bad format: "X X.xxx"
• Numerical values are not allowed in the format string
  • Example of bad format: "12 XX.xxx "
• Format strings may not contain more than one decimal.
  • Example of bad format: "XX.xx."
• X must be the first reserve character.
• There must be at least one X.
• The reserve character before x must be X.
• $ must be followed by N, E, or P
• S, W, n, e, s, and w are not allowed in the format string.
• N and E are only allowed in the format string when prefaced by the $ as described above.
• If there is no format set, the format will default to "XX.xxxxxxxxxxxxxxx"

General Rules for LinearValue::FromString

• The +/- indicator does not need to match the format string. We will always check for a leading N, W, S, E, n, w, s, e, + or -, or a trailing N, W, S, E, n, w, s, e, and assign the sign accordingly. We will throw an exception if there is a trailing + or - (unless the format specifies one either as +, = or as $P). We will throw an exception if there is more than one sign indicator present.
• Spaces are ignored.
• Any non-numerical characters other than those described above will cause exceptions unless they are in the format string. If they are in the format string, however, and are NOT in the string being read in, no error will be thrown (we assume they are only present for ToString, not FromString).
• Additional decimal precision beyond what is specified by the format string is read in, when possible.

General Rules for LinearValue::ToString

• The entire whole number portion of the value will be used in the string, even if the number of digits exceeds the number of Xs in the format string.
• The decimal portion of the value will be rounded up to the precision specified by the number of x terms in the format string.

AngularValue::FromString Examples

AngularValue::ToString Examples

LinearValue::FromString Examples

LinearValue::ToString Examples

LinearValue::MGRS Examples