Area.Area module

Tools for working with bounding boxes.

See also

Usage

local Area = require('__stdlib__/stdlib/area/area')

Constructor Methods

new(area) Converts an area in either array or table format to an area with a metatable.
construct([x1=0][, y1=0][, x2=0][, y2=0]) Creates an area from number parameters.
load(area) Loads the metatable into the passed Area without creating a new one.
from_string(area_string) Converts an area string to an area.
from_key(area_string) Converts a string key area to an area.

Area Methods

store(area) Stores the area for recall later, not deterministic.
recall(area) Recalls the stored area.
normalize(area) Normalizes the given area.
normalized(area) Normalize an area in place.
from_pixels(area) Convert area from pixels.
to_pixels(area) Convert area to pixels.
round(area) Rounds an areas points to its closest integer.
ceil(area) Ceils an area by increasing the size of the area outwards
floor(area) Floors an area by decreasing the size of the area inwards.
center_points(area) Gets the center positions of the tiles where the given area’s two positions reside.
corners(area) add left_bottom and right_top to the area
flip(area) Flip an area such that the value of its width becomes its height, and the value of its height becomes its width.
non_zero(area, amount) Return a non zero sized area by expanding if needed
to_diameter(area, diameter) Returns the area to the diameter from left_top
min(area, area2) Returns the smallest sized area.
max(area, area2) Returns the largest sized area.
shrink(area, amount) Shrinks the area inwards by the given amount.
expand(area, amount) Expands the area outwards by the given amount.
adjust(area, amount) Adjust an area by shrinking or expanding.
offset(area, pos) Offsets the area by the {x, y} values.
translate(area, direction, distance) Translates an area in the given direction.
to_surface_size(area, surface) Set an area to the whole size of the surface.
shrink_to_surface_size(area, surface) Shrinks an area to the size of the surface if it is bigger.
to_chunk_coords(area) Return the chunk coordinates from an area.

Position Conversion Functions

center(area) Calculates the center of the area and returns the position.

Area Functions

to_key(area) Return a suitable string for using as a table key
to_string(area) Converts an area to a string.
to_string_xy(area) Converts an area to an ltx, lty / rbx, rby string.
is_zero(area) Is this a non zero sized area
is_normalized(area) Is the area normalized.
valid(area) Is the area non-zero and normalized.
is_simple_area(area) Is this a simple area.
is_complex_area(area) Is this a complex area {left_top = {x = num, y = num}, right_bottom = {x = num, y = num}}
is_area(area) Is this and area of any kind.
is_Area(area) Does the area have the class attached
unpack(area) Unpack an area into a tuple.
unpack_positions(area) Unpack an area into a tuple of position tables.
pack(area) Pack an area into an array.
pack_positions(area) Pack an area into a simple bounding box array
size(area) Gets the properties of the given area.
rectangle(area) Return the rectangle.
width(area) The width of the area.
height(area) The height of an area.
dimensions(area) The dimensions of an area.
perimeter(area) The Perimiter of an area.
equals(area1, area2) Returns true if two areas are the same.
less_than(area1, area2) Is area1 smaller in size than area2
collides(area1, area2) Does either area overlap/collide with the other area.
contains_positions(area, positions) Are the passed positions all located in an area.
contains_areas(area, areas) Are all passed areas completly inside an area.
collides_areas(area, areas) Do all passed areas collide with an area.

Area Iterators

iterate(area[, as_position=false][, inside=false][, step=1]) Iterates an area.
spiral_iterate(area, as_position) Iterates the given area in a spiral as depicted below, from innermost to the outermost location.

Metamethods

Metamethods Area tables are returned with these Metamethods attached.

Constructor Methods

# new(area)

Converts an area in either array or table format to an area with a metatable.

Returns itself if it already has a metatable

Parameters: Returns:
# construct([x1=0][, y1=0][, x2=0][, y2=0])

Creates an area from number parameters.

Parameters:
  • x1 : (number) x-position of left_top, first position (default: 0)
  • y1 : (number) y-position of left_top, first position (default: 0)
  • x2 : (number) x-position of right_bottom, second position (default: 0)
  • y2 : (number) y-position of right_bottom, second position (default: 0)
Returns:
# load(area)

Loads the metatable into the passed Area without creating a new one.

