1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
== Format Specifications
Several Ruby core classes have instance method +printf+ or +sprintf+:
- ARGF#printf
- IO#printf
- Kernel#printf
- Kernel#sprintf
Each of these methods takes:
- Argument +format_string+, which has zero or more
embedded _format_ _specifications_ (see below).
- Arguments <tt>*arguments</tt>, which are zero or more objects to be formatted.
Each of these methods prints or returns the string
resulting from replacing each
format specification embedded in +format_string+ with a string form
of the corresponding argument among +arguments+.
A simple example:
sprintf('Name: %s; value: %d', 'Foo', 0) # => "Name: Foo; value: 0"
A format specification has the form:
%[flags][width][.precision]type
It consists of:
- A leading percent character.
- Zero or more _flags_ (each is a character).
- An optional _width_ _specifier_ (an integer).
- An optional _precision_ _specifier_ (a period followed by a non-negative integer).
- A _type_ _specifier_ (a character).
Except for the leading percent character,
the only required part is the type specifier, so we begin with that.
=== Type Specifiers
This section provides a brief explanation of each type specifier.
The links lead to the details and examples.
==== \Integer Type Specifiers
- +b+ or +B+: Format +argument+ as a binary integer.
See {Specifiers b and B}[rdoc-ref:doc/format_specifications.rdoc@Specifiers+b+and+B].
- +d+, +i+, or +u+ (all are identical):
Format +argument+ as a decimal integer.
See {Specifier d}[rdoc-ref:doc/format_specifications.rdoc@Specifier+d].
- +o+: Format +argument+ as an octal integer.
See {Specifier o}[rdoc-ref:doc/format_specifications.rdoc@Specifier+o].
- +x+ or +X+: Format +argument+ as a hexadecimal integer.
See {Specifiers x and X}[rdoc-ref:doc/format_specifications.rdoc@Specifiers+x+and+X].
==== Floating-Point Type Specifiers
- +a+ or +A+: Format +argument+ as hexadecimal floating-point number.
See {Specifiers a and A}[rdoc-ref:doc/format_specifications.rdoc@Specifiers+a+and+A].
- +e+ or +E+: Format +argument+ in
{scientific notation}[https://en.wikipedia.org/wiki/Scientific_notation].
See {Specifiers e and E}[rdoc-ref:doc/format_specifications.rdoc@Specifiers+e+and+E].
- +f+: Format +argument+ as a decimal floating-point number.
See {Specifier f}[rdoc-ref:doc/format_specifications.rdoc@Specifier+f].
- +g+ or +G+: Format +argument+ in a "general" format.
See {Specifiers g and G}[rdoc-ref:doc/format_specifications.rdoc@Specifiers+g+and+G].
==== Other Type Specifiers
- +c+: Format +argument+ as a character.
See {Specifier c}[rdoc-ref:doc/format_specifications.rdoc@Specifier+c].
- +p+: Format +argument+ as a string via <tt>argument.inspect</tt>.
See {Specifier p}[rdoc-ref:doc/format_specifications.rdoc@Specifier+p].
- +s+: Format +argument+ as a string via <tt>argument.to_s</tt>.
See {Specifier s}[rdoc-ref:doc/format_specifications.rdoc@Specifier+s].
- <tt>%</tt>: Format +argument+ (<tt>'%'</tt>) as a single percent character.
See {Specifier %}[rdoc-ref:doc/format_specifications.rdoc@Specifier+-25].
=== Flags
The effect of a flag may vary greatly among type specifiers.
These remarks are general in nature.
Multiple flags may be given with single type specifier;
order does not matter.
==== <tt>' '</tt> Flag
Insert a space before a non-negative number:
sprintf('%d', 10) # => "10"
sprintf('% d', 10) # => " 10"
Insert a minus sign for negative value:
sprintf('%d', -10) # => "-10"
sprintf('% d', -10) # => "-10"
==== <tt>'#'</tt> Flag
Use an alternate format; varies among types:
sprintf('%x', 100) # => "64"
sprintf('%#x', 100) # => "0x64"
==== <tt>'+'</tt> Flag
Add a leading plus sign for a non-negative number:
sprintf('%x', 100) # => "64"
sprintf('%+x', 100) # => "+64"
==== <tt>'-'</tt> Flag
Left justify the value in its field:
sprintf('%6d', 100) # => " 100"
sprintf('%-6d', 100) # => "100 "
==== <tt>'0'</tt> Flag
Left-pad with zeros instead of spaces:
sprintf('%6d', 100) # => " 100"
sprintf('%06d', 100) # => "000100"
==== <tt>'*'</tt> Flag
Use the next argument as the field width:
sprintf('%d', 20, 14) # => "20"
sprintf('%*d', 20, 14) # => " 14"
==== <tt>'n$'</tt> Flag
Format the (1-based) <tt>n</tt>th argument into this field:
sprintf("%s %s", 'world', 'hello') # => "world hello"
sprintf("%2$s %1$s", 'world', 'hello') # => "hello world"
=== Width Specifier
In general, a width specifier determines the minimum width (in characters)
of the formatted field:
sprintf('%10d', 100) # => " 100"
# Left-justify if negative.
sprintf('%-10d', 100) # => "100 "
# Ignore if too small.
sprintf('%1d', 100) # => "100"
=== Type Specifier Details and Examples
==== Specifiers +a+ and +A+
==== Specifiers +b+ and +B+
The two specifiers +b+ and +B+ behave identically
except when flag <tt>'#'</tt>+ is used.
Format +argument+ as a binary integer:
sprintf('%b', 1) # => "1"
sprintf('%b', 4) # => "100"
# Prefix '..' for negative value.
sprintf('%b', -4) # => "..100"
Type-specific modifier:
- '#' flag' (use alternate format):
sprintf('%#b', 1) # => "0b1"
sprintf('%#B', 1) # => "0B1"
sprintf('%#b', 4) # => "0b100"
==== Specifier +c+
==== Specifier +d+
==== Specifiers +e+ and +E+
==== Specifier +f+
==== Specifiers +g+ and +G+
==== Specifier +o+
==== Specifier +p+
==== Specifier +s+
==== Specifiers +x+ and +X+
==== Specifier <tt>%</tt>
|
