Skip to main content

OctetRegion

The shape a predicate is evaluated against. Constructed via static factory methods that validate inputs eagerly. Invalid regions trap at construction.

Factories​

country. Verified via MCC.​

public static func country(isoCode: String) -> OctetRegion
// e.g. OctetRegion.country(isoCode: "US")

isoCode must be ISO 3166-1 alpha-2 (two uppercase letters). Verified via mobile country code from the serving cell tower and network operator. Usually works indoors and without GPS.

subdivision. ISO 3166-2.​

public static func subdivision(isoCode: String) -> OctetRegion
// e.g. OctetRegion.subdivision(isoCode: "US-CA")

Country code, hyphen, 1–3 alphanumeric chars. Verified at proof time by reverse-geocoding the trusted fix's admin area.

usState. Sugar for subdivision.​

public static func usState(_ stateCode: String) -> OctetRegion
// OctetRegion.usState("CA") == OctetRegion.subdivision(isoCode: "US-CA")

Takes a standard two-letter US postal abbreviation.

city. Name-resolved.​

public static func city(name: String) -> OctetRegion
// e.g. OctetRegion.city(name: "San Francisco")

The SDK resolves name to an H3 polygon set internally (bundled atlas for top-N cities, server lookup beyond that).

disc. Analytic circle.​

public static func disc(center: LatLon, radiusMeters: Meters) -> OctetRegion
// e.g. OctetRegion.disc(center: LatLon(37.422, -122.084), radiusMeters: 250)

A disc is stored internally as a degenerate ellipse (equal axes, heading 0). The serializer renders this special case as disc(lat,lon,r) for readability.

ellipse. Oriented 2D ground ellipse.​

public static func ellipse(
    center: LatLon,
    semiMajorM: Meters,
    semiMinorM: Meters,
    headingDeg: Double      // [0, 360), clockwise from north
) -> OctetRegion

Pre-validated: semiMinorM > 0, semiMajorM >= semiMinorM, headingDeg ∈ [0, 360).

box3D. Bounding box.​

public static func box3D(
    latRange: ClosedRange<Double>,
    lonRange: ClosedRange<Double>,
    altRange: ClosedRange<Double>
) -> OctetRegion

Latitude validated to [-90, 90], longitude to [-180, 180], altitude finite.

polygonSet. Union of H3 cells.​

public static func polygonSet(cells: [H3Cell]) -> OctetRegion

Non-empty cell list. Free-form lat/lon polygons are not accepted. Quantize to H3 ahead of time. See Regions for why.

earth. Defensive fallback.​

public static func earth(maxAltitudeMeters: Meters = 10_000) -> OctetRegion

isWithin(.earth(...)) always returns YES if the SDK can produce any proof at all.

Value types​

public struct LatLon: Sendable, Hashable {
    public let latitude: Double   // [-90, 90]
    public let longitude: Double  // [-180, 180]
}

public typealias Meters = Double

Construction helpers (Android only at v1)​

RegionSpec + getRegion​

sealed class RegionSpec {
    data class Country(val isoCode: String)        : RegionSpec()
    data class Subdivision(val isoCode: String)    : RegionSpec()
    data class City(val name: String)              : RegionSpec()
    data class NamedZone(val id: String)           : RegionSpec()
}

suspend fun getRegion(spec: RegionSpec): OctetRegion

country and subdivision are local and return immediately. city and namedZone are declared but currently throw OctetFutureFlag. Atlas and server lookup are not yet wired.

buildRegion { … } DSL​

val r = buildRegion {
    disc(center = LatLon(37.422, -122.084), radiusMeters = 250.0)
}

Sugar over the static factories. Synchronous. Same validation rules.

Inspecting a region​

Available on all platforms via the uniform .toStr() / .toJson() / .toJsonl() methods. See Serialization. Android additionally exposes the free functions:

fun whatisRegion(r: OctetRegion): String   // human, NOT stable
fun regionToStr(r: OctetRegion): String    // machine, STABLE wire form

See also​

  • Regions. Why the taxonomy looks the way it does.
  • Predicates. What consumes an OctetRegion.
  • Serialization. .toStr() / .toJson() / .toJsonl() on every region.