SetFormat - Syntax & Usage | AutoHotkey

AutoHotkey

SetFormat

Sets the format of integers and floating point numbers generated by math operations.

Deprecated: This command is not recommended for use in new scripts. Use the Format function instead.

SetFormat, NumberType, Format

Parameters

NumberType

Must be either IntegerFast, FloatFast, Integer, or Float (the two fast modes require [v1.0.48+]; see remarks).

Format

For NumberType Integer or IntegerFast, specify H or HEX for hexadecimal, or D for decimal. Hexadecimal numbers all start with the prefix 0x (e.g. 0xFF). [AHK_L 42+]: Hexadecimal integers are formatted with digits A-F in lowercase when this parameter is h and uppercase when it is H.

For NumberType Float or FloatFast, specify TotalWidth.DecimalPlaces (e.g. 0.6). [v1.0.46.11+]: The letter "e" may be appended to produce scientific notation; e.g. 0.6e or 0.6E (using uppercase produces an uppercase E in each number instead of lowercase). Note: In AutoHotkey 1.x, scientific notation must include a decimal point; e.g. 1.0e1 is valid but not 1e1.

TotalWidth is typically 0 to indicate that number should not have any blank or zero padding. If a higher value is used, numbers will be padded with spaces or zeroes (see remarks) to make them that wide.

DecimalPlaces is the number of decimal places to display (rounding will occur). If blank or zero, neither a decimal portion nor a decimal point will be displayed, that is, floating point results are displayed as integers rather than a floating point number. The starting default is 6.

Padding: If TotalWidth is high enough to cause padding, spaces will be added on the left side; that is, each number will be right-justified. To use left-justification instead, precede TotalWidth with a minus sign. To pad with zeroes instead of spaces, precede TotalWidth with a zero (e.g. 06.2).

Fast vs. Slow Mode

[v1.0.48+]: IntegerFast may be used instead of Integer, and FloatFast may be used instead of Float.
  • Advantages: The fast mode preserves the ability of variables to cache integers and floating point numbers, which substantially accelerates numerically-intensive operations. (By contrast, the slow mode forces all numeric results to be immediately converted and stored as strings.)
  • Disadvantages: When storing a number in a variable, the fast mode delays the effects of SetFormat until the script actually needs a text/string version of that variable (e.g. to display in a MsgBox). Since a different SetFormat may be in effect at that time (e.g. more or fewer decimal places), this can lead to unexpected results. To make the current fast format take effect immediately, use an operation like HexValue .= "", which appends an empty string to the number currently stored in HexValue.

If the slow mode "Integer" or "Float" is used anywhere in the script, even if that SetFormat line is never executed, the caching of integers or floating point numbers (respectively) is disabled the moment the script launches.

Floating Point Format

[v1.0.48+]: Floating point variables have about 15 digits of precision internally unless SetFormat Float (i.e. the slow mode) is present anywhere in the script. In that case, the stored precision of floating point numbers is determined by DecimalPlaces (like it was in pre-1.0.48 versions). In other words, once a floating point result is stored in a variable, the extra precision is lost and cannot be reclaimed without redoing the calculation with something like SetFormat, Float, 0.15. To avoid this loss of precision, avoid using SetFormat Float anywhere in the script, or use SetFormat FloatFast instead.

Regardless of whether slow or fast mode is in effect, floating point results and variables are rounded off to DecimalPlaces whenever they are displayed or converted to a string of text (e.g. MsgBox or FileAppend). To see the full precision, use something like SetFormat, FloatFast, 0.15.

To convert a floating point number to an integer, use Var:=Round(Var), Var:=Floor(Var), or Var:=Ceil(Var). To convert an integer to a floating point number, add 0.0 to it (e.g. Var+=0.0) or use something like MyFloat:=Round(MyInteger, 1).

The built-in variable A_FormatFloat contains the current floating point format (e.g. 0.6).

Integer Format

Integer results are normally displayed as decimal, not hexadecimal. To switch to hexadecimal, use SetFormat, IntegerFast, Hex. This may also be used to convert an integer from decimal to hexadecimal (or vice versa) as shown in the example at the very bottom of this page.

Literal integers specified in a script may be written as either hexadecimal or decimal. Hexadecimal integers all start with the prefix 0x (e.g. 0xA9). They may be used anywhere a numerical value is expected. For example, Sleep 0xFF is equivalent to Sleep 255 regardless of the current integer format set by SetFormat.

AutoHotkey supports 64-bit signed integers, which range from -9223372036854775808 (-0x8000000000000000) to 9223372036854775807 (0x7FFFFFFFFFFFFFFF).

The built-in variable A_FormatInteger contains the current integer format (H or D).

General Remarks

If SetFormat is not used in a script, integers default to decimal format, and floating point numbers default to TotalWidth.DecimalPlaces = 0.6. Every newly launched thread (such as a hotkey, custom menu item, or timed subroutine) starts off fresh with these defaults; but the defaults may be changed by using SetFormat in the auto-execute section (top part of the script).

An old-style assignment like x=%y% omits any leading or trailing spaces (i.e. padding). To avoid this, use AutoTrim or the colon-equals operator (e.g. x:=y).

You can determine whether a variable contains a numeric value by using "if var is number/integer/float"

To pad an integer with zeros or spaces without having to use floating point math on it, follow this example:

Var := "          " . Var     ; The quotes contain 10 spaces.  To pad with zeros, substitute zeros for the spaces.
StringRight, Var, Var, 10  ; This pads the number in Var with enough spaces to make its total width 10 characters.
Var := SubStr("          " . Var, -9)  ; A single-line alternative to the above two lines.

Related

Format(), Caching, Expression assignment (:=), EnvAdd, EnvSub, EnvMult, EnvDiv, AutoTrim, if var is type

Examples

Var = 11.333333
SetFormat, float, 6.2
Var -= 1  ; Sets Var to be 10.33 with one leading space because the total width is 6.
SetFormat, float, 0.2
Var += 1  ; Sets Var to be 11.33 with no leading spaces.
SetFormat, float, 06.0
Var += 0  ; Sets Var to be 000011

; Convert a decimal integer to hexadecimal:
SetFormat, IntegerFast, hex
Var += 0  ; Sets Var (which previously contained 11) to be 0xb.
Var .= ""  ; Necessary due to the "fast" mode.
SetFormat, IntegerFast, d