com.cycling74.max
Class Atom

java.lang.Object
  com.cycling74.max.Atom

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable

public abstract class Atom
extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable

An element of a list or argument of a message. May contain an int, a float, or a String.

See Also:

Serialized Form

Field Summary

static Atom[]

emptyArray A zero-length Atom array.

Method Summary

int	compareTo(java.lang.Object o) Determines if Object o is "bigger than" this Atom.
abstract boolean	equals(java.lang.Object o) Indicates whether some other object is "equal to" this one.
float	getFloat() Return the float contents of this Atom.
int	getInt() Return the integer contents of this Atom.
java.lang.String	getString() Return the String contents of this Atom.
abstract int	hashCode() Returns a hash code for this Atom.
static Atom[]	intersection(Atom[] a, Atom[] b) Returns the intersection of two Atom arrays.
boolean	isFloat() Does this Atom represent a float?
static int	isIn(Atom item, Atom[] atoms) Is item in array atoms?
static int	isIn(Atom item, Atom[] atoms, int highIdx, int lowIdx) Is item in array atoms between indices highIdx and lowIdx?
boolean	isInt() Does this Atom represent an integer?
boolean	isString() Does this Atom represent a String?
static Atom	newAtom(boolean value) Create and return an Atom containing a int that is either 1 or 0 depending on the value of the argument.
static Atom[]	newAtom(boolean[] array) Create and return an Atom array which represents the array of booleans.
static Atom	newAtom(byte value) Create and return an Atom containing an int.
static Atom[]	newAtom(byte[] array) Create and return an Atom array which represents the array of bytes.
static Atom	newAtom(char value) Create and return an Atom containing a String made up of a single character.
static Atom[]	newAtom(char[] array) Create and return an Atom array which represents the array of chars as Strings.
static Atom	newAtom(double value) Create and return an Atom containing a float.
static Atom[]	newAtom(double[] array) Create and return an Atom array which represents the array of doubles.
static Atom	newAtom(float value) Create and return an Atom containing a float.
static Atom[]	newAtom(float[] array) Create and return an Atom array which represents the array of floats.
static Atom	newAtom(int value) Create and return an Atom containing an int.
static Atom[]	newAtom(int[] array) Create and return an Atom array which represents the array of ints.
static Atom	newAtom(long value) Create and return an Atom containing an int.
static Atom[]	newAtom(long[] array) Create and return an Atom array which represents the array of longs.
static Atom	newAtom(short value) Create and return an Atom containing an int.
static Atom[]	newAtom(short[] array) Create and return an Atom array which represents the array of shorts.
static Atom	newAtom(java.lang.String value) Create and return an Atom containing a String.
static Atom[]	newAtom(java.lang.String[] array) Create and return an Atom array which represents the array of Strings.
static Atom[]	newAtom(java.lang.String s, Atom[] args) Create and return an Atom array with the String represented in the first Atom and the args array after.
static Atom[]	parse(java.lang.String str) Parse a String as a sequence of tokens and return an Atom array.
static Atom[]	parse(java.lang.String str, boolean skipFirst) Parse a String as a sequence of tokens and return an Atom array.
static Atom[]	removeFirst(Atom[] atoms) Removes the first element of an Atom array and returns the result.
static Atom[]	removeFirst(Atom[] atoms, int howMany) Removes the first howMany elements of an Atom array and returns the result.
static Atom[]	removeLast(Atom[] atoms) Removes the last element of an Atom array and returns the result.
static Atom[]	removeLast(Atom[] atoms, int howMany) Removes the last howMany elements of an Atom array and returns the result.
static Atom[]	removeOne(Atom[] atoms, int index) Removes one element of an Atom array and returns the result.
static Atom[]	removeSome(Atom[] atoms, int first, int last) Removes some elements of an Atom array and returns the result.
static Atom[]	reverse(Atom[] atoms) Reverses the elements of an Atom array and returns the result.
static Atom[]	rotate(Atom[] atoms, int numberOfPlaces) Rotates the elements of an Atom array by numberOfPlaces and returns the result.
boolean	toBoolean() Convert an Atom to a boolean, following the Atom type coercion rules if necessary.
static boolean[]	toBoolean(Atom[] array) Convert an Atom array to a boolean array, following the Atom type coercion rules if necessary.
byte	toByte() Converts an Atom to a byte, following the Atom type coercion rules if necessary.
static byte[]	toByte(Atom[] array) Converts an Atom array to a byte array, following the Atom type coercion rules if necessary.
char	toChar() Convert an Atom to a char, following the Atom type coercion rules if necessary.
static char[]	toChar(Atom[] array) Convert an Atom array to a char array, following the Atom type coercion rules if necessary.
static java.lang.String	toDebugString(Atom[] array) Converts an Atom array to a printed representation suitable for debugging.
double	toDouble() Convert an Atom to a double, following the Atom type coercion rules if necessary.
static double[]	toDouble(Atom[] array) Convert an Atom array to a double array, following the Atom type coercion rules if necessary.
float	toFloat() Convert an Atom to a float, following the Atom type coercion rules if necessary.
static float[]	toFloat(Atom[] array) Convert an Atom array to a float array, following the Atom type coercion rules if necessary.
int	toInt() Convert an Atom to an int, following the Atom type coercion rules if necessary.
static int[]	toInt(Atom[] array) Convert an Atom array to an int array, following the Atom type coercion rules if necessary.
long	toLong() Convert an Atom to a long, following the Atom type coercion rules if necessary.
static long[]	toLong(Atom[] array) Convert an Atom array to a long array, following the Atom type coercion rules if necessary.
abstract java.lang.Object	toObject() Return the contents of this Atom as a Java object.
static java.lang.String	toOneString(Atom[] array) Convert an Atom array to a single String.
short	toShort() Converts an Atom to a short, following the Atom type coercion rules if necessary.
static short[]	toShort(Atom[] array) Converts an Atom array to a short array, following the Atom type coercion rules if necessary.
static java.lang.String[]	toString(Atom[] array) Convert an Atom array to an array of Strings.
static Atom[]	union(Atom[] a, Atom[] b) Returns the union of two Atom arrays.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

