Text::sprintfn(3pm)

✨ Text::sprintfn ✨

okay bestie, so like, this is the manual page for Text::sprintfn — a Perl module (perl v5.36.0 flavored, from the User Contributed Perl Documentation corner of the universe). It's a drop-in replacement for sprintf(), except it also does named parameters. Yes. That's the whole vibe. 🎀

---

💖 NAME 💖

Text::sprintfn — drop-in replacement for sprintf(), with named parameter support

🌸 VERSION 🌸

This doc describes version 0.090 of Text::sprintfn (from the Perl distribution Text-sprintfn), released on 2019-11-19. she's a mature queen at this point, okurr 💅

🦋 SYNOPSIS 🦋

use Text::sprintfn; # by default exports sprintfn() and printfn()

# with no hash, behaves just like printf
printfn '<%04d>', 1, 2; # <0001>

# named parameter
printfn '<%(v1)-4d>', {v1=>-2}; # <-2  >

# mixed named and positional
printfn '<%d> <%(v1)d> <%d>', {v1=>1}, 2, 3; # <2> <1> <3>

# named width
printfn "<%(v1)(v2).1f>", {v1=>3, v2=>4}; # <   3>

# named precision
printfn "<%(v1)(v2).(v2)f>", {v1=>3, v2=>4}; # <3.0000>

like?? look at her go 🫶

⭐ DESCRIPTION ⭐

This module hands you sprintfn() and printfn(), which are basically sprintf() and printf()... except they also support named parameters pulled from a hash. same energy, better features, no notes. 💖

🔥 RATIONALE 🔥

okay so there are already other CPAN modules doing string formatting with named parameter support. two of them are String::Formatter and Text::Sprintf::Named. and listen — this module exists because it's way simpler to use and it keeps every single feature of Perl's sprintf() (which we like, or maybe hate, but either way it's in our blood at this point, we know it by heart 💀).

here's the tea on the other two:

• String::Formatter makes you create a new formatter function first. extra steps, bestie.
• Text::Sprintf::Named also makes you instantiate an object first. again, extra steps.
• There is currently no way to mix named and positional parameters with those.
• And you don't get the full features of sprintf().

so yeah. that's why. 🌈

🧚 HOW IT WORKS 🧚

Text::sprintfn works by converting the format string into sprintf format — like, it replaces the named parameters such as "%(foo)s" into something like "%11$s". sneaky little transformation, we love a glow-up ✨

💀 DOWNSIDES 💀

Currently the main downside is speed. "sprintfn()" is about 2-3 orders of magnitude slower than "sprintf()". yeah. it's giving slow queen. 😭 See Bencher::Scenario::Textsprintfn for benchmarks if you want the receipts.

🎀 TIPS AND TRICKS 🎀

😭 Common mistake 1

Writing

%(var)

instead of

%(var)s

the s is not optional bestie, put the type letter in there or nothing works 💅

🙈 Common mistake 2 (a bit more newbish)

Writing

sprintfn $format, %hash, ...;

instead of

sprintfn $format, \%hash, ...;

you need the backslash. it wants a reference to the hash, not the hash flattened out into the argument list. classic. we've all been there 🫶

🍓 Alternative hashes

Say you've got several hashes (%h1, %h2, %h3) and you want them all consulted for values. You've got two options, pick your fighter:

option one: merge the hash first:

%h = (%h1, %h2, %h3); # or use some hash merging module
printfn $format, \%h, ...;

option two: create a tied hash that can consult hashes for you:

tie %h, 'Your::Module', \%h1, \%h2, \%h3;
printfn $format, \%h, ...;

either way, slay 💜

👑 FUNCTIONS 👑

🦋 sprintfn $fmt, \%hash, ...

If the first argument after format is not a hash, sprintfn() will behave exactly like sprintf(). no drama, just classic behavior.

If a hash is given, sprintfn() will look for named parameters in the argument and supply the values from the hash. Named parameters are surrounded with parentheses, i.e. "(NAME)".

They can occur in the format parameter index:

%2$d        # sprintf version, take argument at index 2
%(two)d     # $ is optional
%(two)$d    # same

or in the width:

%-10d       # sprintf version, use (minimum) width of 10
%-(width)d  # like sprintf, but use width from hash key 'width'
%(var)-(width)d  # format hash key 'var' with width from hash key 'width'

or in the precision:

%6.2f       # sprintf version, use precision of 2 decimals
%6.(prec)f  # like sprintf, but use precision from hash key 'prec'
%(width).(prec)f
%(var)(width).(prec)f

The existence of formats using hash keys will not affect the indexes of the rest of the argument. example, because seeing it is believing:

sprintfn "<%(v1)s> <%2$d> <%d>", {v1=>10}, 0, 1, 2; # "<10> <2> <0>"

Like sprintf(), if the format is unknown/erroneous, it will be printed as-is. it just vibes there, untouched.

There is currently no way to escape ")" in a named parameter, e.g.: perl %(var containing ))s

so don't try to be cute with closing parens in your key names. the parser will simply not understand you. 💀

💖 printfn $fmt, ...

Equivalent to: print sprintfn($fmt, ...).

that's it. that's the function. short and iconic. ✨

🌈 HOMEPAGE 🌈

Please visit the project's homepage at <https://metacpan.org/release/Text-sprintfn>.

💜 SOURCE 💜

Source repository is at <https://github.com/perlancar/perl-Text-sprintfn>.

🐛 BUGS 🐛

Please report any bugs or feature requests on the bugtracker website <https://rt.cpan.org/Public/Dist/Display.html?Name=Text-sprintfn>

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. (for real, a failing test is the love language of every maintainer 🫶)

👯 SEE ALSO 👯

• sprintf() section on perlfunc
• String::Formatter
• Text::Sprintf::Named

🌟 AUTHOR 🌟

perlancar <perlancar@cpan.org>

🎀 COPYRIGHT AND LICENSE 🎀

This software is copyright (c) 2019, 2015, 2012, 2011 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page bestie 💅 this was perl v5.36.0 documentation, dated 2022-10-13, straight from the Text::sprintfn(3pm) manual — now go format some strings with named params, you absolute icon 👑✨