Class CoordinateID

  • All Implemented Interfaces:
    java.lang.Cloneable, java.lang.Comparable<java.lang.Object>, ID

    public final class CoordinateID
    extends java.lang.Object
    implements ID
    A CoordinateID uniquely identifies a location in a three dimensional space by x-, y- and z-axis components. This is an immutable object.
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  CoordinateID.Triplet
      Convenience implementation of a mutable coordinate triplet.
    • Field Detail

      • INVALID

        public static final CoordinateID INVALID
        denotes an invalid coordinate
      • ZERO

        public static final CoordinateID ZERO
        The coordinate (0,0,0).
    • Method Detail

      • getX

        public int getX()
        Returns the value of x.
        Returns:
        Returns x.
      • getY

        public int getY()
        Returns the value of y.
        Returns:
        Returns y.
      • getZ

        public int getZ()
        Returns the value of z.
        Returns:
        Returns z.
      • toTriplet

        public CoordinateID.Triplet toTriplet()
        Returns a new Triplet with identical coordinates.
      • equals

        public boolean equals​(java.lang.Object o)
        Two instances are equal if their x,y,z values are equal.
        Specified by:
        equals in interface ID
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - the reference object with which to compare.
        Returns:
        true if this object is the same as the obj argument; false otherwise.
      • toString

        public java.lang.String toString()
        Returns a String representation of this coordinate. The x, y and z components are seperated by semicolon with a blank and the z component is ommitted if it equals 0.
        Specified by:
        toString in interface ID
        Overrides:
        toString in class java.lang.Object
        Returns:
        a String representation of the ID formatted in a user friendly manner.
      • toString

        public java.lang.String toString​(java.lang.String delim)
        Returns a String representation of this CoordinateID consisting of the x, y and, if not 0, z coordinates delimited by delim.
        Specified by:
        toString in interface ID
        Returns:
        a String representation of the ID formatted in a user friendly manner.
      • toString

        public java.lang.String toString​(java.lang.String delim,
                                         boolean forceZ)
        Returns a String representation of this CoordinateID. The x, y and z components are seperated by the specified string and the z component is ommitted if it equals 0 and forceZ is false.
        Parameters:
        delim - the string to delimit the x, y and z components.
        forceZ - if true, the z component is only included if it is not 0, else the z component is always included.
      • hashCode

        public int hashCode()
        Returns a hash code value for this CoordinateID. The value depends on the x, y and z values, so be careful when modifying these values.
        Specified by:
        hashCode in interface ID
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        a hash code value for this object.
      • parse

        public static CoordinateID parse​(java.lang.String coords,
                                         java.lang.String delim)
        Creates a new CoordinateID object from a string containing the coordinates separated by delimiters. The string can contain two resp. three integers separated by one resp. two delimiters. For example, parse("12 4"," ") returns the CoordinateID (12,4,0). Leading and trailing whitespace around numbers is ignored. For instance, parse("13, 4, 1",",") returns the CoordinateID (13,4,1), but the result of parse("14 4 5", ",") is undefined.
        Parameters:
        coords - A string which presumably contains a coordinate description
        delim - The delimiters of the coordinates. See java.util.StringTokenizer
        Returns:
        The CoordinateID as read from coord; null if parsing failed
      • create

        public static CoordinateID create​(int x,
                                          int y)
        Create a CoordinateID with a z-value of 0.
      • create

        public static CoordinateID create​(int x,
                                          int y,
                                          int z)
        Creates a new CoordinateID object.
      • translate

        public CoordinateID translate​(CoordinateID c)
        Return a new CoordinateID that is this one modified by c.x on the x-axis and c.y on the y-axis and c.z on the z-axis.
        Parameters:
        c - the relative CoordinateID to translate the current one by.
        Returns:
        A new CoordinateID
      • translateInLayer

        public CoordinateID translateInLayer​(CoordinateID c)
        Return a new CoordinateID that is this one modified by c.x on the x-axis and c.y on the y-axis but has the same z-coordinate.
        Parameters:
        c - the relative CoordinateID to translate the current one by.
        Returns:
        A new CoordinateID
      • subtract

        public CoordinateID subtract​(CoordinateID c)
        Returns a new CoordinateID that is this one modified by -c.x, -c.y, -c.z.
        Parameters:
        c - the relative CoordinateID to subtract from this coordinate.
        Returns:
        A new CoordinateID
      • inverseTranslateInLayer

        public CoordinateID inverseTranslateInLayer​(CoordinateID c)
        Subtract c from this coordinate, but only the x and y coordinates.
        Returns:
        The result as a new CoordinateID
      • createDistanceCoordinate

        public CoordinateID createDistanceCoordinate​(CoordinateID to)
        Creates the distance coordinate from this coordinate to the given coordinate
      • compareTo

        public int compareTo​(java.lang.Object o)
        Defines the natural ordering of coordinates which is: Iff the z coordinates differ their difference is returned. Iff the y coordinates differ their difference is returned. Else the difference of the x coordinates is returned.
        Specified by:
        compareTo in interface java.lang.Comparable<java.lang.Object>
        Specified by:
        compareTo in interface ID
      • clone

        public CoordinateID clone()
        Returns a copy of this CoordinateID object.
        Specified by:
        clone in interface ID
        Overrides:
        clone in class java.lang.Object
      • getInvalid

        public static CoordinateID getInvalid()
        Returns a dummy coordinate that is not equal to any other CoordinateID.