---
name: "Text::sprintfn"
section: "3pm"
platform: "linux"
package: "libtext-sprintfn-perl"
version: "0.090-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Text::sprintfn"
---

# Text::sprintfn(3pm)

Drop-in replacement for sprintf(), with named parameter support

## NAME

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

## VERSION

This document describes version 0.090 of Text::sprintfn (from Perl distribution Text-sprintfn), released on 2019-11-19.

## 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>
```

## DESCRIPTION

This module provides **sprintfn()** and **printfn()**, which are like **sprintf()** and **printf()**, with the exception that they support named parameters from a hash.

## RATIONALE

There exist other CPAN modules for string formatting with named parameter support. Two of such modules are String::Formatter and Text::Sprintf::Named. This module is far simpler to use and retains all of the features of Perl's **sprintf()** (which we like, or perhaps hate, but nevertheless are familiar with).

String::Formatter requires you to create a new formatter function first. Text::Sprintf::Named also accordingly requires you to instantiate an object first. There is currently no way to mix named and positional parameters. And you don't get the full features of **sprintf()**.

## HOW IT WORKS

Text::sprintfn works by converting the format string into sprintf format, i.e. replacing the named parameters like `"%(foo)s"` to something like `"%11$s"`.

## DOWNSIDES

Currently the main downside is speed. `"sprintfn()"` is about 2-3 orders of magnitude slower than `"sprintf()"`. See Bencher::Scenario::Textsprintfn for benchmarks.

## TIPS AND TRICKS

### Common mistake 1

Writing

```
 %(var)
```

instead of

```
 %(var)s
```

### Common mistake 2 (a bit more newbish)

Writing

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

instead of

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

### Alternative hashes

You have several hashes (%h1, `%h2`, `%h3`) which should be consulted for values. You can either merge the hash first:

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

or create a tied hash which can consult hashes for you:

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

## FUNCTIONS

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

If first argument after format is not a hash, **sprintfn()** will behave exactly like **sprintf()**.

If hash is given, **sprintfn()** will look for named parameters in argument and supply the values from the hash. Named parameters are surrounded with parentheses, i.e. "(NAME)". They can occur in format parameter index:

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

or in 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 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 indexes of the rest of the argument, example:

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

Like **sprintf()**, if format is unknown/erroneous, it will be printed as-is.

There is currently no way to escape ")" in named parameter, e.g.:

```
 %(var containing ))s
```

### printfn $fmt, ...

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

## 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.

## 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.