Struct Geography 

pub struct Geography { /* private fields */ }

A geography (spatial) value.

This type wraps raw geography bytes and provides type safety when working with spatial data. With the geography feature enabled, it also supports WKT/WKB parsing and conversion to/from geo_types::Geometry.

Binary Format Notes

Important: This type can hold data in two different binary formats:

1. Hyper’s Legacy Format: Data read from Hyper query results is stored in Hyper’s proprietary legacy serialization format. This format is not WKB-compatible.

2. WKB Format: When created via from_wkt() or from_wkb() (with the geography feature), data is stored in WKB (Well-Known Binary) format.

Methods like to_geometry() and to_wkt() (available with the geography feature) expect WKB format and will fail when called on data in Hyper’s legacy format.

Basic Usage (Always Available)

use hyperdb_api_core::types::Geography;

// Create from raw bytes (e.g., from query results)
let geo = Geography::from_bytes(vec![0x01, 0x02, 0x03]);

// Get raw bytes for insertion
let bytes: &[u8] = geo.as_bytes();

WKT/WKB Parsing (Requires geography Feature)

use hyperdb_api_core::types::Geography;

// Create from WKT string (requires "geography" feature)
let geo = Geography::from_wkt("POINT(-122.4194 37.7749)")?;

// Convert to geo-types for processing
let geometry = geo.to_geometry()?;

// Export as WKT
let wkt_string = geo.to_wkt()?;

Implementations

impl Geography

pub fn from_bytes(data: impl Into<Vec<u8>>) -> Geography

Creates a Geography from raw binary data in Hyper’s legacy format.

Use this when reading geography data from Hyper query results. The data will be in Hyper’s internal legacy serialization format.

Format Compatibility

Data read from Hyper is in Hyper’s proprietary legacy format, not WKB. Methods like to_geometry() and to_wkt() (available with the geography feature) expect WKB format and will fail when called on data created via this method. Use format() to check the format before calling these methods.

pub fn from_wkb_bytes(data: impl Into<Vec<u8>>) -> Geography

Creates a Geography from WKB (Well-Known Binary) data.

Use this when you have WKB data from an external source. Methods like to_geometry() and to_wkt() will work on this data.

pub fn binary_format(&self) -> GeographyBinaryFormat

Returns the binary format of this geography value.

Use this to check whether WKB-dependent methods like to_geometry() and to_wkt() will work on this value.

Note: When the geography feature is enabled, there’s also a format() method that performs runtime detection and returns the actual data.

pub fn is_wkb(&self) -> bool

Returns true if this geography is in WKB format.

WKB-dependent methods like to_geometry() and to_wkt() will only work if this returns true.

pub fn is_hyper_legacy(&self) -> bool

Returns true if this geography is in Hyper’s legacy format.

Data in this format cannot be converted to geometry or WKT.

pub fn as_bytes(&self) -> &[u8]

Returns the raw bytes of this geography value.

pub fn into_bytes(self) -> Vec<u8>

Consumes self and returns the underlying bytes.

pub fn len(&self) -> usize

Returns the length of the binary data in bytes.

pub fn is_empty(&self) -> bool

Returns true if the geography data is empty.

impl Geography

pub const DEFAULT_RING_CLOSURE_EPSILON: f64 = 1e-6

Validates geometry coordinate ranges. Default tolerance for ring closure validation. This is more lenient than typical machine epsilon to accommodate geographic data that may have slightly different precision.

pub fn from_wkt( wkt_str: &str, ) -> Result<Geography, Box<dyn Error + Sync + Send>>

Creates a Geography from a WKT (Well-Known Text) string.

This parses the WKT string and converts it to WKB (Well-Known Binary) format for storage. Coordinates are validated to be within valid geographic ranges (longitude: [-180, 180], latitude: [-90, 90]).

Supported WKT Types

• POINT(x y) - A single point
• LINESTRING(x1 y1, x2 y2, ...) - A line
• POLYGON((x1 y1, x2 y2, ..., x1 y1)) - A polygon
• MULTIPOINT((x1 y1), (x2 y2), ...) - Multiple points
• MULTILINESTRING((...), (...)) - Multiple lines
• MULTIPOLYGON(((...)), ((...))) - Multiple polygons
• GEOMETRYCOLLECTION(...) - Collection of geometries

Example

use hyperdb_api_core::types::Geography;

