Provided by: nfstest_3.2-3_all 
NAME
formatstr - String Formatter object
DESCRIPTION
Object used to format base objects into strings. It extends the functionality of the
string Formatter object to include new modifiers for different objects. Some of these new
modifiers include conversion of strings into a sequence of hex characters, conversion of
strings to their corresponding CRC32 or CRC16 representation.
CLASSES
class FormatStr(string.Formatter)
String Formatter object
FormatStr() -> New string formatter object
Usage:
from formatstr import FormatStr
x = FormatStr()
out = x.format(fmt_spec, *args, **kwargs)
out = x.vformat(fmt_spec, args, kwargs)
Arguments should be surrounded by curly braces {}, anything that is
not contained in curly braces is considered literal text which is
copied unchanged to the output.
Positional arguments to be used in the format spec are specified
by their index: {0}, {1}, etc.
Named arguments to be used in the format spec are specified by
their name: {name1}, {name2}, etc.
Modifiers are specified after the positional index or name preceded
by a ":", "{0:#x}" -- display first positional argument in hex
Examples:
# Format string using positional arguments
out = x.format("{0} -> {1}", a, b)
# Format string using named arguments
out = x.format("{key}: {value}", key="id", value=32)
# Format string using both positional and named arguments
out = x.format("{key}: {value}, {0}, {1}", a, b, key="id", value=32)
# Use vformat() method instead when positional arguments are given
# as a list and named arguments are given as a dictionary
# The following examples show the same as above
pos_args = [a, b]
named_args = {"key":"id", "value":32}
out = x.vformat("{0} -> {1}", pos_args)
out = x.vformat("{key}: {value}", named_args)
out = x.vformat("{key}: {value}, {0}, {1}", pos_args, named_args)
# Display string in hex
out = x.format("{0:x}", "hello") # out = "68656c6c6f"
# Display string in hex with leading 0x
out = x.format("{0:#x}", "hello") # out = "0x68656c6c6f"
# Display string in crc32
out = x.format("{0:crc32}", "hello") # out = "0x3610a686"
# Display string in crc16
out = x.format("{0:crc16}", "hello") # out = "0x9c62"
# Display length of item
out = x.format("{0:len}", "hello") # out = 5
# Substring using "@" format modifier
# Format {0:@sindex[,eindex]} is like value[sindex:eindex]
# {0:@3} is like value[3:]
# {0:@3,5} is like value[3:5]
# {0:.5} is like value[:5]
out = x.format("{0:@3}", "hello") # out = "lo"
out = x.format("{0:.2}", "hello") # out = "he"
# Conditionally display the first format if argument is not None,
# else the second format is displayed
# Format: {0:?format1:format2}
out = x.format("{0:?tuple({0}, {1})}", 1, 2) # out = "tuple(1, 2)"
out = x.format("{0:?tuple({0}, {1})}", None, 2) # out = ""
# Using 'else' format (including the escaping of else character):
out = x.format("{0:?sid{0}:NONE}", 5) # out = "sid:5"
out = x.format("{0:?sid{0}:NONE}", None) # out = "NONE"
# Nested formatting for strings, where processing is done in
# reversed order -- process the last format first
# Format: {0:fmtN:...:fmt2:fmt1}
# Display substring of 4 bytes as hex (substring then hex)
out = x.format("{0:#x:.4}", "hello") # out = "0x68656c6c"
# Display first 4 bytes of string in hex (hex then substring)
out = x.format("{0:.4:#x}", "hello") # out = "0x68"
# Integer extension to display umax name instead of the value
# Format: {0:max32|umax32|max64|umax64}
# Output: if value matches the largest number in format given,
# the max name is displayed, else the value is displayed
out = x.format("{0:max32}", 0x7fffffff) # out = "max32"
out = x.format("{0:max32}", 35) # out = "35"
# Number extension to display the value as an ordinal number
# Format: {0:ord[:s]}
# Output: display value as an ordinal number,
# use the ":s" option to display the short name
out = x.format("{0:ord}", 3) # out = "third"
out = x.format("{0:ord:s}", 3) # out = "3rd"
# Number extension to display the value with units
# Format: {0:units[.precision]}
# Output: display value as a string with units, by default
# precision=2 and all trailing zeros are removed.
# To force the precision use a negative number.
out = x.format("{0:units}", 1024) # out = "1KB"
out = x.format("{0:units.4}", 2000) # out = "1.9531KB"
out = x.format("{0:units.-2}", 1024) # out = "1.00KB"
# Date extension for int, long or float
# Format: {0:date[:datefmt]}
# The spec given by datefmt is converted using strftime()
# The conversion spec "%q" is used to display microseconds
# Output: display value as a date
stime = 1416846041.521868
out = x.format("{0:date}", stime) # out = "Mon Nov 24 09:20:41 2014"
out = x.format("{0:date:%Y-%m-%d}", stime) # out = "2014-11-24"
# List format specification
# Format: {0[[:listfmt]:itemfmt]}
# If one format spec, it is applied to each item in the list
# If two format specs, the first is the item separator and
# the second is the spec applied to each item in the list
alist = [1, 2, 3, 0xffffffff]
out = x.format("{0:umax32}", alist) # out = "[1, 2, 3, umax32]"
out = x.format("{0:--:umax32}", alist) # out = "1--2--3--umax32"
Methods defined here:
---------------------
format_field(self, value, format_spec)
Override original method to include modifier extensions
get_value(self, key, args, kwargs)
Override original method to return "" when the positional argument
or named argument does not exist:
x.format("0:{0}, 1:{1}, arg1:{arg1}, arg2:{arg2}", a, arg1=11)
the {1} will return "" since there is only one positional argument
the {arg2} will return "" since arg2 is not a named argument
FUNCTIONS
crc16(value)
Convert string to its crc16 representation
crc32(value)
Convert string to its crc32 representation
hexstr(value)
Convert string to its hex representation
int_units(value)
Convert string value with units to an integer
value: String to convert
Examples:
out = int_units("1MB") # out = 1048576
ordinal_number(value, short=0)
Return the ordinal number for the given integer
plural(word, count=2)
Return the plural of the word according to the given count
str_time(value)
Convert the number of seconds to a string with a format of "[h:]mm:ss"
value: Time value to convert (in seconds)
Examples:
out = str_time(123.0) # out = "02:03"
out = str_time(12345) # out = "3:25:45"
str_units(value, precision=2)
Convert number to a string value with units
value: Number to convert
precision:
Return string value with the following floating point
precision. By default no trailing zeros are returned
but if the precision is given as a negative number
the precision is enforced [default: 2]
BUGS
No known bugs.
AUTHOR
Jorge Mora (mora@netapp.com)