com.rubecula.jquantity
Class Mill

java.lang.Object
  extended byjava.util.AbstractCollection
      extended byjava.util.AbstractList
          extended byjava.util.Vector
              extended byjava.util.Stack
                  extended bycom.rubecula.jquantity.Mill
All Implemented Interfaces:
Auditable, java.lang.Cloneable, java.util.Collection, Identifiable, java.util.List, Lookupable, MillInterface, java.util.RandomAccess, java.io.Serializable
Direct Known Subclasses:
Mill

public class Mill
extends java.util.Stack
implements MillInterface

This class is responsible for evaluating operations on Presentable objects. It is named in honor of Charles Babbage, father of the (mechanical) computer, and not forgetting the early days of electronic computing, especially in the United Kingdom, and particularly for Maurice Wilkes.

Version:
$Revision: 1.33 $ // TODO Consider moving this class into a new package com.rubecula.mill.
Author:
Robin Hillyard
See Also:
Serialized Form

Nested Class Summary
 
Nested classes inherited from class java.util.AbstractList
 
Field Summary
private  AlphabeticalMap _AllOperations
          This is the table of all operations.
private  AlphabeticalMap _AnadicOperations
          This is the table of anadic operations.
private  AlphabeticalMap _DyadicOperations
          This is the table of dyadic operations.
private  StringMap _Memory
          The user-definable memory for this mill.
private  AlphabeticalMap _MonadicOperations
          This is the table of monadic operations.
private  java.lang.String _Name
          The identifier for this Mill.
private  AlphabeticalMap _SpecialOperations
          This is the table of special operations.
protected static StringMap CONSTANTS
          The system defined (constant) memory for this mill.
protected static java.lang.String K__1
           
protected static java.lang.String K_0
           
protected static java.lang.String K_1
           
protected static java.lang.String K_10
           
protected static java.lang.String K_2
           
protected static java.lang.String K_3
           
protected static java.lang.String K_E
           
protected static java.lang.String K_MEM
           
protected static java.lang.String K_PI
           
protected static java.lang.String OP_2ATAN
           
protected static java.lang.String OP_AUDIT
           
protected static java.lang.String OP_CHS
           
protected static java.lang.String OP_COPY
           
protected static java.lang.String OP_DIFFERENCE
           
protected static java.lang.String OP_E
           
protected static java.lang.String OP_EXP
           
protected static java.lang.String OP_INV
           
protected static java.lang.String OP_LOG
           
protected static java.lang.String OP_NOOP
           
protected static java.lang.String OP_PI
           
protected static java.lang.String OP_POWER
           
protected static java.lang.String OP_PRODUCT
           
protected static java.lang.String OP_QUOTIENT
           
protected static java.lang.String OP_SUM
           
protected static java.lang.String OP_SWAP
           
protected static java.lang.String OP_TANHALF
           
 
Fields inherited from class java.util.Stack
 
Fields inherited from class java.util.Vector
capacityIncrement, elementCount, elementData
 
Fields inherited from class java.util.AbstractList
modCount
 
Constructor Summary
Mill(java.lang.String name)
          Principal constructor for a new Mill.
 
Method Summary
protected  void addConstant(java.lang.String key, Presentable value)
          MUTATING method to add a constant.
 void addConstants(Lookupable table)
          MUTATING method to add a table of constants.
 java.lang.String audit()
          Method to return a detailed (unlabeled) string from an object for debugging purposes.
 void audit(java.io.PrintStream out, java.lang.String label)
          Method to output detailed string from an object for debugging purposes.
 java.lang.String audit(java.lang.String label)
          Method to return a detailed string from an object for debugging purposes.
private static BaseNumber BaseNumberProduct(BaseNumber operand1, BaseNumber operand2)
          Static method to get the product of two BaseNumbers.
private static Millable ChangeSign(Millable operand)
           
private static Millable EvaluatePower(int power, BaseNumber number)
           
 int getAdy(java.lang.String operator)
          This method returns the number of presentables needed to popped off the stack for an operation.
 java.lang.String getIdentifier()
          Method to get the specific identifier for an object.
 java.util.Collection getKeys()
          Method to get the keyset for this Mill's constants.
 AlphabeticalMap getOperations()
          Method to get a map which represents the supported functions of this Mill.
 Presentable getValue(java.lang.String key)
          Method to get a memory presentable defined by key.
 void help(java.io.PrintStream output)
          This method outputs help information listing and describing the various operations supported by the mill.
private  void initOperations()
           
private static Millable Invert(int power, BaseNumber number)
           
private  boolean IsDyadic(java.lang.String operator)
           