emptyArray

public static final Atom[] emptyArray

A zero-length Atom array. This can come in handy. Instead of generating a new one, it's faster to use this one.

Method Detail

newAtom

public static Atom newAtom(byte value)

Create and return an Atom containing an int.

Parameters:

value - the byte value to represent in the Atom

Returns:

an int Atom

newAtom

public static Atom newAtom(short value)

Create and return an Atom containing an int.

Parameters:

value - the short value to represent in the Atom

Returns:

an int Atom

newAtom

public static Atom newAtom(int value)

Create and return an Atom containing an int.

Parameters:

value - the int value to represent in the Atom

Returns:

an int Atom

newAtom

public static Atom newAtom(long value)

Create and return an Atom containing an int. Be careful: if the input long is bigger than Integer.MAX_VALUE the cast from long to int will overflow.

Parameters:

value - the long value to represent in the Atom

Returns:

an int Atom

newAtom

public static Atom newAtom(float value)

Create and return an Atom containing a float.

Parameters:

value - the float value to represent in the Atom

Returns:

a float Atom

newAtom

public static Atom newAtom(double value)

Create and return an Atom containing a float. Be careful:the reduction in numerical precision when casting from double to float can result in a loss of information and/or overflow.

Parameters:

value - the double value to represent in the Atom

Returns:

a float Atom

newAtom

public static Atom newAtom(char value)

Create and return an Atom containing a String made up of a single character.

Parameters:

value - the character to represent in the Atom

Returns:

a String Atom

newAtom

public static Atom newAtom(java.lang.String value)

Create and return an Atom containing a String.

Parameters:

value - the String to represent in the Atom

Returns:

