cox.jmatt.java.MathTools
Class MComplex

java.lang.Object
  extended by cox.jmatt.java.MathTools.MComplex

public class MComplex
extends java.lang.Object

This class provides MathTools support for imaginary and complex numbers. As with MRadical and MathStat this is primarily a formatting class although it does provide some basic numerical manipulation. Once created a MComplex is immutable and any method that would change it returns a new instance. Since MComplex is primarily for formatting and simple manipulation the components are represented as type int. Three formal constructors are defined along with static and instance newInstance() methods and the reParse() method can build an instance from a String of the form 'A + Bi'.

MComplex defines six condition-testing methods, two of which involve another instance. A complex number can be tested as to whether it is (purely) real or imaginary, zero or complex. It can be tested against another MComplex for equality and for being its conjugate.

In terms of numerical manipulation there are addition, subtraction and two multiplication methods. There is a method to form the complex conjugate and one to raise 'i' to an arbitrary (integer) power. All of these methods return MComplex and, since instances are immutable, the original is not changed by doing so. The abs() method returns the absolute value (or magnitude) of the number as type double. This is also available as a formatting token.

Formatting

This is the true strength of this class. For technologies with special symbols for the imaginary number, 'i' can be set to any letter or String. The format() method defines a plethora of replacement tokens, many of which deal with the imaginary part, its sign and the 'i' symbol. There are three pre-defined formats: DEFAULT, STANDARD and TYPICAL. The former always presents a complex number in the form 'A + Bi', even when one part is zero. STANDARD is either 'A + Bi' or 'A - Bi' depending on the sign of B. TYPICAL format omits a component that is zero, including the middle sign if the imaginary part is zero. The toString() and toXML() methods return a constructor-like representation and a MathTools-XML tag, respectively.

The divide() method is a hybrid between presentation and manipulation. Since complex division might result in a fractional value the return type for this method is String. After it is accomplished the components of the division are presented as typewriter-style fractions that can be converted to MFractions if necessary. To facilitate this the middle sign and 'i' symbol appear as String arguments, allowing them to be omitted or replaced with whatever is appropriate for further processing.


Field Summary
static java.lang.String FORMAT_DEFAULT
          String constant for the default format: A + Bi.
static java.lang.String FORMAT_STANDARD
          String constant for standard form: A + Bi or A - Bi, depending on B's sign.
static java.lang.String FORMAT_TYPICAL
          String constant for the typical representation of a complex number.
 
Constructor Summary
MComplex()
          Basic scripting constructor.
MComplex(int pReal, int pImag)
          Standard constructor with both components specified.
MComplex(MComplex pCplx)
          Copy constructor.
 
Method Summary
 double abs()
          Calculate the absolute value (magnitude) of this number.
 MComplex add(MComplex pRHS)
          Add this to another complex number.
 MComplex conjugate()
          Form the complex conjugate of this number: A + Bi becomes A - Bi.
 MComplex copyOf()
          Return a copy of this complex number.
 java.lang.String divide(MComplex pDivisor, java.lang.String pPlus, java.lang.String pImag)
          This is a formatting method.
 boolean equals(MComplex pRHS)
          Return true if the real and imaginary parts of this and 'pRHS' are equal.
 java.lang.String format()
          Format this number per the internal format.
 java.lang.String format(java.lang.String pTemplat)
          Format this MComplex number per the template supplied.
 MComplex from_Knobs(java.lang.String pKnobs)
          Instance Knob-creator.
static MComplex fromKnobs(java.lang.String pKnobs)
          Create a complex number from a Knobs String.
 java.lang.String i_KaPow(int pExp)
          Deprecated. Use ka_Pow instead.
 MComplex i_Pow(int pExp)
          Instance method to raise 'i' to a power.
static java.lang.String iKaPow(int pExp)
          Deprecated. Use kaPow instead.
 int imag()
          Return the imaginary part of this number.
static MComplex iPow(int pExp)
          Raise 'i' to a power.
 boolean isComplex()
          Return true if both parts of this number are nonzero.
 boolean isConjugate(MComplex pRHS)
          Return true if 'pRHS' is the complex conjugate of this number.
 boolean isImaginary()
          Return true if the real part of this number is zero and the imaginary part is not..
 boolean isReal()
          Return true if the imaginary part of this number is zero and the real part isn't.
 boolean isZero()
          Return true if both parts of this number are zero.
 java.lang.String ka_Pow(int pExp)
          Extremely lazy instance Ka-POW.
