The foundational library for the Swift Standards organization. Type-safe primitives for geometry, algebra, time, binary operations, and more. Swift 6 strict concurrency. Swift Embedded compatible.
- Overview
- Why
- Features
- Installation
- Quick Start
- Core Concepts
- Modules
- Usage Examples
- Testing
- Platform Support
- Related Packages
- Contributing
- License
swift-standards provides the shared foundation upon which all Swift Standards packages are built. It delivers types that catch errors at compile time rather than runtime, distinguishing between concepts that look similar but behave differently: coordinates vs displacements, points vs vectors, angles vs scalars.
No Foundation dependency. Pure Swift value types optimized for Swift Embedded and high-performance applications.
Rules deserve to be written in a form that leaves no ambiguity.
The Swift Standards organization implements international technical standards as executable Swift code. Rather than interpreting specification documents, we encode them as precise, compiler-enforced types. Invalid states become unrepresentable.
This package provides the primitives that make that possible:
- Phantom types distinguish values that share the same representation but have different meanings
- Algebraic structure encodes mathematical rules (you can't add two points, but you can add two vectors)
- Zero-cost abstractions ensure type safety without runtime overhead
When a specification says "a rectangle has width and height", this library ensures width and height are distinct types - not just two Double values that could be accidentally swapped.
- Type-safe geometry with compile-time distinction between coordinates and displacements
- Phantom types via
Tagged<Tag, RawValue>for zero-cost type safety - Mathematical precision: affine space (points) vs linear space (vectors)
- Composable predicates with Boolean algebra properties
- Three-valued logic for SQL-style NULL handling
- Standard library extensions without Foundation
- Binary serialization with endianness control
- Calendar operations independent of Foundation
- Swift 6 strict concurrency with Sendable throughout
- 2,400+ tests covering edge cases and mathematical properties
Add swift-standards to your Package.swift:
dependencies: [
.package(url: "https://github.com/swift-standards/swift-standards.git", from: "0.1.0")
]Add the umbrella product or individual modules:
.target(
name: "YourTarget",
dependencies: [
// Umbrella - includes all modules
.product(name: "Standards", package: "swift-standards")
// Or individual modules
.product(name: "Geometry", package: "swift-standards"),
.product(name: "Predicate", package: "swift-standards"),
]
)- Swift 6.2+
- macOS 26.0+ / iOS 26.0+ / watchOS 26.0+ / tvOS 26.0+ / visionOS 26.0+ / Linux
import Geometry
// Points are positions in space
let origin: Geometry<Double>.Point<2> = .zero
let target: Geometry<Double>.Point<2> = .init(x: 10, y: 20)
// Vectors are displacements between points
let displacement = target - origin // Vector<2>
// Point + Vector = Point (moving a point)
let newPoint = origin + displacement
// Point - Point = Vector (displacement between points)
// Point + Point = Compile Error (meaningless operation)import Predicate
// Build predicates from simple conditions
let isEven = Predicate<Int> { $0 % 2 == 0 }
let isPositive = Predicate<Int> { $0 > 0 }
// Compose with operators
let isEvenAndPositive = isEven && isPositive
let isOdd = !isEven
// Fluent factory methods
let isAdult = Predicate<Int>.greater.thanOrEqualTo(18)
let isInRange = Predicate<Int>.in.range(1...100)
let hasPrefix = Predicate<String>.has.prefix("swift-")
// Predicates are callable
isEven(4) // true
isEvenAndPositive(4) // true
isEvenAndPositive(-4) // falseimport Dimension
// Define phantom types for different domains
enum UserIDTag {}
enum OrderIDTag {}
typealias UserID = Tagged<UserIDTag, Int>
typealias OrderID = Tagged<OrderIDTag, Int>
let userId: UserID = Tagged(42)
let orderId: OrderID = Tagged(42)
// Same underlying value, but different types
// userId == orderId // Compile error: cannot compare UserID with OrderID
func fetchUser(id: UserID) -> User { ... }
fetchUser(id: orderId) // Compile error: expected UserID, got OrderIDThe type system distinguishes between positions (coordinates) and directed extents (displacements):
// Coordinates: positions in space (X, Y, Z)
let x: Geometry<Double>.X = 10 // An x-coordinate
let y: Geometry<Double>.Y = 20 // A y-coordinate
// Displacements: directed changes (Width, Height, Depth)
let width: Geometry<Double>.Width = 5 // A horizontal displacement
let height: Geometry<Double>.Height = 3 // A vertical displacement
// Coordinate + Displacement = Coordinate
let newX = x + width // X coordinate
// Coordinate - Coordinate = Displacement
let diff = x - Geometry<Double>.X(5) // Width displacement
// Displacement + Displacement = Displacement
let totalWidth = width + Geometry<Double>.Width(10)This prevents common bugs like accidentally adding two positions or treating a displacement as a position.
Points live in affine space. Vectors live in linear space. The operations available reflect this mathematical structure:
import Affine
import Algebra_Linear
// Points (affine space) - no addition, no scaling
let p1: Affine<Double>.Point<2> = .init(x: 0, y: 0)
let p2: Affine<Double>.Point<2> = .init(x: 10, y: 10)
// Vectors (linear space) - support addition and scaling
let v1: Linear<Double>.Vector<2> = .init(dx: 1, dy: 0)
let v2: Linear<Double>.Vector<2> = .init(dx: 0, dy: 1)
let sum = v1 + v2 // Vector addition
let scaled = v1 * 2.0 // Scalar multiplication
let displacement = p2 - p1 // Point difference yields vector
let moved = p1 + v1 // Point + Vector = PointTagged<Tag, RawValue> wraps values with phantom types that exist only at compile time:
// The tag is purely a compile-time marker
public struct Tagged<Tag, RawValue> {
public var rawValue: RawValue
}
// Geometry.X is just Tagged<Index.X.Coordinate, Scalar>
// No runtime overhead - same memory layout as the raw value| Module | Purpose |
|---|---|
| Standards | Umbrella module including all below |
| Geometry | Points, vectors, rectangles, circles, ellipses, arcs, beziers, polygons |
| Affine | Affine space: points, transforms (translation, rotation, scaling) |
| Algebra Linear | Linear space: vectors, matrices, linear transforms |
| Algebra | Algebraic structures and protocols |
| Dimension | Phantom types: Tagged, axis types, orientations (horizontal, vertical, depth) |
| Angle | Radian and Degree with trigonometric functions |
| Predicate | Composable boolean predicates with Boolean algebra |
| TernaryLogic | Three-valued logic (true, false, unknown) for SQL-style semantics |
| Binary | Byte serialization, endianness, bit manipulation |
| StandardTime | Calendar operations without Foundation |
| Locale | Locale handling without Foundation |
| Formatting | Number and value formatting |
| Positioning | Layout distribution types |
| Layout | Grid, stack, and flow layouts |
| Region | Bounded regions and intervals |
| Symmetry | Geometric symmetry operations |
| StandardLibraryExtensions | Extensions to Swift standard library types |
import Geometry
// Rectangle from corners
let rect = Geometry<Double>.Rectangle(
llx: 0, lly: 0, // lower-left
urx: 100, ury: 50 // upper-right
)
print(rect.width) // 100
print(rect.height) // 50
print(rect.center) // Point(x: 50, y: 25)
// Circle
let circle = Geometry<Double>.Circle(
center: .init(x: 0, y: 0),
radius: 10
)
print(circle.area) // ~314.16
print(circle.circumference) // ~62.83
print(circle.contains(.init(x: 5, y: 5))) // true
// Bezier curves
let bezier = Geometry<Double>.Bezier.quadratic(
from: .init(x: 0, y: 0),
control: .init(x: 50, y: 100),
to: .init(x: 100, y: 0)
)
let midpoint = bezier.point(at: 0.5)import Affine
let point: Affine<Double>.Point<2> = .init(x: 10, y: 0)
// Fluent transform API
let transform = Affine<Double>.Transform.identity
.translated(by: .init(dx: 5, dy: 5))
.rotated(by: .halfPi) // 90 degrees
.scaled(by: 2)
let transformed = transform.apply(to: point)import TernaryLogic
// For SQL-style NULL handling
let a: Ternary = .true
let b: Ternary = .unknown
let c: Ternary = .false
a && b // .unknown (true AND unknown = unknown)
a || b // .true (true OR unknown = true)
b && c // .false (unknown AND false = false)
!b // .unknown (NOT unknown = unknown)import Binary
// Byte serialization with endianness control
let value: UInt32 = 0x12345678
let littleEndian = value.bytes(.littleEndian) // [0x78, 0x56, 0x34, 0x12]
let bigEndian = value.bytes(.bigEndian) // [0x12, 0x34, 0x56, 0x78]
// Bit manipulation
let rotated = value.rotateLeft(by: 8)
let reversed = value.reverseBitsimport StandardLibraryExtensions
// Safe collection access
let array = [1, 2, 3]
array[safe: 5] // nil instead of crash
// Result builders for collections
let numbers = Array.build {
1
2
if condition { 3 }
for i in 4...6 { i }
}
// String utilities
" hello ".trimmed() // "hello"
"hello world".range(of: "world") // Range<String.Index>?# All tests (2,400+)
swift test
# Specific module
swift test --filter Geometry
# With verbose output
swift test --verbose| Platform | Status |
|---|---|
| macOS | Full support |
| iOS | Full support |
| watchOS | Full support |
| tvOS | Full support |
| visionOS | Full support |
| Linux | Full support |
| Swift Embedded | Compatible |
No Foundation dependency. Pure Swift value types only.
By default, the package is Swift Embedded compatible. To enable Codable conformances (which use any existentials not supported in Embedded), add the Codable trait:
.product(name: "Standards", package: "swift-standards", traits: ["Codable"])This package is the foundation for the Swift Standards organization, which implements international technical standards as executable Swift code. Other packages in the organization include implementations of RFC specifications, web standards (WHATWG URL), document formats (PDF, SVG), and more.
- apple/swift-numerics: Real and complex number support
- swift-html-to-pdf: HTML to PDF conversion with actor-based resource pooling
- swift-html: Type-safe HTML and CSS DSL
- swift-resource-pool: Actor-based resource pooling
Contributions welcome. Please:
- Add tests - comprehensive coverage maintained
- Follow conventions - Swift 6, strict concurrency, no force-unwraps
- Document public APIs - DocC comments with examples
Areas for contribution:
- Additional geometric primitives
- Performance optimizations
- Documentation and examples
Apache 2.0 - See LICENSE for details.