NCL Website header
NCL Home > Documentation > Graphics

Format conversion specification strings

NCL and the HLU library provide facilities for creating formatted strings representing numerical data items using a format conversion specifier that is modeled after and extends C language print format specifiers. They support very detailed control of the appearance of numerical output, including access to typographical features such as superscripting for exponents. Specifying formatting requirements in this fashion is somewhat tedious and is seen as an interim solution. Eventually, a Format object class may be created that will allow you to specify format conversions using resources tied to each formatting option. However, the string conversion specification does have the virtue of compactness and will continue to be supported. Currently, NCL and the HLU library only support formatting for floating point values. However, reasonable output can be generated for integers as well if they are first converted to an equivalent floating point value. Both the ContourPlot and TickMark classes use the format conversion facilities to control the appearance of their numerical labels. As yet, there are no public entry points allowing the user to directly specify format conversions.

Note that a number of the format options relate to an output field width defined in terms of a character count within which the converted number is to fit. These options do not have well-defined behavior for variable-width (proportionally spaced) fonts. Also, as in standard C (and unlike Fortran), the conversion is printed even if it contains more characters than the number specified for the field width.

Within a string, a C-language conversion specifier is signaled by the presence of an '%' character. You supply conversion specifier strings as the value of string resources specifying the format for some set of numbers that will appear in the output plot. In this context, a leading signal character is unnecessary and is not understood. When conversion specifiers are recognized within strings, they will be signaled--as in C--using the '%' character.

After the signal character, C conversion specifiers consist of a number of 'flag' characters followed by one or two conversion 'fields': for floating point numbers these specify the output field width and (depending on what follows) either the number of significant digits or the number of digits following the decimal point. A C conversion specifier string ends with a one-character conversion specifier, possibly preceded by a one-character conversion qualifier. Conversion specifiers slightly modify and significantly extend this general model. The format specification eliminates the alternate interpretation of the second C conversion field, but uses additional flag characters to signal several more conversion fields. As in C, the conversion string ends with a one-character conversion specifier, although currently NCL and the HLU library recognize fewer conversion specifiers than C and do not support any conversion qualifier characters.

The default approachh, when only a minimal format conversion string is specified, is to output the value using the least number of characters possible. It must be noted that although the format specification is in general a superset of corresponding features from the C language standard, it does not claim to follow the C standard in every detail.

Flag characters

In general, NCL and the HLU library try to give the format flag characters used by C the same basic meaning as C does. This table of format flag characters gives their conventional names and meaning:
+---------------------------------------------------------------+
|		Format flag characters				|
|---------------------------------------------------------------|
| CHARACTER	| NAME and EFFECT				|
|===============================================================|
|	+	| Plus: generate a leading plus sign for	|
|		| positive values.				|
|---------------------------------------------------------------|
|	-	| Minus: left-justify the conversion within the |
|		| field.					|
|---------------------------------------------------------------|
|	#	| Pound: force a trailing decimal point.	| 
|		| 						|
|---------------------------------------------------------------|
|	0	| Zero: first, fill with zeros to account for 	|
|		| all significant digits to the right of the	|
|		| decimal point; then, if field width is 	|
|		| greater than the current string length, fill	|
|		| to field width, left or right depending on	|
|		| the justification.				|
|---------------------------------------------------------------|
|    <space>    | Space: generate a leading space for positive  |
|		| values if the '+' flag is not also present.	|
|---------------------------------------------------------------|
|	!	| Exclamation: If exponential format is in 	|
|		| effect force mantissas of 1 to print.		|
|---------------------------------------------------------------|
|	,	| Comma: use comma (',') as the decimal point 	|
|		| instead of dot ('.').				|
|---------------------------------------------------------------|
|	@	| At-sign: force initial or trailing zero where |
|		| a decimal point would otherwise be the first  |
|		| or last character.				|
|---------------------------------------------------------------|
|	&	| Ampersand: the character following this flag	|
|		| becomes the fill character used instead of	|
|		| spaces to fill in otherwise unoccupied places	|
|		| within the width of the field. 		| 
+---------------------------------------------------------------+
Note that the way NCL/the HLUs handle filling of the output field using zeros ('0') is different from the way they fill using arbitrary characters specified with the Ampersand flag. When zero is the fill character, sign characters ('+' or '-' or <space>) precede any leading zeros. When any other fill character is used, the sign characters follow any leading instances of the fill character.

