net.cscott.sdr.calls
Class Rotation

java.lang.Object
  net.cscott.sdr.calls.Rotation

Direct Known Subclasses:

ExactRotation

public class Rotation
extends Object

Rotations are represented as fractions, where '0' is facing north (that is, away from the caller), and '1/4' is facing east. The also have a 'modulus', since they can represent "general" directions. For example, "1/4 modulo 1/2" means facing east or west (but not north, south, or any other direction). A rotation modulo 0 matches any direction. A rotation modulo 1 indicates an 'exact' rotation; the modulus can not exceed 1.

Field Summary

Fraction	amount The amount of the rotation.
Fraction	modulus The 'modulus' of the rotation: indicates the amount of uncertainty in the direction.

Constructor Summary

protected

Rotation(Fraction amount, Fraction modulo) Private constructor from a Fraction object.

Method Summary

Rotation	add(Fraction f) Add the given amount to this rotation direction.
static Rotation	create(Fraction amount, Fraction modulo)
boolean	equals(Object o) Rotations are equal iff their normalized rotation amount and modulus are exactly equal.
static Rotation	fromAbsoluteString(String s) Converts a string (one of n/s/e/w, ne/nw/se/sw) to the appropriate rotation object.
int	hashCode() Hashcode of the normalized amount & modulus.
Collection<ExactRotation>	included() Returns an Iterator over the ExactRotations included in this Rotation.
boolean	includes(Rotation r) Returns true iff all the rotations possible with the given r are included within the set of rotations possible with this.
boolean	isExact() Return true iff this rotation is exact (that is, if the modulus is one).
Rotation	negate() Negate this rotation (mirror image).
Rotation	normalize() Normalize rotation to the range [0, modulus).
String	repr() Return an executable representation of this Rotation.
Rotation	subtract(Fraction f) Subtract the given amount from this rotation direction.
String	toAbsoluteString() Returns a human-readable description of the rotation, similar to the input to ExactRotation.fromAbsoluteString(String).
char	toDiagramChar() Convert rotation to an appropriate ascii-art representation.
String	toString() Returns a human-readable description of the rotation.
static Rotation	union(List<Rotation> rots)
Rotation	union(Rotation r) Return a Rotation which includes all the directions represented by this and the specified Rotation.

Methods inherited from class java.lang.Object

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

Field Detail

amount

public final Fraction amount

The amount of the rotation.

modulus

public final Fraction modulus

The 'modulus' of the rotation: indicates the amount of uncertainty in the direction. The modulus cannot exceed 1.

Constructor Detail

Rotation

protected Rotation(Fraction amount,
                   Fraction modulo)

Private constructor from a Fraction object.

Method Detail

create

public static final Rotation create(Fraction amount,
                                    Fraction modulo)

isExact

public boolean isExact()

Return true iff this rotation is exact (that is, if the modulus is one).

add

public Rotation add(Fraction f)

Add the given amount to this rotation direction.

subtract

public Rotation subtract(Fraction f)

Subtract the given amount from this rotation direction.

negate

public Rotation negate()

Negate this rotation (mirror image).

normalize

public Rotation normalize()

Normalize rotation to the range [0, modulus).

equals

public boolean equals(Object o)

Rotations are equal iff their normalized rotation amount and modulus are exactly equal.

Overrides:

equals in class Object

hashCode

public int hashCode()

Hashcode of the normalized amount & modulus.

Overrides:

hashCode in class Object

includes

public boolean includes(Rotation r)

Returns true iff all the rotations possible with the given r are included within the set of rotations possible with this. For example, the Rotation 0 mod 1/4 (ie, north, east, south, or west, but no intermediate directions) includes 3/4 mod 1 (ie, exactly west), but the reverse is not true: 3/4 mod 1 includes 7/4 mod 1, but does not include 0 mod 1/4. Formally, returns true iff the congruence class of this is a superset of the congruence class of r.

Tests:

Demonstrate the properties described above:

js> importPackage(net.cscott.sdr.util)
js> r1 = Rotation.create(Fraction.ZERO, Fraction.ONE_QUARTER)
0 mod 1/4
js> r2 = Rotation.create(Fraction.THREE_QUARTERS, Fraction.ONE)
3/4
js> r3 = Rotation.create(Fraction.valueOf(7, 4), Fraction.ONE)
1 3/4
js> r1.includes(r2)
true
js> r2.includes(r1)
false
js> r2.includes(r3)
true

included

public Collection<ExactRotation> included()

Returns an Iterator over the ExactRotations included in this Rotation.

Tests:

js> r = Rotation.fromAbsoluteString('+')
0 mod 1/4
js> [x for (x in Iterator(r.included()))]
0,1/4,1/2,3/4
js> r = Rotation.fromAbsoluteString('x')
1/8 mod 1/4
js> [x for (x in Iterator(r.included()))]
1/8,3/8,5/8,7/8

union

public Rotation union(Rotation r)

Return a Rotation which includes all the directions represented by this and the specified Rotation. The operation may be inexact; that is, the result may include directions which are not included in either of the arguments.

Tests:

Exact unions:

js> ExactRotation.EAST.union(ExactRotation.WEST)
1/4 mod 1/2
js> ExactRotation.NORTH.union(ExactRotation.SOUTH)
0 mod 1/2
js> Rotation.fromAbsoluteString('|').union(
  > Rotation.fromAbsoluteString('-'))
0 mod 1/4

Inexact unions:

js> importPackage(net.cscott.sdr.util) // for Fraction
js> ExactRotation.NORTH.union(ExactRotation.EAST)
0 mod 1/4
js> Rotation.fromAbsoluteString('|').union(ExactRotation.EAST)
0 mod 1/4
js> Rotation.create(Fraction.ONE_QUARTER, Fraction.ONE_HALF).union(
  >                 ExactRotation.SOUTH)
0 mod 1/4
js> Rotation.create(Fraction.ZERO, Fraction.ONE_HALF).union(
  > Rotation.create(Fraction.ZERO, Fraction.ONE_THIRD))
0 mod 1/6
js> Rotation.create(Fraction.ZERO, Fraction.ONE_THIRD).union(
  >                 ExactRotation.SOUTH)
0 mod 1/6
js> Rotation.create(Fraction.ZERO, Fraction.ONE_THIRD).union(
  > Rotation.create(Fraction.ZERO, Fraction.ONE_QUARTER))
0 mod 1/12
js> Rotation.create(Fraction.ONE_EIGHTH, Fraction.ONE_QUARTER).union(
  >                 ExactRotation.SOUTH)
0 mod 1/8

union

public static Rotation union(List<Rotation> rots)

toString

public String toString()

Returns a human-readable description of the rotation. The output is a valid input to ExactRotation.valueOf(String).

Overrides:

toString in class Object

toAbsoluteString

public String toAbsoluteString()

Returns a human-readable description of the rotation, similar to the input to ExactRotation.fromAbsoluteString(String).

fromAbsoluteString

public static Rotation fromAbsoluteString(String s)

Converts a string (one of n/s/e/w, ne/nw/se/sw) to the appropriate rotation object. 'n' is facing away from the caller. The string '-' means "east or west", and the string '|' means "north or south". The string "+" means "north, south, east, or west". The string 'o' means "any rotation".

toDiagramChar

public char toDiagramChar()

Convert rotation to an appropriate ascii-art representation. (Most of the interesting directions are in ExactRotation, not Rotation.) The character '.' is used for "unrepresentable rotations".

Tests:

Show that fromAbsoluteString and toDiagramChar are inverse

js> function m(s) {
  >   return String.fromCharCode(Rotation.fromAbsoluteString(s).toDiagramChar())
  > }
js> Array.map("|-+xo", m)
|,-,+,x,o

Unrepresentable rotation:

js> importPackage(net.cscott.sdr.util)
js> r = Rotation.create(Fraction.ZERO, Fraction.ONE_THIRD)
0 mod 1/3
js> String.fromCharCode(r.toDiagramChar())
.

repr

public String repr()

Return an executable representation of this Rotation.