private static boolean IsTrig(java.lang.String operator)
           
 java.lang.String lookupOperator(java.lang.String description)
          This method returns the name of an operator whose description matches the string description in some way.
static void main(java.lang.String[] args)
          Main method for testing this class.
 void operate(java.lang.String operator)
          Mutating method to apply the operation operator to the stack.
private  void operate(java.lang.String operator, Millable top)
          Mutating method to apply a dyadic operation operator to the stack.
private  java.lang.Object operateDyadic(java.lang.String operator, Millable next, Millable top)
           
private  Millable popNumber()
          This method takes a Presentable object and returns the corresponding BaseNumber.
private static Millable Pow(Millable operand, int power)
           
private static Millable Product(Millable operand1, Millable operand2)
          Private Method to implement multiplication of operands in the mill.
 void push(Presentable operand)
          Mutating method to push operand onto the top of the Mill stack.
 void setValue(java.lang.String key, Presentable value)
          Method to set a value which can later be retrieved using the name given (using the method defined by the Lookupable interface).
private static Millable Sum(Millable operand1, Millable operand2)
           
 
Methods inherited from class java.util.Stack
empty, peek, pop, push, search
 
Methods inherited from class java.util.Vector
add, add, addAll, addAll, addElement, capacity, clear, clone, contains, containsAll, copyInto, elementAt, elements, ensureCapacity, equals, firstElement, get, hashCode, indexOf, indexOf, insertElementAt, isEmpty, lastElement, lastIndexOf, lastIndexOf, remove, remove, removeAll, removeAllElements, removeElement, removeElementAt, removeRange, retainAll, set, setElementAt, setSize, size, subList, toArray, toArray, toString, trimToSize
 
Methods inherited from class java.util.AbstractList
iterator, listIterator, listIterator
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.rubecula.util.MillInterface
pop, size
 
Methods inherited from interface java.util.List
iterator, listIterator, listIterator
 

Field Detail

_AllOperations

private final AlphabeticalMap _AllOperations
This is the table of all operations. Keys are abbreviated operators (case-independent); Entries are formal definitions.


_DyadicOperations

private final AlphabeticalMap _DyadicOperations
This is the table of dyadic operations. Keys are abbreviated operators (case-independent); Entries are formal definitions.


_MonadicOperations

private final AlphabeticalMap _MonadicOperations
This is the table of monadic operations. Keys are abbreviated operators (case-independent); Entries are formal definitions.


_AnadicOperations

private final AlphabeticalMap _AnadicOperations
This is the table of anadic operations. Keys are abbreviated operators (case-independent); Entries are formal definitions.


_SpecialOperations

private final AlphabeticalMap _SpecialOperations
This is the table of special operations. Keys are abbreviated operators (case-independent); Entries are formal definitions.


_Name

private final java.lang.String _Name
The identifier for this Mill.


_Memory

private final StringMap _Memory
The user-definable memory for this mill. Note that the keys for this store are case-dependent Strings.


CONSTANTS

protected static final StringMap CONSTANTS
The system defined (constant) memory for this mill. Note that the keys for this store are case-dependent Strings.


OP_SUM

protected static final java.lang.String OP_SUM
See Also:
Constant Field Values

OP_DIFFERENCE

protected static final java.lang.String OP_DIFFERENCE
See Also:
Constant Field Values

OP_PRODUCT

protected static final java.lang.String OP_PRODUCT
See Also:
Constant Field Values

OP_QUOTIENT

protected static final java.lang.String OP_QUOTIENT
See Also:
Constant Field Values

OP_POWER

protected static final java.lang.String OP_POWER
See Also:
Constant Field Values

OP_2ATAN

protected static final java.lang.String OP_2ATAN
See Also:
Constant Field Values

OP_TANHALF

protected static final java.lang.String OP_TANHALF
See Also:
Constant Field Values

OP_EXP

protected static final java.lang.String OP_EXP
See Also:
Constant Field Values

OP_LOG

protected static final java.lang.String OP_LOG
See Also:
Constant Field Values

OP_CHS

protected static final java.lang.String OP_CHS
See Also:
Constant Field Values

OP_INV

protected static final java.lang.String OP_INV
See Also:
Constant Field Values

OP_PI

protected static final java.lang.String OP_PI
See Also:
Constant Field Values

OP_E

protected static final java.lang.String OP_E
See Also:
Constant Field Values

OP_COPY

protected static final java.lang.String OP_COPY
See Also:
Constant Field Values

OP_AUDIT

protected static final java.lang.String OP_AUDIT
See Also:
Constant Field Values

OP_SWAP

protected static final java.lang.String OP_SWAP
See Also:
Constant Field Values

