The FormattedPrint method was added to MAXScript in 3ds Max 9. It was previously available through the free Avguard Extensions.
formattedPrint <value> format:<string> userLocale:<boolean>Returns a string representation of value based on the format specified.
The format specified is applied for each component value for values that are comprised of more than a single value.
For values or component values that are floating point numbers, the default format string is "0.8g", for integers, "%d".
The value specified must be one of: float, double, integer, integer64, intptr, string, bool, ray, point2, point3, point4, quat, angleAxis, eulerAngle, matrix3, box2, color, time, or interval.
formattedPrint() function calls the c++ printf() function with the corresponding value and format. There is no validation that the format is correct for the specified value type. It is up to the user to ensure that the format specified is correct for the value type. For example, using a format of "04d" for a float value will result in the string "0000". See the printf() format specification for more information.The optional userLocal parameter specifies whether to use the decimal character specified by the user's locale. If false (the default) a period (".") is used as the decimal character, regardless of locale. Available in 3ds Max 2020.1 Update and higher.
The optional format: string is of the form:
"[Flags][Width][.Precision][SizePrefix]Type"where
Flags is:
| Flag | Meaning |
|---|---|
- |
Left align the result within the given field width. Default is to right align. |
+ |
Prefix the output value with a sign (+ or -). Default is that sign appears only for negative signed values (-). |
0 |
If width is prefixed with 0, zeros are added until the minimum width is reached. If 0 and - appear, the 0 is ignored. If 0 is specified with an integer format (i, u, x, X, o, d) the 0 is ignored. Default is no padding. |
Blank(' ') |
Prefix the output value with a blank if the output value is signed and positive; the blank is ignored if both the blank and + flags appear. Default is no blank appears. |
# |
When used with the o, x, or X format, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively. Default is no blank appears. When used with the e, E, or f format, the # flag forces the output value to contain a decimal point in all cases. Default is decimal point appears only if digits follow it. When used with the g or G format, the # flag forces the output value to contain a decimal point in all cases and prevents the truncation of trailing zeros. Default is decimal point appears only if digits follow it, and trailing zeros are truncated. Ignored when used with d, i, or u. |
Width is a non-negative decimal integer controlling the minimum number of characters printed. If the number of characters in the output value is less than the specified width, blanks are added to the left or the right of the values - depending on whether the - flag (for left alignment) is specified - until the minimum width is reached. If width is prefixed with 0, zeros are added until the minimum width is reached (not useful for left-aligned numbers). The width specification never causes a value to be truncated. If the number of characters in the output value is greater than the specified width, or if width is not given, all characters of the value are printed (subject to the precision specification).
Precision specifies a non-negative decimal integer, preceded by a period (.), which specifies the number of characters to be printed, the number of decimal places, or the number of significant digits. Unlike the width specification, the precision specification can cause either truncation of the output value or rounding of a floating-point value. If precision is specified as 0 and the value to be converted is 0, the result is no characters output.
Type:d, i, u, o, x, X - The precision specifies the minimum number of digits to be printed. If the number of digits in the argument is less than precision, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds precision. Default precision is 1.
Type:e, E - The precision specifies the number of digits to be printed after the decimal point. The last printed digit is rounded. Default precision is 6; if precision is 0 or the period (.) appears without a number following it, no decimal point is printed.
Type: f - The precision value specifies the number of digits after the decimal point. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits. Default precision is 6; if precision is 0, or if the period (.) appears without a number following it, no decimal point is printed.
Type: g, G - The precision specifies the maximum number of significant digits printed. Six significant digits are printed, with any trailing zeros truncated.
Type: s - The precision specifies the minimum number of characters in the string, and left-pads the formatted string with space characters, if required.
where Type character is the only required format field; it appears after any optional format fields.
| Character | Type | Output Format |
|---|---|---|
d, i |
int | Signed decimal integer. |
o |
int | Unsigned octal integer. |
u |
int | Unsigned decimal integer. |
x |
int | Unsigned hexadecimal integer, using "abcdef." |
X |
int | Unsigned hexadecimal integer, using "ABCDEF." |
e |
double | Signed value having the form [ - ]d.dddd e [sign]ddd where d is a single decimal digit, dddd is one or more decimal digits, ddd is exactly three decimal digits, and sign is + or - ;. |
E |
double | Identical to the e format except that E rather than e introduces the exponent. |
f |
double | Signed value having the form [ - ]dddd.dddd, where dddd is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number, and the number of digits after the decimal point depends on the requested precision. |
g |
double | Signed value printed in f or e format, whichever is more compact for the given value and precision. The e format is used only when the exponent of the value is less than -4 or greater than or equal to the precision argument. Trailing zeros are truncated, and the decimal point appears only if one or more digits follow it. |
G |
double | Identical to the g format, except that E, rather than e, introduces the exponent (where appropriate). |
s |
string | A string of characters. |
SizePrefix is:
I - value being printed is an IntegerPtr
I32 - value being printed is an Integer
I64 - value being printed is an Integer64
For Integer values, the default format is "I32d"
v = 12611668 -- Integer formattedPrint v "12611668"
For Integer64 values, the default format is "I64d"
v = 126116680000L -- Integer64 formattedPrint v "126116680000"
For IntegerPtr values, the default format is "Id"
v = 12611668P -- IntegerPtr formattedPrint v "12611668"
EXAMPLE
formattedPrint pi "3.1415927" formattedPrint pi format:"0 g" " 3.14159" formattedPrint -pi format:"0 g" "-3.14159" formattedPrint pi format:"12.8g" " 3.1415927" -- when user locale uses "," as the decimal separator: formattedPrint pi userLocale:true "3,1415927" formattedPrint yellow "(color 255 255 0)" m = matrix3 1 formattedPrint m "(matrix3 [1,0,0] [0,1,0] [0,0,1])" formattedPrint m format:"#g" "(matrix3 [1.00000,0.000000,0.000000] [0.000000,1.00000,0.000000] [0.000000,0.000000,1.00000])" formattedPrint 10 format:"#o" "012" formattedPrint 10 format:"#x" "0xa" formattedPrint v format:"19.18g" " 1.2345678901234567" formattedPrint "abc" format:"15s" " abc"