SnapTo.pm

- NAME
- SYNOPSIS
- DESCRIPTION

- FUNCTIONS

- snap_basic( [NUM], [ACCURACY] );
- snap_sigfig( [NUMBER], [SIGNIFICANT_FIGURES] )
- snap_units( [NUMBER], [UNITS] )

- EXPORT

- AUTHOR

# NAME

Math::Snap - Perl extension providing numeric snap-to functions

# SYNOPSIS

      use Math::SnapTo qw( snap_basic snap_sigfig snap_units );

# DESCRIPTION

The Math::SnapTo module provides several methods to snap numeric values to desired values according to various criteria.

## FUNCTIONS

This module supplies three functions. None are exported by default so you have to specify what you want in the use or use the fully quialified name. For a detailed overview of how the functions behave run snap.test in the ./t directory

        $ perl snap.test | more

### snap_basic( [NUM], [ACCURACY] );

Something that has always anoyed me is how float operations return 0.499999999998 or 5.00000000001 when the actual value is 0.5. The `snap_basic()` function 'fixes' these ugly numbers in the same way you tend to in your head.

By default the approx sub will modify numbers so if we have a number like 0.499999945 with 6 9s or 0.50000012 with 6 0s the number will be rounded to 0.5.

The `snap_basic()` function also takes a second optional argument that specifies how many 0s or 9s in a row will trigger rounding. For want of a better term I call this the accuracy. The default is 6.

        snap_basic($num, 7);  # will return 0.5 for 0.500000001 but 0.50000001 if
                              # that is passed as it only has 6 zeros.

It should be noted that this is largely a cosmetic function rather than an implementation of the IEEE 754 standard. Any sequence of (default 6) 0s or 9s will trigger the modification so these modifications will occur:

        snap_basic(999999)   == 1000000;
        snap_basic(0.999999) == 1;
        snap_basic(999.999)  == 1000;

Numbers that do not fulfill the requisite criteria are returned unchanged. For example 0.5000001 will not be rounded to 0.5 as it only has 5 0s.

### snap_sigfig( [NUMBER], [SIGNIFICANT_FIGURES] )

The `snap_sigfig()` function returns its integer or float argument modified to the desired number of significant figures. If the SIGNIFICANT_FIGURES argument is not supplied a value of 6 is used. Appropriate rounding is performed.

        snap_sigfig(999999)     == 1000000;
        snap_sigfig(555555,4)   == 555600;
        snap_sigfig(0.555555,4) == 0.5556;

### snap_units( [NUMBER], [UNITS] )

The `snap_units()` function returns its integer or float argument modified so that NUMBER % UNITS == 0. UNITS can be an integer or a float. Rounding up occurs if NUMBER % UNITS >= UNITS / 2

        snap_units(13,4)       == 12
        snap_units(14,4)       == 16 ;
        snap_units(15,4)       == 16 ;
        snap_units(16,4)       == 16 ;
        snap_units(17,4)       == 16 ;
        snap_units(18,4)       == 20 ;
        snap_units(0.75, 0.25) == 0.75;
        snap_units(0.87, 0.25) == 0.75;
        snap_units(0.88, 0.25) == 1;

## EXPORT

None by default.

# AUTHOR

Dr James Freeman, <james.freeman@id3.org.uk>

SnapTo.pm