Parameters:
  • area : (BoundingBox) the Area to set the metatable onto
Returns:
# from_string(area_string)

Converts an area string to an area.

Parameters:
  • area_string : (string) the area to convert
Returns:
# from_key(area_string)

Converts a string key area to an area.

Parameters:
  • area_string : (string) the area to convert
Returns:

Area Methods

# store(area)

Stores the area for recall later, not deterministic.

Only the last area stored is saved.

Parameters:
# recall(area)

Recalls the stored area.

Parameters: Returns:
# normalize(area)

Normalizes the given area.

  • Swaps the values between right_bottom.x & left_top.x IF right_bottom.x < left_top.x
  • Swaps the values between right_bottom.y & left_top.y IF right_bottom.y < left_top.y

Parameters: Returns:
# normalized(area)

Normalize an area in place.

Parameters: Returns:
  • (area) The area normalized in place
# from_pixels(area)

Convert area from pixels.

Parameters: Returns:
# to_pixels(area)

Convert area to pixels.

Parameters: Returns:
# round(area)

Rounds an areas points to its closest integer.

Parameters: Returns:
# ceil(area)

Ceils an area by increasing the size of the area outwards

Parameters: Returns:
# floor(area)

Floors an area by decreasing the size of the area inwards.

Parameters: Returns:
# center_points(area)

Gets the center positions of the tiles where the given area’s two positions reside.

Parameters: Returns:
  • (BoundingBox) the area with its two positions at the center of the tiles in which they reside
# corners(area)

add left_bottom and right_top to the area

Parameters: Returns:
  • (BoundingBox) the area with left_bottom and right_top included
# flip(area)

Flip an area such that the value of its width becomes its height, and the value of its height becomes its width.

Parameters: Returns:
# non_zero(area, amount)

Return a non zero sized area by expanding if needed

Parameters: Returns:
# to_diameter(area, diameter)

Returns the area to the diameter from left_top

Parameters: Returns:
# min(area, area2)

Returns the smallest sized area.

Parameters: Returns:
# max(area, area2)

Returns the largest sized area.

Parameters: Returns:
# shrink(area, amount)

Shrinks the area inwards by the given amount.

The area shrinks inwards from top-left towards the bottom-right, and from bottom-right towards the top-left.

Parameters: Returns:
# expand(area, amount)

Expands the area outwards by the given amount.

Parameters: Returns: See also:
# adjust(area, amount)

Adjust an area by shrinking or expanding.

Imagine pinching & holding with fingers the top-left & bottom-right corners of a 2D box and pulling outwards to expand and pushing inwards to shrink the box.

Parameters: Returns: Usage: 
local area = Area.adjust({{-2, -2}, {2, 2}}, {4, -1})
 -- returns {left_top = {x = -6, y = -1}, right_bottom = {x = 6, y = 1}}
# offset(area, pos)

Offsets the area by the {x, y} values.

Parameters:
  • area : (BoundingBox) the area to offset
  • pos : (Position) the position to which the area will offset
Returns:
# translate(area, direction, distance)

Translates an area in the given direction.

Parameters: Returns:
# to_surface_size(area, surface)

Set an area to the whole size of the surface.

Parameters: Returns:
# shrink_to_surface_size(area, surface)

Shrinks an area to the size of the surface if it is bigger.

Parameters: Returns:
# to_chunk_coords(area)

Return the chunk coordinates from an area.

Parameters: Returns:

Position Conversion Functions

# center(area)

Calculates the center of the area and returns the position.

Parameters: Returns:

Area Functions

# to_key(area)

Return a suitable string for using as a table key

Parameters: Returns:
  • string
# to_string(area)

Converts an area to a string.

Parameters: Returns:
  • (string) the string representation of the area
# to_string_xy(area)

Converts an area to an ltx, lty / rbx, rby string.

Parameters: Returns:
  • (string) the string representation of the area
# is_zero(area)

Is this a non zero sized area

Parameters: Returns:
# is_normalized(area)

Is the area normalized.

Parameters: Returns:
# valid(area)

Is the area non-zero and normalized.

Parameters: Returns:
# is_simple_area(area)

Is this a simple area.

{{num, num}, {num, num}}

Parameters: Returns:
# is_complex_area(area)

