godoc additions and changes, changes to add-trie API

Author: Sean Foley

go.mod

@@ -18,4 +18,4 @@ module github.com/seancfoley/ipaddress-go
 
 go 1.18
 
-require github.com/seancfoley/bintree v1.3.0
+require github.com/seancfoley/bintree v1.3.1

ipaddr/addrtrie.go

@@ -402,7 +402,7 @@ func (trie *Trie[T]) String() string {
 	return trie.toTrie().String()
 }
 
-// AddedNodesTreeString provides a flattened version of the trie showing only the contained added nodes and their containment structure, which is non-binary.
+// AddedNodesTreeString provides a string showing a flattened version of the trie showing only the contained added nodes and their containment structure, which is non-binary.
 // The root node is included, which may or may not be added.
 func (trie *Trie[T]) AddedNodesTreeString() string {
 	return trie.toTrie().AddedNodesTreeString()
@@ -421,12 +421,16 @@ func (trie *Trie[T]) Add(addr T) bool {
 
 // AddNode adds the address to this trie.
 // The address must match the same type and version of any existing addresses already in the trie.
+//
+// If the argument is not a single address nor prefix block, this method will panic.
+// The [Partition] type can be used to convert the argument to single addresses and prefix blocks before calling this method.
+//
 // The new or existing node for the address is returned.
 func (trie *Trie[T]) AddNode(addr T) *TrieNode[T] {
 	return toAddressTrieNode(trie.addNode(addr))
 }
 
-// AddTrie adds nodes for the keys in the trie with the root node as the passed in node.
+// AddTrie adds nodes for the keys from the trie with the argument trie root.
 // AddTrie returns the sub-node in the trie where the added trie begins, where the first node of the added trie is located.
 func (trie *Trie[T]) AddTrie(added *TrieNode[T]) *TrieNode[T] {
 	return toAddressTrieNode(trie.addTrie(added.toBase()))
@@ -564,7 +568,7 @@ func (trie *Trie[T]) GetNode(addr T) *TrieNode[T] {
 // The [Partition] type can be used to convert the argument to single addresses and prefix blocks before calling this method.
 //
 // Use Contains to check for the existence of a given address in the trie,
-// as well as GetNode to search for all nodes including those not-added but also auto-generated nodes for subnet blocks.
+// as well as GetNode to search all nodes including those not-added but auto-generated for subnet blocks.
 func (trie *Trie[T]) GetAddedNode(addr T) *TrieNode[T] {
 	return toAddressTrieNode[T](trie.getAddedNode(addr))
 }
@@ -820,7 +824,7 @@ func (trie *AssociativeTrie[T, V]) String() string {
 	return trie.toTrie().String()
 }
 
-// AddedNodesTreeString provides a flattened version of the trie showing only the contained added nodes and their containment structure, which is non-binary.
+// AddedNodesTreeString provides a string showing a flattened version of the trie showing only the contained added nodes and their containment structure, which is non-binary.
 // The root node is included, which may or may not be added.
 func (trie *AssociativeTrie[T, V]) AddedNodesTreeString() string {
 	return trie.toTrie().AddedNodesTreeString()
@@ -838,12 +842,16 @@ func (trie *AssociativeTrie[T, V]) Add(addr T) bool {
 }
 
 // AddNode adds the address key to this trie.
+//
+// If the argument is not a single address nor prefix block, this method will panic.
+// The [Partition] type can be used to convert the argument to single addresses and prefix blocks before calling this method.
+//
 // The new or existing node for the address is returned.
 func (trie *AssociativeTrie[T, V]) AddNode(addr T) *AssociativeTrieNode[T, V] {
 	return toAssociativeTrieNode[T, V](trie.addNode(addr))
 }
 
-// AddTrie adds nodes for the keys in the trie with the root node as the passed in node.  To add both keys and values, use PutTrie.
+// AddTrie adds nodes for the keys from the trie with the argument trie root.  To add both keys and values, use PutTrie.
 // AddTrie returns the sub-node in the trie where the added trie begins, where the first node of the added trie is located.
 func (trie *AssociativeTrie[T, V]) AddTrie(added *AssociativeTrieNode[T, V]) *AssociativeTrieNode[T, V] {
 	return toAssociativeTrieNode[T, V](trie.addTrie(added.toBase()))
@@ -938,12 +946,12 @@ func (trie *AssociativeTrie[T, V]) LongestPrefixMatch(addr T) T {
 	return trie.longestPrefixMatch(addr)
 }
 
-// LongestPrefixMatchNode returns the node of the address with the longest matching prefix compared to the provided address.
+// LongestPrefixMatchNode returns the node of the address with the longest matching prefix compared to the provided address, or nil if no matching address.
 func (trie *AssociativeTrie[T, V]) LongestPrefixMatchNode(addr T) *AssociativeTrieNode[T, V] {
 	return toAssociativeTrieNode[T, V](trie.longestPrefixMatchNode(addr))
 }
 
-// ShortestPrefixMatch returns the address added to the trie with the shortest matching prefix compared to the provided address, or nil if no matching address.
+// ShortestPrefixMatch returns the node of the address added to the trie with the shortest matching prefix compared to the provided address, or nil if no matching address.
 func (trie *AssociativeTrie[T, V]) ShortestPrefixMatch(addr T) T {
 	return trie.shortestPrefixMatch(addr)
 }
@@ -1155,22 +1163,22 @@ func (trie *AssociativeTrie[T, V]) DeepEqual(other *AssociativeTrie[T, V]) bool
 	return trie.toBase().deepEqual(other.toBase())
 }
 
-// Put associates the specified value with the specified key in this map.
+// Put associates the specified value with the specified key in this trie.
 //
 // If the argument is not a single address nor prefix block, this method will panic.
 // The [Partition] type can be used to convert the argument to single addresses and prefix blocks before calling this method.
 //
-// If this map previously contained a mapping for a key,
+// If this trie previously contained a node for the given key,
 // the old value is replaced by the specified value, and false is returned along with the old value.
-// If this map did not previously contain a mapping for the key, true is returned along with a nil value.
-// The boolean return value allows you to distinguish whether the address was previously mapped to nil or not mapped at all.
+// If this trie did not previously contain a mapping for the key, true is returned along with the zero value.
+// The boolean return value allows you to distinguish whether the address was previously mapped to the zero value or not mapped at all.
 func (trie *AssociativeTrie[T, V]) Put(addr T, value V) (V, bool) {
 	return trie.put(addr, value)
 }
 
-// PutTrie adds nodes for the address keys and values in the trie with the root node as the passed in node.  To add only the keys, use AddTrie.
+// PutTrie adds nodes with the address keys and values from the trie with the argument trie root.  To add only the keys, use AddTrie.
 //
-// For each added in the given node that does not exist in the trie, a copy of each node will be made,
+// For each added node from the given trie that does not exist in this trie, a copy will be made,
 // the copy including the associated value, and the copy will be inserted into the trie.
 //
 // The address type/version of the keys must match.
@@ -1246,7 +1254,7 @@ func (trie *AssociativeTrie[T, V]) RemapIfAbsent(addr T, supplier func() V) *Ass
 // The [Partition] type can be used to convert the argument to single addresses and prefix blocks before calling this method.
 //
 // Returns the value for the given key.
-// Returns nil if the contains no mapping for that key or if the mapped value is nil.
+// Returns nil if the trie contains no mapping for that key or if the mapped value is nil.
 func (trie *AssociativeTrie[T, V]) Get(addr T) (V, bool) {
 	return trie.get(addr)
 }

ipaddr/cmd/main.go

@@ -578,6 +578,197 @@ func main() {
 	fmt.Println("dual trie 0x format")
 	fmt.Printf("%0x\n", dualTrie)
 
+	dualAddrs := []string{
+		"ff80::",
+		"ff80:8000::",
+		"ff80:8000::/24",
+		"ff80:8000::/32",
+		"ff80:8000:c000::/34",
+		"ff80:8000:c800::",
+		"ff80:8000:cc00::/38",
+		"ff80:8000:cc00::/40",
+		"0.0.0.0/0",
+		"128.0.0.0/8",
+		"128.0.0.0/16",
+		"128.0.128.0/24",
+		"128.0.128.0",
+		"2.2.3.128",
+		"2.2.3.0/24",
+		"2.2.4.0/24",
+		"2.2.7.0/24",
+		"2.2.4.3",
+		"1::ffff:2:3:5",
+		"1::ffff:2:3:4",
+		"1::ffff:2:3:6",
+	}
+	dualAssocTrie := ipaddr.DualIPv4v6AssociativeTries[string]{}
+	for _, addr := range dualAddrs {
+		addressStr := ipaddr.NewIPAddressString(addr)
+		address := addressStr.GetAddress()
+		dualAssocTrie.Put(address, address.String())
+	}
+	fmt.Println("original dual")
+	fmt.Println(dualAssocTrie)
+
+	dualAssocTrie2 := ipaddr.DualIPv4v6AssociativeTries[string]{}
+	dualAssocTrie2.AddTrie(dualAssocTrie.GetIPv4Trie().GetRoot())
+	dualAssocTrie2.AddTrie(dualAssocTrie.GetIPv6Trie().GetRoot())
+	fmt.Println("dual copied no vals")
+	fmt.Println(dualAssocTrie2)
+
+	dualAssocTrie3 := ipaddr.DualIPv4v6AssociativeTries[string]{}
+	dualAssocTrie3.PutTrie(dualAssocTrie.GetIPv4Trie().GetRoot())
+	dualAssocTrie3.PutTrie(dualAssocTrie.GetIPv6Trie().GetRoot())
+	fmt.Println("dual copied vals")
+	fmt.Println(dualAssocTrie3)
+
+	/*
+				original dual
+
+				○ * (21)
+				├─● 0.0.0.0/0 = 0.0.0.0/0 (10)
+				│ ├─○ 2.2.0.0/21 (5)
+				│ │ ├─● 2.2.3.0/24 = 2.2.3.0/24 (2)
+				│ │ │ └─● 2.2.3.128 = 2.2.3.128 (1)
+				│ │ └─○ 2.2.4.0/22 (3)
+				│ │   ├─● 2.2.4.0/24 = 2.2.4.0/24 (2)
+				│ │   │ └─● 2.2.4.3 = 2.2.4.3 (1)
+				│ │   └─● 2.2.7.0/24 = 2.2.7.0/24 (1)
+				│ └─● 128.0.0.0/8 = 128.0.0.0/8 (4)
+				│   └─● 128.0.0.0/16 = 128.0.0.0/16 (3)
+				│     └─● 128.0.128.0/24 = 128.0.128.0/24 (2)
+				│       └─● 128.0.128.0 = 128.0.128.0 (1)
+				└─○ ::/0 (11)
+				  ├─○ 1::ffff:2:3:4/126 (3)
+				  │ ├─○ 1::ffff:2:3:4/127 (2)
+				  │ │ ├─● 1::ffff:2:3:4 = 1::ffff:2:3:4 (1)
+				  │ │ └─● 1::ffff:2:3:5 = 1::ffff:2:3:5 (1)
+				  │ └─● 1::ffff:2:3:6 = 1::ffff:2:3:6 (1)
+				  └─○ ff80::/16 (8)
+				    ├─● ff80:: = ff80:: (1)
+				    └─● ff80:8000::/24 = ff80:8000::/24 (7)
+				      └─● ff80:8000::/32 = ff80:8000::/32 (6)
+				        ├─● ff80:8000:: = ff80:8000:: (1)
+				        └─● ff80:8000:c000::/34 = ff80:8000:c000::/34 (4)
+				          └─○ ff80:8000:c800::/37 (3)
+				            ├─● ff80:8000:c800:: = ff80:8000:c800:: (1)
+				            └─● ff80:8000:cc00::/38 = ff80:8000:cc00::/38 (2)
+				              └─● ff80:8000:cc00::/40 = ff80:8000:cc00::/40 (1)
+
+				dual copied no vals
+		the map is to strings, so you see the zero value of strings
+
+				○ * (21)
+				├─● 0.0.0.0/0 =  (10)
+				│ ├─○ 2.2.0.0/21 (5)
+				│ │ ├─● 2.2.3.0/24 =  (2)
+				│ │ │ └─● 2.2.3.128 =  (1)
+				│ │ └─○ 2.2.4.0/22 (3)
+				│ │   ├─● 2.2.4.0/24 =  (2)
+				│ │   │ └─● 2.2.4.3 =  (1)
+				│ │   └─● 2.2.7.0/24 =  (1)
+				│ └─● 128.0.0.0/8 =  (4)
+				│   └─● 128.0.0.0/16 =  (3)
+				│     └─● 128.0.128.0/24 =  (2)
+				│       └─● 128.0.128.0 =  (1)
+				└─○ ::/0 (11)
+				  ├─○ 1::ffff:2:3:4/126 (3)
+				  │ ├─○ 1::ffff:2:3:4/127 (2)
+				  │ │ ├─● 1::ffff:2:3:4 =  (1)
+				  │ │ └─● 1::ffff:2:3:5 =  (1)
+				  │ └─● 1::ffff:2:3:6 =  (1)
+				  └─○ ff80::/16 (8)
+				    ├─● ff80:: =  (1)
+				    └─● ff80:8000::/24 =  (7)
+				      └─● ff80:8000::/32 =  (6)
+				        ├─● ff80:8000:: =  (1)
+				        └─● ff80:8000:c000::/34 =  (4)
+				          └─○ ff80:8000:c800::/37 (3)
+				            ├─● ff80:8000:c800:: =  (1)
+				            └─● ff80:8000:cc00::/38 =  (2)
+				              └─● ff80:8000:cc00::/40 =  (1)
+				dual copied vals
+
+				○ * (21)
+				├─● 0.0.0.0/0 = 0.0.0.0/0 (10)
+				│ ├─○ 2.2.0.0/21 (5)
+				│ │ ├─● 2.2.3.0/24 = 2.2.3.0/24 (2)
+				│ │ │ └─● 2.2.3.128 = 2.2.3.128 (1)
+				│ │ └─○ 2.2.4.0/22 (3)
+				│ │   ├─● 2.2.4.0/24 = 2.2.4.0/24 (2)
+				│ │   │ └─● 2.2.4.3 = 2.2.4.3 (1)
+				│ │   └─● 2.2.7.0/24 = 2.2.7.0/24 (1)
+				│ └─● 128.0.0.0/8 = 128.0.0.0/8 (4)
+				│   └─● 128.0.0.0/16 = 128.0.0.0/16 (3)
+				│     └─● 128.0.128.0/24 = 128.0.128.0/24 (2)
+				│       └─● 128.0.128.0 = 128.0.128.0 (1)
+				└─○ ::/0 (11)
+				  ├─○ 1::ffff:2:3:4/126 (3)
+				  │ ├─○ 1::ffff:2:3:4/127 (2)
+				  │ │ ├─● 1::ffff:2:3:4 = 1::ffff:2:3:4 (1)
+				  │ │ └─● 1::ffff:2:3:5 = 1::ffff:2:3:5 (1)
+				  │ └─● 1::ffff:2:3:6 = 1::ffff:2:3:6 (1)
+				  └─○ ff80::/16 (8)
+				    ├─● ff80:: = ff80:: (1)
+				    └─● ff80:8000::/24 = ff80:8000::/24 (7)
+				      └─● ff80:8000::/32 = ff80:8000::/32 (6)
+				        ├─● ff80:8000:: = ff80:8000:: (1)
+				        └─● ff80:8000:c000::/34 = ff80:8000:c000::/34 (4)
+				          └─○ ff80:8000:c800::/37 (3)
+				            ├─● ff80:8000:c800:: = ff80:8000:c800:: (1)
+				            └─● ff80:8000:cc00::/38 = ff80:8000:cc00::/38 (2)
+				              └─● ff80:8000:cc00::/40 = ff80:8000:cc00::/40 (1)
+
+
+	*/
+
+	dualAssocTrie4 := ipaddr.DualIPv4v6AssociativeTries[(*ipaddr.IPAddress)]{}
+	for i, addr := range dualAddrs {
+		addressStr := ipaddr.NewIPAddressString(addr)
+		address := addressStr.GetAddress()
+		if i%2 == 0 {
+			dualAssocTrie4.Put(address, address)
+		} else {
+			dualAssocTrie4.Add(address)
+		}
+	}
+	fmt.Println("another dual")
+	fmt.Println(dualAssocTrie4)
+
+	/*
+		another dual
+
+		○ * (21)
+		├─● 0.0.0.0/0 = 0.0.0.0/0 (10)
+		│ ├─○ 2.2.0.0/21 (5)
+		│ │ ├─● 2.2.3.0/24 = 2.2.3.0/24 (2)
+		│ │ │ └─● 2.2.3.128 (1)
+		│ │ └─○ 2.2.4.0/22 (3)
+		│ │   ├─● 2.2.4.0/24 (2)
+		│ │   │ └─● 2.2.4.3 (1)
+		│ │   └─● 2.2.7.0/24 = 2.2.7.0/24 (1)
+		│ └─● 128.0.0.0/8 (4)
+		│   └─● 128.0.0.0/16 = 128.0.0.0/16 (3)
+		│     └─● 128.0.128.0/24 (2)
+		│       └─● 128.0.128.0 = 128.0.128.0 (1)
+		└─○ ::/0 (11)
+		  ├─○ 1::ffff:2:3:4/126 (3)
+		  │ ├─○ 1::ffff:2:3:4/127 (2)
+		  │ │ ├─● 1::ffff:2:3:4 (1)
+		  │ │ └─● 1::ffff:2:3:5 = 1::ffff:2:3:5 (1)
+		  │ └─● 1::ffff:2:3:6 = 1::ffff:2:3:6 (1)
+		  └─○ ff80::/16 (8)
+		    ├─● ff80:: = ff80:: (1)
+		    └─● ff80:8000::/24 = ff80:8000::/24 (7)
+		      └─● ff80:8000::/32 (6)
+		        ├─● ff80:8000:: (1)
+		        └─● ff80:8000:c000::/34 = ff80:8000:c000::/34 (4)
+		          └─○ ff80:8000:c800::/37 (3)
+		            ├─● ff80:8000:c800:: (1)
+		            └─● ff80:8000:cc00::/38 = ff80:8000:cc00::/38 (2)
+		              └─● ff80:8000:cc00::/40 (1)
+	*/
+
 	trie = ipaddr.IPv4AddressTrie{}
 	fmt.Printf("%v %d %d %t %t",
 		trie,