FORMATSTR(3)

✨ NAME ✨

formatstr — String Formatter object 💅

okay so bestie, this is the manual page for formatstr, page 3 of the manual, version 1.6. buckle up, it's giving extremely useful 🎀

---

🌸 DESCRIPTION 🌸

So like, formatstr is an object used to format base objects into strings. 🦋

The way it works: 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. no cap, it's iconic ✨

---

🎀 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. ✨ (periodt, we love a clean bill of health)

---

👑 AUTHOR 👑

Jorge Mora (mora@netapp.com) 💖

---

and that's the whole thing bestie!! this page came to you from NFStest 3.2, dated 21 March 2023 🎀 go forth and format, you absolute main character 👑💅