格式規範

多個 Ruby 核心類別有實例方法 printfsprintf

這些方法各取用

這些方法各會列印或傳回字串,其結果是將 format_string 中內嵌的每個格式規範替換為 arguments 中對應參數的字串形式。

一個簡單範例

sprintf('Name: %s; value: %d', 'Foo', 0) # => "Name: Foo; value: 0"

格式規範的格式為

%[flags][width][.precision]type

它包含

除了開頭的百分比字元之外,唯一必要的部份是類型規範,所以我們從此開始。

類型規範

此節提供每個類型規範的簡短說明。連結會導向詳細資料和範例。

整數類型規範

浮點型態規範符號

其他型態規範符號

旗標

旗標的效果在不同型態規範符號中可能差異很大。這些說明為一般性質。請參閱 型態特定詳細資料

可以針對單一型態規範符號指定多個旗標;順序不重要。

' ' 旗標

在非負數之前插入空格

sprintf('%d', 10)  # => "10"
sprintf('% d', 10) # => " 10"

在負值之前插入減號

sprintf('%d', -10)  # => "-10"
sprintf('% d', -10) # => "-10"

'#' 旗標

使用替代格式;在不同型態中有所不同

sprintf('%x', 100)  # => "64"
sprintf('%#x', 100) # => "0x64"

'+' 旗標

在非負數之前加上正號

sprintf('%x', 100)  # => "64"
sprintf('%+x', 100) # => "+64"

'-' 旗標

在欄位中靠左對齊值

sprintf('%6d', 100)  # => "   100"
sprintf('%-6d', 100) # => "100   "

'0' 旗標

使用零而非空格進行左邊補齊

sprintf('%6d', 100)  # => "   100"
sprintf('%06d', 100) # => "000100"

'*' 旗標

使用下一個參數作為欄位寬度

sprintf('%d', 20, 14)  # => "20"
sprintf('%*d', 20, 14) # => "                  14"

'n$' 旗標

將第 n 個參數 (從 1 開始) 格式化為此欄位

sprintf("%s %s", 'world', 'hello')     # => "world hello"
sprintf("%2$s %1$s", 'world', 'hello') # => "hello world"

寬度規格

一般而言,寬度規格會決定格式化欄位的最小寬度 (以字元為單位)

sprintf('%10d', 100)  # => "       100"

# Left-justify if negative.
sprintf('%-10d', 100) # => "100       "

# Ignore if too small.
sprintf('%1d', 100)   # => "100"

精度規格

精度規格是小數點後接零個或多個小數位。

對於整數類型規格,精度會指定要寫入的最小位數。如果精度比整數短,結果會補上前導零。如果整數比精度長,則不會修改或截斷結果

sprintf('%.3d', 1)    # => "001"
sprintf('%.3d', 1000) # => "1000"

# If the precision is 0 and the value is 0, nothing is written
sprintf('%.d', 0)  # => ""
sprintf('%.0d', 0) # => ""

對於 a/Ae/Ef/F 規格,精度會指定小數點後要寫入的位數

sprintf('%.2f', 3.14159)  # => "3.14"
sprintf('%.10f', 3.14159) # => "3.1415900000"

# With no precision specifier, defaults to 6-digit precision.
sprintf('%f', 3.14159)    # => "3.141590"

對於 g/G 規格,精度會指定要寫入的有效位數

sprintf('%.2g', 123.45)  # => "1.2e+02"
sprintf('%.3g', 123.45)  # => "123"
sprintf('%.10g', 123.45) # =>  "123.45"

# With no precision specifier, defaults to 6 significant digits.
sprintf('%g', 123.456789) # => "123.457"

對於 sp 規格,精度會指定要寫入的字元數

sprintf('%s', Time.now)    # => "2022-05-04 11:59:16 -0400"
sprintf('%.10s', Time.now) # => "2022-05-04"

類型規格詳細資料和範例

規格 aA

argument 格式化為十六進位浮點數

sprintf('%a', 3.14159)   # => "0x1.921f9f01b866ep+1"
sprintf('%a', -3.14159)  # => "-0x1.921f9f01b866ep+1"
sprintf('%a', 4096)      # => "0x1p+12"
sprintf('%a', -4096)     # => "-0x1p+12"

