strformat

strformat() Function

• Introduced in version 1.3b48

Returns a string formatted based on the escape sequences in the passed string and optional arguments.

The format string can contain special instructions that are introduced with the % symbol. There are two different approaches to using strformat.

(This function is directly implemented by Java. You can find more details on the syntax of the format here. In particular, that page documents the argument_index modifier which isn't specified here, and MapTool numbers are converted to BigInteger's when formatting integers and BigDecimal's when formatting floating point values.)

Simple words

Simply said, this means that it facilitates creating a string (sentences) which consists of variables or string operations. It's especially useful if you want to store the string into a variable first. The most common method is concatenation:

  [h:target = "Orc"]
  [h:tok = token.name]
  [h:hit = 2d6]
  [h:output = tok + "hits the " + target + " for: " + hit + "wounds."]
  [r:output]

Using strformat, this becomes (just replacing line 4):

  [h:output = strformat("%{tok} hits the %{target} for: %{hit} wounds.")]

Or the other method, if you do not wish to create variables first:

  [h:target = "Orc"]
  [h:output = strformat("%s hits the %{target} for: %d wounds.", token.name, 2d6)]

So why would you use this over the concatenation method? Four reasons:

1. it's cleaner (easier to read),
2. it's faster (though barely noticeable),
3. you can embed the whole operation inside a function call, and
4. it has lots of formatting options.

Formatting by Data Type

The most general use of strformat is to pass a format string first, followed by a list of parameters. Each parameter is matched against the corresponding marker in the format string. Any characters in the format string that are not markers are treated as literal text to be output.

 %(+0x

The first character is the percent sign (%). This denotes a format marker. All text up to the next alphabetic character is part of the marker. In the string above (the %(+0x), each character represents one type of option.

Option Representation	Applies to...	Literal Values
%	All	% identifies the beginning of a format marker.
(	Numeric	( will cause the numeric value to be enclosed in parentheses if it's negative.
+	Numeric	+ indicates that all numeric values, positive or negative, will have a preceding sign.
	All	- indicates that the value to be formatted should be left-justified within the specified field.
0	String	digits indicates the field width for this format marker. This field may contain a decimal point and additional digits to signify the maximum number of characters from the parameter that will be used.
	Numeric	digits indicates the field width for this format marker. If digits starts with a literal 0 (zero), the numeric value being formatted will be zero-filled within the field instead of space-filled. If the format type is floating point, this field may contain a decimal point and additional digits to signify the number of digits after the decimal in the output.
x	All	type is one of the alphabetic characters from the table below. The type identifies the basic characteristics of how the corresponding parameter will be displayed.

Format Types (conversion characters)

The following format types are supported (lower case format arguments perform the same conversion as the lowercase letters but return the result in uppercase).

Format Type	Data Type	Description
%h, %H, %x, %X	Integer	Inserts the hexadecimal representation.
%s, %S	String	Inserts the string representation.
%d	Integer	Inserts the decimal representation.
%e, %E	Numeric	Inserts the floating point value in scientific notation.
%f	Numeric	Inserts the floating point value in fixed-point notation.
%g, %G	Numeric	Inserts the floating point value in computerized scientific notion or fixed-point format.
%a, %A	Numeric	Inserts the floating point value as a hexadecimal floating-point number with a significand and an exponent.
%%	-	Inserts a literal percent symbol.
%n	-	Inserts a newline.

Formatting by Embedding Variables

This type of formatting does not control how the contents of a variable are displayed except that those contents are put into the output at a specific point in the data.

In this style, a single % is followed by a set of braces "{" and "}" with a variable name inside them.

This technique can be mixed with the usage of strformat as shown above.

Usage

strformat(string)

strformat(string, arg, ...)

Examples

    [h: weaponName = "Long Sword"]
    [h: maxDam = 8]
    [r: strformat("Weapon Name=%{weaponName}; Max Damage=%{maxDam}")]

Returns:

Weapon Name=Long Sword; Max Damage=8

    [h: weaponName = "Long Sword"]
    [h: maxDam = 8]
    [r: strformat("Weapon Name=%s; Max Damage=%d", weaponName, maxDam)]

Returns the same result as the previous:

Weapon Name=Long Sword; Max Damage=8

    [h: weaponName = "Long Sword"]
    [h: maxDam = 8]
    [r: strformat("Weapon Name='%12s'; Max Damage=%04d", weaponName, maxDam)]

Returns the same data but formatted. Note how there are two additional spaces in front of the weapon name this time? That's because the field width was specified as 12 in the format marker so the function generated 2 spaces and then the 10 characters from the variable. Also note that 04 caused the damage field to be 4 digits filled with leading zeroes. Take out the 0 from 04 and the output would still include 4 characters, but it would've been space-filled instead of zero-filled.

Weapon Name='  Long Sword'; Max Damage=0008

    [h: weaponName = "Long Sword"]
    [h: maxDam = 8]
    [h: style="background-color: yellow" ]
    [r: strformat("<table><tr style='%{style}'><td>%{weaponName}</td></tr><tr><td>%.0f</td></tr></table>",
           maxDam*1.5)]

Combining the two techniques is often convenient as show here. Note that maxDam is multiplied by 1½ and this could result in a fractional component. Such floating point values must be displayed using one of the floating point format types. (Otherwise the error will be f != java.lang.BigInteger because an integer was provided where a float was expected and it's telling you that the f type doesn't apply to integers. A similar message is displayed if you try to display a floating point value as a decimal.)

    [strformat("%f", -10.502)] [strformat("%g", -10.502)]
    [strformat("%+e", -10.502)] [strformat("%(5.1f", -10.502)]
    [strformat("%5.1f", -10.502)]

Returns:

   -10.502000 
   -10.5020 
    -1.050200e+01 
   (10.5) 
   -10.5