// Requires "geography" feature
let point = Geography::from_wkt("POINT(-122.4194 37.7749)")?;
let line = Geography::from_wkt("LINESTRING(0 0, 1 1, 2 2)")?;
let polygon = Geography::from_wkt("POLYGON((0 0, 4 0, 4 4, 0 4, 0 0))")?;

Errors

Returns an error if the WKT string is invalid or contains out-of-range coordinates.

pub fn from_wkb( wkb_bytes: &[u8], ) -> Result<Geography, Box<dyn Error + Sync + Send>>

Creates a Geography from WKB (Well-Known Binary) data.

This accepts standard WKB format and validates it eagerly.

Errors

Returns an error if the WKB data is invalid.

pub fn validate_wkb_format(&self) -> Result<(), Box<dyn Error + Sync + Send>>

Validates that the stored data is valid WKB.

Calling this on geography values sourced from Hyper query results (which are in Hyper’s legacy format, not WKB) will return an error.

Errors

• Returns an error if the payload is fewer than 9 bytes (the minimum WKB envelope size).
• Returns an error if the leading endianness marker is not 0x00 (big-endian) or 0x01 (little-endian).
• Returns an error if the bytes cannot be parsed as a valid WKB geometry via geozero.

pub fn format(&self) -> Result<GeographyFormat, Box<dyn Error + Sync + Send>>

Detects the underlying binary format (legacy vs WKB).

This helps avoid calling WKB-only methods on legacy data by making the format explicit. Returns an error for empty payloads.

Errors

Returns an error if the geography data is empty. A non-empty payload that fails WKB validation is reported as GeographyFormat::Legacy rather than an error.

pub fn from_geometry( geometry: &Geometry, ) -> Result<Geography, Box<dyn Error + Sync + Send>>

Creates a Geography from a geo_types::Geometry.

Coordinates are validated to be within valid geographic ranges.

Example

use hyperdb_api_core::types::Geography;
use geo_types::Point;

// Requires "geography" feature
let point = Point::new(-122.4194, 37.7749);
let geo = Geography::from_geometry(&point.into())?;

Errors

• Returns an error if any coordinate’s longitude falls outside [-180, 180] or latitude outside [-90, 90].
• Returns an error if a polygon ring is not closed within Self::DEFAULT_RING_CLOSURE_EPSILON.
• Returns an error if geozero fails to serialize the geometry to WKB.

pub fn to_geometry(&self) -> Result<Geometry, Box<dyn Error + Sync + Send>>

Converts this geography to a geo_types::Geometry.

Format Requirements

This method requires WKB format. It will fail if called on data created via from_bytes() with data read from Hyper query results. Use is_wkb() or binary_format() to check the format before calling.

Errors

• Returns an error if this value is in Hyper’s legacy format (GeographyBinaryFormat::HyperLegacy). Construct via Self::from_wkt or Self::from_wkb to use this method.
• Returns an error if the stored bytes cannot be parsed as WKB by geozero.

pub fn to_wkt(&self) -> Result<String, Box<dyn Error + Sync + Send>>

Exports this geography as a WKT (Well-Known Text) string.

Format Requirements

This method requires WKB format. It will fail if called on data created via from_bytes() with data read from Hyper query results. Use is_wkb() or binary_format() to check the format before calling.

Errors

• Returns an error if this value is in Hyper’s legacy format (GeographyBinaryFormat::HyperLegacy). Construct via Self::from_wkt or Self::from_wkb to use this method.
• Returns an error if the stored bytes cannot be serialized to WKT by geozero (malformed WKB).

pub fn to_wkb(&self) -> Vec<u8>

Returns the WKB data (clone of internal bytes).

pub fn validate_geometry_bounds_with_tolerance( geometry: &Geometry, ring_closure_epsilon: f64, ) -> Result<(), Box<dyn Error + Sync + Send>>

Validates geometry bounds with a configurable ring closure tolerance.

Use this method when you need a different tolerance for ring closure validation (e.g., for data with lower precision).

Arguments

• geometry - The geometry to validate
• ring_closure_epsilon - The tolerance for ring closure validation. Use a larger value for data with lower precision.

Errors

• Returns an error if any coordinate longitude is outside [-180, 180] or latitude outside [-90, 90].
• Returns an error if a polygon ring’s first and last vertices differ by more than ring_closure_epsilon on either axis.

Trait Implementations

impl AsRef<[u8]> for Geography

fn as_ref(&self) -> &[u8]

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Geography

