All Packages  This Package  Class Hierarchy  Class Search  Index

Class aima.util.DottedPair

java.lang.Object
   |
   +----aima.util.DottedPair

The DottedPair class provides an implementation of LISP-like cons cells.

Potential BUG: Concurrency issues have not yet been addressed. While we could synchronize on individual DottedPairs, one advantage of having a DottedPair type is that multiple lists can easily and cheaply share substructures: synchronizing on an individual DottedPair will not address concurrency issues between two lists that share substructure.

See Also: aima.utilities.Expression

public class  DottedPair
     extends java.lang.Object
{
          // Constructors 1
     public DottedPair(Object, Object);

          // Methods 25
     public DottedPair append(DottedPair);
     public DottedPair assoc(Object);
     public final Object car();
     public final Object cdr();
     public DottedPair copySeq();
     public Object elt(int) throws ClassCastException, RuntimeException;
     public boolean eql(Object);
     public boolean equals(Object);
     public final Object first();
     public static final DottedPair getNull();
     public final boolean isAtomic();
     public final boolean isCompound();
     public final boolean isNull();
     public final boolean isTrueCompound();
     public int length() throws ClassCastException;
     public static void main(String[]);
     public DottedPair member(Object) throws ClassCastException;
     public DottedPair nreverse() throws ClassCastException;
     public DottedPair nthcdr(int) throws ClassCastException, RuntimeException;
     public final Object rest();
     public DottedPair reuse(Object, Object);
     public DottedPair reverse() throws ClassCastException;
     public DottedPair subseq(int);
     public DottedPair subseq(int, int) throws ClassCastException, RuntimeException;
     public String toString();
}

• DottedPair

   public DottedPair(Object car, 
                     Object cdr) 

Creates a new DottedPair.

Comment: Maybe one day we'll make this whole class protected or private to force people to use the Expression(car,cdr) constructor to create DottedPairs.

Parameter	Description
car	the Object to go to the left of the "dot"
cdr	the Object to go to the right of the "dot"

See Also: aima.utilities.Expression

• reuse

   public DottedPair reuse(Object car, 
                           Object cdr) 

Possibly create a new DottedPair which contains the passed parameters, or return this object if it actually contains the passed parameters.

Parameter	Description
car	the Object to go to the left of the "dot"
cdr	the Object to go to the right of the "dot"

Returns:

This object if it already has the given contents, or a new DottedPair containing the given contents.

See Also: aima.utilities.Expression

• getNull

   public static final DottedPair getNull() 

Returns the unique object used to represent the empty list (and which is used to terminate DottedPairs that are true lists). Analogous to NIL in LISP.

Returns:

the unique Null object.

• car

   public final Object car() 

Returns the Object to the left of the "dot".

Returns:

the Object to the left of the "dot".

See Also: aima.utilities.Expression

• first

   public final Object first() 

Returns the Object to the left of the "dot". An alias for car, used when manipulating true lists, to find the value of the first element of the list.

Returns:

the Object to the left of the "dot".

See Also: car, aima.utilities.Expression

• cdr

   public final Object cdr() 

Returns the Object to the right of the "dot".

Returns:

the Object to the right of the "dot".

See Also: aima.utilities.Expression

• rest

   public final Object rest() 

Returns the Object to the right of the "dot". An alias for cdr, used when manipulating true lists, to return the sub-list representing the rest of the list appearing after the first element.

Returns:

the Object to the right of the "dot".

See Also: cdr, aima.utilities.Expression

• nthcdr

   public DottedPair nthcdr(int n)  throws ClassCastException, RuntimeException

Returns the result of applying the cdr method the specified number of times.

Parameter	Description
n	the number of times to take the cdr.

Returns:

The result of applying the cdr method cdr times.

Throws: ClassCastException

Possibly thrown at runtime if this is not a true list (ends in a non-Null atomic Object).

Throws: RuntimeException

Possibly thrown at runtime if given number of times is negative.

See Also: cdr, getNull

• elt

   public Object elt(int index)  throws ClassCastException, RuntimeException

Returns the Object found at the given (0-based) index of this list.

Parameter	Description
index	the (0-based) position at which to select.

Returns:

the Object found at the given index.

Throws: ClassCastException

Possibly thrown at runtime if this is not a true list (ends in a non-Null atomic Object).

Throws: RuntimeException

Thrown if attempting to access beyond the end of the list, or if given index is negative.

See Also: nthcdr, elt

• subseq

   public DottedPair subseq(int start, 
                            int end)  throws ClassCastException, RuntimeException

Returns a top level copy of the subset of this list indicated by the two (0-based) indices.

Parameter	Description
start	the (0-based) start index
end	the (0-based) end index

Returns:

a top level copy of the indicated subset of the list.

Throws: ClassCastException

Possibly thrown at runtime if this is not a true list (ends in a non-Null atomic Object).

Throws: RuntimeException

Thrown if given indices are beyond the bounds of the list.

See Also: subseq

• subseq

   public DottedPair subseq(int start) 

Returns a top level copy of the suffix of this list starting at the indicated (0-based) index.

Parameter	Description
start	the (0-based) start index

