NAME

Number::FormatEng - Format a number using engineering notation

VERSION

This document refers to Number::FormatEng version 0.03.

SYNOPSIS

    use Number::FormatEng qw(:all);
    print format_eng(1234);     # prints 1.234e3
    print format_pref(-0.035);  # prints -35m
    unformat_pref('1.23T');     # returns 1.23e+12

DESCRIPTION

Format a number for printing using engineering notation. Engineering notation is similar to scientific notation except that the power of ten must be a multiple of three. Alternately, the number can be formatted using an International System of Units (SI) prefix representing a factor of a thousand.

SUBROUTINES

format_eng($number)

Format a numeric value using engineering notation. This function returns a string whose exponent is a multiple of 3. Here are some examples:

    format_eng(1234);   # returns 1.234e3
    format_eng(-0.03);  # returns -30e-3
    format_eng(7.8e7);  # returns 78e6

Since floating-point arithmetic is performed, rounding may occur.

format_pref($number)

Format a numeric value using engineering notation. This function returns a string using one of the following SI prefixes (representing a power of a thousand):

    m u n p f a z y
    k M G T P E Z Y

Notice that lower-case u is used instead of the Greek letter Mu.

If the number is beyond the prefix ranges (y and Y), then format_pref returns the same formatted string as format_eng. In other words, it does not use an SI prefix.

Here are some examples:

    format_pref(1234);      # returns 1.234k
    format_pref(-0.0004);   # returns -400u
    format_pref(1.27e13);   # returns 12.7T
    format_pref(7.5e60);    # returns 7.5e60

Since floating-point arithmetic is performed, rounding may occur.

unformat_pref($string)

Convert a string formatted using format_pref into a numeric value. Here are some examples:

    unformat_pref('1.23T'); # returns 1.23e+12
    unformat_pref('-400u'); # returns -4e-4
    unformat_pref(37.5);    # returns 37.5

use_e_zero() and no_e_zero()

By default, if the exponent is zero, e0 is not displayed by format_eng. To explicitly display e0, use the use_e_zero method. Use the no_e_zero method to return to the default behavior.

    format_eng(55);     # returns 55
    Number::FormatEng::use_e_zero();
    format_eng(55);     # now returns 55e0
    Number::FormatEng::no_e_zero();
    format_eng(55);     # back to 55

EXPORT

Nothing is exported by default. Functions may be exported individually, or all functions may be exported at once, using the special tag :all.

DIAGNOSTICS

Error conditions cause the program to die using croak from the Carp Core module.

BUGS AND LIMITATIONS

There are no known bugs in this module.

SEE ALSO

Refer to the following website:

http://en.wikipedia.org/wiki/Engineering_notation

AUTHOR

Gene Sullivan (gsullivan@cpan.org)

ACKNOWLEDGEMENTS

Influenced by the following PerlMonks: BrowserUk, GrandFather and repellent.

COPYRIGHT AND LICENSE

Copyright (c) 2009 Gene Sullivan. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.