Conversion fields

The use of the term field could be somewhat confusing in this context. What is meant here are certain options specified using numbers within the format conversion string itself. Some of these fields specify attributes of the "field" within which the converted number is printed in the output plot. Wherever the context does not make it clear, the phrases "conversion field" and "output field" will be used to differentiate between the two uses of the word.

As with C-language format conversion specifiers, any digits immediately following the recognized flag characters (other than an initial zero ('0'), since it is a flag character) specify the width in characters of the output field. All other conversion fields are preceded by a special character signaling the conversion field type, and may appear in any order following any flags and/or field width specification digits. The digits making up each conversion field are interpreted as a single integer read from left to right. Note that for all conversion fields, an asterisk ('*') character may take the place of the digits, and implies that the field value is to be determined dynamically. The code internal to the object that calls the actual formatting routine would then be allowed to supply a value for the conversion field based on its own criteria. If it chooses not to supply a value for any dynamic conversion field, the formatting routine will act as if the field had not been specified at all. As a special shortcut, you can give all otherwise unspecified conversion fields the dynamic attribute by either replacing or following the the output field width conversion field with the characters '*+'. Some of the conversion fields have default values; others are ignored when left unspecified. Here is a table of the conversion fields:

+---------------------------------------------------------------+
|		Conversion fields				|
|---------------------------------------------------------------|
| SIGNAL CHAR	| NAME and MEANING				|
|===============================================================|
|    <none>     | Field width: specifies the output field       |
|		| width in characters. By default, the output 	|
|		| field width is equal to the width required	|
|		| to represent the string. The field width	|
|		| conversion field must directly follow any 	|
|		| format conversion flags.			|
|---------------------------------------------------------------|
|	.	| Significant digits: specifies the number of 	|
|		| significant digits used to express the 	|
|		| output value. Note that for the 'f', 'e', and |
|		| 'E' conversion specifiers this is a departure |
|		| from the C standard where the '.' field 	|
|		| specifies the number of digits to the right 	|
|		| of the decimal point. Use the leftmost 	|
|		| significant digit field (';') in conjunction  |
|		| with the significant digit field to specify a |
|		| constant number of fraction digits. Remember 	|
|		| that zeroes to the right of the rightmost 	|
|		| non-zero digit will not be included in the    |
|		| output string unless the zero flag character  |
|		| ('0') is specified. Default: 6		|
|---------------------------------------------------------------|
|	;	| Leftmost significant digit: specifies the 	|
|		| digit position (in a decimal system) that is  |
|		| to be considered the leftmost significant     |
|		| digit. The units position (the digit directly |
|		| to the left of the decimal point) is counted  |
|		| as digit position 0, and positions are 	|
|		| counted positively towards the left. This	|
|		| conversion field allows you to format a group |
|		| of numbers in a uniform fashion, usually	|
|		| based on the value of the largest number in	|
|		| the group. To achieve this, you would 	|
|		| normally set the field using the dynamic 	|
|		| specifier--the asterisk character ('*')--so	|
|		| that the code invoking the formatting routine |
|		| can specify this conversion field based on	|
|		| its knowledge of each number's value relative	|
|		| to the group of numbers with which it is 	|
|		| associated. If left unspecified, the leftmost |
|		| significant digit is the digit position of 	|
|		| the number's actual most significant digit. 	|
|---------------------------------------------------------------|
|	^	| Exponent field specifier: this conversion	|
|		| field is unusual in that one or two exponent  |
|		| flag characters may precede the field value.	|
|		| Directly after the signal character, either  	|
|		| the letter 'a' or the letter 's' may appear.	|
|		| Next may appear the character '+'. If no 	|
|		| letter appears, the exponent field is written	|
|		| in the form 'exxx...' or 'Exxx...', depending,|
|		| as in the C language, on the case of the final|
|		| conversion specifier character. The letter 'a'|
|		| means that the exponent is written in 	|
|		| 'asterisk' format: 'x10**xxx...'. The letter	|
|		| 's' causes it to be written as a superscript	|
|		| using low-level library function codes. This  |
|		| format cannot be rendered in ascii, but looks |
|		| approximately like 'x10^^^'. The plus		|
|		| character indicates that positive 		|
|		| exponent values should be preceded by a '+'	|
|		| sign. The numerical value specifies the 	| 
|		| number of digits to use in the exponent. If	|
|		| unspecified, the exponent will be expressed 	|
|		| using the fewest digits possible.		|
|---------------------------------------------------------------|
|	?	| Exponent switch length: When the conversion	|
|		| specifier is 'g' or 'G', this conversion 	|
|		| field specifies that the non-exponential 	|
|		| format should be used as long as it requires  |
|		| no more characters than the field's value to 	|
|		| express. Otherwise, the format using the  	|
|		| fewest characters should be used. Default: 5	|
|---------------------------------------------------------------|
|	~	| Point Position: If an output field width is 	|
|		| specified this conversion field specifies	|
|		| the position, counting from the left edge of	|
|		| output field, where the decimal point is to 	|
|		| appear. If it is not possible to place the	|
|		| decimal point in the requested position,	|
|		| it will be placed as near to it as possible. 	|
|		| Note that use of this conversion field 	|
|		| overrides any justification flags. As long as |
|		| a fixed font is used, this field allows you   |
|		| to align vertical columns of numbers based on |
|		| the decimal point position.			|
+---------------------------------------------------------------+

