Refactor TWKB unmarshal interface

[peterstace]

Description

This change modifies the TWKB unmarshal interface while minimally changing its internal implementation (I may change the internal implementation later).

There were a few problems with the previous interface that prompted this change:

• All non-geometry data was returned by a single function (UnmarshalTWKBWithHeaders), making the function signature awkward (with three non-error return values).

• UnmarshalTWKBWithHeaders also returned the geometry decoded from the TWKB, which is discordant with returning the envelope. The whole point of being able to parse the envelope is so that the user can skip full geometry decoding.

• Three different functions would provide the envelope: UnmarshalTWKBBoundingBoxHeader, UnmarshalTWKBEnvelope, and UnmarshalTWKBWithHeaders. There was a lot of overlap in functionality between these, and it wasn't clear to callers which one they should use.

• Some functions expose the extended envelope (an XY envelope with the addition of Z and M ranges) as a []Point. This way of representing an envelope is awkward for users since nothing in the type signature enforces that there are two elements in the slice. While comments indicate that the slice will contain two elements, the type system doesn't enforce this. Furthermore, return values from the function represent empty envelopes via an empty slice. While comments communicate this behaviour, users could easily miss this.

• When the ID list is present in the TWKB, it is returned as a []int64. This is error-prone for users since nothing in the type signature suggests that the slice may be empty to indicate that no ID list exists (this is only conveyed in comments).

The interface is tweaked to address the problems outlined above:

• UnmarshalTWKB stays exactly the same (and simply unmarshals the geometry part of the TWKB).

• The UnmarshalTWKBWithHeaders, UnmarshalTWKBBoundingBoxHeader, and UnmarshalTWKBEnvelope functions are removed.

• UnmarshalTWKBEnvelope is added back but with a different function signature. It now returns an ExtendedEnvelope type, which is a struct that contains an Envelope and two Interval's (for Z and M ranges). It also returns a boolean flag. This function signature, combined with theExtendedEnvelope` type, explicitly indicates that the envelope is optional and that the Z and M ranges may not be present even when the envelope is.

• UnmarshalTWKBList is added, which returns the ID list from the TWKB (if it exists). This function returns a []int64 and a boolean flag indicating if the list is present in the TWKB.

• UnmarshalTWKBSize is added, which returns the size of the TWKB in bytes. This can be used to quickly scan through a concatenated sequence of TWKBs, just reading each TWKBs bounding box (for example). TWKB size was not previously exposed to users, but is a useful part of the TWKB spec.

Check List

Have you:

• Added unit tests? Yes.

• Add cmprefimpl tests? (if appropriate?) N/A

• Updated release notes? (if appropriate?) Yes.

Related Issue

• https://github.com/peterstace/simplefeatures/issues/534

[peterstace]

Thanks for reviewing Albert, I really appreciate it!