NAME
DBIO::PostgreSQL::PostGIS::Codec::WKB::Decoder - EWKB-hex decoder for PostGIS geometry values
VERSION
version 0.900007
DESCRIPTION
Reads the hex-encoded EWKB PostGIS sends for a geometry or geography value. An input has one of three outcomes:
Decoded. The types
point,linestring,polygon,multipoint,multilinestring,multipolygonandgeometrycollectionare decoded to their coordinates, and to whether they are empty.Named, not decoded. PostGIS writes more types than those:
circularstring,compoundcurve,curvepolygon,multicurve,multisurface,polyhedralsurface,tinandtriangle. Their header is read, their body is not, and "decode_hex" returnscoordsasundef. So it does for ageometrycollectionthat holds a member of such a type, at any depth -- a collection is decoded as a whole or not at all -- and for a type id that has no name here, whosetypeisundefas well. No coordinates are returned for bytes this decoder does not know the layout of.Refused. Input that is no EWKB -- not hex (a character that is no hex digit, or an odd number of them), empty, a byte order that is neither 0 nor 1 (in the header or in a member), cut off, a count the rest of the input cannot hold, bytes left over behind the end of a decoded geometry, a
multipointwhose member is not a point, a member whose Z or M flag differs from that of the whole, ageometrycollectionnested deeper than 32 levels (the outermost is level 1) -- throws a DBIO::Exception. "decode_header" tells what the header of such an input says, if it has one (not for input that is not hex).
PostGIS does not send input of the third kind: a value read from a database is decoded, or named and left alone.
METHODS
decode_hex
my $result = DBIO::PostgreSQL::PostGIS::Codec::WKB::Decoder->decode_hex($hex);
Decodes an EWKB hex string into a hashref:
{
type => 'point',
srid => 4326, # undef if not present
has_z => 0,
has_m => 0,
coords => [x, y], # nested for non-point types
is_empty => 0,
}
coords is undef for a value that is not decoded (see "DESCRIPTION"); type, srid, has_z and has_m are those of its header all the same. type is undef for a type id that has no name here. Throws for input that is refused.
is_empty is true for what PostGIS calls empty (ST_IsEmpty): a geometry without parts -- a linestring or polygon with no points or rings, a multi* or geometrycollection with no members -- a point whose X and Y are both NaN (this is how PostGIS writes POINT EMPTY), and a multi* or geometrycollection whose members are all empty, MULTIPOINT(EMPTY) for one. coords of an empty geometry is [], and so is that of an empty point: not [NaN, NaN]. A point with just one NaN ordinate is a point. is_empty is undef, not false, for a value that is not decoded: nothing is known about it.
An empty member of a multi* keeps its place in coords as an empty list: MULTIPOINT(EMPTY,(1 2)) is [[], [1,2]]. The structure of a multi* is otherwise the plain coordinates of its parts.
The members of a geometrycollection are a list of hashes, one per member, in order, each carrying what the whole has:
{
type => 'linestring', # any decoded type, a collection too
coords => [[0,0],[1,1]], # as for that type; a collection's
# coords are again such a list
is_empty => 0, # that of the member
}
The members are returned with their types, not as bare coordinates, so the geometry and a valid WKT can be told from them. The Z and M flags of a member are those of the whole, the decoder refuses a member that differs.
What is read, and what is not, where PostGIS (ST_GeomFromEWKB, checked against 3.6) is more lenient than this decoder or the other way round:
Both byte orders are read, and so are the members of a
MULTI*or a collection in a byte order of their own: a big-endian member in a little-endian value is read as big-endian, as PostGIS does. Nothing but 0 and 1 is a byte order.A member with an SRID flag: PostGIS never writes one, but accepts it and drops it; the SRID of the geometry is that of the outer header. The decoder reads the SRID word of the member and drops it as well.
A member must have the Z and M flags of the whole. PostGIS refuses anything else ("Dimensions mismatch in lwcollection"); so does the decoder, which would otherwise read the member at the wrong width.
Bytes left behind the end of a decoded geometry are refused ("trailing bytes"). PostGIS ignores them; but a value it sends has none, so they mean the input is not what it claims to be. For a value that is not decoded the end of the body is not known, and nothing is checked.
The hex must be hex: pairs of digits, either case, nothing else -- no
0xprefix, no whitespace.ISO WKB type codes (1001 for
POINT Z, 2001 forPOINT M, 3001 forPOINT ZMand so on) are not read. PostGIS understands them when it is given them, but never sends them: it writes EWKB, with the dimension in the flags. The decoder masks the type word with0xFFFF, so such a code is a type id without a name, and the value is returned as one:typeandcoordsareundef.
decode_header
my $header = DBIO::PostgreSQL::PostGIS::Codec::WKB::Decoder->decode_header($hex);
Reads the header of an EWKB hex string -- byte order, type word, SRID -- and nothing after it. Returns what "decode_hex" returns, without coords:
{ type => 'point', srid => 4326, has_z => 0, has_m => 0 }
This is what there is to say about an input "decode_hex" refuses for its body. Throws if the header itself cannot be read, with the message "decode_hex" throws for it.
AUTHOR
DBIO Authors
COPYRIGHT AND LICENSE
Copyright (C) 2026 DBIO Authors
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.