Conversion specifiers

Following the conversion fields, a conversion string ends with a one-character conversion string. Five characters are currently recognized:
+---------------------------------------------------------------+
|		Conversion specifiers				|
|---------------------------------------------------------------|
| CHARACTER	| NAME and MEANING				|
|===============================================================|
|	f	| Floating point format: the number is 		|
|		| expressed in non-exponential format 		|
|		| regardless of its size.			|
|---------------------------------------------------------------|
|	e	| Exponential format, lowercase: the number is  |
|		| expressed using a exponential format. If the	|
|		| letters 'a' or 's' do not appear as part of 	|
|		| the exponential conversion field, the exponent|
|		| is preceded by the character 'e' (lowercase). |
|---------------------------------------------------------------|
|	E	| Exponential format, uppercase: the number is  |
|		| expressed using a exponential format. If the	|
|		| letters 'a' or 's' do not appear as part of 	|
|		| the exponential conversion field, the exponent|
|		| is preceded by the character 'E' (uppercase). |
|---------------------------------------------------------------|
|	g	| Generic format, lowercase: if the number can  |
|		| be expressed in a non-exponential format using|
|		| fewer digits than the value specified by the 	|
|		| exponent switch length conversion field 	|
|		| (default: 5), then the non-exponential 	|
|		| format is used. Otherwise the format using	|
|		| the fewest characters is used. If the 	|
|		| exponential format is used and the		|
|		| letters 'a' or 's' do not appear as part of 	|
|		| the exponential conversion field, the exponent|
|		| is preceded by the character 'e' (lowercase). |
|---------------------------------------------------------------|
|	G	| Generic format, uppercase: if the number can  |
|		| be expressed in a non-exponential format using|
|		| fewer digits than the value specified by the 	|
|		| exponent switch length conversion field 	|
|		| (default: 5), then the non-exponential 	|
|		| format is used. Otherwise the format using	|
|		| the fewest characters is used. If the 	|
|		| exponential format is used and the		|
|		| letters 'a' or 's' do not appear as part of 	|
|		| the exponential conversion field, the exponent|
|		| is preceded by the character 'E' (uppercase). |
+---------------------------------------------------------------+