fn clone(&self) -> Geography

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Geography

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Display for Geography

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl From<&[u8]> for Geography

fn from(bytes: &[u8]) -> Geography

Creates a Geography from bytes, assuming Hyper’s legacy format.

Use Geography::from_wkb_bytes() if the data is in WKB format.

impl From<Geography> for Vec<u8>

fn from(geo: Geography) -> Vec<u8>

Converts to this type from the input type.

impl From<Vec<u8>> for Geography

fn from(bytes: Vec<u8>) -> Geography

Creates a Geography from bytes, assuming Hyper’s legacy format.

Use Geography::from_wkb_bytes() if the data is in WKB format.

impl FromHyperBinary for Geography

fn from_hyper_binary( buf: &[u8], ) -> Result<Geography, Box<dyn Error + Sync + Send>>

Deserializes a value from HyperBinary format.

impl Hash for Geography

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Geography

fn eq(&self, other: &Geography) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl ToHyperBinary for Geography

fn to_hyper_binary( &self, buf: &mut BytesMut, ) -> Result<(), Box<dyn Error + Sync + Send>>

Serializes the value to HyperBinary format for a nullable column.

fn to_hyper_binary_not_null( &self, buf: &mut BytesMut, ) -> Result<(), Box<dyn Error + Sync + Send>>

Serializes the value to HyperBinary format for a NOT NULL column.

fn hyper_binary_size(&self) -> usize

Returns the size in bytes this value will occupy when serialized (nullable).

fn hyper_binary_size_not_null(&self) -> usize

Returns the size in bytes this value will occupy when serialized (not nullable).

impl TryFrom<&Geometry> for Geography

type Error = Box<dyn Error + Sync + Send>

The type returned in the event of a conversion error.

fn try_from( geometry: &Geometry, ) -> Result<Geography, <Geography as TryFrom<&Geometry>>::Error>

Performs the conversion.

impl TryFrom<&str> for Geography

type Error = Box<dyn Error + Sync + Send>

The type returned in the event of a conversion error.

fn try_from(wkt: &str) -> Result<Geography, <Geography as TryFrom<&str>>::Error>

Performs the conversion.

impl TryFrom<Geometry> for Geography

type Error = Box<dyn Error + Sync + Send>

The type returned in the event of a conversion error.

fn try_from( geometry: Geometry, ) -> Result<Geography, <Geography as TryFrom<Geometry>>::Error>

Performs the conversion.

impl TryFrom<LineString> for Geography

type Error = Box<dyn Error + Sync + Send>

The type returned in the event of a conversion error.

fn try_from( line: LineString, ) -> Result<Geography, <Geography as TryFrom<LineString>>::Error>

Performs the conversion.

impl TryFrom<MultiLineString> for Geography

type Error = Box<dyn Error + Sync + Send>

The type returned in the event of a conversion error.

fn try_from( mls: MultiLineString, ) -> Result<Geography, <Geography as TryFrom<MultiLineString>>::Error>

Performs the conversion.

impl TryFrom<MultiPoint> for Geography

type Error = Box<dyn Error + Sync + Send>

The type returned in the event of a conversion error.

fn try_from( mp: MultiPoint, ) -> Result<Geography, <Geography as TryFrom<MultiPoint>>::Error>

Performs the conversion.

impl TryFrom<MultiPolygon> for Geography

type Error = Box<dyn Error + Sync + Send>

The type returned in the event of a conversion error.

fn try_from( mp: MultiPolygon, ) -> Result<Geography, <Geography as TryFrom<MultiPolygon>>::Error>

Performs the conversion.

impl TryFrom<Point> for Geography

type Error = Box<dyn Error + Sync + Send>

The type returned in the event of a conversion error.

fn try_from( point: Point, ) -> Result<Geography, <Geography as TryFrom<Point>>::Error>

Performs the conversion.

impl TryFrom<Polygon> for Geography

type Error = Box<dyn Error + Sync + Send>

The type returned in the event of a conversion error.

fn try_from( polygon: Polygon, ) -> Result<Geography, <Geography as TryFrom<Polygon>>::Error>

Performs the conversion.

impl TryFrom<String> for Geography

type Error = Box<dyn Error + Sync + Send>

The type returned in the event of a conversion error.

fn try_from( wkt: String, ) -> Result<Geography, <Geography as TryFrom<String>>::Error>

Performs the conversion.

impl Eq for Geography

impl StructuralPartialEq for Geography