a String Atom

newAtom

public static Atom newAtom(boolean value)

Create and return an Atom containing a int that is either 1 or 0 depending on the value of the argument.

Parameters:

value - the boolean to represent in the Atom

Returns:

an int Atom whose value is either 0 or 1

newAtom

public static Atom[] newAtom(byte[] array)

Create and return an Atom array which represents the array of bytes.

Parameters:

array - the byte array to represent in the Atoms

Returns:

an integer Atom array

newAtom

public static Atom[] newAtom(short[] array)

Create and return an Atom array which represents the array of shorts.

Parameters:

array - the short array to represent in the Atoms

Returns:

an integer Atom array

newAtom

public static Atom[] newAtom(int[] array)

Create and return an Atom array which represents the array of ints.

Parameters:

array - the int array to represent in the Atoms

Returns:

an integer Atom array

newAtom

public static Atom[] newAtom(long[] array)

Create and return an Atom array which represents the array of longs. Be careful: if an input long is bigger than Integer.MAX_VALUE the cast from long to int will overflow.

Parameters:

array - the long array to represent in the Atoms

Returns:

an integer Atom array

newAtom

public static Atom[] newAtom(float[] array)

Create and return an Atom array which represents the array of floats.

Parameters:

array - the float array to represent in the Atoms

Returns:

a float Atom array

newAtom

public static Atom[] newAtom(double[] array)

Create and return an Atom array which represents the array of doubles. Be careful:the reduction in numerical precision when casting from double to float can result in a loss of information and/or overflow.

Parameters:

array - the double array to represent in the Atoms

Returns:

a float Atom array

newAtom

public static Atom[] newAtom(char[] array)

Create and return an Atom array which represents the array of chars as Strings.

Parameters:

array - the character array to represent in the Atoms

Returns:

a String Atom array

newAtom

public static Atom[] newAtom(java.lang.String[] array)

Create and return an Atom array which represents the array of Strings.

Parameters:

array - the String array to represent in the Atoms

Returns:

a String Atom array

newAtom

public static Atom[] newAtom(java.lang.String s,
                             Atom[] args)

Create and return an Atom array with the String represented in the first Atom and the args array after. Useful for forwarding an anything message to a method like list that takes an Atom array.

Parameters:

s - the first element of the Atom array

args - all the other elements of the Atom array

Returns:

an Atom array

newAtom

public static Atom[] newAtom(boolean[] array)

Create and return an Atom array which represents the array of booleans.

Parameters:

array - the boolean array to represent in the Atoms

Returns:

an int Atom array

isInt

public boolean isInt()

Does this Atom represent an integer?

Returns:

true if this contains an integer value (int)

isFloat

public boolean isFloat()

Does this Atom represent a float?

Returns:

true if this contains a float

isString

public boolean isString()

Does this Atom represent a String?

Returns:

true if this contains a String

getFloat

public float getFloat()

Return the float contents of this Atom.

Returns:

the float value represented in the Atom

Throws:

java.lang.UnsupportedOperationException - if the Atom does not represent a float.

getInt

public int getInt()

Return the integer contents of this Atom.

Returns:

the int value represented in the Atom.

Throws:

java.lang.UnsupportedOperationException - if the Atom does not represent an int.

getString

public java.lang.String getString()

Return the String contents of this Atom.

Returns:

the String value represented in the Atom.

Throws:

java.lang.UnsupportedOperationException - if this Atom does not represent a String.

toObject

public abstract java.lang.Object toObject()

Return the contents of this Atom as a Java object. If it contains an int, return an Integer object; if it contains a float, return a Float object; and if it contains a String, return a String.

Returns:

the contents of the Atom as an Object.

equals

public abstract boolean equals(java.lang.Object o)

Indicates whether some other object is "equal to" this one.

Overrides:

equals in class java.lang.Object

Parameters:

o - the other Object to test for equivalence

Returns:

