Format(3pm)

💖 Format(3pm) 💖

okay bestie, so this is a page from the User Contributed Perl Documentation and it's literally about the module Template::Plugin::Number::Format — yes that's the whole vibe, iykyk ✨

---

🌸 NAME 🌸

Template::Plugin::Number::Format — it's a plugin and a filter interface to Number::Format, and it ate, no cap 💅

---

✨ SYNOPSIS ✨

[% USE Number.Format %]
[% num | format_number %]

look at that. two lines. iconic. periodt 🎀

---

🦋 ABSTRACT 🦋

Template::Plugin::Number::Format makes the number-munging grooviness of Number::Format available to your templates. You use it like a plugin, but plot twist — it installs filters into the current context. the way that it does both?? main character energy fr fr 😭

---

💜 DESCRIPTION 💜

So every single filter that Template::Plugin::Number::Format creates can be configured two ways: by constructor options, and by options you pass straight to individual filters. If you want all the juicy details, go read "METHODS" in Number::Format — that's where the lore lives, bestie 📖

🍓 Constructor Parameters 🍓

Your USE line takes these parameters, and they are all optional (no pressure, babe). They set the default behavior for the filters inside the current Context:

• THOUSANDS_SEP — the character that gets inserted between groups of 3 digits. grouping slay 💫
• DECIMAL_POINT — the character separating the integer part from the fractional part. the lil divider 🌈
• MON_THOUSANDS_SEP — same energy as THOUSANDS_SEP, except it's the one used for format_price 💸
• MON_DECIMAL_POINT — like DECIMAL_POINT, but for format_price 💰
• MON_DECIMAL_POINT's cousin energy aside — INT_CURR_SYMBOL — the character(s) that denote currency (peep format_price()) 👑
• DECIMAL_DIGITS — how many digits sit to the right of the decimal point (def 2) 🔢
• DECIMAL_FILL — boolean; whether to add zeroes to fill out the decimal. yes/no vibes 🫶
• NEG_FORMAT — the format for displaying negative numbers (def -x) 🙈
• KILO_SUFFIX — the suffix to add when format_bytes formats kilobytes 🌸
• MEGA_SUFFIX — the suffix to add when format_bytes formats megabytes 🌟
• GIGA_SUFFIX — the suffix to add when format_bytes formats gigabytes 💥

---

🧚 Using Template::Plugin::Number::Format 🧚

When you invoke:

[% USE Number.Format(option = value) %]

the following filters get installed into the current Context. yes bestie, ALL of them 👑

• round($precision) — Rounds the number to the specified precision. If $precision is omitted, it uses the value of the DECIMAL_DIGITS parameter (default value 2). rounding is self care 💅
• format_number($precision, $trailing_zeros) — Formats a number by adding THOUSANDS_SEP between each set of 3 digits to the left of the decimal point, substituting DECIMAL_POINT for the decimal point, and rounding to the specified precision using round(). Heads up though: $precision is a maximum precision specifier, which means trailing zeroes will only show up in the output if $trailing_zeroes is provided, or if the parameter DECIMAL_FILL is set, with a value that is true (so not zero, not undef, not the empty string). And if $precision is omitted, the value of the DECIMAL_DIGITS parameter (default value of 2) gets used. so many rules but we love her ✨
• format_negative($picture) — Formats a negative number. The picture should be a string containing the letter x exactly where the number should be inserted. For example, for standard negative numbers you might use -x, while for accounting purposes you might use (x). And if the specified number begins with a - character, that gets removed before formatting — but formatting will happen whether or not the number is negative. equal opportunity formatting fr fr 😌
• format_picture($picture) — Returns a string based on $picture with the # characters replaced by digits from $number. But if the integer part of $number is too long to fit, those # characters get replaced with asterisks (*) instead. not the asterisks 💀
• format_price($precision) — Returns a string containing $number formatted similarly to format_number(), except the decimal portion may have trailing zeroes added so it's exactly $precision characters long, and the currency string gets prefixed. If the INT_CURR_SYMBOL attribute of the object is the empty string, then no currency gets added at all. And if $precision isn't provided, the default of 2 is used. money money money 💸
• format_bytes($precision) — Returns a string containing $number formatted similarly to format_number(), except: if the number is over 1024, it gets divided by 1024 and the value of KILO_SUFFIX gets appended to the end; or if it's over 1048576 (1024*1024), it gets divided by 1048576 and MEGA_SUFFIX gets appended to the end. And bestie, listen — negative values will result in an error. do not do it. just don't 🙅‍♀️

If $precision is not provided, the default of 2 will be used.

• unformat_number — Converts a string as returned by format_number(), format_price(), or format_picture(), and returns the corresponding value as a numeric scalar. And it returns undef if the number doesn't contain any digits. the reverse uno card 🃏

---

🌈 SEE ALSO 🌈

Template, Number::Format — go read those too, they're part of the friend group 🫶

---

👑 AUTHOR 👑

darren chamberlain <darren@cpan.org> — the legend who wrote this 💖

---

and that's the whole page bestie, no notes 💅

so yeah, that was Format(3pm) from perl v5.34.0, dated 2022-06-17 — a true classic, we stan, ok bye love u 🌸🦋✨