Is this a complex area {left_top = {x = num, y = num}, right_bottom = {x = num, y = num}}

Parameters: Returns:
# is_area(area)

Is this and area of any kind.

Parameters: Returns:
# is_Area(area)

Does the area have the class attached

Parameters: Returns:
# unpack(area)

Unpack an area into a tuple.

Parameters: Returns:
  • (tuple) lt.x, lt.y, rb.x, rb.y
# unpack_positions(area)

Unpack an area into a tuple of position tables.

Parameters: Returns:
# pack(area)

Pack an area into an array.

Parameters: Returns:
# pack_positions(area)

Pack an area into a simple bounding box array

Parameters: Returns:
# size(area)

Gets the properties of the given area.

This function returns a total of four values that represent the properties of the given area.

Parameters:
  • area : (BoundingBox) the area from which to get the size
Returns:
  • (number) the size of the area — (width × height)
  • (number) the width of the area
  • (number) the height of the area
  • (number) the perimeter of the area — (2 × (width + height))
# rectangle(area)

Return the rectangle.

Parameters: Returns:
# width(area)

The width of the area.

Parameters: Returns:
# height(area)

The height of an area.

Parameters: Returns:
# dimensions(area)

The dimensions of an area.

Parameters: Returns:
# perimeter(area)

The Perimiter of an area.

Parameters: Returns:
# equals(area1, area2)

Returns true if two areas are the same.

Parameters: Returns:
  • (boolean) true if areas are the same
# less_than(area1, area2)

Is area1 smaller in size than area2

Parameters: Returns:
  • (boolean) is area1 less than area2 in size
# collides(area1, area2)

Does either area overlap/collide with the other area.

Parameters: Returns:
# contains_positions(area, positions)

Are the passed positions all located in an area.

Parameters:
  • area : (BoundingBox) the search area
  • positions : (array) array of Concepts.Position
Returns:
  • (boolean) true if the positions are located in the area
# contains_areas(area, areas)

Are all passed areas completly inside an area.

Parameters: Returns:
# collides_areas(area, areas)

Do all passed areas collide with an area.

Parameters: Returns:

Area Iterators

# iterate(area[, as_position=false][, inside=false][, step=1])

Iterates an area.

Parameters:
  • area : (BoundingBox) the area to iterate
  • as_position : (boolean) return a position object (default: false)
  • inside : (boolean) only return values that contain the areas tiles (default: false)
  • step : (number) size to increment (default: 1)
Returns: Usage: 
local area = {{0, -5}, {3, -3}}
for x,y in Area.iterate(area) do
  -- return x, y values
end
for position in Area.iterate(area, true) do
  -- returns a position object
end
-- Iterates from left_top.x to right_bottom.x then goes down y until right_bottom.y
# spiral_iterate(area, as_position)

Iterates the given area in a spiral as depicted below, from innermost to the outermost location.

Parameters:
  • area : (BoundingBox) the area on which to perform a spiral iteration
  • as_position : (boolean) return a position object instead of x, y
Returns: Usage: 
for x, y in Area.spiral_iterate({{-2, -1}, {2, 1}}) do
print('(' .. x .. ', ' .. y .. ')')
end
prints: (0, 0) (1, 0) (1, 1) (0, 1) (-1, 1) (-1, 0) (-1, -1) (0, -1) (1, -1) (2, -1) (2, 0) (2, 1) (-2, 1) (-2, 0) (-2, -1)

Metamethods

# Metamethods

Area tables are returned with these Metamethods attached.

Fields:
  • __class
  • __index : If key is not found see if there is one available in the Area module.
  • __tostring : Will print a string representation of the area.
  • __concat : calls tostring on both sides of concat.
  • __add : Will adjust if RHS is vector/position, add offset if RHS is number/area
  • __sub : Will adjust if RHS is vector/position, sub offset if RHS is number/area
  • __mul
  • __div
  • __mod
  • __unm
  • __eq : Is area1 the same as area2.
  • __lt : Is the size of area1 less than number/area2.
  • __le : Is the size of area1 less than or equal to number/area2.
  • __len : The size of the area.
  • __call : Return a new copy.
  • __debugline
generated by LDoc 1.4.6
Last updated 2022-03-16 23:48:55 UTC