## Area.Position module

Tools for working with `<x,y>` coordinates.

### Usage

``local Position = require('__stdlib__/stdlib/area/position')``

### Constructor Methods

 new(pos) Returns a correctly formated position object. construct(x, y) Creates a table representing the position from x and y. update(pos, x, y) Update a position in place without returning a new position. load(pos) Load the metatable into the passed position without creating a new one. from_string(pos_string) Converts a position string to a position. from_key(pos_string) Converts a string key position to a position. from_chunk_position(pos) Gets the left top tile position of a chunk from the chunk position. from_pixels(pos) Convert position from pixels

### Metamethods

 Metamethods Position tables are returned with these metamethods attached.

### Position Methods

 add(pos1, ...) Addition of two positions. subtract(pos1, ...) Subtraction of two positions.. multiply(pos1, ...) Multiplication of two positions. divide(pos1, ...) Division of two positions. mod(pos1, ...) Modulo of two positions. closest(pos1, positions) Return the closest position to the first position. farthest(pos1, positions) Return the farthest position from the first position. between(pos1, pos2) The middle of two positions. projection(pos1, pos2) The projection point of two positions. reflection(pos1, pos2) The reflection point or two positions. store(pos) Stores the position for recall later, not deterministic. recall(pos) Recalls the stored position. normalize(pos) Normalizes a position by rounding it to 2 decimal places. abs(pos) Abs x, y values ceil(pos) Ceil x, y values. floor(pos) Floor x, y values. center(pos) The center position of the tile where the given position resides. round(pos) Rounds a positions points to the closest integer. perpendicular(pos) Perpendicular position. swap(pos) Swap the x and y coordinates. flip(pos) Flip the signs of the position. flip_x(pos) Flip the x sign. flip_y(pos) Flip the y sign. lerp(pos1, pos2, alpha) Lerp position of pos1 and pos2. trim(pos, max_len) Trim the position to a length. offset_along_line(pos1, pos2, distance_from_pos2) Returns the position along line between source and target, at the distance from target. translate(pos, direction, distance) Translates a position in the given direction. random(pos[, minimum=0][, maximum=1][, random_tile=false]) Return a random offset of a position. average(positions) Return the average position of the passed positions. min(positions) Return the minimum position of the passed positions. max(positions) Return the maximum position of the passed positions. min_xy(positions) Return a position created from the smallest x, y values in the passed positions. max_xy(positions) Return a position created from the largest x, y values in the passed positions. intersection(pos1_start, pos1_end, pos2_start, pos2_end) The intersection of 4 positions.

### Position Mutate Methods

 normalized(pos) Normalizes a position by rounding it to 2 decimal places. absed(pos) Abs x, y values ceiled(pos) Ceil x, y values in place. floored(pos) Floor x, y values. centered(pos) The center position of the tile where the given position resides. rounded(pos) Rounds a positions points to the closest integer. swapped(pos) Swap the x and y coordinates. flipped(pos) Flip the signs of the position.

### Position Conversion Methods

 to_pixels(pos) Convert to pixels from position to_chunk_position(pos) Gets the chunk position of a chunk where the specified position resides.

### Area Conversion Methods

 expand_to_area(pos, radius) Expands a position to a square area. to_area(pos, width, height) Expands a position into an area by setting pos to left_top. to_tile_area(pos) Converts a tile position to the area of the tile it is in. to_chunk_area(pos) Get the chunk area the specified position is in. chunk_position_to_chunk_area(pos) Get the chunk area for the specified chunk position.

