v1.16.9

ADDED:
* netx.IsPub
* encodingx/hexx

Rest are mostly small corrections and docs

encodingx/binaryx/doc.go

@@ -0,0 +1,4 @@
+/*
+Package binaryx aims to extend functionality of the stdlib [encoding/binary] module.
+*/
+package binaryx

encodingx/binaryx/funcs.go

@@ -0,0 +1,122 @@
+package binaryx
+
+import (
+	"bytes"
+	"encoding"
+	"encoding/binary"
+)
+
+/*
+Marshal provides a Golang convention marshaling function entry point
+(e.g. like [encoding/json.Marshal], [encoding/xml.Marshal]) for arbitrary
+binary data.
+
+It simply wraps [OrderedMarshal] with [encoding/binary.NativeEndian]
+(which can differ from platform to platform) as the ord parameter to [OrderedMarshal].
+
+If you need to use a different or explicit [encoding/binary.ByteOrder],
+use [OrderedMarshal] directly instead.
+*/
+func Marshal(v any) (data []byte, err error) {
+
+	if data, err = OrderedMarshal(v, binary.NativeEndian); err != nil {
+		return
+	}
+
+	return
+}
+
+/*
+OrderedMarshal provides a slightly more flexible Golang convention marshaling
+function entry point (e.g. similar to [encoding/json.MarshalIndent],
+[encoding/xml.MarshalIndent]) for arbitrary binary data.
+
+If v conforms to [encoding.BinaryMarshaler], then the marshal method will be called.
+
+Otherwise, it wraps [encoding/binary.Write] with an internal buffer using ord
+as the [encoding/binary.ByteOrder] (endianness), so refer to that function
+for all caveats and other details.
+Note that [encoding/binary.Write] is *much* more strict than marshaling,
+and requires very basic typing.
+
+If you have no need for a specific byte order/endianness or want to explicitly use this
+system's native byte order/endianness,
+use [Marshal] instead.
+*/
+func OrderedMarshal(v any, ord binary.ByteOrder) (data []byte, err error) {
+
+	var ok bool
+	var b binary.Marshaler
+	var buf *bytes.Buffer = new(bytes.Buffer)
+
+	if b, ok = v.(encoding.BinaryMarshaler); ok {
+		if data, err = b.MarshalBinary(); err != nil {
+			return
+		}
+		return
+	}
+
+	if err = binary.Write(buf, ord, v); err != nil {
+		return
+	}
+
+	data = buf.Bytes()
+
+	return
+}
+
+/*
+Unmarshal provides a Golang convention unmarshaling function entry point
+(e.g. like [encoding/json.Unmarshal], [encoding/xml.Unmarshal]) for arbitrary
+binary data.
+
+It simply wraps [OrderedUnmarshal] with [encoding/binary.NativeEndian]
+(which can differ from platform to platform) as the ord parameter to [OrderedUnmarshal].
+
+If you need to use a different or explicit [encoding/binary.ByteOrder],
+use [OrderedUnmarshal] directly instead.
+*/
+func Unmarshal(data []byte, v any) (err error) {
+
+	if err = OrderedUnmarshal(data, v, binary.NativeEndian); err != nil {
+		return
+	}
+
+	return
+}
+
+/*
+OrderedUnmarshal provides a slightly more flexible Golang convention unmarshaling
+for arbitrary binary data.
+
+If v conforms to [encoding.BinaryUnmarshaler], then the unmarshal method will be called.
+
+Otherwise, it wraps [encoding/binary.Read] with an internal buffer using ord
+as the [encoding/binary.ByteOrder] (endianness), so refer to that function
+for all caveats and other details.
+Note that [encoding/binary.Read] is *much* more strict than unmarshaling,
+and requires very basic typing.
+
+If you have no need for a specific byte order/endianness or want to explicitly use this
+system's native byte order/endianness,
+use [Unmarshal] instead.
+*/
+func OrderedUnmarshal(data []byte, v any, ord binary.ByteOrder) (err error) {
+
+	var ok bool
+	var b encoding.BinaryUnmarshaler
+	var buf *bytes.Reader = bytes.NewReader(data)
+
+	if b, ok = v.(encoding.BinaryUnmarshaler); ok {
+		if err = b.UnmarshalBinary(data); err != nil {
+			return
+		}
+		return
+	}
+
+	if err = binary.Read(buf, ord, v); err != nil {
+		return
+	}
+
+	return
+}

