edu.nrao.sss.math
Interface NumberSet

public interface NumberSet

A collection of numbers that can act like a map or a lookup table. This collection can be a discrete set of numbers, or a continuum stretching from a minimum to maximum number.

Example Usage:
Assume that you have an instrument that has a number of power levels, but that these levels must be an integral power of two. The lowest level is 1 unit and the highest is 1,024 units. Clients of this instrument would like to set the power level to any arbitrary non-negative number. Your instrument takes a request for a power level and returns the greatest power that it can provide that is not greater than the request. This is how you would implement such logic:

   private int powerLevel = 0;
   ...
   private NumberSet validPowerLevels =
     NumberSet.factory.makeDiscreteSetMultiplicative(
       1, 1024, 2, NumberSet.LookupMethod.LARGEST_LESS_THAN_OR_EQUAL);
   ...
   public Number setPowerLevel(Number newLevel)
   {
     //The actual level must be an integral power of two,
     //while the requested new level could be any number.
     
     Number actualLevel = validPowerLevels.getBestMatchFor(newLevel);
     
     if (actualLevel != null)
       powerLevel = actualLevel.intValue();
     else
       powerLevel = 0;
       
     return powerLevel;
   }
 

Version Info:

$Revision: 558 $

$Date: 2007-04-24 16:46:41 -0600 (Tue, 24 Apr 2007) $

$Author: dharland $

Since:

2007-03-01

Author:

David M. Harland

Nested Class Summary

static class

NumberSet.LookupMethod A set of instructions for number sets that helps the sets find values.

Field Summary

static NumberSetFactory

factory Returns a factory that produces number sets.

Method Summary

Number

getBestMatchFor(Number myNumber) Returns the number in this set that is the best match for myNumber.

Field Detail

factory

static final NumberSetFactory factory

Returns a factory that produces number sets.

Method Detail

getBestMatchFor

Number getBestMatchFor(Number myNumber)

Returns the number in this set that is the best match for myNumber. The returned number depends on the type of this set (continuous vs. discrete), the minimum and maximum values held by this set, and the LookupMethod used for finding a match.

Parameters:

myNumber - a number for which a best match is desired.

Returns:

the best match for myNumber, or null if there is no best match. A value of null is returned if:

1. The LookupMethod is EQUAL and myNumber is above the maximum or below the minimum.
2. The LookupMethod is EQUAL, this set is discrete, myNumber is within the minimum and maximum bounds, but is not one of the discrete values held by this set.
3. The LookupMethod is LARGEST_LESS_THAN_OR_EQUAL and myNumber is below the minimum.
4. The LookupMethod is SMALLEST_GREATER_THAN_OR_EQUAL and myNumber is above the maximum.