# Format

根据格式字符串格式化一个可变数量的输入值.

    String := Format(FormatStr , Values...)

## 参数

FormatStr

  类型: 字符串

  格式字符串由原义文本和占位符组成, 其形式为 `{Index:Format}`.

  Index 是一个整数, 表示要使用的那个输入值, 其中 1 是第一个值.

  Format 是一个可选的格式指定器, 如下文所述.

  省略索引可以使用序列中的下一个输入值(即使先前已经被使用过). 例如, `"{2:i} {:i}"` 会将第二个和第三个输入值格式化成十进制整数, 用空格隔开. 如果省略了 Index, 仍然必须在 Format 前面加上 `:`. 指定空大括号, 将使用默认格式处理下一个输入值: `{}`

  使用 `{{}` 和 `{}}` 来包含字符串中的原义括号. 任何其他无效的占位符都会被包含在结果中.

  不允许在大括号中包含空格符(除非作为标志).

Values

  类型: 字符串, 整数或浮点数

  将要格式化的输入值. 每个值都是一个独立的参数. 第一个值的索引为 1.

  要传递一个数组值, 可以使用可变函数调用:

      arr := [13, 240]
      MsgBox Format("{2:x}{1:02x}", arr*)

## 返回值

类型: 字符串

该函数返回指定字符串的格式化版本.

## 格式指定器

每个格式指定器可以按顺序包含以下几个部分(不含空格):

    Flags Width .Precision ULT Type

Flags: 从下面的标志表中选择零个或多个标志来影响输出的对齐方式和前缀.

Width: 十进制整数, 控制格式化值的最小宽度, 以字符为单位. 默认情况下, 值是右对齐的, 使用空格进行填充. 这可以通过使用 `-`(左对齐) 和 `0`(前缀 0) 标志来覆盖.

.Precision: 十进制整数, 控制要输出的字符串, 小数位数或有效数字的最大位数, 取决于输出类型. 输出类型(Type) 的最前面必须是小数点. 指定精度可能会导致输出值被截断(或四舍五入) 或补全的方式. 输出类型以及每种类型受到精度值的影响如下(有关不同输出类型的解释, 参见下表):

- `f`, `e`, `E`: Precision 指定小数点后的位数. 默认值为 6.
- `g`, `G`: Precision 指定最大的有效数字数. 默认值为 6.
- `s`: Precision 指定要打印的最大字符数. 超过这个数字的字符不会被打印.
- 对于整数类型(`d`, `i`, `u`, `x`, `X`, `o`), Precision 的作用类似于前缀为 `0` 默认值为 1 的 Width.

ULT: 指定应用于字符串值的大小写转换 -- U(大写), L(小写) 或 T(标题). 仅对 `s` 类型有效. 例如 `{:U}` 或 `{:.20Ts}`. 也支持小写字母 `l` 和 `t`, 但 `u` 被保留给无符号整数.

Type: 下面类型表中一个指示输入值将被如何解析的字符. 如果省略, 默认为 `s`.

## Flags

标志 | 含义
--- | ---
`-` | 在给定位宽下使结果左对齐(不足位宽的右侧部分补以空格). 例如, `Format("{:-10}", 1)` 返回 `1` . 如果省略, 结果将在给定的位宽内右对齐.
`+` | 如果输出值是带符号的类型, 则使用符号(+ 或 -) 作为前缀. 例如, `Format("{:+d}", 1)` 返回 `+1`. 如果省略, 仅在输出值是负数时显示符号(-).
`0` | 如果 width 以 0 为前缀, 前导 0 将被添加直至最小宽度. 例如, `Format("{:010}", 1)` 返回 `0000000001`. 若同时使用 `0` 和 `-`, 则前者将被忽略. 如果 0 被指定为整数格式(i, u, x, X, o, d) 且同时带有精度指示 - 例如, `{:04.d}` - 此时的 0 会被忽略. 如果省略, 不填充.
`` (空格) | 当输出值有符号且为正数时, 以 单个 空格为前缀来修饰. 如果空格 `` 和 `+` 同时出现时, 空格将被忽略. 例如, `Format("{: 05d}", 1)` 返回 `0001`. 如果省略, 无空格.
`#` | 当 # 和 o, x 或 X 格式一起使用时, 此标志使用 `0`, `0x` 或 `0X` 的形式分别修饰任意非零的输出值. 例如, `Format("{:#x}", 1)` 返回 `0x1`. 当 # 和 e, E, f, a, A 格式一起使用时, 此标志强制使输出值包含小数点. 例如, `Format("{:#.0f}", 1)` 返回 `1.`. 当 # 和 g 或 G 一起使用时, 此标志强制使输出值包含小数点并保留末尾的 0. 当 # 和 c, d, i, u 或 s 格式一起使用时会被忽略. |

