Merge pull request #5 from JesseCoretta/v1.0.2

v1.0.2

README.md

@@ -1,6 +1,6 @@
 # go-objectid
 
-[![Go Report Card](https://goreportcard.com/badge/JesseCoretta/go-objectid)](https://goreportcard.com/report/github.com/JesseCoretta/go-objectid) [![Go Reference](https://pkg.go.dev/badge/github.com/JesseCoretta/go-objectid.svg)](https://pkg.go.dev/github.com/JesseCoretta/go-objectid) [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat)](https://github.com/JesseCoretta/go-objectid/blob/main/LICENSE) [![codecov](https://codecov.io/gh/JesseCoretta/go-objectid/graph/badge.svg?token=RLW4DHLKQP)](https://codecov.io/gh/JesseCoretta/go-objectid) [![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/JesseCoretta/go-objectid/issues) [![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/JesseCoretta/go-objectid/go.yml)](https://github.com/JesseCoretta/go-objectid/actions/workflows/go.yml) [![Author](https://img.shields.io/badge/author-Jesse_Coretta-darkred?label=%F0%9F%94%BA&labelColor=indigo&color=maroon)](mailto:[email protected]) [![Help Animals](https://img.shields.io/badge/help_animals-gray?label=%F0%9F%90%BE%20%F0%9F%98%BC%20%F0%9F%90%B6&labelColor=yellow)](https://github.com/JesseCoretta/JesseCoretta/blob/main/DONATIONS.md)
+[![Go Report Card](https://goreportcard.com/badge/JesseCoretta/go-objectid)](https://goreportcard.com/report/github.com/JesseCoretta/go-objectid) [![CodeQL](https://github.com/JesseCoretta/go-objectid/workflows/CodeQL/badge.svg)](https://github.com/JesseCoretta/go-objectid/actions/workflows/github-code-scanning/codeql) [![Go Reference](https://pkg.go.dev/badge/github.com/JesseCoretta/go-objectid.svg)](https://pkg.go.dev/github.com/JesseCoretta/go-objectid) [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat)](https://github.com/JesseCoretta/go-objectid/blob/main/LICENSE) [![codecov](https://codecov.io/gh/JesseCoretta/go-objectid/graph/badge.svg?token=RLW4DHLKQP)](https://codecov.io/gh/JesseCoretta/go-objectid) [![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/JesseCoretta/go-objectid/issues) [![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/JesseCoretta/go-objectid/go.yml)](https://github.com/JesseCoretta/go-objectid/actions/workflows/go.yml) [![GitHub release (with filter)](https://img.shields.io/github/v/release/JesseCoretta/go-objectid)](https://github.com/JesseCoretta/go-objectid/releases) [![Author](https://img.shields.io/badge/author-Jesse_Coretta-darkred?label=%F0%9F%94%BA&labelColor=indigo&color=maroon)](mailto:[email protected]) [![Help Animals](https://img.shields.io/badge/help_animals-gray?label=%F0%9F%90%BE%20%F0%9F%98%BC%20%F0%9F%90%B6&labelColor=yellow)](https://github.com/JesseCoretta/JesseCoretta/blob/main/DONATIONS.md)
 
-Package objectid offers convenient ASN.1 Object Identifier types with useful methods and a uint128-based NumberForm type allowing X.667 support.
+Package objectid offers convenient ASN.1 Object Identifier types with useful methods and a `uint128`-based NumberForm type allowing support for [ITU-T Rec. X.667](https://www.itu.int/rec/T-REC-X.667) compliant ASN.1 Object Identifiers.
 

asn.go

@@ -1,14 +1,12 @@
 package objectid
 
 /*
-ASN1Notation contains an ordered sequence of NameAndNumberForm
-instances.
+ASN1Notation contains an ordered sequence of [NameAndNumberForm] instances.
 */
 type ASN1Notation []NameAndNumberForm
 
 /*
-String is a stringer method that returns a properly formatted
-ASN.1 string value.
+String is a stringer method that returns a properly formatted ASN.1 string value.
 */
 func (a ASN1Notation) String() string {
 	var x []string
@@ -35,8 +33,7 @@ func (a ASN1Notation) Leaf() NameAndNumberForm {
 }
 
 /*
-Parent returns the leaf node's parent (-2) string value from
-the receiver.
+Parent returns the leaf node's parent (-2) string value from the receiver.
 */
 func (a ASN1Notation) Parent() NameAndNumberForm {
 	x, _ := a.Index(-2)
@@ -49,8 +46,7 @@ Len returns the integer length of the receiver.
 func (a ASN1Notation) Len() int { return len(a) }
 
 /*
-IsZero returns a boolean indicative of whether the receiver
-is unset.
+IsZero returns a Boolean indicative of whether the receiver is unset.
 */
 func (a ASN1Notation) IsZero() (is bool) {
 	if is = &a == nil; !is {
@@ -61,7 +57,7 @@ func (a ASN1Notation) IsZero() (is bool) {
 }
 
 /*
-Index returns the Nth index from the receiver, alongside a boolean
+Index returns the Nth index from the receiver, alongside a Boolean
 value indicative of success. This method supports the use of negative
 indices.
 */
@@ -92,12 +88,12 @@ func (a ASN1Notation) Index(idx int) (nanf NameAndNumberForm, ok bool) {
 }
 
 /*
-NewASN1Notation returns an instance of *ASN1Notation alongside an error.
+NewASN1Notation returns an instance of *[ASN1Notation] alongside an error.
 
 Valid input forms for ASN.1 values are string (e.g.: "{iso(1)}") and string
 slices (e.g.: []string{"iso(1)", "identified-organization(3)" ...}).
 
-NumberForm values CANNOT be negative, and CANNOT overflow NumberForm (uint128).
+[NumberForm] values CANNOT be negative, and CANNOT overflow [NumberForm] (uint128).
 */
 func NewASN1Notation(x any) (a *ASN1Notation, err error) {
 	// prepare temporary instance
@@ -139,7 +135,7 @@ func NewASN1Notation(x any) (a *ASN1Notation, err error) {
 }
 
 /*
-Valid returns a boolean value indicative of whether the receiver's
+Valid returns a Boolean value indicative of whether the receiver's
 length is greater than or equal to one (1) slice member.
 */
 func (a ASN1Notation) Valid() (is bool) {
@@ -156,11 +152,11 @@ func (a ASN1Notation) Valid() (is bool) {
 }
 
 /*
-Ancestry returns slices of DotNotation values ordered from leaf node
+Ancestry returns slices of [DotNotation] values ordered from leaf node
 (first) to root node (last).
 
 Empty slices of DotNotation are returned if the dotNotation value
-within the receiver is less than two (2) NumberForm values in length.
+within the receiver is less than two (2) [NumberForm] values in length.
 */
 func (a ASN1Notation) Ancestry() (anc []ASN1Notation) {
 	if a.Len() >= 2 {
@@ -173,9 +169,9 @@ func (a ASN1Notation) Ancestry() (anc []ASN1Notation) {
 }
 
 /*
-NewSubordinate returns a new instance of ASN1Notation based upon the
-contents of the receiver as well as the input NameAndNumberForm
-subordinate value. This creates a fully-qualified child ASN1Notation
+NewSubordinate returns a new instance of [ASN1Notation] based upon the
+contents of the receiver as well as the input [NameAndNumberForm]
+subordinate value. This creates a fully-qualified child [ASN1Notation]
 value of the receiver.
 */
 func (a ASN1Notation) NewSubordinate(nanf any) *ASN1Notation {
@@ -196,8 +192,8 @@ func (a ASN1Notation) NewSubordinate(nanf any) *ASN1Notation {
 }
 
 /*
-AncestorOf returns a boolean value indicative of whether the receiver
-is an ancestor of the input value, which can be string or ASN1Notation.
+AncestorOf returns a Boolean value indicative of whether the receiver
+is an ancestor of the input value, which can be string or [ASN1Notation].
 */
 func (a ASN1Notation) AncestorOf(asn any) (anc bool) {
 	if !a.IsZero() {

doc.go

@@ -3,10 +3,10 @@ Package objectid implements ASN.1 Object Identifier types and methods.
 
 # Features
 
-  - Unsigned 128-bit numberForm support (allows for expressing registrations found below {joint-iso-itu-t(2) uuid(25)}, per [X.667](https://www.itu.int/rec/T-REC-X.667))
+  - Unsigned 128-bit number form support (allows for expressing registrations found below {joint-iso-itu-t(2) uuid(25)}, per ITU-T Rec. X.667.
   - Flexible index support, allowing interrogation through negative indices without the risk of panic
   - Convenient Leaf, Parent and Root index alias methods, wherever applicable
-  - Ge, Gt, Le, Lt, Equal comparison methods for interacting with NumberForm instances
+  - Ge, Gt, Le, Lt, Equal comparison methods for interacting with [NumberForm] instances
 
 # License
 
@@ -16,10 +16,10 @@ For further details, see the LICENSE file within the root of the source reposito
 
 # NumberForm Maximum
 
-Valid NumberForm instances may fall between the minimum decimal value of zero (0) and the maximum decimal value of 340,282,366,920,938,463,463,374,607,431,768,211,455 (three hundred forty undecillion and change). This ensures no panics occur when parsing valid UUID-based object identifiers, such as those found beneath joint-iso-itu-t(2) uuid(25) per [X.667](https://www.itu.int/rec/T-REC-X.667).
+Valid [NumberForm] instances may fall between the minimum decimal value of zero (0) and the maximum decimal value of 340,282,366,920,938,463,463,374,607,431,768,211,455 (three hundred forty undecillion and change). This ensures no panics occur when parsing UUID-based [OID]s.
 
 # Special Credit
 
-A special thanks to Luke Champine for his excellent Uint128 package (found at https://github.com/lukechampine/uint128), which is incorporated within this package for [X.667](https://www.itu.int/rec/T-REC-X.667) support within NumberForm instances.
+A special thanks to Luke Champine for his excellent Uint128 package (found at https://github.com/lukechampine/uint128), which is incorporated within this package.
 */
 package objectid

dot.go

@@ -1,13 +1,12 @@
 package objectid
 
 /*
-DotNotation contains an ordered sequence of NumberForm instances.
+DotNotation contains an ordered sequence of [NumberForm] instances.
 */
 type DotNotation []NumberForm
 
 /*
-String is a stringer method that returns the dotNotation
-form of the receiver (e.g.: "1.3.6.1").
+String is a stringer method that returns the dot notation form of the receiver (e.g.: "1.3.6.1").
 */
 func (d DotNotation) String() (s string) {
 	if !d.IsZero() {
@@ -22,7 +21,7 @@ func (d DotNotation) String() (s string) {
 }
 
 /*
-Root returns the root node (0) NumberForm instance.
+Root returns the root node (0) [NumberForm] instance.
 */
 func (d DotNotation) Root() NumberForm {
 	x, _ := d.Index(0)
@@ -34,24 +33,23 @@ func (d DotNotation) Len() int {
 }
 
 /*
-Leaf returns the leaf-node (-1) NumberForm instance.
+Leaf returns the leaf-node (-1) [NumberForm] instance.
 */
 func (d DotNotation) Leaf() NumberForm {
 	x, _ := d.Index(-1)
 	return x
 }
 
 /*
-Parent returns the leaf-node's parent (-2) NumberForm instance.
+Parent returns the leaf-node's parent (-2) [NumberForm] instance.
 */
 func (d DotNotation) Parent() NumberForm {
 	x, _ := d.Index(-2)
 	return x
 }
 
 /*
-IsZero returns a boolean indicative of whether the receiver
-is unset.
+IsZero returns a Boolean indicative of whether the receiver is unset.
 */
 func (d *DotNotation) IsZero() (is bool) {
 	if d != nil {
@@ -61,8 +59,7 @@ func (d *DotNotation) IsZero() (is bool) {
 }
 
 /*
-NewDotNotation returns an instance of *DotNotation alongside a boolean
-value indicative of success.
+NewDotNotation returns an instance of *[DotNotation] alongside a Boolean value indicative of success.
 */
 func NewDotNotation(id string) (d *DotNotation, err error) {
 	if len(id) == 0 {
@@ -91,7 +88,7 @@ IntSlice returns slices of integer values and an error. The integer values are b
 upon the contents of the receiver. Note that if any single arc number overflows int,
 a zero slice is returned.
 
-Successful output can be cast as an instance of asn1.ObjectIdentifier, if desired.
+Successful output can be cast as an instance of [encoding/asn1.ObjectIdentifier], if desired.
 */
 func (d DotNotation) IntSlice() (slice []int, err error) {
 	if d.IsZero() {
@@ -114,7 +111,7 @@ func (d DotNotation) IntSlice() (slice []int, err error) {
 }
 
 /*
-Index returns the Nth index from the receiver, alongside a boolean
+Index returns the Nth index from the receiver, alongside a Boolean
 value indicative of success. This method supports the use of negative
 indices.
 */
@@ -137,11 +134,11 @@ func (d DotNotation) Index(idx int) (a NumberForm, ok bool) {
 }
 
 /*
-Ancestry returns slices of DotNotation values ordered from leaf
+Ancestry returns slices of [DotNotation] values ordered from leaf
 node (first) to root node (last).
 
-Empty slices of DotNotation are returned if the dotNotation value
-within the receiver is less than two (2) NumberForm values in length.
+Empty slices of [DotNotation] are returned if the dot notation value
+within the receiver is less than two (2) [NumberForm] values in length.
 */
 func (d DotNotation) Ancestry() (anc []DotNotation) {
 	if d.Len() > 0 {
@@ -154,8 +151,8 @@ func (d DotNotation) Ancestry() (anc []DotNotation) {
 }
 
 /*
-AncestorOf returns a boolean value indicative of whether the receiver
-is an ancestor of the input value, which can be string or DotNotation.
+AncestorOf returns a Boolean value indicative of whether the receiver
+is an ancestor of the input value, which can be string or [DotNotation].
 */
 func (d DotNotation) AncestorOf(dot any) (is bool) {
 	if !d.IsZero() {
@@ -198,9 +195,9 @@ func (d DotNotation) matchDotNot(dot *DotNotation) bool {
 }
 
 /*
-NewSubordinate returns a new instance of DotNotation based upon the
-contents of the receiver as well as the input NumberForm subordinate
-value. This creates a fully-qualified child DotNotation value of the
+NewSubordinate returns a new instance of [DotNotation] based upon the
+contents of the receiver as well as the input [NumberForm] subordinate
+value. This creates a fully-qualified child [DotNotation] value of the
 receiver.
 */
 func (d DotNotation) NewSubordinate(nf any) (dot *DotNotation) {
@@ -221,7 +218,7 @@ func (d DotNotation) NewSubordinate(nf any) (dot *DotNotation) {
 }
 
 /*
-Valid returns a boolean value indicative of the following:
+Valid returns a Boolean value indicative of the following:
 
 • Receiver's length is greater than or equal to one (1) slice member, and ...
 • The first slice in the receiver contains a decimal value that is less than three (3)

nanf.go

@@ -7,7 +7,7 @@ nanf.go deals with NameAndNumberForm syntax and viability
 /*
 NameAndNumberForm contains either an identifier with a parenthesis-enclosed
 decimal value, or a decimal value alone. An ordered sequence of instances of
-this type comprise an instance of ASN1Notation.
+this type comprise an instance of [ASN1Notation].
 */
 type NameAndNumberForm struct {
 	identifier        string
@@ -16,7 +16,7 @@ type NameAndNumberForm struct {
 }
 
 /*
-IsZero returns a boolean valu indicative of whether
+IsZero returns a Boolean valu indicative of whether
 the receiver is considered nil.
 */
 func (nanf NameAndNumberForm) IsZero() bool {
@@ -32,7 +32,7 @@ func (nanf NameAndNumberForm) Identifier() string {
 }
 
 /*
-NumberForm returns the underlying NumberForm
+NumberForm returns the underlying [NumberForm]
 value assigned to the receiver instance.
 */
 func (nanf NameAndNumberForm) NumberForm() NumberForm {
@@ -41,7 +41,7 @@ func (nanf NameAndNumberForm) NumberForm() NumberForm {
 
 /*
 String is a stringer method that returns the properly
-formatted NameAndNumberForm string value.
+formatted [NameAndNumberForm] string value.
 */
 func (nanf NameAndNumberForm) String() (val string) {
 	n := nanf.primaryIdentifier.String()
@@ -52,8 +52,8 @@ func (nanf NameAndNumberForm) String() (val string) {
 }
 
 /*
-Equal returns a boolean value indicative of whether instance
-n of NameAndNumberForm matches the receiver.
+Equal returns a Boolean value indicative of whether instance
+n of [NameAndNumberForm] matches the receiver.
 */
 func (nanf NameAndNumberForm) Equal(n any) (is bool) {
 	switch tv := n.(type) {
@@ -69,7 +69,7 @@ func (nanf NameAndNumberForm) Equal(n any) (is bool) {
 }
 
 /*
-parseNaNFstr returns an instance of *NameAndNumberForm alongside an error.
+parseNaNFstr returns an instance of *[NameAndNumberForm] alongside an error.
 */
 func parseNaNFstr(x string) (nanf *NameAndNumberForm, err error) {
 	// Don't waste time on bogus values.
@@ -116,15 +116,15 @@ func parseNaNFstr(x string) (nanf *NameAndNumberForm, err error) {
 }
 
 /*
-NewNameAndNumberForm returns an instance of *NameAndNumberForm
+NewNameAndNumberForm returns an instance of *[NameAndNumberForm]
 alongside an error. Valid input forms are:
 
 • nameAndNumberForm (e.g.: "enterprise(1)"), or ...
 
 • numberForm (e.g.: 1)
 
-NumberForm components CANNOT be negative and CANNOT overflow
-NumberForm (uint128). Permitted input types are string, uint64
+[NumberForm] components CANNOT be negative and CANNOT overflow
+[NumberForm] (uint128). Permitted input types are string, uint64
 and (non-negative) int.
 */
 func NewNameAndNumberForm(x any) (nanf *NameAndNumberForm, err error) {