Block Geometry Domain API Guidelines

Core Semantics

Coordinate Model

coordinate = signed terminal-cell-space scalar
coordinate span = half-open origin plus non-negative extent on one axis
position/vector = signed x/y coordinates
size = non-negative width/height extents
rectangle = top-left position plus size
margin pair = leading and trailing offsets on one axis
empty rectangle = zero width or height

Primary Types

Coordinate // signed saturating terminal-cell coordinate
CoordinateSpan // one-dimensional half-open coordinate range
MarginPair // leading and trailing margins on one axis
Position // two-dimensional coordinate or vector
Size // non-negative width and height
Rectangle // axis-aligned half-open rectangle

Secondary Types

Margins // horizontal and vertical margin pairs; also top, right, bottom and left offsets
Direction // compass direction on a block grid
AlignedSource // target/source rectangle pair after alignment and cropping
PositionList, RectangleList // common position and rectangle containers

Pattern Definitions

G = Position/Size // position or size selected by a shared accessor pattern
Pa = PositionArray❮size❯ // fixed-size array of block positions
V = ❮Value❯ // value selected for a physical axis

Value Object Patterns

o.x/y() -> Coordinate // get position coordinates
o.setX/setY(value) -> void // set one position coordinate
o.width/height() -> Coordinate // get size dimensions
o.setWidth/setHeight(value) -> void // set one size dimension, clamping to non-negative
o.pos/size() -> G // get rectangle origin and extent
o.setPos/setSize(value) -> void // set rectangle origin or extent
o.top/right/bottom/left() -> Coordinate // get margins by side
o.setTop/setRight/setBottom/setLeft(value) -> void // set margins by side
o.horizontal/vertical() -> MarginPair // get physical-axis margins
o.component(axis/orientation) -> AxisComponent // select one physical-axis component
o.leading/trailing() -> Coordinate // get a margin-pair side
o.origin/extent/end() -> Coordinate // inspect a coordinate span
o.extent/delta/spacing() -> Coordinate // calculate one-axis margin effects
o.at(side) -> Coordinate // select a margin by side
o.hash() -> std::size_t // hash a value object

State and Membership Patterns

o.isZero() -> bool // test whether a size has no area
o.isInRange(minimum, maximum) -> bool // component-wise range test
o.fitsInto(size) -> bool // component-wise size containment
o.contains(position/rect) -> bool // geometry membership
o.overlaps(rect) -> bool // rectangle intersection test
o.isFrame(position) -> bool // test whether a position lies on the rectangle frame

Geometry Arithmetic Patterns

o.distanceTo(position) -> Coordinate // Manhattan distance
o.componentMin/componentMax(position) -> Position // component-wise position extrema
o.add/subtract(value[, orientation]) -> T& // saturating in-place arithmetic
o.expandedWith/limitedWith(value[, axis-or-side]) -> T // return constrained copy
o.expandTo/limitTo(value[, axis-or-side]) -> T& // apply component-wise constraints
o.expandedBy/insetBy(margins) -> Rectangle // apply margins to rectangle bounds
o.clampTo(minimum, maximum) -> Size // component-wise size clamp
o.area() -> math::SatInt32 // compute width times height
T::minimum()/maximum()/zero() -> T // common boundary factories

Direction and Ring Patterns

o.contains(direction) -> bool // lexical containment of compass components
o.toDelta() -> Position // convert direction to unit position delta
T::fromDelta(delta) -> Direction // convert delta signs to direction
o.toString() -> text::String // normalized lowercase direction name
T::fromString(text) -> T // parse text, returning the neutral state on failure
T::isValidString(text) -> bool // test if text can be parsed
o.cardinalFour() -> Pa // four neighbor positions
T::cardinalFourDeltas() -> Pa // four unit deltas
o.ringEight() -> Pa // eight surrounding positions
T::ringEightDeltas() -> Pa // eight unit deltas

Layout Patterns

o.anchor(anchor) -> Position // resolve anchor to a position inside size or rectangle
o.center() -> Position // shorthand for the center anchor
o.alignmentOffset(size, geometry::Alignment) -> Position // place content inside available space
o.subRectangle(anchor, size, margins) -> Rectangle // create an anchored child rectangle
o.alignedSource(rect, geometry::Alignment) -> AlignedSource // align and crop a source rectangle

Iteration and Division Patterns

o.forEach(function) -> void // visit all contained positions in row-major order
o.forEachInFrame(function) -> void // visit frame positions clockwise
o.frameIndex(position) -> int64_t // clockwise frame index or -1
o.frameDirection(position) -> Direction // frame direction or None
o.rotateCCW/mirror/transform(position, geometry::Orientation/Symmetry) -> Position // transform positions
o.gridCells(rows, columns[, spacing]) -> vector<Rectangle> // divide a rectangle into grid cells
T::bounds(positions) -> Rectangle // create bounds for a position list