OP_NOOP

protected static final java.lang.String OP_NOOP
See Also:
Constant Field Values

K_PI

protected static final java.lang.String K_PI
See Also:
Constant Field Values

K_E

protected static final java.lang.String K_E
See Also:
Constant Field Values

K__1

protected static final java.lang.String K__1
See Also:
Constant Field Values

K_0

protected static final java.lang.String K_0
See Also:
Constant Field Values

K_1

protected static final java.lang.String K_1
See Also:
Constant Field Values

K_2

protected static final java.lang.String K_2
See Also:
Constant Field Values

K_3

protected static final java.lang.String K_3
See Also:
Constant Field Values

K_10

protected static final java.lang.String K_10
See Also:
Constant Field Values

K_MEM

protected static final java.lang.String K_MEM
See Also:
Constant Field Values
Constructor Detail

Mill

public Mill(java.lang.String name)
Principal constructor for a new Mill.

Parameters:
name - by which this Mill will be referred to.
Method Detail

push

public void push(Presentable operand)
          throws MillException
Mutating method to push operand onto the top of the Mill stack.

Specified by:
push in interface MillInterface
Parameters:
operand - a presentable object which will displace the former top of the stack to the second position and itself become the top object.
Throws:
MillException - operand not a BaseNumber.

operate

public void operate(java.lang.String operator)
             throws java.util.EmptyStackException,
                    MillException

Mutating method to apply the operation operator to the stack. The number of items required on the stack prior to the operation and the number of items left on the stack afterwards depends upon the operation.

Specified by:
operate in interface MillInterface
Parameters:
operator - the name for the operation. The following operators ONLY are supported by this Mill:
$name
Retrieve the value indicated by name and push it on the stack. Note that such values are first looked up in the constants list and then, if nothing is found, in the instance list.
<blank>
Pop one value from the stack and push it back.
swap
Reverse the order of the two top stack items.
copy
Pop the top item off the stack and push it back twice.
+
Pop two values from the stack and push their sum.
-
Pop two values from the stack and push their difference.
*
Pop two values from the stack and push their product.
/
Pop two values from the stack and push their quotient.
inv
Pop one value from the stack, take its reciprocal and push the result.
chs
Pop one value from the stack, change its sign and push the result.
log
Pop one value from the stack, take its natural logarithm and push the result.
exp
Pop one value from the stack, raise e to its power and push the result.
2atan
Pop one value from the stack, evaluate twice the arctangent and push the result.
tanhalf
Pop one value from the stack, evaluate the tangent of half the value and push the result.
Throws:
java.util.EmptyStackException
MillException

getValue

public Presentable getValue(java.lang.String key)
Method to get a memory presentable defined by key. The lookup is first made in the class constants and then, if that fails, in this instance's memory. In this way, constants cannot be replaced either deliberately or inadvertently.

Specified by:
getValue in interface Lookupable
Parameters:
key - the name of the memory object, without any preceding "$".
Returns:
the presentable value specified or null.

setValue

public void setValue(java.lang.String key,
                     Presentable value)
              throws MillException
Method to set a value which can later be retrieved using the name given (using the method defined by the Lookupable interface). A memory value can be unset by setting to the null value. Names which appear in the constants list cannot be reused.

Specified by:
setValue in interface MillInterface
Parameters:
key - the name or key by which this value can be retrieved (without any preceding "$").
value - a Presentable value which is lookupable.
Throws:
MillException - if memory slot name cannot be set to value, because the name is already in use (or an attempt to remove a constant). // TODO Why isn't this method defined in Lookupable?

getOperations

public AlphabeticalMap getOperations()
Method to get a map which represents the supported functions of this Mill. The keys are the operators (typically abbreviations, all lower case) and the entries are the full mathematical function names (all lower case).

Specified by:
getOperations in interface MillInterface
Returns:
a map of the abbreviation-function mappings for the supported operations of this mill.

lookupOperator

public java.lang.String lookupOperator(java.lang.String description)
                                throws MillException
This method returns the name of an operator whose description matches the string description in some way.

Specified by:
lookupOperator in interface MillInterface
Parameters:
description - the mathematical name or description of the operator.
Returns:
the name of the operator, or null if no match found.
Throws:
MillException - more than one operator matched.

help

public void help(java.io.PrintStream output)
This method outputs help information listing and describing the various operations supported by the mill.

Specified by:
help in interface MillInterface
Parameters:
output - an output stream. // TODO sort by key.

getIdentifier

public java.lang.String getIdentifier()
Method to get the specific identifier for an object.

Specified by:
getIdentifier in interface Identifiable
Returns:
the identifier.