static java.lang.String kaPow(int pExp)
          This is an extreme laziness method.
 MComplex multiply(int pVal)
          Multiply this number by a scalar (int) constant.
 MComplex multiply(MComplex pRHS)
          Multiply this by another complex number.
 MComplex new_Instance(int pReal, int pImag)
          Create and return a new MComplex, instance version.
static MComplex newInstance(int pReal, int pImag)
          Create and return a new MComplex.
 MComplex re_Parse(java.lang.String pCplx)
          Instance method to parse a complex number.
 int real()
          Return the real part of this complex number.
static MComplex reParse(java.lang.String pCplx)
          Attempt to parse a complex number of the form 'A + Bi'.
static void set_i(java.lang.String pNewI)
          Set the global (static) symbol used to represent the imaginary number 'i'.
 void setDefaultFormat(java.lang.String pFormat)
          Set a new default format for subsequent complex numbers.
 void setFormat(java.lang.String pFormat)
          Set the format for this instance.
 void setNew_i(java.lang.String pNewI)
          Instance flavored 'set_i'.
 void setNewDefaultFormat(java.lang.String pFormat)
          Instance version.
 MComplex subtract(MComplex pRHS)
          Subtract another complex number from this one.
 java.lang.String toString()
          Return a constructor-like representation of this complex number.
 java.lang.String toXML(java.lang.String pID)
          Create a simplified (MathTools) XML representation of this complex number.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

FORMAT_DEFAULT

public static final java.lang.String FORMAT_DEFAULT
String constant for the default format: A + Bi. Both components appear, no special formatting is done.

See Also:
Constant Field Values

FORMAT_STANDARD

public static final java.lang.String FORMAT_STANDARD
String constant for standard form: A + Bi or A - Bi, depending on B's sign. Zero parts are displayed.

See Also:
Constant Field Values

FORMAT_TYPICAL

public static final java.lang.String FORMAT_TYPICAL
String constant for the typical representation of a complex number. If either part is zero it is not displayed.

See Also:
Constant Field Values
Constructor Detail

MComplex

public MComplex()
Basic scripting constructor. It creates the complex number 0 + 0i.


MComplex

public MComplex(int pReal,
                int pImag)
Standard constructor with both components specified.


MComplex

public MComplex(MComplex pCplx)
Copy constructor.

Method Detail

reParse

public static MComplex reParse(java.lang.String pCplx)

Attempt to parse a complex number of the form 'A + Bi'. If the String cannot be parsed zero is returned. If the input String cannor be parsed or one of the components is not an Integer a debug-level message is given. If 'pCplx' is null or blank zero is returned immediately.

In order to parse properly the complex number must be of the form 'A + Bi'. The middle sign may be plus or minus and may have spaces around it but the signs on the numbers, if present, must not have any space between. Also, if one component is zero it must still be present! The 're' in this method name is for regular expression and that is how the value is parsed. The 'i' is a part of the pattern as is the no-space requirement between a component's sign and the number itself.


re_Parse

public MComplex re_Parse(java.lang.String pCplx)
Instance method to parse a complex number.


newInstance

public static MComplex newInstance(int pReal,
                                   int pImag)
Create and return a new MComplex.


new_Instance

public MComplex new_Instance(int pReal,
                             int pImag)
Create and return a new MComplex, instance version.


fromKnobs

public static MComplex fromKnobs(java.lang.String pKnobs)
Create a complex number from a Knobs String. If 'pKnobs' is null or blank zero is returned. If there are not enough numbers zeros will be used. Any leftovers are silently ignored.


from_Knobs

public MComplex from_Knobs(java.lang.String pKnobs)
Instance Knob-creator.


setDefaultFormat

public void setDefaultFormat(java.lang.String pFormat)
Set a new default format for subsequent complex numbers. If null or blank FORMAT_DEFAULT is used.


setNewDefaultFormat

public void setNewDefaultFormat(java.lang.String pFormat)
Instance version.


setFormat

public void setFormat(java.lang.String pFormat)
Set the format for this instance. If null or blank FORMAT_DEFAULT is used.


set_i

public static void set_i(java.lang.String pNewI)

