# Module: `gears.geometry`

Helper functions used to compute geometries.

When this module refer to a geometry table, this assume a table with at least an *x*, *y*, *width* and *height* keys and numeric values.

### Info:

- Copyright: 2008 Julien Danjou
- Originally authored by: Julien Danjou <julien@danjou.info>
  (Full contributors list available on our github project)

## Static module functions

gears.geometry.rectangle.get_square_distance (geom, x, y) -> number | Get the square distance between a rectangle and a point. |
gears.geometry.rectangle.get_closest_by_coord (list, x, y) -> () | Return the closest rectangle from `list` for a given point. |
gears.geometry.rectangle.get_by_coord (list, x, y) -> () | Return the rectangle containing the [x, y] point. |
gears.geometry.rectangle.get_in_direction (dir, recttbl, cur) -> () | Get the nearest rectangle in the given direction. |
gears.geometry.rectangle.are_equal (a, b) -> boolean | Return true if the area are exactly identical. |
gears.geometry.rectangle.is_inside (a, b) -> boolean | Return if rectangle `a` is within rectangle `b`. |
gears.geometry.rectangle.area_intersect_area (a, b) -> () | Check if an area intersect another area. |
gears.geometry.rectangle.get_intersection (a, b) -> table | Get the intersect area between a and b. |
gears.geometry.rectangle.area_remove (areas, elem) -> () | Remove an area from a list, splitting the space between several area that can overlap. |

## Static module functions

🔗 gears.geometry.rectangle.get_square_distance (geom, x, y) -> number
  Get the square distance between a rectangle and a point.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  geom |  | table | A rectangle
  x |  | number | The horizontal coordinate
  y |  | number | The vertical coordinate
  width |  | number | The rectangle width
  height |  | number | The rectangle height
  x |  | number | X coordinate of point
  y |  | number | Y coordinate of point

  ### Returns:

  number The squared distance of the rectangle to the provided point.
🔗 gears.geometry.rectangle.get_closest_by_coord (list, x, y) -> ()
  Return the closest rectangle from `list` for a given point.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  list |  | table | A list of geometry tables.
  x |  | number | The x coordinate
  y |  | number | The y coordinate

  ### Returns:

  The key from the closest geometry.
🔗 gears.geometry.rectangle.get_by_coord (list, x, y) -> ()
  Return the rectangle containing the [x, y] point.

  Note that if multiple element from the geometry list contains the point, the returned result is nondeterministic.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  list |  | table | A list of geometry tables.
  x |  | number | The x coordinate
  y |  | number | The y coordinate

  ### Returns:

  The key from the closest geometry. In case no result is found, *nil* is returned.
🔗 gears.geometry.rectangle.get_in_direction (dir, recttbl, cur) -> ()
  Get the nearest rectangle in the given direction. Every rectangle is specified as a table with *x*, *y*, *width*, *height* keys, the same as client or screen geometries.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  dir |  | string | The direction, can be either *up*, *down*, *left* or *right*.
  recttbl |  | table | A table of rectangle specifications.
  cur |  | table | The current rectangle.

  ### Returns:

  The index for the rectangle in recttbl closer to cur in the given direction. nil if none found.
🔗 gears.geometry.rectangle.are_equal (a, b) -> boolean
  Return true if the area are exactly identical.

  The areas are table with a `x`, `y`, `width` and `height` keys.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  a |  | table | The area.
  b |  | table | The other area.

  ### Returns:

  boolean If the areas are identical.
🔗 gears.geometry.rectangle.is_inside (a, b) -> boolean
  Return if rectangle `a` is within rectangle `b`.

  This includes the edges. 100% of `a` area has to be within `b` for this function to return true. If you wish to know if any part of `a` intersect with `b`, use gears.geometry.rectangle.get_intersection.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  a |  | table | The smaller area.
  b |  | table | The larger area.

  ### Returns:

  boolean If the areas are identical.

  ### See also:

  gears.geometry.rectangle.get_intersection | Get the intersect area between a and b. | static module functions

🔗 gears.geometry.rectangle.area_intersect_area (a, b) -> ()
  Check if an area intersect another area.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  a |  | table | The area.
  b |  | table | The other area.

  ### Returns:

  True if they intersect, false otherwise.
🔗 gears.geometry.rectangle.get_intersection (a, b) -> table
  Get the intersect area between a and b.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  a |  | table | The area.
  x |  | number | The horizontal coordinate
  y |  | number | The vertical coordinate
  width |  | number | The rectangle width
  height |  | number | The rectangle height
  b |  | table | The other area.
  x |  | number | The horizontal coordinate
  y |  | number | The vertical coordinate
  width |  | number | The rectangle width
  height |  | number | The rectangle height

  ### Returns:

  table The intersect area.

  ### See also:

  gears.geometry.rectangle.is_inside | Return if rectangle `a` is within rectangle `b`. | static module functions

🔗 gears.geometry.rectangle.area_remove (areas, elem) -> ()
  Remove an area from a list, splitting the space between several area that can overlap.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  areas |  | table | Table of areas.
  elem |  | table | Area to remove.
  x |  | number | The horizontal coordinate
  y |  | number | The vertical coordinate
  width |  | number | The rectangle width
  height |  | number | The rectangle height

  ### Returns:

  The new area list.

generated by LDoc 1.5.0