/*---------------------------------------------------------------------------

   Decimal encoding sample code

   (C) Copyright International Business Machines Corporation 2003
   All Rights Reserved.
   
   This sample code is intended to illustrate encoding of decimal
   floating-point numbers in binary bit strings, and corresponding
   decoding. Please see the document "General Decimal Arithmetic"
   at http://speleotrove.com/decimal for a full description of
   the encoding formats used.

   This sample code is experimental, and may contain errors. It is
   offered on an as-is basis. In particular, this sample code is
   designed to be illustrative rather than to be an implementation
   optimised for any particular purpose. Indeed, a number of obvious
   optimisations are omitted in the interests of maximising clarity.

   Please send comments, suggestions, and corrections to the author:
     Dave Clark
     IBM UK, PO Box 31, Birmingham Road, Warwick CV34 5JL, UK
     dave_clark@uk.ibm.com
     
 --------------------------------------------------------------------------*/
package com.ibm.eou.decimal;

/**
 * This class provides static types and constants used
 * by library methods on {@link DecimalEncoder DecimalEncoder}
 * and {@link DecimalDecoder DecimalDecoder} for encoding and
 * decoding binary representations of decimal floating-point
 * numbers using the decimal32, decimal64 and decimal128 formats.
 * @author Dave Clark, IBM Ease of Use
 */
public final class DecimalConstants
{
  // protected constructor to prevent instantiation
  // but allow classes to extend us
  protected DecimalConstants()
  {
  }
  
  // constants for which features are which in an encoding specification
  private static final int FEATURE_BITS = 0;
  private static final int FEATURE_COEFF_DIGITS = 1;
  private static final int FEATURE_EXP_BITS = 2;
  private static final int FEATURE_EXP_MIN = 3;
  private static final int FEATURE_EXP_MAX = 4;
  
  /**
   * This class represents an encoding specification.
   * @see #DECIMAL32
   * @see #DECIMAL64
   * @see #DECIMAL128
   */
  public static class DecimalEncoding
  {
    private final int[] fFeatures;
    
    // private constructor to prevent instantiation except by ourselves
    private DecimalEncoding(final int[] features)
    {
      fFeatures = features;
    }
    
    /**
     * Return the number of bits used by this encoding.
     * @return the number of bits.
     */
    public int getNumberOfBits()
    {
      return fFeatures[FEATURE_BITS];
    }
    
    /**
     * Return the number of coefficient digits accommodated by this encoding.
     * @return the number of coefficient digits.
     */
    public int getNumberOfCoefficientDigits()
    {
      return fFeatures[FEATURE_COEFF_DIGITS];
    }
    
    /**
     * Return the number of exponent continuation bits accommodated by this encoding.
     * @return the number of exponent continuation bits.
     */
    public int getNumberOfExponentContinuationBits()
    {
      return fFeatures[FEATURE_EXP_BITS];
    }
    
    /**
     * Return the minimum encodable exponent in this encoding.
     * @return the minimum encodable exponent.
     */
    public int getMinimumEncodableExponent()
    {
      return fFeatures[FEATURE_EXP_MIN];
    }
    
    /**
     * Return the maximum encodable exponent in this encoding.
     * @return the maximum encodable exponent.
     */
    public int getMaximumEncodableExponent()
    {
      return fFeatures[FEATURE_EXP_MAX];
    }
  };
  
  /**
   * Constant specifying decimal32 encoding. This encoding uses 32 bits,
   * and accommodates 7 decimal digits of coefficient. It uses 6 bits for
   * the exponent continuation, taking exponents in the range -101 to 90.
   */
  public final static DecimalEncoding DECIMAL32 = new DecimalEncoding(new int[] { 32, 7, 6, -101, 90 });
  
  /**
   * Constant specifying decimal64 encoding. This encoding uses 64 bits,
   * and accommodates 16 decimal digits of coefficient. It uses 8 bits for
   * the exponent continuation, taking exponents in the range -398 to 369.
   */
  public final static DecimalEncoding DECIMAL64 = new DecimalEncoding(new int[] { 64, 16, 8, -398, 369 });
  
  /**
   * Constant specifying decimal128 encoding. This encoding uses 128 bits,
   * and accommodates 34 decimal digits of coefficient. It uses 12 bits for
   * the exponent continuation, taking exponents in the range -6176 to 6111.
   */
  public final static DecimalEncoding DECIMAL128 = new DecimalEncoding(new int[] { 128, 34, 12, -6176, 6111 });
  
  /**
   * This class represents a rounding mode.
   * @see #ROUNDING_FLOOR
   * @see #ROUNDING_CEILING
   * @see #ROUNDING_DOWN
   * @see #ROUNDING_UP
   * @see #ROUNDING_HALF_DOWN
   * @see #ROUNDING_HALF_UP
   * @see #ROUNDING_HALF_EVEN
   */
  public static class RoundingMode
  {
    // private constructor to prevent instantiation except by ourselves
    private RoundingMode()
    {
    }
  };
  
  /**
   * Constant specifying a rounding mode in which non-integer finite numbers
   * are rounded to the nearest integer in the negative direction.
   */
  public final static RoundingMode ROUNDING_FLOOR = new RoundingMode();

  /**
   * Constant specifying a rounding mode in which non-integer finite numbers
   * are rounded to the nearest integer in the positive direction.
   */
  public final static RoundingMode ROUNDING_CEILING = new RoundingMode();

  /**
   * Constant specifying a rounding mode in which non-integer finite numbers
   * are rounded to the nearest integer in the direction towards zero.
   */
  public final static RoundingMode ROUNDING_DOWN = new RoundingMode();

  /**
   * Constant specifying a rounding mode in which non-integer finite numbers
   * are rounded to the nearest integer in the direction away from zero.
   */
  public final static RoundingMode ROUNDING_UP = new RoundingMode();

  /**
   * Constant specifying a rounding mode in which non-integer finite numbers
   * are rounded to the nearest integer in either direction, and exact halves
   * are rounded to the nearest integer in the direction towards zero.
   */
  public final static RoundingMode ROUNDING_HALF_DOWN = new RoundingMode();

  /**
   * Constant specifying a rounding mode in which non-integer finite numbers
   * are rounded to the nearest integer in either direction, and exact halves
   * are rounded to the nearest integer in the direction away from zero.
   */
  public final static RoundingMode ROUNDING_HALF_UP = new RoundingMode();

  /**
   * Constant specifying a rounding mode in which non-integer finite numbers
   * are rounded to the nearest integer in either direction, and exact halves
   * are rounded in whichever direction will make the previous digit even.
   */
  public final static RoundingMode ROUNDING_HALF_EVEN = new RoundingMode();

  /**
   * Constant specifying the bit position at which the sign is stored
   * in DecimalNNN formats.
   */
  public static final int BIT_SIGN = 0;

  /**
   * Constant specifying the bit position at which the combination
   * field is stored in DecimalNNN formats.
   */
  public static final int BIT_COMBINATION = 1;

  /**
   * Constant specifying the bit position at which the exponent
   * continuation field is stored in DecimalNNN formats.
   */
  public static final int BIT_EXPONENT = 6;
}