encodingx/doc.go

@@ -0,0 +1,4 @@
+/*
+Package encodingx aims to extend functionality of the stdlib [encoding] module.
+*/
+package encodingx

encodingx/hexx/doc.go

@@ -0,0 +1,4 @@
+/*
+Package hexx aims to extend [encoding/hex] functionality.
+*/
+package hexx

encodingx/hexx/funcs.go

@@ -0,0 +1,30 @@
+package hexx
+
+import (
+	`io`
+)
+
+/*
+HexString returns a custom-formatted hex representation of b.
+*/
+func HexString(b []byte, opts ...hexStrFmtrOpt) (out string) {
+
+	// TODO
+
+	return
+}
+
+/*
+HexStringStream encodes a stream read from r and written into w.
+
+HexStringStream will return cleanly if r returns no more bytes or if an [io.EOF] is encountered (the [io.EOF] will not be returned).
+Any other error will immediately halt reading/writing and will b returned in err.
+
+If w is of a fixed capacity, it must be at least 2x the size of r's capacity.
+*/
+func HexStringStream(r io.Reader, w io.Writer, opts ...hexStrFmtrOpt) (read, wrtn uint64, err error) {
+
+	// TODO
+
+	return
+}

encodingx/hexx/funcs_hexstrfmtropt.go

@@ -0,0 +1,67 @@
+package hexx
+
+/*
+HexStrWithPrefix sets whether a prefix ("0x" by default, see [HexStrWithPrefixStr])
+*/
+func HexStrWithPrefix(pfx bool) (f hexStrFmtrOpt) {
+
+	f = func(h *hexStrFmtr) {
+		if h.pfxStr == "" {
+			h.pfxStr = "0x"
+		}
+		h.pfx = pfx
+	}
+
+	return
+}
+
+/*
+HexStrWithPrefixStr sets the prefix used if a prefix is to be included (see [HexStrWithPrefix]).
+
+The default is "0x".
+*/
+func HexStrWithPrefixStr(pfx string) (f hexStrFmtrOpt) { return func(h *hexStrFmtr) { h.pfxStr = pfx } }
+
+/*
+HexStrWithLower uses lowercase or uppercase hex character representation. The default is lowercase.
+
+To use uppercase, specify this option with lower == false.
+*/
+func HexStrWithLower(lower bool) (f hexStrFmtrOpt) { return func(h *hexStrFmtr) { h.lower = lower } }
+
+/*
+HexStrWithLeftPad specifies if left zero-padding should be used.
+
+The default is true.
+*/
+func HexStrWithLeftPad(leftPad bool) (f hexStrFmtrOpt) {
+	return func(h *hexStrFmtr) { h.noLeftPad = !leftPad }
+}
+
+/*
+HexStrWithSegLeftPad specifies if left zero-padding should be used for each segment (see [HexStrWithSplit]).
+
+The default is true.
+*/
+func HexStrWithSegLeftPad(segLeftPad bool) (f hexStrFmtrOpt) {
+	return func(h *hexStrFmtr) { h.noSegmentLeftPad = !segLeftPad }
+}
+
+/*
+HexStrWithSplit will split the hex string into "chunks" of numBytes bytes.
+
+For example:
+	numBytes == 0:
+	0x0123456789abcdef
+
+	numBytes == 1:
+	0x01 0x23 0x45 0x67 0x89 0xab 0xcd 0xef
+
+	numBytes == 2:
+	0x0123 0x4567 0x89ab 0xcdef
+*/
+func HexStrWithSplit(numBytes uint) (f hexStrFmtrOpt) {
+	return func(h *hexStrFmtr) { h.segmentBytes = numBytes }
+}
+
+// TODO

encodingx/hexx/types.go

@@ -0,0 +1,16 @@
+package hexx
+
+type (
+	hexStrFmtrOpt func(h *hexStrFmtr)
+
+	hexStrFmtr struct {
+		pfx              bool
+		pfxStr           string
+		lower            bool
+		noLeftPad        bool
+		noSegmentLeftPad bool
+		segmentBytes     uint
+		segmentSep       string
+		newlineBytes     uint
+	}
+)