/ 
Number-Finance-Human-0.001
/ Number::Finance::Human

NAME

Number::Finance::Human - Human-readable numbers for accounting and finance

SYNOPSIS

use Number::Finance::Human qw(to_number to_human);

my $n = to_number("2.5M");   # 2500000
my $h = to_human(1500);     # "1.50k"

my $x = Number::Finance::Human->new("3k");
say $x + 500;               # "3.50k"

use Number::Finance::Human ':autobox';
say 2500000->to_human;      # "2.50M"

DESCRIPTION

This module converts between numeric values and human-readable representations commonly used in finance and accounting.

It supports suffixes such as k, M, B, %, and c, and provides operator overloading so objects behave like numbers while stringifying to human-readable form.

SUFFIXES

The following suffixes are recognized:

k   1_000
M   1_000_000
B   1_000_000_000
%   0.01
c   0.01
(empty) 1

Suffix matching is case-insensitive.

FUNCTIONS

to_number($value)

Converts a human-readable string (e.g. "2.5M", "10%") into a numeric value.

If passed a Number::Finance::Human object, returns its numeric value.

to_human($number [, $precision ])

Formats a numeric value as a human-readable string using the largest applicable suffix.

An optional precision (default: 2) controls the number of decimal places.

If called on an object that was constructed from a non-numeric string, the original string is preserved.

METHODS

new($value)

Creates a new Number::Finance::Human object from either a numeric value or a human-readable string.

to_number

Returns the numeric value of the object.

to_human

Returns the human-readable string representation.

to_string

Alias for to_human.

OPERATOR OVERLOADING

Objects overload the following operators:

0+    numeric context
""    string context (human-readable)
+ - * /

Arithmetic between objects or scalars returns a new Number::Finance::Human object.

AUTOBOXING

When imported with :autobox, scalar values gain the following methods:

to_nfh
to_number
to_human

Example:

use Number::Finance::Human ':autobox';
say 1200000->to_human;   # "1.20M"

EXPORTS

Nothing is exported by default.

Optional exports:

to_number
to_human

Tag:

:all       exports all functions
:autobox   enables autoboxing

SEE ALSO

autobox, Scalar::Util

AUTHOR

Simone Cesano <scesano@cpan.org>

LICENSE

This software is copyright (c) 2025 by Simone Cesano.

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