1FORMATSTR(3)                     formatstr 1.5                    FORMATSTR(3)
2
3
4

NAME

6       formatstr - String Formatter object
7

DESCRIPTION

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

CLASSES

16   class FormatStr(string.Formatter)
17       String Formatter object
18
19       FormatStr() -> New string formatter object
20
21       Usage:
22           from formatstr import FormatStr
23
24           x = FormatStr()
25
26           out = x.format(fmt_spec, *args, **kwargs)
27           out = x.vformat(fmt_spec, args, kwargs)
28
29           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
37           Modifiers are specified after the positional index or name preceded
38           by a ":", "{0:#x}" -- display first positional argument in hex
39
40       Examples:
41           # Format string using positional arguments
42           out = x.format("{0} -> {1}", a, b)
43
44           # Format string using named arguments
45           out = x.format("{key}: {value}", key="id", value=32)
46
47           # Format string using both positional and named arguments
48           out = x.format("{key}: {value}, {0}, {1}", a, b, key="id", value=32)
49
50           # 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
59           # Display string in hex
60           out = x.format("{0:x}", "hello")  # out = "68656c6c6f"
61
62           # Display string in hex with leading 0x
63           out = x.format("{0:#x}", "hello") # out = "0x68656c6c6f"
64
65           # Display string in crc32
66           out = x.format("{0:crc32}", "hello") # out = "0x3610a686"
67
68           # Display string in crc16
69           out = x.format("{0:crc16}", "hello") # out = "0x9c62"
70
71           # Substring using "@" format modifier
72           # Format {0:@sindex[,eindex]} is like value[sindex:eindex]
73           #   {0:@3} is like value[3:]
74           #   {0:@3,5} is like value[3:5]
75           #   {0:.5} is like value[:5]
76           out = x.format("{0:@3}", "hello") # out = "lo"
77           out = x.format("{0:.2}", "hello") # out = "he"
78
79           # Conditionally display the first format if argument is not None,
80           # else the second format is displayed
81           # Format: {0:?format1:format2}
82           out = x.format("{0:?tuple({0}, {1})}", 1, 2)    # out = "tuple(1, 2)"
83           out = x.format("{0:?tuple({0}, {1})}", None, 2) # out = ""
84           # Using 'else' format (including the escaping of else character):
85           out = x.format("{0:?sid{0}:NONE}", 5)    # out = "sid:5"
86           out = x.format("{0:?sid{0}:NONE}", None) # out = "NONE"
87
88           # Nested formatting for strings, where processing is done in
89           # reversed order -- process the last format first
90           # Format: {0:fmtN:...:fmt2:fmt1}
91           #   Display substring of 4 bytes as hex (substring then hex)
92           out = x.format("{0:#x:.4}", "hello") # out = "0x68656c6c"
93           #   Display first 4 bytes of string in hex (hex then substring)
94           out = x.format("{0:.4:#x}", "hello") # out = "0x68"
95
96           # Integer extension to display umax name instead of the value
97           # Format: {0:max32|umax32|max64|umax64}
98           # Output: if value matches the largest number in format given,
99           #         the max name is displayed, else the value is displayed
100           out = x.format("{0:max32}", 0x7fffffff) # out = "max32"
101           out = x.format("{0:max32}", 35)         # out = "35"
102
103           # Number extension to display the value with units
104           # Format: {0:units[.precision]}
105           # Output: display value as a string with units, by default
106           #         precision=2 and all trailing zeros are removed.
107           #         To force the precision use a negative number.
108           out = x.format("{0:units}", 1024)    # out = "1KB"
109           out = x.format("{0:units.4}", 2000)  # out = "1.9531KB"
110           out = x.format("{0:units.-2}", 1024) # out = "1.00KB"
111
112           # Date extension for int, long or float
113           # Format: {0:date[:datefmt]}
114           #         The spec given by datefmt is converted using strftime()
115           #         The conversion spec "%q" is used to display microseconds
116           # Output: display value as a date
117           stime = 1416846041.521868
118           out = x.format("{0:date}", stime) # out = "Mon Nov 24 09:20:41 2014"
119           out = x.format("{0:date:%Y-%m-%d}", stime) # out = "2014-11-24"
120
121           # List format specification
122           # Format: {0[[:listfmt]:itemfmt]}
123           #   If one format spec, it is applied to each item in the list
124           #   If two format specs, the first is the item separator and
125           #   the second is the spec applied to each item in the list
126           alist = [1, 2, 3, 0xffffffff]
127           out = x.format("{0:umax32}", alist)    # out = "[1, 2, 3, umax32]"
128           out = x.format("{0:--:umax32}", alist) # out = "1--2--3--umax32"
129
130
131       Methods defined here:
132       ---------------------
133
134       format_field(self, value, format_spec)
135       Override original method to include modifier extensions
136
137       get_value(self, key, args, kwargs)
138       Override original method to return "" when the positional argument
139       or named argument does not exist:
140         x.format("0:{0}, 1:{1}, arg1:{arg1}, arg2:{arg2}", a, arg1=11)
141         the {1} will return "" since there is only one positional argument
142         the {arg2} will return "" since arg2 is not a named argument
143

FUNCTIONS

145   crc16(value)
146       Convert string to its crc16 representation
147
148   crc32(value)
149       Convert string to its crc32 representation
150
151   hexstr(value)
152       Convert string to its hex representation
153
154   int_units(value)
155       Convert string value with units to an integer
156
157
158              value: String to convert
159
160              Examples:
161
162   out = num_units("1MB") # out = 1048576
163   str_time(value)
164       Convert the number of seconds to a string with a format of "[h:]mm:ss"
165
166
167              value: Time value to convert (in seconds)
168
169              Examples:
170
171   out = str_time(123.0) # out = 02:03
172   out = str_time(12345) # out = 3:25:45
173   str_units(value, precision=2)
174       Convert number to a string value with units
175
176
177              value: Number to convert
178
179              precision:
180                     Return  string  value  with  the following floating point
181                     precision. By default no trailing zeros are returned  but
182                     if the precision is given as a negative number the preci‐
183                     sion is enforced [default: 2]
184

BUGS

186       No known bugs.
187

AUTHOR

189       Jorge Mora (mora@netapp.com)
190
191
192
193NFStest 2.1.5                  14 February 2017                   FORMATSTR(3)
Impressum