## Types

类型字符 | 参数 | 输出格式
--- | --- | ---
`d` 或 `i` | 整数 | 有符号整数. 例如, `Format("{:d}", 1.23)` 返回 `1`.
`u` | 整数 | 无符号整数.
`x` 或 `X` | 整数 | 无符号十六进制整数; 由 `x` 的大小写形式决定输出值是 "abcdef" 还是 "ABCDEF" 的形式, 仅当使用了 `#` 标志时, `0x` 前缀才会包含到输出值中, 如 `{:#x}`. 要总是包含前缀, 请使用 `0x{:x}` 或类似的. 例如, `Format("{:X}", 255)` 返回 `FF`.
`o` | 整数 | 无符号八进制整数. 例如, `Format("{:o}", 255)` 返回 `377`.
`f` | 浮点数 | 形如 [ - ]dddd.dddd 的有符号数值, dddd 可以是一位或多位十进制数字. 小数点前的数字位数取决于整数部分的大小, 小数点后的数字位数取决于需求的精度. 例如, `Format("{:.2f}", 1)` 返回 `1.00`.
`e` | 浮点数 | 形如 [ - ]d.dddd e [符号]dd[d] 的有符号值, 这里的 d 是一位数字, dddd 是一位或多位数字, dd[d] 是两或三位数字, 取决于输出格式的定义和指数的大小, 这里的 符号 是 + 或 -. 例如, `Format("{:e}", 255)` 返回 `2.550000e+002`.
`E` | 浮点数 | 等同于 `e` 格式, 但结果中指数部分显示的是 E 而不是 e.
`g` | 浮点数 | 以 `f` 或 `e` 格式显示带符号的值, 以给定值和精度更紧凑的为准. `e` 格式只在值的指数小于 -4 或大于或等于 precision 参数时使用. 尾部的零被截断, 小数点只在后面有一个或多个数字时才会出现.
`G` | 浮点数 | 等同于 `g` 格式, 但引入指数时的 e 将被 E 代替(在适当的地方).
`a` | 浮点数 | 形如 [?]0xh.hhhh p±dd 的有符号十六进制双精度浮点值, 其中 h.hhhh 的小数部分是十六进制数值(使用小写字母), 而 dd 是代表指数的一个或多个数字, 精度指定了小数点后的位数.
`A` | 浮点数 | 等同于 `a` 格式, 但当引入指数时使用 P, 而不是 p.
`p` | 整数 | 将参数显示为十六进制的内存地址. 例如, `Format("{:p}", 255)` 返回 `000000FF`.
`s` | 字符串 | 输出字符串. 如果输入值是数值, 该输入值会在 Width 和 Precision 生效前, 自动转换为字符串.
`c` | 字符编码 | 按照编码顺序输出一个单字符, 类似于 `Chr(n)`. 如果输入值不在预期范围内将被回转. 例如, `Format("{:c}", 116)` 返回 `t`.

## 备注

不同于 printf, 不支持大小指定符. 所有的整数和浮点数输入值都是 64 位的.

## 相关

FormatTime

## 示例

演示不同的用法.

    s := ""
    ; 简单替换
    s .= Format("{2}, {1}!`r`n", "World", "Hello")
    ; 填充空格
    s .= Format("|{:-10}|`r`n|{:10}|`r`n", "Left", "Right")
    ; 十六进制
    s .= Format("{1:#x} {2:X} 0x{3:x}`r`n", 3735928559, 195948557, 0)
    ; 浮点数
    s .= Format("{1:0.3f} {1:.10f}", 4*ATan(1))

    ListVars  ; 用 AutoHotkey 的主窗口显示等宽文本.
    WinWaitActive "ahk_class AutoHotkey"
    ControlSetText(s, "Edit1")
    WinWaitClose

dftg