ModulusTenCheckDigit (Apache Commons Validator 1.11.0 API)
Description: declaration: package: org.apache.commons.validator.routines.checkdigit, class: ModulusTenCheckDigit

# Class ModulusTenCheckDigit

java.lang.Object
org.apache.commons.validator.routines.checkdigit.ModulusCheckDigit
org.apache.commons.validator.routines.checkdigit.ModulusTenCheckDigit

All Implemented Interfaces:
  `Serializable, CheckDigit`

public final class ModulusTenCheckDigit extends ModulusCheckDigit
General Modulus 10 Check Digit calculation/validation.

## How it Works

This implementation calculates/validates the check digit in the following way:

- Converting each character to an integer value using `Character.getNumericValue(char)` - negative integer values from that method are invalid.
- Calculating a weighted value by multiplying the character's integer value by a weighting factor. The weighting factor is selected from the configured `positionWeight` array based on its position. The `postitionWeight` values are used either left-to-right (when `useRightPos=false`) or right-to-left (when `useRightPos=true`).
- If `sumWeightedDigits=true`, the weighted value is re-calculated by summing its digits.
- The weighted values of each character are totalled.
- The total modulo 10 will be zero for a code with a valid Check Digit.

## Limitations

This implementation has the following limitations:

- It assumes the last character in the code is the Check Digit and validates that it is a numeric character.
- The only limitation on valid characters are those that `Character.getNumericValue(char)` returns a positive value. If, for example, the code should only contain numbers, this implementation does not check that.
- There are no checks on code length.

Note: This implementation can be combined with the `CodeValidator` in order to ensure the length and characters are valid.

## Example Usage

This implementation was added after a number of Modulus 10 routines and these are shown re-implemented using this routine below:

ABA Number Check Digit Routine (equivalent of `ABANumberCheckDigit`). Weighting factors are `[1, 7, 3]` applied from right to left.

    CheckDigit routine = new ModulusTenCheckDigit(new int[] { 1, 7, 3 }, true);

CUSIP Check Digit Routine (equivalent of `CUSIPCheckDigit`). Weighting factors are `[1, 2]` applied from right to left and the digits of the weighted value are summed.

    CheckDigit routine = new ModulusTenCheckDigit(new int[] { 1, 2 }, true, true);

EAN-13 / UPC Check Digit Routine (equivalent of `EAN13CheckDigit`). Weighting factors are `[1, 3]` applied from right to left.

    CheckDigit routine = new ModulusTenCheckDigit(new int[] { 1, 3 }, true);

Luhn Check Digit Routine (equivalent of `LuhnCheckDigit`). Weighting factors are `[1, 2]` applied from right to left and the digits of the weighted value are summed.

    CheckDigit routine = new ModulusTenCheckDigit(new int[] { 1, 2 }, true, true);

SEDOL Check Digit Routine (equivalent of `SedolCheckDigit`). Weighting factors are `[1, 3, 1, 7, 3, 9, 1]` applied from left to right.

    CheckDigit routine = new ModulusTenCheckDigit(new int[] { 1, 3, 1, 7, 3, 9, 1 });

Since:
  1.6
See Also:
  - Serialized Form

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ModulusTenCheckDigit(int[] positionWeight)`
  Constructs a modulus 10 Check Digit routine with the specified weighting from left to right.
  `ModulusTenCheckDigit(int[] positionWeight, boolean useRightPos)`
  Constructs a modulus 10 Check Digit routine with the specified weighting, indicating whether its from the left or right.
  `ModulusTenCheckDigit(int[] positionWeight, boolean useRightPos, boolean sumWeightedDigits)`
  Constructs a modulus 10 Check Digit routine with the specified weighting, indicating whether its from the left or right and whether the weighted digits should be summed.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `isValid(String code)`
  Validate a modulus check digit for a code.
  `protected int`
  `toInt(char character, int leftPos, int rightPos)`
  Convert a character at a specified position to an integer value.
  `String`
  `toString()`
  Return a string representation of this implementation.
  `protected int`
  `weightedValue(int charValue, int leftPos, int rightPos)`
  Calculates the weighted value of a character in the code at a specified position.

  ### Methods inherited from class ModulusCheckDigit

  `calculate, calculateModulus, getModulus, sumDigits, toCheckDigit`
  Modifier and Type
  Method
  Description
  `String`
  `calculate(String code)`
  Calculates a modulus Check Digit for a code which does not yet have one.
  `protected int`
  `calculateModulus(String code, boolean includesCheckDigit)`
  Calculates the modulus for a code.
  `int`
  `getModulus()`
  Gets the modulus value this check digit routine is based on.
  `static int`
  `sumDigits(int number)`
  Adds together the individual digits in a number.
  `protected String`
  `toCheckDigit(int charValue)`
  Converts an integer value to a check digit.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### ModulusTenCheckDigit

    public ModulusTenCheckDigit(int[] positionWeight)
    Constructs a modulus 10 Check Digit routine with the specified weighting from left to right.
    Parameters:
      `positionWeight` - The weighted values to apply based on the character position

  - ### ModulusTenCheckDigit

    public ModulusTenCheckDigit(int[] positionWeight, boolean useRightPos)
    Constructs a modulus 10 Check Digit routine with the specified weighting, indicating whether its from the left or right.
    Parameters:
      `positionWeight` - The weighted values to apply based on the character position
      `useRightPos` - `true` if use positionWeights from right to left

  - ### ModulusTenCheckDigit

    public ModulusTenCheckDigit(int[] positionWeight, boolean useRightPos, boolean sumWeightedDigits)
    Constructs a modulus 10 Check Digit routine with the specified weighting, indicating whether its from the left or right and whether the weighted digits should be summed.
    Parameters:
      `positionWeight` - The weighted values to apply based on the character position
      `useRightPos` - `true` if use positionWeights from right to left
      `sumWeightedDigits` - `true` if sum the digits of the weighted value

- ## Method Details

  - ### isValid

    public boolean isValid(String code)
    Validate a modulus check digit for a code.

    Note: assumes last digit is the check digit.

    Specified by:
      `isValid` in interface `CheckDigit`
    Overrides:
      `isValid` in class `ModulusCheckDigit`
    Parameters:
      `code` - The code to validate.
    Returns:
      `true` if the check digit is valid, otherwise `false`.

  - ### toInt

    protected int toInt(char character, int leftPos, int rightPos) throws CheckDigitException
    Convert a character at a specified position to an integer value.

    Note: this implementation only handlers values that Character.getNumericValue(char) returns a non-negative number.

    Overrides:
      `toInt` in class `ModulusCheckDigit`
    Parameters:
      `character` - The character to convert.
      `leftPos` - The position of the character in the code, counting from left to right (for identifying the position in the string).
      `rightPos` - The position of the character in the code, counting from right to left (not used here).
    Returns:
      The integer value of the character.
    Throws:
      `CheckDigitException` - if Character.getNumericValue(char) returns a negative number.

  - ### toString

    public String toString()
    Return a string representation of this implementation.
    Overrides:
      `toString` in class `Object`
    Returns:
      A string representation.

  - ### weightedValue

    protected int weightedValue(int charValue, int leftPos, int rightPos)
    Calculates the weighted value of a character in the code at a specified position.
    Specified by:
      `weightedValue` in class `ModulusCheckDigit`
    Parameters:
      `charValue` - The numeric value of the character.
      `leftPos` - The position of the character in the code, counting from left to right.
      `rightPos` - The position of the character in the code, counting from right to left.
    Returns:
      The weighted value of the character.