true if and only if the other Object is an Atom of the same content type (float, int, or String) with equal contents.

hashCode

public abstract int hashCode()

Returns a hash code for this Atom. For an Atom that represents an int, the value returned is the int value itself. For an Atom that represents a float the result is the integer bit representation produced by the Float.floatToIntBits(float) method. For an Atom that represents a String the result is the integer bit representation produced by the String.hashCode() method.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code value for this object, calculated using an algorithm appropriate to the Atom's content type.

reverse

public static Atom[] reverse(Atom[] atoms)

Reverses the elements of an Atom array and returns the result.

Parameters:

atoms - the array of Atoms to operate on

Returns:

a reversed copy of the atoms parameter

rotate

public static Atom[] rotate(Atom[] atoms,
                            int numberOfPlaces)

Rotates the elements of an Atom array by numberOfPlaces and returns the result.

Parameters:

atoms - the array of Atoms to operate on

numberOfPlaces - the number of places to rotate the array by (can be negative)

Returns:

a rotated copy of the atoms parameter

intersection

public static Atom[] intersection(Atom[] a,
                                  Atom[] b)

Returns the intersection of two Atom arrays.

Parameters:

a - an array of Atoms to operate on

b - another array of Atoms to operate on

Returns:

an array that contains the intersection of a and b

union

public static Atom[] union(Atom[] a,
                           Atom[] b)

Returns the union of two Atom arrays.

Parameters:

a - an array of Atoms to operate on

b - another array of Atoms to operate on

Returns:

an array that contains the union of a and b

isIn

public static int isIn(Atom item,
                       Atom[] atoms)

Is item in array atoms?

Parameters:

item - the Atom to search for

atoms - the array of Atoms to search

Returns:

an integer that represents the position of the found item, or -1 if the item was not found

isIn

public static int isIn(Atom item,
                       Atom[] atoms,
                       int highIdx,
                       int lowIdx)

Is item in array atoms between indices highIdx and lowIdx?

Parameters:

item - the Atom to search for

atoms - the array of Atoms to search

highIdx - the highest index of the array to check

lowIdx - the lowest index of the array to check

Returns:

an integer that represents the position of the found item, or -1 if the item was not found

removeOne

public static Atom[] removeOne(Atom[] atoms,
                               int index)

Removes one element of an Atom array and returns the result. If atoms has length of zero, returns it unchanged.

Parameters:

atoms - the array of Atoms to operate on

index - the index of the element to remove

Returns:

a copy of the atoms parameter, with the index element removed

removeSome

public static Atom[] removeSome(Atom[] atoms,
                                int first,
                                int last)

Removes some elements of an Atom array and returns the result. If atoms has length of zero, returns it unchanged.

Parameters:

atoms - the array of Atoms to operate on

first - the index of the first element of the range to remove

last - the index of the last element of the range to remove

Returns:

a copy of the atoms parameter, with all elements between first and last (inclusive) removed

removeFirst

public static Atom[] removeFirst(Atom[] atoms)

Removes the first element of an Atom array and returns the result. If atoms has length of zero, returns it unchanged. If atoms has a length of one, returns the emptyArray.

Parameters:

atoms - the array of Atoms to operate on

Returns:

a copy of the atoms parameter, one element removed from the left

removeFirst

public static Atom[] removeFirst(Atom[] atoms,
                                 int howMany)

Removes the first howMany elements of an Atom array and returns the result. If atoms has length of zero, returns it unchanged. If atoms has length of howMany, returns the emptyArray.

Parameters:

atoms - the Atom array to operate on

howMany - the number of elements to remove

Returns:

a copy of the atoms parameter, howMany elements removed from the left

Throws:

java.lang.IllegalArgumentException - If howMany is a negative amount or more than the array's length.

removeLast

public static Atom[] removeLast(Atom[] atoms)

Removes the last element of an Atom array and returns the result. If atoms has length of zero, returns it unchanged. If atoms has a length of one, returns the emptyArray.

Parameters:

atoms - the array of Atoms to operate on

Returns:

a copy of the atoms parameter, one element removed from the left

removeLast

public static Atom[] removeLast(Atom[] atoms,
                                int howMany)

Removes the last howMany elements of an Atom array and returns the result. If atoms has length of zero, returns it unchanged. If atoms has length of howMany, returns the emptyArray.

Parameters:

atoms - the Atom array to operate on

howMany - the number of elements to remove

Returns:

a copy of the atoms parameter, howMany elements removed from the left

Throws:

java.lang.IllegalArgumentException - If howMany is a negative amount or more than the array's length.

toOneString

public static java.lang.String toOneString(Atom[] array)

Convert an Atom array to a single String. The resulting String contains the result of calling toString on all of the Atoms in the array, separated by a space character.

Parameters:

array - the Atom array to convert to one String.

Returns:

a String containing representations of all of the Atoms in the array

toString

public static java.lang.String[] toString(Atom[] array)

Convert an Atom array to an array of Strings.

Parameters:

array - the Atom array to convert to a String array.

Returns:

a String array containing representations of all of the Atoms in the array

toByte

public byte toByte()

Converts an Atom to a byte, following the Atom type coercion rules if necessary. If the Atom represents a float, its fractional portion will be truncated, then the resulting int will be cast to a byte. If the Atom represents a String, 0 will be returned.

Returns:

a byte that represents the value of the Atom

toByte

public static byte[] toByte(Atom[] array)

Converts an Atom array to a byte array, following the Atom type coercion rules if necessary. If the Atom represents a float, its fractional portion will be truncated and the resulting int cast to a byte. If the Atom represents a String, 0 will be returned.

Parameters:

array - the Atom array to convert to a byte array.

Returns:

an int array that represents the values of the Atom array, coerced to the integer type if necessary

toShort

public short toShort()

Converts an Atom to a short, following the Atom type coercion rules if necessary. If the Atom represents a float, its fractional portion will be truncated, then the resulting int will be cast to a short. If the Atom represents a String, 0 will be returned.

Returns:

a short that represents the value of the Atom

toShort

public static short[] toShort(Atom[] array)

Converts an Atom array to a short array, following the Atom type coercion rules if necessary. If the Atom represents a float, its fractional portion will be truncated and the resulting int cast to a short. If the Atom represents a String, 0 will be returned.

Parameters:

array - the Atom array to convert to a short array.

Returns:

a short array that represents the values of the Atom array

toInt

public int toInt()

Convert an Atom to an int, following the Atom type coercion rules if necessary. If the Atom represents a float, its fractional portion will be truncated. If the Atom represents a String, 0 will be returned.

Returns:

an int that represents the value of the Atom, coerced to the integer type if necessary

toInt

public static int[] toInt(Atom[] array)

Convert an Atom array to an int array, following the Atom type coercion rules if necessary. If the Atom represents a float, its fractional portion will be truncated. If the Atom represents a String, 0 will be returned.

Parameters:

array - the Atom array to convert to an int array.

Returns:

an int array that represents the values of the Atom array, coerced to the integer type if necessary

toLong

public long toLong()

Convert an Atom to a long, following the Atom type coercion rules if necessary. If the Atom represents a float, its fractional portion will be truncated. If the Atom represents a String, 0 will be returned.

Returns:

a long that represents the value of the Atom, coerced to the long type if necessary

toLong

public static long[] toLong(Atom[] array)

Convert an Atom array to a long array, following the Atom type coercion rules if necessary. If the Atom represents a float, its fractional portion will be truncated. If the Atom represents a String, 0 will be returned.

Parameters:

array - the Atom array to convert to a long array.

Returns:

a long array that represents the values of the Atom array

toFloat

public float toFloat()

Convert an Atom to a float, following the Atom type coercion rules if necessary. If the Atom represents an int, it is converted to a float. If the Atom represents a String, 0.0f will be returned.