Set the global (static) symbol used to represent the imaginary number 'i'. The default is 'i' but this method allows it to be changed to accommodate formatting applications that have a specific symbol or character sequence for it. Setting null or blank resets the default.

NOTE: Setting this value affects formatting only! The reParse(), toString() and toXML() methods always use 'i'.

Parameters:
pNewI - The new 'i' symbol.

setNew_i

public void setNew_i(java.lang.String pNewI)
Instance flavored 'set_i'.


iPow

public static MComplex iPow(int pExp)
Raise 'i' to a power. If pExp is negative it is computed by rationalizing the reciprocal of 'i' to that power.


i_Pow

public MComplex i_Pow(int pExp)
Instance method to raise 'i' to a power.


iKaPow

public static java.lang.String iKaPow(int pExp)
Deprecated. Use kaPow instead.


kaPow

public static java.lang.String kaPow(int pExp)
This is an extreme laziness method. It returns iPow(pExp).format(FORMAT_TYPICAL) because that can be a pain to type.


i_KaPow

public java.lang.String i_KaPow(int pExp)
Deprecated. Use ka_Pow instead.


ka_Pow

public java.lang.String ka_Pow(int pExp)
Extremely lazy instance Ka-POW.


real

public int real()
Return the real part of this complex number.


imag

public int imag()
Return the imaginary part of this number.


isReal

public boolean isReal()
Return true if the imaginary part of this number is zero and the real part isn't.


isImaginary

public boolean isImaginary()
Return true if the real part of this number is zero and the imaginary part is not..


isComplex

public boolean isComplex()
Return true if both parts of this number are nonzero.


isZero

public boolean isZero()
Return true if both parts of this number are zero.


abs

public double abs()
Calculate the absolute value (magnitude) of this number.


equals

public boolean equals(MComplex pRHS)
Return true if the real and imaginary parts of this and 'pRHS' are equal. Returns false if 'pRHS' is null.


isConjugate

public boolean isConjugate(MComplex pRHS)
Return true if 'pRHS' is the complex conjugate of this number. Returns false if 'pRHS' is null.


add

public MComplex add(MComplex pRHS)
Add this to another complex number. Neither is changed, a new instance is returned. If 'pRHS' is null this is returned.


subtract

public MComplex subtract(MComplex pRHS)
Subtract another complex number from this one. If 'pRHS' is null nothing happens and this is returned.


multiply

public MComplex multiply(MComplex pRHS)
Multiply this by another complex number. Neither is changed, if 'pRHS' is null this is returned.


multiply

public MComplex multiply(int pVal)
Multiply this number by a scalar (int) constant. A new MComplex is created.


conjugate

public MComplex conjugate()
Form the complex conjugate of this number: A + Bi becomes A - Bi.


format

public java.lang.String format(java.lang.String pTemplat)

Format this MComplex number per the template supplied. The following replacement tokens are defined:

If the template is null or blank it is returned.

Parameters:
pTemplat - A Question.fillTemplate()-style formatting String.
Returns:
The supplied String template, filled using the defined tokens.

format

public java.lang.String format()
Format this number per the internal format.


divide

public java.lang.String divide(MComplex pDivisor,
                               java.lang.String pPlus,
                               java.lang.String pImag)

This is a formatting method. Since division might result in a non-integer number this method returns a String consisting of one or two typewriter-style fractions along with some embellishments. The 'pPlus' argument is for the sign (or whatever) between the two parts. the 'pImag' argument is the symbol used for 'i'. If numerical manipulation is still required each part can be parsed into a MFraction; simply use the default values.

The division itself is accomplished by multiplying this MComplex by the conjugate of the divisor. Each part is then expressed as a simple fraction of the product part over the (real-only!) product of the divisor and its conjugate.

If the divisor is null or zero an error String is returned.

Parameters:
pDivisor - The MComplex to divide this one by.
pPlus - The separator between the two parts. Defaults to a single space.
pImag - The 'i' symbol. Defaults to blank.

toString

public java.lang.String toString()
Return a constructor-like representation of this complex number.

Overrides:
toString in class java.lang.Object

toXML

public java.lang.String toXML(java.lang.String pID)
Create a simplified (MathTools) XML representation of this complex number. The 'data' attribute contains a simple String representation and the 'pID' argument, if present, is for an optional 'id' attribute. All of this is within an empty 'MComplex' tag.


copyOf

public MComplex copyOf()
Return a copy of this complex number.