NAME

Number::Textify - turn number into some string.

VERSION

version 20200512

SYNOPSIS

  use Number::Textify ();

  my $time_converter = Number::Textify
    -> new( [ [ 60 * 60, 'hour' ],
              [ 60, 'minute' ],
              [ 0, 'second' ],
            ],

            skip_zeroes => 1,
          );

  print $time_converter -> textify( 7274 ); # 2 hours 1 minute 14 seconds


  my $time_converter_digital_neat = Number::Textify
    -> new( [ [ 24 * 60 * 60, '%dd ' ],
              [ 60 * 60, '%02d:' ],
              [ 60, '%02d:' ],
              [ 0, '%02d' ],
            ],

            joiner => '',
            formatter => sub { my $format = $_[ 1 ] // '%02d';
                               sprintf $format,
                                 $_[ 0 ];
                             },
            post_process => sub {
              $_[ 0 ] =~ s/^0+//;
              $_[ 0 ];
            },
          );

  print $time_converter_digital_neat -> textify( 10_000_000 ); # 115d 17:46:40


  my $size_converter = Number::Textify
    -> new( [ [ 1_024 * 1_024 * 1_024, '%.2f GiB' ],
              [ 1_024 * 1_024, '%.2f MiB' ],
              [ 1_024, '%.2f KiB' ],
              [ 0, '%d B' ],
            ],

            rounding => 1,
            formatter => sub { sprintf $_[ 1 ],
                                 $_[ 0 ];
                             },
          );

  print $size_converter -> textify( 10_000_000 ); # 9.54 MiB

DESCRIPTION

Number::Textify helps you to build and use converter of number to some text representation of it.

For example 10_000_000 can be represented as '115 days 17 hours 46 minutes 40 seconds', '115.7 days', '115d 17:46:40', '9.54 MiB' or '10.00 MB'. You can see some examples in t/02-examples.t

This module uses object oriented approach and doesn't export anything.

OBJECT CREATION

new

Expects one required parameter and a hash of optional ones. If some incorrectness detected, it dies.

First (and only required) parameter is an arrayref to arrayrefs. First element in the nested arrayref is a positive number, which is a threshold for the range. The rest of elements are passed to the formatter. Arrayrefs should be sorted by the first element in descending order.

Range representation figured using the threshold is passed to the formatter along with the rest of elements in the nested arrayref.

Default formatter joins the range representation with the first of the rest of elements in the arrayref. Unless range representation equals 1, adds 's' to the result.

If you need something else instead of that, you can pass a pair:

  formatter => sub { my ( $range_representation, @tail_of_nested_arrayref ) = @_; .. },

Then those formatted range representations are joined with the default joiner, which is ' ' (a space). If you want to use another joiner, you can provide it as:

  joiner => ':',

Then the joined result is passed through the post_process sub, which by default doesn't change anything. If you want to do some processing though, you can replace it:

  post_process => sub { my $result = shift; .. },

If you prefer to avoid zero values in the middle of result ( like '2 hours 0 minutes 14 seconds' ), you can use the option:

  skip_zeroes => 1,

If you don't want the exact representation, but only some rounding, there's an option for that:

  rounding => 1,

though in this case it usually has sense to provide a custom formatter too.

OBJECT METHODS

textify

Returns text presentation of the only one passed numeric parameter.

AUTHOR

Valery Kalesnik, <valkoles at gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2020 by Valery Kalesnik.

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

cpanm Number::Textify

perl -MCPAN -e shell
install Number::Textify