FLORMAT Name
FLORMAT
Author
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
Craig.Markwardt@nasa.gov Purpose
Format a string with named format variables
Calling Sequence
RESULT = FLORMAT(FORMAT, [ struct ], [x=x, y=y, ...], [_EXTRA=struct])
Description
The function FLORMAT is used to easily insert a set of named
parameters into a string using simple format codes. The key point
is that format strings use *named* parameters instead of the
position in the string.
FLORMAT makes it easy to make maintainable and understandable
format codes. FLORMAT is a convenience routine, which will be most
suitable for formatting tabular output, but can be used for any
complicated string formatting job where the positional parameters
of STRING() become hard to manage. Users of Python will recognize
FLORMAT as implementing "string interpolation."
The user passes a format string similar to the IDL printf-style
format string (i.e. using modified "%" notation), and a set of
named fields either by passing a structure, keywords, or both. The
output strings are composed by inserting the named fields into the
format string with any requested formatting.
The function FLORMAT is equivalent to the STRING(...,FORMAT=fmt)
method of formatting a string, where the format string is allowed
to have the name of the variable.
Let us consider an example of formatting a time with hours, minutes
and seconds into a string as HH:MM:SS. One could use FLORMAT()
like this,
result = flormat('%(hour)02d:%(min)02d:%(sec)02d', $
hour=hour, min=min, sec=sec)
The variables HOUR, MIN and SEC are allowed to be scalars or
vectors. The key point here is that the format string contains the
*named* keyword variables (or structure entries). Unlike STRING(),
the actual variables can be passed in any order, since the format
string itself describes in what order the values will be assembled.
This is similar to string interpolation in Python.
The same variable can appear multiple times in the format string,
but the user only need to specify that variable once. For example,
result = flormat('<A="%(href)s">Download %(href)s', $
href='filename.txt')
Note that HREF appears twice in the format string.
Input Variables
FLORMAT() allows you to pass in the values as named keywords as
shown above, where the keyword values are arrays, or by passing in
an array of structures. A similar example to the one above is,
S = replicate({hour: 0, min: 0, sec: 0}, 100)
; ... fill the structure S with 100 time values ...
result = flormat('%(hour)02d:%(min)02d:%(sec)02d', s)
In this case S is an array of structures, and the result will be an
array of strings with the same number of elements as S.
Compare this with standard IDL where a FOR-loop is required, no
repetition is permitted, and it is difficult to see which format
code corresponds to which variable. For example,
for i = 0, n_elements(hour)-1 do begin
result(i) = string(hour(i), min(i), sec(i), $
format='(%"%02d:%02d:%02d")')
The input structure STRUCT may be an array of structures or a
structure of arrays. It is also possible pass *both* a structure
STRUCT and keywords. The important thing is that the each keyword
and each STRUCT.FIELD must evaluate to the same number of
elements. If they don't, then the smallest number of elements is
used.
PRINTF-STYLE FORMAT CODES
FLORMAT() uses format codes in either C printf-style format codes
(the default), or a new "$" shell-style syntax if /SHELL_STYLE$ is
set.
FLORMAT() assumes that by default the C printf-style format codes
are passed. FLORMAT() uses a slightly short-hand notation for
print-style format codes which saves some space and is more
flexible.
Standard printf-style format codes are of the form,
FORMAT='(%"...format here...")' ;; Standard IDL
The FLORMAT printf-style format codes simply dispense with the
redundant parentheses and percent symbol,
FORMAT='...format here...' ;; FLORMAT notation
This notation improves the readability of the format string, since
only the actual format string needs to be present. Also, this
notation does not embed one set of quotation marks within another,
as the standard IDL notation does, so format strings with quotation
marks will be easier to compose.
Standard IDL format codes look like this,
%s - string
%d - integer
%04d - integer zero-padded to 4 spaces, etc
The new FLORMAT format strings look like this,
%(name)s - string based on variable named NAME
%(value)d - integer based on variable named VALUE
%(index)04d - integer based on variable named INDEX,
zero-padded to 4 spaces
As you can see, the only difference is the addition of the variable
name in parenthesis. These names are looked up in the input
keywords and/or structure passed to FLORMAT().
SHELL-STYLE FORMAT CODES
Shell style "$" is a convenience notation when strict formatting is
less important. Shell-style "$" format strings will be signaled by
setting the SHELL_STYLE$ keyword. Note the trailing dollar-sign
'$'. The format coes will look like this,
$name - variable named NAME will be placed here
$value - variable named VALUE will be placed here, etc.
This is exactly how Unix shell string interpolation works.
Variables are substituted into place using their "natural" format
code, based on the variable type.
result = flormat('<A=\"$href\">Download $href', /shell_style$, $
href='filename.txt')
Note that quotation marks still need to be escaped as \", just the
same as calling STRING() or PRINT with a %-style format string.
CAVEATS:
FLORMAT() is a convenience routine meant mostly to improve the
readability and maintainability of format codes. FLORMAT() is not
meant for high performance applications. It spends time parsing
the input format string. It also spends memory building up a
temporary output structure. However, for most applications such as
constructing tables of up to thousands of entries, FLORMAT() should
be perfectly adequate.
The name "FLORMAT" is a play on the words "floor-mat" and "format."
The "L" in FLORMAT can be thought of standing for "long-form" IDL
format codes. Parameters
FORMAT - format string used to
STRUCT - input structure containing named entries. This should
either be an array of structures, with each field
containing a scalar; or, a structure where each field
contains an array with the same number of elements.
Returns
The resulting formatted strings. The return value will be an
array of strings containing the same number of elements as passed
as input. Keyword Parameters
SHELL_STYLE$ - if set, then the format string is a shell-style
string.
All named keywords are available to be used as named formats in
your format code. Values may be either scalar, or vector.
Vectors dimensions must match the dimensions of STRUCT (if
STRUCT is passed). Example
; Additional examples appear above.
See Also
STRING, Format codes, C print-style format codes
Modification History
Written, CM, 14 Sep 2009
Finalized and documented, CM, 08 Dec 2011