Package squidpony.squidmath

Class Region

java.lang.Object
java.util.AbstractCollection<E>
java.util.AbstractList<Coord>
squidpony.squidmath.Region
All Implemented Interfaces:
Serializable, Iterable<Coord>, Collection<Coord>, List<Coord>
public class Region
extends AbstractList<Coord>
implements Serializable
NOTE: You should consider GreasedRegion before using this class, unless you know Region does exactly what you want.
Represents an area or series of areas as one logical unit, and allows iterating over or altering that unit. This can be useful for getting an iterable data structure from a FOV map, Dijkstra map, or just a map from a dungeon generator. It can also work with some shapes (circles and rectangles). Regions must be no larger than 256x256 (actually, the Coords in them should fit in that), even if Coord has had its expandPool() method called. This is because CoordPacker relies on that maximum size to significantly improve efficiency, and this is really just a convenience class wrapping CoordPacker to avoid some of its complexity. GreasedRegion allows larger maps, particularly when the Coord pool has been expanded, and should be much faster at tasks that involve changing the size or shape of an area. It also is mutable by default, without needing to track the "dirty" and "clean" states of this class. GreasedRegion does not implement the List interface, though; it does implement Iterable of Coord.
Created by Tommy Ettinger on 5/12/2016.
See Also:
You should prefer GreasedRegion for most usage., Serialized Form

  • Field Summary

    Fields 
    Modifier and Type Field Description
    protected Coord[] coords  
    protected short[] raw  

    Fields inherited from class java.util.AbstractList

    modCount

  • Constructor Summary

    Constructors 
    Constructor Description
    Region​(char[][] map, char... using)
    A constructor for a Region that takes a 2D char array, the kind produced by most map/dungeon generators in this library, and a vararg or array of char that will have their Coord positions used where those chars appear in map.
    Region​(double[][] fovMap)
    A constructor for a Region that takes a 2D double array, usually the kind produced by FOV, and stores only Coord positions that correspond to values greater than 0.0 (actually, greater than epsilon, which here is 0.0001).
    Region​(double[][] dijkstraMap, double maximum)
    A constructor for a Region that takes a 2D double array, usually produced by DijkstraMap, and a maximum value, and stores only Coord positions that correspond to values no greater than maximum.
    Region​(int minX, int minY, int width, int height)
    A constructor for a rectangular Region that stores Coords for the area from (minX,minY) at the minimum corner to (width + minX - 1, height + minY - 1) at the maximum corner.
    Region​(short[] packedData)
    A constructor for a Region that takes a specifically-formatted short array (packed data), as produced by CoordPacker or sometimes other classes, like RegionMap or RoomFinder.
    Region​(Collection<Coord> points)
    A constructor for a Region that takes a Collection of Coord, such as a List or Set, and encodes all of them in the Region.
    Region​(Coord... points)
    A constructor for a Region that takes an array or vararg of Coord and encodes all of them in the Region.
    Region​(Coord center, int circleRadius, int mapWidth, int mapHeight)
    A constructor for a circular Region (possibly truncated at the edges) with a Coord center, an int radius, and a maximum width and height that the Coords in this Region will not exceed.
    Region​(Region other)
    A constructor that copies another Region so this Region will have the same contents.

  • Method Summary

    Modifier and Type Method Description
    boolean add​(Coord coord)
    Adds a Coord to this Region, returning false if the Coord is null or already included in this, or true otherwise.
    void debugPrint​(int width, int height)
    Prints this Region to System.out as a grid of chars with the given width and height, using '.' for Coords this contains and '#' for empty space.
    Coord get​(int index)
    Gets the Coord stored at the given index in this Region, or null if index is out of bounds.
    Coord[] getCoords()
    Gets the Coords contained in this as an array, a direct reference that does permit modifying the Coords in your own code without altering "dirty/clean" status.
    Coord getRandomCoord​(IRNG rng)
    Gets a single random Coord from this using the given RNG (which can be seeded); returns null if this is empty.
    short[] getRaw()
    Gets a direct reference to this Region's "raw packed data"; don't modify it unless you know what you're doing! It's fine to pass this to methods in CoordPacker, since essentially all of those methods won't modify packed data given as arguments.
    boolean isEmpty()
    Returns true if there are no Coords in this Region, or false otherwise.
    Region randomSeparated​(int separation, IRNG rng)
    Takes this region and walks through its Coords in chunks with length equal to separation, creating a new Region where one randomly-chosen Coord in each chunk is kept and the others are discarded.
    Region separated​(int separation)
    Takes this region and walks through its Coords in chunks with length equal to separation, creating a new Region where one Coord in each chunk is kept and the others are discarded.
    void setCoords​(Coord... coords)
    Changes this Region to include the given Coords and disregard its previous contents.
    void setRaw​(short[] raw)
    Sets the "raw packed data" to the given short array, as generated by CoordPacker or some parts of RegionMap.
    int size()
    Gets the size of this Region as measured in Coords stored.
    boolean[][] toBooleanArray​(int width, int height)
    Gets a representation of this Region as a 2D boolean array with the given width and height.
    char[][] toCharArray​(int width, int height, char on, char off)
    Gets a representation of this Region as a 2D char array with the given width and height, using on to represent present Coords and off to represent absent ones.

    Methods inherited from class java.util.AbstractList

    add, addAll, clear, equals, hashCode, indexOf, iterator, lastIndexOf, listIterator, listIterator, remove, removeRange, set, subList

    Methods inherited from class java.util.AbstractCollection

    addAll, contains, containsAll, remove, removeAll, retainAll, toArray, toArray, toString

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface java.util.Collection

    parallelStream, removeIf, stream, toArray

    Methods inherited from interface java.lang.Iterable

    forEach

    Methods inherited from interface java.util.List

    addAll, contains, containsAll, remove, removeAll, replaceAll, retainAll, sort, spliterator, toArray, toArray

  • Field Details

  • Constructor Details

    • Region

      public Region​(double[][] fovMap)
      A constructor for a Region that takes a 2D double array, usually the kind produced by FOV, and stores only Coord positions that correspond to values greater than 0.0 (actually, greater than epsilon, which here is 0.0001). This won't behave as-expected if you give it a double[][] that DijkstraMap produces; there's a different constructor for that purpose.
      Parameters:
      fovMap - a 2D double array as produced by FOV

    • Region

      public Region​(double[][] dijkstraMap, double maximum)
      A constructor for a Region that takes a 2D double array, usually produced by DijkstraMap, and a maximum value, and stores only Coord positions that correspond to values no greater than maximum. This won't behave as-expected if you give it a double[][] that FOV produces; there's a different constructor for that purpose.
      Parameters:
      dijkstraMap - a 2D double array as produced by DijkstraMap
      maximum - the highest value that a position can have in dijkstraMap and still be given a Coord in this

    • Region

      public Region​(char[][] map, char... using)
      A constructor for a Region that takes a 2D char array, the kind produced by most map/dungeon generators in this library, and a vararg or array of char that will have their Coord positions used where those chars appear in map. This is optimized for the common case of a single char in using if you only want to, for example, store '.' to make a Region of floors, or '#' for walls.
      Parameters:
      map - a 2D char array that is usually the kind returned by a dungeon or map generator
      using - an array or vararg of char that will have their Coords used where they appear in map

    • Region

      public Region​(Coord... points)
      A constructor for a Region that takes an array or vararg of Coord and encodes all of them in the Region.
      Parameters:
      points - an array or vararg of Coord that will be stored in this Region, none can be null

    • Region

      public Region​(Collection<Coord> points)
      A constructor for a Region that takes a Collection of Coord, such as a List or Set, and encodes all of them in the Region.
      Parameters:
      points - a Collection of Coord that will be stored in this Region, none can be null

    • Region

      public Region​(Region other)
      A constructor that copies another Region so this Region will have the same contents. If the other Region is "dirty", this won't perform "cleanup" on it, but will ensure that this Region is "clean" at creation. None of the reference types in other will be used directly in this Region, so changes made to this Region won't be reflected in other.
      Parameters:
      other - another Region to copy into this one

    • Region

      public Region​(Coord center, int circleRadius, int mapWidth, int mapHeight)
      A constructor for a circular Region (possibly truncated at the edges) with a Coord center, an int radius, and a maximum width and height that the Coords in this Region will not exceed.
      Parameters:
      center - the center of the circular Region
      circleRadius - the radius as an int
      mapWidth - one more than the maximum x-position of any Coord this will contain
      mapHeight - one more than the maximum y-position of any Coord this will contain

    • Region

      public Region​(int minX, int minY, int width, int height)
      A constructor for a rectangular Region that stores Coords for the area from (minX,minY) at the minimum corner to (width + minX - 1, height + minY - 1) at the maximum corner. All parameters should be non-negative and less than 256, and height and width will be reduced if a Coord in the rectangle would extend to 256 in either dimension. This doesn't take two Coords as parameters because that would be confusing with the constructor that takes a vararg or array of Coord for its parameters.
      Parameters:
      minX - lowest x-coordinate in the rectangle; should be between 0 and 255
      minY - lowest y-coordinate in the rectangle; should be between 0 and 255
      width - total width of the rectangle; must be non-negative
      height - total height of the rectangle; must be non-negative

    • Region

      public Region​(short[] packedData)
      A constructor for a Region that takes a specifically-formatted short array (packed data), as produced by CoordPacker or sometimes other classes, like RegionMap or RoomFinder. If you don't have such data, the other constructors are recommended instead.
      Note: arrays of Hilbert indices are occasionally returned in CoordPacker as a different kind of short array, but those methods are always noted as such and those short arrays won't make sense if passed to this constructor. They may result in a technically-valid Region with random-seeming contents. In general, if a method in CoordPacker returns a short array (most of them do), but the name contains Hilbert, it may return the wrong kind (an array of Hilbert indices is wrong, packed data is right); check the documentation for that method.
      Parameters:
      packedData - a short array as produced by CoordPacker (usually), or sometimes RoomFinder or RegionMap

  • Method Details

    • getRandomCoord

      public Coord getRandomCoord​(IRNG rng)
      Gets a single random Coord from this using the given RNG (which can be seeded); returns null if this is empty.
      Parameters:
      rng - the source of random numbers used to get a random Coord from this Region
      Returns:
      a random Coord in this Region, or null if this is empty

    • separated

      public Region separated​(int separation)
      Takes this region and walks through its Coords in chunks with length equal to separation, creating a new Region where one Coord in each chunk is kept and the others are discarded.
      Parameters:
      separation - an int where higher numbers mean there will be more distance between Coords, and fewer total
      Returns:
      a new Region made of the separated Coords

    • randomSeparated

      public Region randomSeparated​(int separation, IRNG rng)
      Takes this region and walks through its Coords in chunks with length equal to separation, creating a new Region where one randomly-chosen Coord in each chunk is kept and the others are discarded.
      Parameters:
      separation - an int where higher numbers mean there will be more distance between Coords, and fewer total
      rng - the source of random numbers used to randomize Coords used, removing any noticeable pattern
      Returns:
      a new Region made of the separated Coords

    • toBooleanArray

      public boolean[][] toBooleanArray​(int width, int height)
      Gets a representation of this Region as a 2D boolean array with the given width and height. If this contains a Coord with x and y less than width and height, that position will be true in the 2D array this returns, otherwise it will be false.
      Parameters:
      width - the width of the 2D array to return
      height - the height of the 2D array to return
      Returns:
      a 2D boolean array where present Coords in this Region will be true, and everything else will be false

    • toCharArray

      public char[][] toCharArray​(int width, int height, char on, char off)
      Gets a representation of this Region as a 2D char array with the given width and height, using on to represent present Coords and off to represent absent ones. If this contains a Coord with x and y less than width and height, that position will be equal to on in the 2D array this returns, otherwise it will be equal to off.
      Parameters:
      width - the width of the 2D array to return
      height - the height of the 2D array to return
      on - the char to use when a Coord is present in this Region
      off - the char to use where no Coord is present in this Region
      Returns:
      a 2D char array where present Coords in this Region will be on, and everything else will be off

    • get

      public Coord get​(int index)
      Gets the Coord stored at the given index in this Region, or null if index is out of bounds. The ordering this class uses may seem unusual, but it is predictable, using the pattern a Hilbert Curve takes to wind through a 256x256 space (at its maximum). Any two given Coords will always have the same before-after relationship, regardless of other Coords in the Region. A Region is a dense data structure, like a List or array, so valid indices shouldn't ever return null.
      Specified by:
      get in interface List<Coord>
      Specified by:
      get in class AbstractList<Coord>
      Parameters:
      index - the index into this Region to get a Coord at; should be less than size() and non-negative.
      Returns:
      the Coord this Region holds at index, if index is valid; otherwise null

    • size

      public int size()
      Gets the size of this Region as measured in Coords stored. Performs "cleanup" if the Region is "dirty," even though this doesn't specifically request a Coord. As such, it may take longer than a call to size() might be expected to, but only just after a "dirtying" method was called.
      Specified by:
      size in interface Collection<Coord>
      Specified by:
      size in interface List<Coord>
      Specified by:
      size in class AbstractCollection<Coord>
      Returns:
      the number of Coords stored in this Region.

    • isEmpty

      public boolean isEmpty()
      Returns true if there are no Coords in this Region, or false otherwise. Can be more efficient than checking if size() is greater than 0 because it doesn't depend on the "dirty or clean" state, and can quickly check.
      Specified by:
      isEmpty in interface Collection<Coord>
      Specified by:
      isEmpty in interface List<Coord>
      Overrides:
      isEmpty in class AbstractCollection<Coord>
      Returns:

    • add

      public boolean add​(Coord coord)
      Adds a Coord to this Region, returning false if the Coord is null or already included in this, or true otherwise. Causes the Region to be considered "dirty", which will make anything that gets a Coord from this to perform some "cleanup" on the Coords this holds when a Coord is requested. You can perform multiple "dirtying" operations in succession without needing more "cleanups" than the one when a Coord is next requested.
      Specified by:
      add in interface Collection<Coord>
      Specified by:
      add in interface List<Coord>
      Overrides:
      add in class AbstractList<Coord>
      Parameters:
      coord - a Coord to add to this region
      Returns:
      true if the Coord was added and was not already present; false if the Coord as null or already present

    • getRaw

      public short[] getRaw()
      Gets a direct reference to this Region's "raw packed data"; don't modify it unless you know what you're doing! It's fine to pass this to methods in CoordPacker, since essentially all of those methods won't modify packed data given as arguments.
      Returns:
      the raw packed data this class uses; should not be modified carelessly

    • setRaw

      public void setRaw​(short[] raw)
      Sets the "raw packed data" to the given short array, as generated by CoordPacker or some parts of RegionMap. This hopefully won't need to be consumed too much externally, but is an important bridge between this and CoordPacker's API, which deals mostly with these special short arrays. Causes the Region to be considered "dirty", which will make anything that gets a Coord from this to perform some "cleanup" on the Coords this holds when a Coord is requested. You can perform multiple "dirtying" operations in succession without needing more "cleanups" than the one when a Coord is next requested.
      Parameters:
      raw - a short array of packed data; has a very specific format and should usually not be made manually

    • getCoords

      public Coord[] getCoords()
      Gets the Coords contained in this as an array, a direct reference that does permit modifying the Coords in your own code without altering "dirty/clean" status. This method does "cleanup" in itself if necessary, but once the Coords are returned you can change them at-will. The Coords may not reflect changes made by this object if it creates a new Coord array, as it often does.
      Returns:
      the Coords contained in this Region as an array

    • setCoords

      public void setCoords​(Coord... coords)
      Changes this Region to include the given Coords and disregard its previous contents. If any elements of coords are null, this Region will hold no Coords (a sort of escape hatch to avoid throwing an exception, since all other methods in this class fail on null entries without potentially crashing a program).
      Parameters:
      coords - an array or vararg of Coord that will be used as the entirety of this Region

    • debugPrint

      public void debugPrint​(int width, int height)
      Prints this Region to System.out as a grid of chars with the given width and height, using '.' for Coords this contains and '#' for empty space. Consider using toCharArray() instead if you need more customization for what you want printed.
      Parameters:
      width - the width in chars of the grid to print
      height - the height in chars of the grid to print