audit

public java.lang.String audit(java.lang.String label)
Method to return a detailed string from an object for debugging purposes.

Specified by:
audit in interface Auditable
Parameters:
label - the label to associate with the data. If label is non-null, a more detailed audit will be returned (this normally occurs only at the top level).
Returns:
the detailed string. // TODO implement.

audit

public java.lang.String audit()
Method to return a detailed (unlabeled) string from an object for debugging purposes.

Specified by:
audit in interface Auditable
Returns:
the detailed string.

audit

public void audit(java.io.PrintStream out,
                  java.lang.String label)
Method to output detailed string from an object for debugging purposes.

Specified by:
audit in interface Auditable
Parameters:
out - the output stream.
label - the label to attach to the output (may be null).

operate

private void operate(java.lang.String operator,
                     Millable top)
              throws java.util.EmptyStackException,
                     MillException
Mutating method to apply a dyadic operation operator to the stack. One item is required to be on the stack and the result will be placed on the stack after the operation.

Parameters:
operator - the name for the operation. Different Mills will naturally support different operations.
top - the value which was on the top of the stack (or null).
Throws:
java.util.EmptyStackException
MillException

IsDyadic

private boolean IsDyadic(java.lang.String operator)

IsTrig

private static boolean IsTrig(java.lang.String operator)

operateDyadic

private java.lang.Object operateDyadic(java.lang.String operator,
                                       Millable next,
                                       Millable top)
                                throws InvalidOperandException,
                                       MillException
Throws:
InvalidOperandException
MillException

popNumber

private Millable popNumber()
                    throws MillException
This method takes a Presentable object and returns the corresponding BaseNumber. If presentable is a BaseNumber then it is returned as is, but if presentable is a Text object or some other object, it may be looked up in a memory table as appropriate (more later).

Returns:
the appropriate BaseNumber corresponding to presentable.
Throws:
MillException - if top of stack is not a BaseNumber.

getAdy

public int getAdy(java.lang.String operator)
           throws MillException
This method returns the number of presentables needed to popped off the stack for an operation.

Specified by:
getAdy in interface MillInterface
Parameters:
operator - the name (abbreviation) of the operator.
Returns:
0, 1 or 2 for an-, mon- or dy-adic operators; special operators that don't make a net change in the stack at all return -1.
Throws:
MillException - operator is not supported.

addConstants

public void addConstants(Lookupable table)
MUTATING method to add a table of constants. All entries in the table are Presentables.

Specified by:
addConstants in interface MillInterface
Parameters:
table - the set of constants to be added.

addConstant

protected void addConstant(java.lang.String key,
                           Presentable value)
MUTATING method to add a constant.

Parameters:
key - the constant's key for retrieval purposes.
value - the constant's value.

ChangeSign

private static Millable ChangeSign(Millable operand)
                            throws MillException
Throws:
MillException

Pow

private static Millable Pow(Millable operand,
                            int power)
                     throws MillException
Throws:
MillException

EvaluatePower

private static Millable EvaluatePower(int power,
                                      BaseNumber number)

Invert

private static Millable Invert(int power,
                               BaseNumber number)
                        throws MillException
Throws:
MillException

Sum

private static Millable Sum(Millable operand1,
                            Millable operand2)
                     throws MillException,
                            InvalidOperandException
Throws:
MillException
InvalidOperandException

Product

private static Millable Product(Millable operand1,
                                Millable operand2)
                         throws MillException,
                                InvalidOperandException
Private Method to implement multiplication of operands in the mill. Although it can throw exceptions, in normal circumstances it should not. The method should be able to handle all classes of both operands, and the ordering of the operands should be immaterial.

Parameters:
operand1 - a Millable object
operand2 - a Millable object
Returns:
the product of operand1 and operand2
Throws:
MillException - a problem which could not be worked around
InvalidOperandException - this should point to a programming error: there should be no combination of Millable operands which cannot by multiplied together.

BaseNumberProduct

private static BaseNumber BaseNumberProduct(BaseNumber operand1,
                                            BaseNumber operand2)
                                     throws InvalidOperandException
Static method to get the product of two BaseNumbers.

Parameters:
operand1 -
operand2 -
Returns:
Throws:
InvalidOperandException

initOperations

private void initOperations()

main

public static void main(java.lang.String[] args)
Main method for testing this class.

Parameters:
args - String[] : the command line options.

getKeys

public java.util.Collection getKeys()
Method to get the keyset for this Mill's constants. Note that we do not currently return the memory items.

Specified by:
getKeys in interface Lookupable
See Also:
Lookupable.getKeys()