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. Positive or negative integers and floats are supported.

## 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 0.500000000001 when the actual value is 0.5.

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