squidpony.squidmath

Class Region

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractList<Coord>

squidpony.squidmath.Region

All Implemented Interfaces:

java.io.Serializable, java.lang.Iterable<Coord>, java.util.Collection<Coord>, java.util.List<Coord>

public class Region
extends java.util.AbstractList<Coord>
implements java.io.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 and Description
protected Coord[]	coords
protected short[]	raw

Fields inherited from class java.util.AbstractList

modCount

Constructor Summary

Constructors

Constructor and 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(java.util.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(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(Region other) A constructor that copies another Region so this Region will have the same contents.
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.

Method Summary

Modifier and Type	Method and 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.List

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

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream

Methods inherited from interface java.lang.Iterable

forEach

Field Detail

raw

protected short[] raw

coords

protected Coord[] coords

Constructor Detail

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(java.util.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 Detail

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 java.util.List<Coord>

Specified by:

get in class java.util.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 java.util.Collection<Coord>

Specified by:

size in interface java.util.List<Coord>

Specified by:

size in class java.util.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 java.util.Collection<Coord>

Specified by:

isEmpty in interface java.util.List<Coord>

Overrides:

isEmpty in class java.util.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 java.util.Collection<Coord>

Specified by:

add in interface java.util.List<Coord>

Overrides:

add in class java.util.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