Home | Modules

pLine provides functions for placing and mutating axis-aligned line segments.

This is a one-dimensional version of pRect.

Dependencies: pAssert, pInterp, pMath, pName

local pLine = require("p_line")

local l1 = {x=0, w=16}
local l2 = {x=0, w=8}
pLine.copy(l1, l2)

print(l2.x, l2.w) --> 0 16

API

pLine.center

Centers LineSegment b within LineSegment a.

pLine.center(a, b)

  • a: The reference LineSegment.

  • b: The LineSegment to center.

Returns: a, for method chaining.

pLine.copy

Copies a LineSegment’s position and length.

pLine.copy(a, b)

  • a: The source LineSegment.

  • b: The LineSegment to overwrite.

Returns: a, for method chaining.

pLine.expand

Expands a LineSegment by shifting its sides.

pLine.expand(a, x1, x2)

  • a: The LineSegment to modify.

  • x1: How much to expand the left side.

  • x2: How much to expand the right side.

Returns: a, for method chaining.

pLine.expandLeft

Expands a LineSegment’s left side.

pLine.expandLeft(a, x1)

  • a: The LineSegment to modify.

  • x1: How much to expand the left side.

Returns: a, for method chaining.

pLine.expandRight

Expands a LineSegment’s right side.

pLine.expandRight(a, x2)

  • a: The LineSegment to modify.

  • x2: How much to expand the right side.

Returns: a, for method chaining.

pLine.expandT

Expands a LineSegment by shifting its sides. Like pLine.expand, but takes a LineDelta table.

pLine.expandT(a, ld)

Returns: a, for method chaining.

pLine.flip

Flips the LineSegment in relation to another LineSegment.

pLine.flip(a, b)

  • a: The reference LineSegment.

  • b: The LineSegment to flip.

Returns: a, for method chaining.

pLine.getBounds

Gets the range of a group of LineSegments.

local x1, x2 = pLine.getBounds(...)

Returns: The furthest left and right positions.

Notes

If no arguments are provided, then both returned positions will be zero.

pLine.getBoundsT

Gets the range of a group of LineSegments. Like pLine.getBounds, but takes an array of LineSegments rather than a vararg list.

local x1, x2 = pLine.getBoundsT(list)

Returns: The furthest left and right positions.

Notes

If there are no elements in the array, then both returned positions will be zero.

pLine.placeInner

Places LineSegment b within the boundaries of LineSegment a at an interpolated position.

pLine.placeInner(a, b, unit)

  • a: The reference LineSegment.

  • b: The LineSegment to place.

  • unit: A number from 0.0 to 1.0.

Returns: a, for method chaining.

Notes

a is assumed to be at least as big as b.

The final coordinates of b are rounded to integers.

pLine.placeMidpoint

Places LineSegment b's center point within the boundaries of LineSegment a, at an interpolated position.

pLine.placeMidpoint(a, b, unit)

  • a: The reference LineSegment.

  • b: The LineSegment to place.

  • unit: A number from 0.0 to 1.0.

Returns: a, for method chaining.

Notes

The final coordinates of b are rounded to integers.

pLine.placeOuter

Places LineSegment b within or just outside the boundaries of LineSegment a at an interpolated position.

pLine.placeOuter(a, b, unit)

  • a: The reference LineSegment.

  • b: The LineSegment to place.

  • unit: A number from 0.0 to 1.0.

Returns: a, for method chaining.

Notes

The final coordinates of b are rounded to integers.

pLine.positionOverlap

Checks if a position is within a LineSegment.

local overlap = pLine.positionOverlap(a, x)

Returns: true if the point overlaps the LineSegment, false if not.

pLine.reduce

Shortens a LineSegment by shifting its sides.

pLine.reduce(a, x1, x2)

  • a: The LineSegment to modify.

  • x1: How much to shorten the left side.

  • x2: How much to shorten the right side.

Returns: a, for method chaining.

pLine.reduceLeft

Shortenes a LineSegment’s left side.

pLine.reduceLeft(a, x1)

  • a: The LineSegment to modify.

  • x1: How much to shorten the left side.

Returns: a, for method chaining.

pLine.reduceRight

Shortens a LineSegment’s right side.

pLine.reduceRight(a, x2)

  • a: The LineSegment to modify.

  • x2: How much to shorten the right side.

Returns: a, for method chaining.

pLine.reduceT

Shortens a LineSegment by shifting its sides. Like pLine.reduce, but takes a LineDelta table.

pLine.reduceT(a, ld)

Returns: a, for method chaining.

pLine.set

Sets a LineSegment’s position and length.

pLine.set(a, x, w)

  • a: The LineSegment to modify.

  • x: The new position.

  • w: The new width.

Returns: a, for method chaining.

pLine.split

Splits a LineSegment.

pLine.split(a, b, side, len)

  • a: The input LineSegment.

  • b: The output LineSegment.

  • side: The side to split: left or right.

  • len: The length of the split.

Returns: a, for method chaining.

pLine.splitLeft

Shortens LineSegment a by cutting a chunk from its left side, and overwrites LineSegment b to match the chunk.

pLine.splitLeft(a, b, len)

  • a: The LineSegment to shorten.

  • b: The LineSegment to be assigned the removed part.

Returns: a, for method chaining.

pLine.splitOrOverlay

Splits or copies a LineSegment, based on the arguments provided.

pLine.splitOrOverlay(a, b, placement, len)

  • a: The input LineSegment.

  • b: The output LineSegment.

  • placement: How to place LineSegment b: by splitting LineSegment a (left or right), or by copying it (overlay).

  • len: The length of the split. Not used when the placement mode is overlay.

Returns: a, for method chaining.

pLine.splitRight

Shortens LineSegment a by cutting a chunk from its right side, and overwrites LineSegment b to match the chunk.

pLine.splitRight(a, b, len)

  • a: The LineSegment to shorten.

  • b: The LineSegment to be assigned the removed part.

Returns: a, for method chaining.

Module Notes

Omissions

Functions that would change only one variable in a trivial way, like setPosition() or setLength(), are omitted from the API.

Structures

pLine does not come with functions to create the structures described here. Any table that contains the expected fields may be used. Out of concern for overhead, function arguments are not validated by default.

LineSegment

A table with x and w fields, both numbers. The length (w) is assumed to be greater than or equal to zero.

local LineSegment = {x=0, w=0}

LineDelta

A table with measurements for each side of a LineSegment. These are typically used to apply margins, padding, etc.

local ld = {x1=0, x2=0} -- left, right

VERSION: 2.106