renaming the standard methods

gaissmai · Jan 5, 2024 · c846a4e · c846a4e
1 parent 31526e8
commit c846a4e
Show file tree

Hide file tree

Showing 7 changed files with 131 additions and 128 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,3 +1,7 @@
+v0.3.0 ...
+    * API CHANGE!!!
+    * simplified the names of the standard methods 
+
 v0.2.1 Fri Dec 29 23:47:49 2023 +0100
     * update to latest extnetip version
 

diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@
 
 ## !!! ATTENTION, API HAS CHANGED
 
-The API has changed from v0.1.4 to v0.2.0.
+The API has changed from v2.0.0 to v0.3.0.
 
 ## Overview
 
@@ -28,17 +28,17 @@ but explicit for CIDRs. It has a narrow focus with a specialized API for IP rout
   type Table struct { // Has unexported fields.  }
     Table is an IPv4 and IPv6 routing table. The zero value is ready to use.
 
-  func (t Table) LookupIP(ip netip.Addr) (lpm netip.Prefix, value any, ok bool)
-  func (t Table) LookupCIDR(pfx netip.Prefix) (lpm netip.Prefix, value any, ok bool)
+  func (t Table) Lookup(ip netip.Addr) (lpm netip.Prefix, value any, ok bool)
+  func (t Table) LookupPrefix(pfx netip.Prefix) (lpm netip.Prefix, value any, ok bool)
 
-  func (t Table) Insert(pfx netip.Prefix, val any) *Table
-  func (t Table) Delete(cidr netip.Prefix) (*Table, bool)
-  func (t Table) Union(other *Table) *Table
-  func (t Table) Clone() *Table
+  func (t *Table) Insert(pfx netip.Prefix, val any)
+  func (t *Table) Delete(pfx netip.Prefix) bool
+  func (t *Table) Union(other *Table)
 
-  func (t *Table) InsertMutable(pfx netip.Prefix, val any)
-  func (t *Table) DeleteMutable(cidr netip.Prefix) bool
-  func (t *Table) UnionMutable(other *Table)
+  func (t Table) InsertImmutable(pfx netip.Prefix, val any) *Table
+  func (t Table) DeleteImmutable(pfx netip.Prefix) (*Table, bool)
+  func (t Table) UnionImmutable(other *Table) *Table
+  func (t Table) Clone() *Table
 
   func (t Table) String() string
   func (t Table) Fprint(w io.Writer) error

diff --git a/bench_test.go b/bench_test.go
@@ -29,7 +29,7 @@ func BenchmarkLookupIP(b *testing.B) {
 		rt := new(cidrtree.Table)
 		cidrs := shuffleFullTable(k)
 		for _, cidr := range cidrs {
-			rt.InsertMutable(cidr, nil)
+			rt.Insert(cidr, nil)
 		}
 		probe := cidrs[mrand.Intn(k)]
 		ip := probe.Addr()
@@ -38,7 +38,7 @@ func BenchmarkLookupIP(b *testing.B) {
 		b.ResetTimer()
 		b.Run(name, func(b *testing.B) {
 			for n := 0; n < b.N; n++ {
-				_, _, _ = rt.LookupIP(ip)
+				_, _, _ = rt.Lookup(ip)
 			}
 		})
 	}
@@ -49,15 +49,15 @@ func BenchmarkLookupCIDR(b *testing.B) {
 		rt := new(cidrtree.Table)
 		cidrs := shuffleFullTable(k)
 		for _, cidr := range cidrs {
-			rt.InsertMutable(cidr, nil)
+			rt.Insert(cidr, nil)
 		}
 		probe := cidrs[mrand.Intn(k)]
 		name := fmt.Sprintf("In%10s", intMap[k])
 
 		b.ResetTimer()
 		b.Run(name, func(b *testing.B) {
 			for n := 0; n < b.N; n++ {
-				_, _, _ = rt.LookupCIDR(probe)
+				_, _, _ = rt.LookupPrefix(probe)
 			}
 		})
 	}
@@ -71,7 +71,7 @@ func BenchmarkNew(b *testing.B) {
 			for n := 0; n < b.N; n++ {
 				rt := new(cidrtree.Table)
 				for i := range cidrs {
-					rt = rt.Insert(cidrs[i], nil)
+					rt = rt.InsertImmutable(cidrs[i], nil)
 				}
 			}
 		})
@@ -82,7 +82,7 @@ func BenchmarkClone(b *testing.B) {
 	for k := 1; k <= 1_000_000; k *= 10 {
 		rt := new(cidrtree.Table)
 		for _, cidr := range shuffleFullTable(k) {
-			rt = rt.Insert(cidr, nil)
+			rt = rt.InsertImmutable(cidr, nil)
 		}
 		name := fmt.Sprintf("%10s", intMap[k])
 		b.ResetTimer()
@@ -99,14 +99,14 @@ func BenchmarkInsert(b *testing.B) {
 		rt := new(cidrtree.Table)
 		cidrs := shuffleFullTable(k)
 		for _, cidr := range cidrs {
-			rt = rt.Insert(cidr, 0)
+			rt = rt.InsertImmutable(cidr, 0)
 		}
 		probe := routes[mrand.Intn(len(routes))]
 		name := fmt.Sprintf("Into%10s", intMap[k])
 		b.ResetTimer()
 		b.Run(name, func(b *testing.B) {
 			for n := 0; n < b.N; n++ {
-				_ = rt.Insert(probe.cidr, 0)
+				_ = rt.InsertImmutable(probe.cidr, 0)
 			}
 		})
 	}
@@ -117,14 +117,14 @@ func BenchmarkInsertMutable(b *testing.B) {
 		rt := new(cidrtree.Table)
 		cidrs := shuffleFullTable(k)
 		for _, cidr := range cidrs {
-			rt = rt.Insert(cidr, 0)
+			rt = rt.InsertImmutable(cidr, 0)
 		}
 		probe := routes[mrand.Intn(len(routes))]
 		name := fmt.Sprintf("Into%10s", intMap[k])
 		b.ResetTimer()
 		b.Run(name, func(b *testing.B) {
 			for n := 0; n < b.N; n++ {
-				rt.InsertMutable(probe.cidr, 0)
+				rt.Insert(probe.cidr, 0)
 			}
 		})
 	}
@@ -135,15 +135,15 @@ func BenchmarkDelete(b *testing.B) {
 		rt := new(cidrtree.Table)
 		cidrs := shuffleFullTable(k)
 		for _, cidr := range cidrs {
-			rt = rt.Insert(cidr, nil)
+			rt = rt.InsertImmutable(cidr, nil)
 		}
 		probe := routes[mrand.Intn(len(routes))]
 		name := fmt.Sprintf("From%10s", intMap[k])
 
 		b.ResetTimer()
 		b.Run(name, func(b *testing.B) {
 			for n := 0; n < b.N; n++ {
-				_, _ = rt.Delete(probe.cidr)
+				_, _ = rt.DeleteImmutable(probe.cidr)
 			}
 		})
 	}
@@ -154,15 +154,15 @@ func BenchmarkDeleteMutable(b *testing.B) {
 		rt := new(cidrtree.Table)
 		cidrs := shuffleFullTable(k)
 		for _, cidr := range cidrs {
-			rt = rt.Insert(cidr, nil)
+			rt = rt.InsertImmutable(cidr, nil)
 		}
 		probe := routes[mrand.Intn(len(routes))]
 		name := fmt.Sprintf("From%10s", intMap[k])
 
 		b.ResetTimer()
 		b.Run(name, func(b *testing.B) {
 			for n := 0; n < b.N; n++ {
-				_ = rt.DeleteMutable(probe.cidr)
+				_ = rt.Delete(probe.cidr)
 			}
 		})
 	}
@@ -173,7 +173,7 @@ func BenchmarkWalk(b *testing.B) {
 		rt := new(cidrtree.Table)
 		cidrs := shuffleFullTable(k)
 		for _, cidr := range cidrs {
-			rt.InsertMutable(cidr, nil)
+			rt.Insert(cidr, nil)
 		}
 		name := fmt.Sprintf("Walk%10s", intMap[k])
 

diff --git a/example_test.go b/example_test.go
@@ -28,7 +28,7 @@ var input = []netip.Prefix{
 func ExampleTable_Fprint() {
 	rtbl := new(cidrtree.Table)
 	for _, cidr := range input {
-		rtbl.InsertMutable(cidr, nil)
+		rtbl.Insert(cidr, nil)
 	}
 	rtbl.Fprint(os.Stdout)
 
@@ -59,7 +59,7 @@ func ExampleTable_Walk() {
 
 	rtbl := new(cidrtree.Table)
 	for _, cidr := range input {
-		rtbl.InsertMutable(cidr, nil)
+		rtbl.Insert(cidr, nil)
 	}
 	rtbl.Walk(cb)
 

diff --git a/treap.go b/treap.go
@@ -31,25 +31,25 @@ type node struct {
 	prio     uint64
 }
 
-// Insert adds pfx to the table with value val, returning a new table.
+// Insert adds pfx to the table with value val, changing the original table.
 // If pfx is already present in the table, its value is set to val.
-func (t Table) Insert(pfx netip.Prefix, val any) *Table {
+func (t *Table) Insert(pfx netip.Prefix, val any) {
 	if pfx.Addr().Is4() {
-		t.root4 = t.root4.insert(makeNode(pfx, val), true)
-		return &t
+		t.root4 = t.root4.insert(makeNode(pfx, val), false)
+		return
 	}
-	t.root6 = t.root6.insert(makeNode(pfx, val), true)
-	return &t
+	t.root6 = t.root6.insert(makeNode(pfx, val), false)
 }
 
-// InsertMutable adds pfx to the table with value val, changing the original table.
+// InsertImmutable adds pfx to the table with value val, returning a new table.
 // If pfx is already present in the table, its value is set to val.
-func (t *Table) InsertMutable(pfx netip.Prefix, val any) {
+func (t Table) InsertImmutable(pfx netip.Prefix, val any) *Table {
 	if pfx.Addr().Is4() {
-		t.root4 = t.root4.insert(makeNode(pfx, val), false)
-		return
+		t.root4 = t.root4.insert(makeNode(pfx, val), true)
+		return &t
 	}
-	t.root6 = t.root6.insert(makeNode(pfx, val), false)
+	t.root6 = t.root6.insert(makeNode(pfx, val), true)
+	return &t
 }
 
 // insert into treap, changing nodes are copied, new treap is returned,
@@ -124,19 +124,19 @@ func (n *node) insert(m *node, immutable bool) *node {
 	return n
 }
 
-// Delete removes the cdir if it exists, returns the new table and true, false if not found.
-func (t Table) Delete(cidr netip.Prefix) (*Table, bool) {
-	cidr = cidr.Masked() // always canonicalize!
+// DeleteImmutable removes the prefix if it exists, returns the new table and true, false if not found.
+func (t Table) DeleteImmutable(pfx netip.Prefix) (*Table, bool) {
+	pfx = pfx.Masked() // always canonicalize!
 
-	is4 := cidr.Addr().Is4()
+	is4 := pfx.Addr().Is4()
 
 	n := t.root6
 	if is4 {
 		n = t.root4
 	}
 
 	// split/join must be immutable
-	l, m, r := n.split(cidr, true)
+	l, m, r := n.split(pfx, true)
 	n = l.join(r, true)
 
 	if is4 {
@@ -149,20 +149,19 @@ func (t Table) Delete(cidr netip.Prefix) (*Table, bool) {
 	return &t, ok
 }
 
-// DeleteMutable removes the cidr from table, returns true if it exists, false otherwise.
-// If the original table does not need to be preserved then this is much faster than the immutable delete.
-func (t *Table) DeleteMutable(cidr netip.Prefix) bool {
-	cidr = cidr.Masked() // always canonicalize!
+// Delete removes the prefix from table, returns true if it exists, false otherwise.
+func (t *Table) Delete(pfx netip.Prefix) bool {
+	pfx = pfx.Masked() // always canonicalize!
 
-	is4 := cidr.Addr().Is4()
+	is4 := pfx.Addr().Is4()
 
 	n := t.root6
 	if is4 {
 		n = t.root4
 	}
 
 	// split/join is mutable
-	l, m, r := n.split(cidr, false)
+	l, m, r := n.split(pfx, false)
 	n = l.join(r, false)
 
 	if is4 {
@@ -174,17 +173,17 @@ func (t *Table) DeleteMutable(cidr netip.Prefix) bool {
 	return m != nil
 }
 
-// Union combines any two tables immutable and returns the combined table.
+// UnionImmutable combines any two tables immutable and returns the combined table.
 // If there are duplicate entries, the value is taken from the other table.
-func (t Table) Union(other *Table) *Table {
+func (t Table) UnionImmutable(other *Table) *Table {
 	t.root4 = t.root4.union(other.root4, true, true)
 	t.root6 = t.root6.union(other.root6, true, true)
 	return &t
 }
 
-// UnionMutable combines two tables, changing the receiver table.
+// Union combines two tables, changing the receiver table.
 // If there are duplicate entries, the value is taken from the other table.
-func (t *Table) UnionMutable(other *Table) {
+func (t *Table) Union(other *Table) {
 	t.root4 = t.root4.union(other.root4, true, false)
 	t.root6 = t.root6.union(other.root6, true, false)
 }
@@ -265,10 +264,10 @@ func (n *node) walk(cb func(netip.Prefix, any) bool) bool {
 	return true
 }
 
-// LookupIP returns the longest-prefix-match (lpm) for given ip.
+// Lookup returns the longest-prefix-match (lpm) for given ip.
 // If the ip isn't covered by any CIDR, the zero value and false is returned.
 //
-// LookupIP does not allocate memory.
+// Lookup does not allocate memory.
 //
 //	example:
 //
@@ -291,10 +290,10 @@ func (n *node) walk(cb func(netip.Prefix, any) bool) bool {
 //	   ├─ fe80::/10
 //	   └─ ff00::/8
 //
-//	    rtbl.LookupIP(42.0.0.0)             returns (netip.Prefix{}, <nil>,  false)
-//	    rtbl.LookupIP(10.0.1.17)            returns (10.0.1.0/24,    <value>, true)
-//	    rtbl.LookupIP(2001:7c0:3100:1::111) returns (2000::/3,       <value>, true)
-func (t Table) LookupIP(ip netip.Addr) (lpm netip.Prefix, value any, ok bool) {
+//	    rtbl.Lookup(42.0.0.0)             returns (netip.Prefix{}, <nil>,  false)
+//	    rtbl.Lookup(10.0.1.17)            returns (10.0.1.0/24,    <value>, true)
+//	    rtbl.Lookup(2001:7c0:3100:1::111) returns (2000::/3,       <value>, true)
+func (t Table) Lookup(ip netip.Addr) (lpm netip.Prefix, value any, ok bool) {
 	if ip.Is4() {
 		// don't return the depth
 		lpm, value, ok, _ = t.root4.lpmIP(ip, 0)
@@ -343,10 +342,10 @@ func (n *node) lpmIP(ip netip.Addr, depth int) (lpm netip.Prefix, value any, ok
 	return n.left.lpmIP(ip, depth+1)
 }
 
-// LookupCIDR returns the longest-prefix-match (lpm) for given prefix.
+// LookupPrefix returns the longest-prefix-match (lpm) for given prefix.
 // If the prefix isn't equal or covered by any CIDR in the table, the zero value and false is returned.
 //
-// LookupCIDR does not allocate memory.
+// LookupPrefix does not allocate memory.
 //
 //	example:
 //
@@ -369,11 +368,11 @@ func (n *node) lpmIP(ip netip.Addr, depth int) (lpm netip.Prefix, value any, ok
 //	   ├─ fe80::/10
 //	   └─ ff00::/8
 //
-//	    rtbl.LookupCIDR(42.0.0.0/8)         returns (netip.Prefix{}, <nil>,  false)
-//	    rtbl.LookupCIDR(10.0.1.0/29)        returns (10.0.1.0/24,    <value>, true)
-//	    rtbl.LookupCIDR(192.168.0.0/16)     returns (192.168.0.0/16, <value>, true)
-//	    rtbl.LookupCIDR(2001:7c0:3100::/40) returns (2000::/3,       <value>, true)
-func (t Table) LookupCIDR(pfx netip.Prefix) (lpm netip.Prefix, value any, ok bool) {
+//	    rtbl.LookupPrefix(42.0.0.0/8)         returns (netip.Prefix{}, <nil>,  false)
+//	    rtbl.LookupPrefix(10.0.1.0/29)        returns (10.0.1.0/24,    <value>, true)
+//	    rtbl.LookupPrefix(192.168.0.0/16)     returns (192.168.0.0/16, <value>, true)
+//	    rtbl.LookupPrefix(2001:7c0:3100::/40) returns (2000::/3,       <value>, true)
+func (t Table) LookupPrefix(pfx netip.Prefix) (lpm netip.Prefix, value any, ok bool) {
 	if pfx.Addr().Is4() {
 		// don't return the depth
 		lpm, value, ok, _ = t.root4.lpmCIDR(pfx, 0)