# Capital 'A' means that alphabetical characters are printed in upper case.
sprintf('%A', 4096)      # => "0X1P+12"
sprintf('%A', -4096)     # => "-0X1P+12"

規格 bB

兩個規格 bB 的行為相同,除非使用旗標 '#'+。

argument 格式化為二進位整數

sprintf('%b', 1)  # => "1"
sprintf('%b', 4)  # => "100"

# Prefix '..' for negative value.
sprintf('%b', -4) # => "..100"

# Alternate format.
sprintf('%#b', 4)  # => "0b100"
sprintf('%#B', 4)  # => "0B100"

規格 c

argument 格式化為單一字元

sprintf('%c', 'A') # => "A"
sprintf('%c', 65)  # => "A"

規格 d

argument 格式化為十進位整數

sprintf('%d', 100)  # => "100"
sprintf('%d', -100) # => "-100"

旗標 '#' 不適用。

規格 eE

argument 格式化為科學記號

sprintf('%e', 3.14159)  # => "3.141590e+00"
sprintf('%E', -3.14159) # => "-3.141590E+00"

規格 f

argument 格式化為浮點數

sprintf('%f', 3.14159)  # => "3.141590"
sprintf('%f', -3.14159) # => "-3.141590"

旗標 '#' 不適用。

規格 gG

如果指數小於 -4 或大於或等於精度,則使用指數形式 (e/E 規格) 格式化 argument。否則,使用浮點形式 (f 規格) 格式化 argument

sprintf('%g', 100)  # => "100"
sprintf('%g', 100.0)  # => "100"
sprintf('%g', 3.14159)  # => "3.14159"
sprintf('%g', 100000000000)  # => "1e+11"
sprintf('%g', 0.000000000001)  # => "1e-12"

# Capital 'G' means use capital 'E'.
sprintf('%G', 100000000000)  # => "1E+11"
sprintf('%G', 0.000000000001)  # => "1E-12"

# Alternate format.
sprintf('%#g', 100000000000)  # => "1.00000e+11"
sprintf('%#g', 0.000000000001)  # => "1.00000e-12"
sprintf('%#G', 100000000000)  # => "1.00000E+11"
sprintf('%#G', 0.000000000001)  # => "1.00000E-12"

規格 o

argument 格式化為八進位整數。如果 argument 為負數,則會將其格式化為二補數,並加上前置詞 ..7

sprintf('%o', 16)   # => "20"

# Prefix '..7' for negative value.
sprintf('%o', -16)  # => "..760"

# Prefix zero for alternate format if positive.
sprintf('%#o', 16)  # => "020"
sprintf('%#o', -16) # => "..760"

規格 p

透過 argument.inspectargument 格式化為字串

t = Time.now
sprintf('%p', t)   # => "2022-05-01 13:42:07.1645683 -0500"

指定符號 s

透過 argument.to_sargument 格式化為字串

t = Time.now
sprintf('%s', t) # => "2022-05-01 13:42:07 -0500"

旗標 '#' 不適用。

指定符號 xX

argument 格式化為十六進位整數。如果 argument 為負數,則會將其格式化為以 ..f 為字首的二補數

sprintf('%x', 100)   # => "64"

# Prefix '..f' for negative value.
sprintf('%x', -100)  # => "..f9c"

# Use alternate format.
sprintf('%#x', 100)  # => "0x64"

# Alternate format for negative value.
sprintf('%#x', -100) # => "0x..f9c"

指定符號 %

argument ('%') 格式化為單一百分比字元

sprintf('%d %%', 100) # => "100 %"

旗標不適用。

依名稱參照

對於較複雜的格式化,Ruby 支援依名稱參照。%<name>s 樣式使用格式樣式,但 %{name} 樣式不使用。

範例

sprintf("%<foo>d : %<bar>f", { :foo => 1, :bar => 2 }) # => 1 : 2.000000
sprintf("%{foo}f", { :foo => 1 })                      # => "1f"