Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
String::Errf(3)	      User Contributed Perl Documentation      String::Errf(3)

NAME
       String::Errf - a	simple sprintf-like dialect

VERSION
       version 0.007

SYNOPSIS
	 use String::Errf qw(errf);

	 print errf "This process was started at %{start}t with	%{args;argument}n.\n",
	   { start => $^T, args	=> 0 + @ARGV };

       ...might	print something	like:

	 This process was started at 2010-10-17	14:05:29 with 0	arguments.

DESCRIPTION
       String::Errf provides "errf", a simple string formatter that works
       something like "sprintf".  It is	implemented using String::Formatter
       and Sub::Exporter.  Their documentation may be useful in	understanding
       or extending String::Errf.  The "errf" subroutine is only available
       when imported.  Calling String::Errf::errf will not do what you want.

DIFFERENCES FROM SPRINTF
       The data	passed to "errf" should	be organized in	a single hashref, not
       a list.

       Formatting codes	require	named parameters, and the available codes are
       different.  See "FORMATTING CODES" below.

       As with most String::Formatter formatters, "%" is not a format code.
       If you want a literal "%", do not put anything between the two percent
       signs, just write "%%".

   FORMATTING CODES
       "errf" formatting codes require a set of	arguments between the "%" and
       the formatting code letter.  These arguments are	placed in curly	braces
       and separated by	semicolons.  The first argument	is the name of the
       data to look for	in the format data.  For example, this is a valid use
       of "errf":

	 errf "The current time	in %{tz}s is %{now;local}t.", {
	   tz  => $ENV{TZ},
	   now => time,
	 };

       The second argument, if present,	may be a compact form for multiple
       named arguments.	 The rest of the arguments will	be named values	in the
       form "name=value".  The examples	below should help clarify how
       arguments are passed.  When an argument appears in both a compact and
       named form, the named form trumps the compact form.

       The specific codes and their arguments are:

       s for string

       The "s" format code is for any string, and takes	no arguments.  It just
       includes	the named item from the	input data.

	 errf "%{name}s", { name => 'John Smith' }; # returns "John Smith"

       Remember, "errf"	does not have any of the left- or right-padding
       formatting that "sprintf" provides.  It is not meant for	building
       tables, only strings.

       i for integer

       The "i" format code is used for integers.  It takes one optional
       argument, "prefix", which defaults to the empty string.	"prefix" may
       be given	as the compact argument, standing alone.  "prefix" is used to
       prefix non-negative integers.  It may only be a plus sign.

	 errf "%{x}i",	  { x => 10 }; # returns "10"
	 errf "%{x;+}i",  { x => 10 }; # returns "+10"

	 errf "%{x;prefix=+}i",	 { x =>	10 }; #	returns	"+10"

       The rounding behavior for non-integer values is not currently
       specified.

       f for float (or fractional)

       The "f" format code is for numbers with sub-integer precision.  It
       works just like "i", but	adds a "precision" argument which specifies
       how many	decimal	places of precision to display.	 The compact argument
       may be just the prefix or the prefix followed by	a period followed by
       the precision.

	 errf "%{x}f",	   { x => 10.1234 }; # returns "10";
	 errf "%{x;+}f",   { x => 10.1234 }; # returns "+10";

	 errf "%{x;.2}f",  { x => 10.1234 }; # returns	"10.12";
	 errf "%{x;+.2}f", { x => 10.1234 }; # returns "+10.12";

	 errf "%{x;precision=.2}f",	     { x => 10.1234 }; # returns  "10.12";
	 errf "%{x;prefix=+;precision=.2}f", { x => 10.1234 }; # returns "+10.12";

       t for time

       The "t" format code is used to format timestamps	provided in epoch
       seconds.	 It can	be given two arguments:	"type" and "tz".

       "type" can be either date, time,	or datetime, and indicates what	part
       of the timestamp	should be displayed.  The default is datetime.	"tz"
       requests	that the timestamp be displayed	in either UTC or the local
       time zone.  The default is local.

       The compact form	is just	"type" alone.

	 # Assuming our	local time zone	is America/New_York...

	 errf "%{x}t",		     { x => 1280530906 }; # "2010-07-30	19:01:46"
	 errf "%{x;type=date}t",     { x => 1280530906 }; # "2010-07-30"
	 errf "%{x;type=time}t",     { x => 1280530906 }; # "19:01:46"
	 errf "%{x;type=datetime}t", { x => 1280530906 }; # "2010-07-30	19:01:46"

	 errf "%{x;tz=UTC}t",		    { x	=> 1280530906 }; # "2010-07-30 23:01:46	UTC"
	 errf "%{x;tz=UTC;type=date}t",	    { x	=> 1280530906 }; # "2010-07-30 UTC"
	 errf "%{x;tz=UTC;type=time}t",	    { x	=> 1280530906 }; # "23:01:46 UTC"
	 errf "%{x;tz=UTC;type=datetime}t", { x	=> 1280530906 }; # "2010-07-30 23:01:46	UTC"

       n and N for numbered

       The "n" and "N" format codes are	for picking words based	on number.  It
       takes two of its	own arguments, "singular" and "plural",	as well	as
       "prefix"	and "precision"	which may be used for formatting the number
       itself.

       If the value being formatted is 1, the singular word is used.
       Otherwise, the plural form is used.

	 errf "%{x;singular=dog;plural=dogs}n",	{ x => 0 }; # 0	dogs
	 errf "%{x;singular=dog;plural=dogs}n",	{ x => 1 }; # 1	dog
	 errf "%{x;singular=dog;plural=dogs}n",	{ x => 2 }; # 2	dogs

	 errf "%{x;singular=dog;plural=dogs}n",	{ x => 1.4 }; #	1.4 dogs
	 errf "%{x;singular=dog;plural=dogs;precision=1}n", { x	=> 1.4 }; # 1.4	dogs
	 errf "%{x;singular=dog;plural=dogs;precision=0}n", { x	=> 1.4 }; # 1 dog

       If "N" is used instead of "n", the number will not be included, only
       the chosen word.

	 errf "%{x;singular=is;plural=are}N", {	x => 0 }; # are
	 errf "%{x;singular=is;plural=are}N", {	x => 1 }; # is
	 errf "%{x;singular=is;plural=are}N", {	x => 2 }; # are

	 errf "%{x;singular=is;plural=are}N", {	x => 1.4 }; # 1.4 are
	 errf "%{x;singular=is;plural=are;precision=1}N", { x => 1.4 };	# 1.4 are
	 errf "%{x;singular=is;plural=are;precision=0}N", { x => 1.4 };	# 1 is

       The compact form	may take any of	the following forms:

	 word	       - equivalent to singular=word

	 word+suffix   - equivalent to singular=word;plural=wordsuffix

	 word1/word2   - equivalent to singular=word;plural=word2

       If no singular form is given, an	exception is thrown.  If no plural
       form is given, one will be generated according to some basic rules of
       English noun orthography.

AUTHOR
       Ricardo Signes <rjbs@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2013 by Ricardo Signes.

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

perl v5.24.1			  2013-11-24		       String::Errf(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | DIFFERENCES FROM SPRINTF | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=String::Errf&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help