wkb

README

encoding/wkb

This package provides encoding and decoding of WKB data. The interface is defined as:

func Marshal(geom orb.Geometry, byteOrder ...binary.ByteOrder) ([]byte, error)
func MarshalToHex(geom orb.Geometry, byteOrder ...binary.ByteOrder) (string, error)
func MustMarshal(geom orb.Geometry, byteOrder ...binary.ByteOrder) []byte
func MustMarshalToHex(geom orb.Geometry, byteOrder ...binary.ByteOrder) string

func NewEncoder(w io.Writer) *Encoder
func (e *Encoder) SetByteOrder(bo binary.ByteOrder)
func (e *Encoder) Encode(geom orb.Geometry) error

func Unmarshal(b []byte) (orb.Geometry, error)

func NewDecoder(r io.Reader) *Decoder
func (d *Decoder) Decode() (orb.Geometry, error)

Reading and Writing to a SQL database

This package provides wrappers for orb.Geometry types that implement sql.Scanner and driver.Value. For example:

row := db.QueryRow("SELECT ST_AsBinary(point_column) FROM postgis_table")

var p orb.Point
err := row.Scan(wkb.Scanner(&p))

db.Exec("INSERT INTO table (point_column) VALUES (?)", wkb.Value(p))

The column can also be wrapped in ST_AsEWKB. The SRID will be ignored.

If you don't know the type of the geometry try something like

s := wkb.Scanner(nil)
err := row.Scan(&s)

switch g := s.Geometry.(type) {
case orb.Point:
case orb.LineString:
}

Scanning directly from MySQL columns is supported. By default MySQL returns geometry data as WKB but prefixed with a 4 byte SRID. To support this, if the data is not valid WKB, the code will strip the first 4 bytes, the SRID, and try again. This works for most use cases.

Documentation

Overview

Package wkb is for decoding ESRI's Well Known Binary (WKB) format sepcification at https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry#Well-known_binary

Index

• Variables
• func Marshal(geom orb.Geometry, byteOrder ...binary.ByteOrder) ([]byte, error)
• func MarshalToHex(geom orb.Geometry, byteOrder ...binary.ByteOrder) (string, error)
• func MustMarshal(geom orb.Geometry, byteOrder ...binary.ByteOrder) []byte
• func MustMarshalToHex(geom orb.Geometry, byteOrder ...binary.ByteOrder) string
• func Unmarshal(data []byte) (orb.Geometry, error)
• func Value(g orb.Geometry) driver.Valuer
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (d *Decoder) Decode() (orb.Geometry, error)
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func (e *Encoder) Encode(geom orb.Geometry) error
  • func (e *Encoder) SetByteOrder(bo binary.ByteOrder) *Encoder
• type GeometryScanner
  • func Scanner(g interface{}) *GeometryScanner
  • func (s *GeometryScanner) Scan(d interface{}) error

Variables

var (
	// ErrUnsupportedDataType is returned by Scan methods when asked to scan
	// non []byte data from the database. This should never happen
	// if the driver is acting appropriately.
	ErrUnsupportedDataType = errors.New("wkb: scan value must be []byte")

	// ErrNotWKB is returned when unmarshalling WKB and the data is not valid.
	ErrNotWKB = errors.New("wkb: invalid data")

	// ErrIncorrectGeometry is returned when unmarshalling WKB data into the wrong type.
	// For example, unmarshaling linestring data into a point.
	ErrIncorrectGeometry = errors.New("wkb: incorrect geometry")

	// ErrUnsupportedGeometry is returned when geometry type is not supported by this lib.
	ErrUnsupportedGeometry = errors.New("wkb: unsupported geometry")
)

var DefaultByteOrder binary.ByteOrder = binary.LittleEndian

DefaultByteOrder is the order used for marshalling or encoding is none is specified.

Functions

func Marshal

func Marshal(geom orb.Geometry, byteOrder ...binary.ByteOrder) ([]byte, error)

Marshal encodes the geometry with the given byte order.

func MarshalToHex

func MarshalToHex(geom orb.Geometry, byteOrder ...binary.ByteOrder) (string, error)

MarshalToHex will encode the geometry into a hex string representation of the binary wkb.

func MustMarshal

func MustMarshal(geom orb.Geometry, byteOrder ...binary.ByteOrder) []byte

MustMarshal will encode the geometry and panic on error. Currently there is no reason to error during geometry marshalling.

func MustMarshalToHex

func MustMarshalToHex(geom orb.Geometry, byteOrder ...binary.ByteOrder) string

MustMarshalToHex will encode the geometry and panic on error. Currently there is no reason to error during geometry marshalling.

func Unmarshal

func Unmarshal(data []byte) (orb.Geometry, error)

Unmarshal will decode the type into a Geometry.

func Value

func Value(g orb.Geometry) driver.Valuer

Value will create a driver.Valuer that will WKB the geometry into the database query.

Types

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

Decoder can decoder WKB geometry off of the stream.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder will create a new WKB decoder.

func (*Decoder) Decode

func (d *Decoder) Decode() (orb.Geometry, error)

Decode will decode the next geometry off of the stream.

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

An Encoder will encode a geometry as WKB to the writer given at creation time.

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder creates a new Encoder for the given writer.

func (*Encoder) Encode

func (e *Encoder) Encode(geom orb.Geometry) error

Encode will write the geometry encoded as WKB to the given writer.

func (*Encoder) SetByteOrder

func (e *Encoder) SetByteOrder(bo binary.ByteOrder) *Encoder

SetByteOrder will override the default byte order set when the encoder was created.

type GeometryScanner

type GeometryScanner struct {
	Geometry orb.Geometry
	Valid    bool // Valid is true if the geometry is not NULL
	// contains filtered or unexported fields
}

GeometryScanner is a thing that can scan in sql query results. It can be used as a scan destination:

s := &wkb.GeometryScanner{}
err := db.QueryRow("SELECT latlon FROM foo WHERE id=?", id).Scan(s)
...
if s.Valid {
  // use s.Geometry
} else {
  // NULL value
}

func Scanner

func Scanner(g interface{}) *GeometryScanner

Scanner will return a GeometryScanner that can scan sql query results. The geometryScanner.Geometry attribute will be set to the value. If g is non-nil, it MUST be a pointer to an orb.Geometry type like a Point or LineString. In that case the value will be written to g and the Geometry attribute.

var p orb.Point
err := db.QueryRow("SELECT latlon FROM foo WHERE id=?", id).Scan(wkb.Scanner(&p))
...
// use p

If the value may be null check Valid first:

var point orb.Point
s := wkb.Scanner(&point)
err := db.QueryRow("SELECT latlon FROM foo WHERE id=?", id).Scan(&s)
...
if s.Valid {
  // use p
} else {
  // NULL value
}

Deprecated behavior: Scanning directly from MySQL columns is supported. By default MySQL returns geometry data as WKB but prefixed with a 4 byte SRID. To support this, if the data is not valid WKB, the code will strip the first 4 bytes and try again. This works for most use cases.

For supported behavior see `ewkb.ScannerPrefixSRID`

func (*GeometryScanner) Scan

func (s *GeometryScanner) Scan(d interface{}) error

Scan will scan the input []byte data into a geometry. This could be into the orb geometry type pointer or, if nil, the scanner.Geometry attribute.