1FORMATSTR(3) formatstr 1.6 FORMATSTR(3)
2
6 formatstr - String Formatter object
7
9 Object used to format base objects into strings. It extends the func‐
10 tionality of the string Formatter object to include new modifiers for
11 different objects. Some of these new modifiers include conversion of
12 strings into a sequence of hex characters, conversion of strings to
13 their corresponding CRC32 or CRC16 representation.
14
16 class FormatStr(string.Formatter)
17 String Formatter object
18 FormatStr() -> New string formatter object
20 Usage:
22 from formatstr import FormatStr
23 x = FormatStr()
25 out = x.format(fmt_spec, *args, **kwargs)
27 out = x.vformat(fmt_spec, args, kwargs)
28 Arguments should be surrounded by curly braces {}, anything that is
30 not contained in curly braces is considered literal text which is
31 copied unchanged to the output.
32 Positional arguments to be used in the format spec are specified
33 by their index: {0}, {1}, etc.
34 Named arguments to be used in the format spec are specified by
35 their name: {name1}, {name2}, etc.
36 Modifiers are specified after the positional index or name preceded
38 by a ":", "{0:#x}" -- display first positional argument in hex
39 Examples:
41 # Format string using positional arguments
42 out = x.format("{0} -> {1}", a, b)
43 # Format string using named arguments
45 out = x.format("{key}: {value}", key="id", value=32)
46 # Format string using both positional and named arguments
48 out = x.format("{key}: {value}, {0}, {1}", a, b, key="id", value=32)
49 # Use vformat() method instead when positional arguments are given
51 # as a list and named arguments are given as a dictionary
52 # The following examples show the same as above
53 pos_args = [a, b]
54 named_args = {"key":"id", "value":32}
55 out = x.vformat("{0} -> {1}", pos_args)
56 out = x.vformat("{key}: {value}", named_args)
57 out = x.vformat("{key}: {value}, {0}, {1}", pos_args, named_args)
58 # Display string in hex
60 out = x.format("{0:x}", "hello") # out = "68656c6c6f"
61 # Display string in hex with leading 0x
63 out = x.format("{0:#x}", "hello") # out = "0x68656c6c6f"
64 # Display string in crc32
66 out = x.format("{0:crc32}", "hello") # out = "0x3610a686"
67 # Display string in crc16
69 out = x.format("{0:crc16}", "hello") # out = "0x9c62"
70 # Display length of item
72 out = x.format("{0:len}", "hello") # out = 5
73 # Substring using "@" format modifier
75 # Format {0:@sindex[,eindex]} is like value[sindex:eindex]
76 # {0:@3} is like value[3:]
77 # {0:@3,5} is like value[3:5]
78 # {0:.5} is like value[:5]
79 out = x.format("{0:@3}", "hello") # out = "lo"
80 out = x.format("{0:.2}", "hello") # out = "he"
81 # Conditionally display the first format if argument is not None,
83 # else the second format is displayed
84 # Format: {0:?format1:format2}
85 out = x.format("{0:?tuple({0}, {1})}", 1, 2) # out = "tuple(1, 2)"
86 out = x.format("{0:?tuple({0}, {1})}", None, 2) # out = ""
87 # Using 'else' format (including the escaping of else character):
88 out = x.format("{0:?sid{0}:NONE}", 5) # out = "sid:5"
89 out = x.format("{0:?sid{0}:NONE}", None) # out = "NONE"
90 # Nested formatting for strings, where processing is done in
92 # reversed order -- process the last format first
93 # Format: {0:fmtN:...:fmt2:fmt1}
94 # Display substring of 4 bytes as hex (substring then hex)
95 out = x.format("{0:#x:.4}", "hello") # out = "0x68656c6c"
96 # Display first 4 bytes of string in hex (hex then substring)
97 out = x.format("{0:.4:#x}", "hello") # out = "0x68"
98 # Integer extension to display umax name instead of the value
100 # Format: {0:max32|umax32|max64|umax64}
101 # Output: if value matches the largest number in format given,
102 # the max name is displayed, else the value is displayed
103 out = x.format("{0:max32}", 0x7fffffff) # out = "max32"
104 out = x.format("{0:max32}", 35) # out = "35"
105 # Number extension to display the value as an ordinal number
107 # Format: {0:ord[:s]}
108 # Output: display value as an ordinal number,
109 # use the ":s" option to display the short name
110 out = x.format("{0:ord}", 3) # out = "third"
111 out = x.format("{0:ord:s}", 3) # out = "3rd"
112 # Number extension to display the value with units
114 # Format: {0:units[.precision]}
115 # Output: display value as a string with units, by default
116 # precision=2 and all trailing zeros are removed.
117 # To force the precision use a negative number.
118 out = x.format("{0:units}", 1024) # out = "1KB"
119 out = x.format("{0:units.4}", 2000) # out = "1.9531KB"
120 out = x.format("{0:units.-2}", 1024) # out = "1.00KB"
121 # Date extension for int, long or float
123 # Format: {0:date[:datefmt]}
124 # The spec given by datefmt is converted using strftime()
125 # The conversion spec "%q" is used to display microseconds
126 # Output: display value as a date
127 stime = 1416846041.521868
128 out = x.format("{0:date}", stime) # out = "Mon Nov 24 09:20:41 2014"
129 out = x.format("{0:date:%Y-%m-%d}", stime) # out = "2014-11-24"
130 # List format specification
132 # Format: {0[[:listfmt]:itemfmt]}
133 # If one format spec, it is applied to each item in the list
134 # If two format specs, the first is the item separator and
135 # the second is the spec applied to each item in the list
136 alist = [1, 2, 3, 0xffffffff]
137 out = x.format("{0:umax32}", alist) # out = "[1, 2, 3, umax32]"
138 out = x.format("{0:--:umax32}", alist) # out = "1--2--3--umax32"
139 Methods defined here:
142 ---------------------
143 format_field(self, value, format_spec)
145 Override original method to include modifier extensions
146 get_value(self, key, args, kwargs)
148 Override original method to return "" when the positional argument
149 or named argument does not exist:
150 x.format("0:{0}, 1:{1}, arg1:{arg1}, arg2:{arg2}", a, arg1=11)
151 the {1} will return "" since there is only one positional argument
152 the {arg2} will return "" since arg2 is not a named argument
153
155 crc16(value)
156 Convert string to its crc16 representation
157 crc32(value)
159 Convert string to its crc32 representation
160 hexstr(value)
162 Convert string to its hex representation
163 int_units(value)
165 Convert string value with units to an integer
166 value: String to convert
169 Examples:
171 out = int_units("1MB") # out = 1048576
172 ordinal_number(value, short=0)
174 Return the ordinal number for the given integer
175 plural(word, count=2)
177 Return the plural of the word according to the given count
178 str_time(value)
180 Convert the number of seconds to a string with a format of "[h:]mm:ss"
181 value: Time value to convert (in seconds)
184 Examples:
186 out = str_time(123.0) # out = "02:03"
187 out = str_time(12345) # out = "3:25:45"
188 str_units(value, precision=2)
190 Convert number to a string value with units
191 value: Number to convert
194 precision:
196 Return string value with the following floating point
197 precision. By default no trailing zeros are returned
198 but if the precision is given as a negative number
199 the precision is enforced [default: 2]
200
202 No known bugs.
203
205 Jorge Mora (mora@netapp.com)
206NFStest 3.2 21 March 2023 FORMATSTR(3)