Returns:

a float that represents the value of the Atom, coerced to the float type if necessary

toFloat

public static float[] toFloat(Atom[] array)

Convert an Atom array to a float array, following the Atom type coercion rules if necessary. If the Atom represents an int, it is converted to a float. If the Atom represents a String, 0.0f will be returned.

Parameters:

array - the Atom array to convert to a float array.

Returns:

a float array that represents the values of the Atom array, coerced to the float type if necessary

toDouble

public double toDouble()

Convert an Atom to a double, following the Atom type coercion rules if necessary. If the Atom represents an int, it is converted to a double. If the Atom represents a String, 0.0 will be returned.

Returns:

a double that represents the value of the Atom, coerced to the double type if necessary

toDouble

public static double[] toDouble(Atom[] array)

Convert an Atom array to a double array, following the Atom type coercion rules if necessary. If the Atom represents an int, it is converted to a double. If the Atom represents a String, 0.0 will be returned.

Parameters:

array - the Atom array to convert to a double array.

Returns:

a double array that represents the values of the Atom array, coerced to the double type if necessary

toChar

public char toChar()

Convert an Atom to a char, following the Atom type coercion rules if necessary. If the Atom represents an int or a float, it is cast to a char. If the Atom represents a String, its first character is returned.

Returns:

a char that represents the value of the Atom

toChar

public static char[] toChar(Atom[] array)

Convert an Atom array to a char array, following the Atom type coercion rules if necessary. If the Atom represents an int or a float, it is cast to a char. If the Atom represents a String, its first character is returned.

Parameters:

array - the Atom array to convert to a char array

Returns:

a char array that represents the values of the Atom array

toBoolean

public boolean toBoolean()

Convert an Atom to a boolean, following the Atom type coercion rules if necessary. If the Atom represents an int, true is returned for all non-zero values. If the Atom represents a float, true is returned for all non-zero values. If the Atom represents a String, true is returned for all values that aren't "false".

Returns:

a boolean that represents the value of the Atom

toBoolean

public static boolean[] toBoolean(Atom[] array)

Convert an Atom array to a boolean array, following the Atom type coercion rules if necessary. If the Atom represents an int, true is returned for all non-zero values. If the Atom represents a float, true is returned for all non-zero values. If the Atom represents a String, true is returned for all values that aren't "false".

Parameters:

array - the Atom array to convert to a boolean array.

Returns:

a boolean array that represents the values of the Atom array

parse

public static Atom[] parse(java.lang.String str)

Parse a String as a sequence of tokens and return an Atom array.

Parameters:

str - the String to parse

Returns:

an Atom array corresponding to the tokens in the String

parse

public static Atom[] parse(java.lang.String str,
                           boolean skipFirst)

Parse a String as a sequence of tokens and return an Atom array. If skipFirst is true, do not include the first Atom in the result.

Parameters:

str - the String to parse

skipFirst - whether to include the first Atom in the result

Returns:

an Atom array corresponding to the tokens in the String

toDebugString

public static java.lang.String toDebugString(Atom[] array)

Converts an Atom array to a printed representation suitable for debugging. So if givena three-element Atom array containing the int 1, the float 3.14 and the String "test" as input, the output would be Atom[3]={1:I}{3.14:F}{test:S}.

Parameters:

array - an array of Atom objects

Returns:

a verbose String describing the elements of array

compareTo

public int compareTo(java.lang.Object o)

Determines if Object o is "bigger than" this Atom. Atoms that represent Strings are defined to be less than ints and floats - that is, if you make use of the Arrays.sort(Object[]) method, Strings will be sorted first. Comparisons between Atoms that represent floats and ints give the results you would expect.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

o - the Object to compare with.

Returns:

-1 if o is bigger than the called object, 0 if they're equal, and 1 if o is smaller

Throws:

java.lang.NullPointerException - if the input is null

java.lang.ClassCastException - if something other than an Atom is passed in as an argument