Returns:

a top level copy of the indicated suffix of the list.

Throws: ClassCastException

Possibly thrown at runtime if this is not a true list (ends in a non-Null atomic Object).

Throws: RuntimeException

Thrown if given index is beyond the bounds of the list.

See Also: subseq

• copySeq

   public DottedPair copySeq() 

Returns a top level copy of this list.

Returns:

a top level copy of this list.

Throws: ClassCastException

Possibly thrown at runtime if this is not a true list (ends in a non-Null atomic Object).

See Also: copySeq

• isNull

   public final boolean isNull() 

Indicates if this is the special Null object. Analogous to the null predicate in LISP.

Returns:

true iff this is the special Null object.

• isAtomic

   public final boolean isAtomic() 

Indicates if this is an atomic object. Analogous to the atom predicate in LISP. Since we are dealing with DottedPairs, the only way that this method could return true would be if this object is the special Null object (which, like in LISP, has been given the dual properties of a compound and an atomic object).

Returns:

true iff this object is Atomic.

See Also: aima.utilities.Expression

• isTrueCompound

   public final boolean isTrueCompound() 

Indicates if this is a true compound object. Analogous to the consp predicate in LISP. Since we are dealing with DottedPairs, the only way that this method could return false would be if this object is the special Null object (which, like in LISP, has been given the dual properties of a compound and an atomic object).

Returns:

true iff this object is a non-NULL DottedPair.

See Also: aima.utilities.Expression

• isCompound

   public final boolean isCompound() 

Indicates if this is a compound object. Analogous to the listp predicate in LISP. Since we are dealing with DottedPairs, the method must always return true.

Returns:

true iff this object is a DottedPair (which it is!)

See Also: aima.utilities.Expression

• eql

   public boolean eql(Object obj) 

Indicates if this is equal to the passed object in the LISP eql sense. Since we are dealing with DottedPairs, this method only return true if this is equal to the passed object in the JAVA == sense.

Parameter	Description
obj	the Object with which to compare.

Returns:

true iff this is identical to obj

See Also: aima.utilities.Expression

• equals

   public boolean equals(Object obj) 

Indicates if this is equal to the passed object in the LISP equal sense. This means that, recursively, all sub-components of this object must equal the corresponding subcomponents of the passed object, but, unlike with eql, the objects and their subcomponents need not be identical in the JAVA == sense.

Parameter	Description
obj	the Object with which to compare.

Returns:

true iff this "looks" equal to obj, without necessarily being the identical object.

Overrides:

equals in class Object

See Also: aima.utilities.Expression, eql

• append

   public DottedPair append(DottedPair appendee) 

Returns a new list that is the result of appending the given list to a copy (top level only) of this list.

Note: As in LISP, the result contains a reference to the argument passed (the passed argument is not itself copied).

Parameter	Description
appendee	the list to be appended.

Returns:

The appended result.

• assoc

   public DottedPair assoc(Object target) 

Finds and returns the association pair whose first element is eql to the given target, or the special Null object if the target is not found.

Note: Should one day implement a version of this code that takes an arbitrary predicate, rather than assuming eql. Similarly, should possibly take a function that directs the search to more than just the first element of each pair.

Parameter	Description
target	the Object for which to search.

Returns:

The pair whose first element is eql to the given target, or the special Null object if no matching element is found.

See Also: eql

• member

   public DottedPair member(Object target)  throws ClassCastException

Finds and returns the sublist of this list whose first element is eql to the given target, or the special Null object if the target is not found.

Note: Should one day implement a version of this code that takes an arbitrary predicate, rather than assuming eql.

Parameter	Description
target	the Object for which to search.

Returns:

The sublist whose first element is eql to the given target, or the special Null object if no matching element is found.

See Also: eql

• length

   public int length()  throws ClassCastException

Returns the number of top-level elements of this list.

Returns:

The number of top-level elements of this list.

Throws: ClassCastException

Thrown at runtime if this is not a true list (ends in a non-Null atomic Object).

• reverse

   public DottedPair reverse()  throws ClassCastException

Reverses this list (non-destructively).

Returns:

the reversed list.

Throws: ClassCastException

Possibly thrown at runtime if this is not a true list (ends in a non-Null atomic Object).

See Also: reverse

• nreverse

   public DottedPair nreverse()  throws ClassCastException

Destructively reverses this list.

Returns:

the first DottedPair element of the reversed list.

Throws: ClassCastException

Possibly thrown at runtime if this is not a true list (ends in a non-Null atomic Object).

See Also: nreverse

• toString

   public String toString() 

Created a LISP-like pretty String representation of this object. The return value is pretty in the sense that the DottedPair:

    DottedPair dp = new DottedPair("x",
                                   new DottedPair("y",
                                                   getNull()));
 

which equals "(x . (y . ()))" will be formatted by toString as "(x y)"

Returns:

A pretty string representation of this DottedPair.

Overrides:

toString in class Object

• main

   public static void main(String[] args) 

Tests out the functionality of this class.

Parameter	Description
args	Ignored.

All Packages  This Package  Class Hierarchy  Class Search  Index