### Position Functions

 len_squared(pos) Gets the squared length of a position len(pos) Gets the length of a position to_string(pos) Converts a position to a string. to_string_xy(pos) Converts a position to an x, y string. to_key(pos) Converts a position to a string suitable for using as a table index. unpack(pos) Unpack a position into a tuple. pack(pos) Packs a position into an array. is_zero(pos) Is this position {0, 0}. inside(pos, area) Is a position inside of an area. is_simple_position(pos) Is this a simple position. is_complex_position(pos) Is this a complex position. is_Position(pos) Does the position have the class attached is_position(pos) Is this any position atan2(pos1, pos2) Return the atan2 of 2 positions. angle(pos1, pos2) The angle between two positions cross(pos1, pos2) Return the cross product of two positions. equals(pos1, pos2) Tests whether or not the two given positions are equal. less_than(pos1, pos2) Is pos1 less than pos2. less_than_eq(pos1, pos2) Is pos1 less than or equal to pos2. distance_squared(pos1[, pos2]) Calculates the Euclidean distance squared between two positions, useful when sqrt is not needed. distance(pos1[, pos2={x=0]) Calculates the Euclidean distance between two positions. manhattan_distance(pos1[, pos2]) Calculates the manhatten distance between two positions. direction_to(pos1, pos2) Returms the direction to a position using simple delta comparisons. complex_direction_to(pos1, pos2, eight_way) Returns the direction to a position. increment(pos[, inc_x=0][, inc_y=0][, increment_initial=false]) Increment a position each time it is called. increment_closure([new_inc_x=0][, new_inc_y=0]) A closure which the increment function returns.

### Constructor Methods

# new(pos)

Returns a correctly formated position object.

Parameters:
• pos : (Position) the position table or array to convert
Returns: Usage:
``Position.new({0, 0}) -- returns {x = 0, y = 0}``
# construct(x, y)

Creates a table representing the position from x and y.

Parameters:
Returns:
# update(pos, x, y)

Update a position in place without returning a new position.

Parameters:
Returns:
• Concepts.Position the passed position updated.

Load the metatable into the passed position without creating a new one.

Always assumes a valid position is passed

Parameters:
• pos : (Position) the position to set the metatable onto
Returns:
• (Position) the position with metatable attached
# from_string(pos_string)

Converts a position string to a position.

Parameters:
• pos_string : (string) the position to convert
Returns:
# from_key(pos_string)

Converts a string key position to a position.

Parameters:
• pos_string : (string) the position to convert
Returns:
# from_chunk_position(pos)

Gets the left top tile position of a chunk from the chunk position.

Parameters:
Returns:
# from_pixels(pos)

Convert position from pixels

Parameters:
Returns:

### Metamethods

# Metamethods

Position tables are returned with these metamethods attached.

Methods that return a position will return a NEW position without modifying the passed positions.

Fields:
• __class
• __index : If key is not found, see if there is one availble in the Position module.
• __sub : Subtracts one position from another. Returns a new position.
• __mul : Multiply 2 positions. Returns a new position.
• __div : Divide 2 positions. Returns a new position.
• __mod : Modulo of 2 positions. Returns a new position.
• __unm : Unary Minus of a position. Returns a new position.
• __len : Length of a single position.
• __eq : Are two positions at the same spot.
• __lt : Is position1 less than position2.
• __le : Is position1 less than or equal to position2.
• __tostring : Returns a string representation of the position
• __concat : calls tostring on both sides of concact.
• __call : copy the position.
• __debugline

### Position Methods

Parameters:
• pos1 : (Position)
• ... : () position or x, y values.
Returns:
# subtract(pos1, ...)

Subtraction of two positions..

Parameters:
• pos1 : (Position)
• ... : () position or x, y values
Returns:
# multiply(pos1, ...)

Multiplication of two positions.

Parameters:
• pos1 : (Position)
• ... : () position or x, y values
Returns:
# divide(pos1, ...)

Division of two positions.

Parameters:
• pos1 : (Position)
• ... : () position or x, y values
Returns:
# mod(pos1, ...)

Modulo of two positions.

Parameters:
• pos1 : (Position)
• ... : () position or x, y values
Returns:
# closest(pos1, positions)

Return the closest position to the first position.

Parameters:
• pos1 : (Positions) The position to find the closest too
• positions : (array) array of Concepts.Position
Returns:
# farthest(pos1, positions)

Return the farthest position from the first position.

Parameters:
• pos1 : (Positions) The position to find the farthest from
• positions : (array) array of Concepts.Position
Returns:
# between(pos1, pos2)

The middle of two positions.

Parameters:
Returns:
• (Position) pos1 the middle of two positions
# projection(pos1, pos2)

The projection point of two positions.

Parameters:
Returns:
# reflection(pos1, pos2)

The reflection point or two positions.

Parameters:
Returns:
# store(pos)

Stores the position for recall later, not deterministic.

Only the last position stored is saved.

Parameters:
# recall(pos)

Recalls the stored position.

Parameters:
Returns:
# normalize(pos)

Normalizes a position by rounding it to 2 decimal places.

Parameters:
Returns:
# abs(pos)

Abs x, y values

Parameters:
Returns:
# ceil(pos)

Ceil x, y values.

Parameters:
Returns:
# floor(pos)

Floor x, y values.

Parameters:
Returns:
# center(pos)

The center position of the tile where the given position resides.

Parameters:
Returns:
• (Position) A new position at the center of the tile
# round(pos)

Rounds a positions points to the closest integer.

Parameters:
Returns:
# perpendicular(pos)

Perpendicular position.

Parameters:
Returns:
# swap(pos)

Swap the x and y coordinates.

Parameters:
Returns:
• (Position) A new position with x and y swapped
# flip(pos)

Flip the signs of the position.

Parameters:
Returns:
• Concepts.Position A new position with flipped signs
# flip_x(pos)

Flip the x sign.

Parameters:
Returns:
• Concepts.Position A new position with flipped sign on the x
# flip_y(pos)

Flip the y sign.

Parameters:
Returns:
• Concepts.Position A new position with flipped sign on the y
# lerp(pos1, pos2, alpha)

Lerp position of pos1 and pos2.

Parameters:
Returns:
# trim(pos, max_len)

Trim the position to a length.

Parameters:
# offset_along_line(pos1, pos2, distance_from_pos2)

Returns the position along line between source and target, at the distance from target.

Parameters:
• pos1 : (Position) where the line starts and extends from.
• pos2 : (Position) where the line ends and is offset back from.
• distance_from_pos2 : (number) backwards from pos1 for the new position.
Returns:
• (Position) a point along line between source and target, at requested offset back from target.
# translate(pos, direction, distance)

Translates a position in the given direction.

Parameters:
Returns:
# random(pos[, minimum=0][, maximum=1][, random_tile=false])

Return a random offset of a position.

Parameters:
• pos : (Position) the position to randomize
• minimum : (number) the minimum amount to offset (default: 0)
• maximum : (number) the maximum amount to offset (default: 1)
• random_tile : (boolean) randomize the location on the tile (default: false)
Returns:
• (Position) a new random offset position
# average(positions)

Return the average position of the passed positions.

Parameters:
• positions : (array) array of Concepts.Position
Returns:
# min(positions)

Return the minimum position of the passed positions.

Parameters:
• positions : (array) array of Concepts.Position
Returns:
# max(positions)

Return the maximum position of the passed positions.

Parameters:
• positions : (array) array of Concepts.Position
Returns:
# min_xy(positions)

Return a position created from the smallest x, y values in the passed positions.

Parameters:
• positions : (array) array of Concepts.Position
Returns:
# max_xy(positions)

Return a position created from the largest x, y values in the passed positions.

Parameters:
• positions : (array) array of Concepts.Position
Returns:
# intersection(pos1_start, pos1_end, pos2_start, pos2_end)

The intersection of 4 positions.

Parameters:
• pos1_start
• pos1_end
• pos2_start
• pos2_end
Returns:

### Position Mutate Methods

# normalized(pos)

Normalizes a position by rounding it to 2 decimal places.

Parameters:
Returns:
• (Position) the normalized position mutated
# absed(pos)

Abs x, y values

Parameters:
Returns:
• (Position) the absolute position mutated
# ceiled(pos)

Ceil x, y values in place.

Parameters:
Returns:
• (Position) the ceiled position mutated
# floored(pos)

Floor x, y values.

Parameters:
Returns:
• (Position) the floored position mutated
# centered(pos)

The center position of the tile where the given position resides.

Parameters:
Returns:
• (Position) the centered position mutated
# rounded(pos)

Rounds a positions points to the closest integer.

Parameters:
Returns:
• (Position) the rounded position mutated
# swapped(pos)

Swap the x and y coordinates.

Parameters:
Returns:
• (Position) the swapped position mutated
# flipped(pos)

Flip the signs of the position.

Parameters:
Returns:
• Concepts.Position the flipped position mutated

### Position Conversion Methods

# to_pixels(pos)

Convert to pixels from position

Parameters:
Returns:
# to_chunk_position(pos)

Gets the chunk position of a chunk where the specified position resides.

Parameters:
• pos : (Position) a position residing somewhere in a chunk
Returns:
Usage:
``local chunk_x = Position.chunk_position(pos).x``

### Area Conversion Methods

Expands a position to a square area.

Parameters:
• pos : (Position) the position to expand into an area
• radius : (number) half of the side length of the area
Returns:
# to_area(pos, width, height)

Expands a position into an area by setting pos to left_top.

Parameters:
Returns:
# to_tile_area(pos)

Converts a tile position to the area of the tile it is in.

Parameters:
Returns:
# to_chunk_area(pos)

Get the chunk area the specified position is in.

Parameters:
Returns:
# chunk_position_to_chunk_area(pos)

Get the chunk area for the specified chunk position.

Parameters:
Returns:

### Position Functions

# len_squared(pos)

Gets the squared length of a position

Parameters:
Returns:
# len(pos)

Gets the length of a position

Parameters:
Returns:
# to_string(pos)

Converts a position to a string.

Parameters:
• pos : (Position) the position to convert
Returns:
• (string) string representation of the position
# to_string_xy(pos)

Converts a position to an x, y string.

Parameters:
• pos : (Position) the position to convert
Returns:
# to_key(pos)

Converts a position to a string suitable for using as a table index.

Parameters:
• pos : (Position) the position to convert
Returns:
# unpack(pos)

Unpack a position into a tuple.

Parameters:
• pos : (Position) the position to unpack
Returns:
• (tuple) x, y
# pack(pos)

Packs a position into an array.

Parameters:
Returns:
# is_zero(pos)

Is this position {0, 0}.

Parameters:
Returns:
# inside(pos, area)

Is a position inside of an area.

Parameters:
Returns:
• (boolean) Is the position inside of the area.
# is_simple_position(pos)

Is this a simple position.

{num, num}

Parameters:
Returns:
# is_complex_position(pos)

Is this a complex position.

{x = number, y = number}

Parameters:
Returns:
# is_Position(pos)

Does the position have the class attached

Parameters:
Returns:
# is_position(pos)

Is this any position

Parameters:
Returns:
# atan2(pos1, pos2)

Return the atan2 of 2 positions.

Parameters:
Returns:
# angle(pos1, pos2)

The angle between two positions

Parameters:
Returns:
# cross(pos1, pos2)

Return the cross product of two positions.

Parameters:
Returns:
# equals(pos1, pos2)

Tests whether or not the two given positions are equal.

Parameters:
Returns:
• (boolean) true if positions are equal
# less_than(pos1, pos2)

Is pos1 less than pos2.

Parameters:
Returns:
# less_than_eq(pos1, pos2)

Is pos1 less than or equal to pos2.

Parameters:
Returns:
# distance_squared(pos1[, pos2])

Calculates the Euclidean distance squared between two positions, useful when sqrt is not needed.

Parameters:
Returns:
• (number) the square of the euclidean distance
# distance(pos1[, pos2={x=0])

Calculates the Euclidean distance between two positions.

Parameters:
Returns:
• (number) the euclidean distance
# manhattan_distance(pos1[, pos2])

Calculates the manhatten distance between two positions.

Parameters:
Returns:
• (number) the manhatten distance
# direction_to(pos1, pos2)

Returms the direction to a position using simple delta comparisons.

Parameters:
Returns:
# complex_direction_to(pos1, pos2, eight_way)

Returns the direction to a position.

Parameters:
Returns:
# increment(pos[, inc_x=0][, inc_y=0][, increment_initial=false])

Increment a position each time it is called.

This can be used to increment or even decrement a position quickly.

Do not store function closures in the global object; use them in the current tick.

Parameters:
• inc_x : (number) optional increment x by this amount (default: 0)
• inc_y : (number) optional increment y by this amount (default: 0)
• increment_initial : (boolean) Whether the first use should be incremented (default: false)
Returns:
Usage:
``````local next_pos = Position.increment({0,0})
for i = 1, 5 do next_pos(0,1) -- returns {x = 0, y = 1} {x = 0, y = 2} {x = 0, y = 3} {x = 0, y = 4} {x = 0, y = 5}``````
``````local next_pos = Position.increment({0, 0}, 1)
next_pos() -- returns {1, 0}
next_pos(0, 5) -- returns {1, 5}
next_pos(nil, 5) -- returns {2, 10}``````
``````local next_pos = Position.increment({0, 0}, 0, 1)
surface.create_entity{name = 'flying-text', text = 'text', position = next_pos()}
surface.create_entity{name = 'flying-text', text = 'text', position = next_pos()} -- creates two flying text entities 1 tile apart``````
# increment_closure([new_inc_x=0][, new_inc_y=0])

A closure which the increment function returns.

> Do not call this directly and do not store this in the global object.

Parameters:
• new_inc_x : (number) (default: 0)
• new_inc_y : (number) (default: 0)
Returns: