clean the API

example_test.go

@@ -7,7 +7,7 @@ import (
 )
 
 func mustParse(s string) iprange.IPRange {
-	b, err := iprange.Parse(s)
+	b, err := iprange.FromString(s)
 	if err != nil {
 		panic(err)
 	}
@@ -19,13 +19,13 @@ func isPrefix(p iprange.IPRange) bool {
 	return ok
 }
 
-func ExampleParse() {
+func ExampleFromString() {
 	for _, s := range []string{
 		"fe80::1-fe80::2",         // as range
 		"10.0.0.0-11.255.255.255", // as range but true CIDR, see output
 		"",                        // invalid
 	} {
-		r, _ := iprange.Parse(s)
+		r, _ := iprange.FromString(s)
 		fmt.Printf("%-20s isPrefix: %5v\n", r, isPrefix(r))
 	}
 
@@ -59,7 +59,7 @@ func ExampleMerge() {
 		"fe80:0000:0000:0000:fe2d:5eff:fef0:fc64/128",
 		"fe80::/10",
 	} {
-		b, _ := iprange.Parse(s)
+		b, _ := iprange.FromString(s)
 		rs = append(rs, b)
 	}
 
@@ -71,15 +71,15 @@ func ExampleMerge() {
 }
 
 func ExampleIPRange_Prefixes() {
-	r, _ := iprange.Parse("10.0.0.6-10.0.0.99")
+	r, _ := iprange.FromString("10.0.0.6-10.0.0.99")
 	fmt.Printf("%s -> Prefixes:\n", r)
 	for _, p := range r.Prefixes() {
 		fmt.Println(p)
 	}
 
 	fmt.Println()
 
-	r, _ = iprange.Parse("2001:db8::affe-2001:db8::ffff")
+	r, _ = iprange.FromString("2001:db8::affe-2001:db8::ffff")
 	fmt.Printf("%s -> Prefixes:\n", r)
 	for _, p := range r.Prefixes() {
 		fmt.Println(p)
@@ -101,7 +101,7 @@ func ExampleIPRange_Prefixes() {
 }
 
 func ExampleIPRange_Remove_v4() {
-	outer, _ := iprange.Parse("192.168.2.0/24")
+	outer, _ := iprange.FromString("192.168.2.0/24")
 	inner := []iprange.IPRange{
 		mustParse("192.168.2.0/26"),
 		mustParse("192.168.2.240-192.168.2.249"),
@@ -123,7 +123,7 @@ func ExampleIPRange_Remove_v4() {
 }
 
 func ExampleIPRange_Remove_v6() {
-	outer, _ := iprange.Parse("2001:db8:de00::/40")
+	outer, _ := iprange.FromString("2001:db8:de00::/40")
 	inner := []iprange.IPRange{mustParse("2001:db8:dea0::/44")}
 
 	fmt.Printf("outer: %v\n", outer)

iprange.go

@@ -38,7 +38,7 @@ var (
 	invalidStr = "invalid IPRange"
 )
 
-// Parse returns the input string as type IPRange.
+// FromString parses the input string and returns an IPRange.
 //
 // Returns an error on invalid input.
 //
@@ -56,7 +56,7 @@ var (
 // IP addresses as input are converted to /32 or /128 ranges.
 //
 // The hard part is done by netip.ParseAddr and netip.ParsePrefix from the stdlib.
-func Parse(s string) (IPRange, error) {
+func FromString(s string) (IPRange, error) {
 	if s == "" {
 		return zeroValue, errors.New("empty string")
 	}
@@ -183,7 +183,7 @@ func (r IPRange) String() string {
 // Merge adjacent and overlapping IPRanges.
 //
 // Remove dups and subsets and invalid ranges, returns the remaining IPRanges sorted.
-func Merge(in []IPRange) []IPRange {
+func Merge(in []IPRange) (out []IPRange) {
 	if len(in) == 0 {
 		return nil
 	}
@@ -193,21 +193,19 @@ func Merge(in []IPRange) []IPRange {
 	copy(rs, in)
 	sortRanges(rs)
 
-	var result []IPRange
-
 	for _, this := range rs {
 		if this == zeroValue {
 			continue
 		}
 
 		// starting point
-		if result == nil {
-			result = append(result, this)
+		if out == nil {
+			out = append(out, this)
 			continue
 		}
 
 		// take ptr to last result item
-		topic := &result[len(result)-1]
+		topic := &out[len(out)-1]
 
 		// compare topic with this range
 		// case order is VERY important!
@@ -217,7 +215,7 @@ func Merge(in []IPRange) []IPRange {
 			topic.last = this.last
 		case topic.last.Less(this.first):
 			// ranges are disjoint [f...l]....[f...l]
-			result = append(result, this)
+			out = append(out, this)
 		case topic.last.Less(this.last):
 			// partial overlap [f......l]
 			//                       [f....l]
@@ -227,7 +225,7 @@ func Merge(in []IPRange) []IPRange {
 		}
 	}
 
-	return result
+	return
 }
 
 func (a IPRange) isDisjunct(b IPRange) bool {
@@ -245,7 +243,7 @@ func (a IPRange) covers(b IPRange) bool {
 }
 
 // Remove the slice of IPRanges from receiver, returns the remaining IPRanges.
-func (r IPRange) Remove(in []IPRange) []IPRange {
+func (r IPRange) Remove(in []IPRange) (out []IPRange) {
 	if r == zeroValue {
 		return nil
 	}
@@ -265,7 +263,6 @@ func (r IPRange) Remove(in []IPRange) []IPRange {
 		return []IPRange{r}
 	}
 
-	var result []IPRange
 	for _, d := range merged {
 		// case order is important!
 		switch {
@@ -274,31 +271,31 @@ func (r IPRange) Remove(in []IPRange) []IPRange {
 			continue
 		case d.covers(r):
 			// d covers r, d masks the rest
-			return result
+			return out
 		case d.first.Compare(r.first) <= 0:
 			// left overlap, move cursor
 			r.first = d.last.Next()
 		case d.first.Compare(r.first) > 0:
 			// right overlap, save [r.first, d.first-1)
-			result = append(result, IPRange{r.first, d.first.Prev()})
+			out = append(out, IPRange{r.first, d.first.Prev()})
 			// new r, (d.last, r.last]
 			r.first = d.last.Next()
 		default:
 			panic("logic error")
 		}
 		// overflow from d.last.Next()
 		if !r.first.IsValid() {
-			return result
+			return out
 		}
 		// cursor moved behind r.last
 		if r.last.Less(r.first) {
-			return result
+			return out
 		}
 	}
 	// save the rest
-	result = append(result, r)
+	out = append(out, r)
 
-	return result
+	return out
 }
 
 // #########################################################################################
@@ -348,7 +345,7 @@ func (r *IPRange) UnmarshalText(text []byte) error {
 	}
 
 	var err error
-	*r, err = Parse(string(text))
+	*r, err = FromString(string(text))
 	return err
 }
 

iprange_test.go

@@ -21,7 +21,7 @@ var (
 	}
 
 	mustParseIPRange = func(s string) iprange.IPRange {
-		r, err := iprange.Parse(s)
+		r, err := iprange.FromString(s)
 		if err != nil {
 			panic(err)
 		}
@@ -117,7 +117,7 @@ func TestParseRangeInvalid(t *testing.T) {
 	}
 
 	for _, s := range tests {
-		if r, err := iprange.Parse(s); err == nil {
+		if r, err := iprange.FromString(s); err == nil {
 			t.Fatalf("ParseRange(%s); got %q, want err; got %v", s, r, err)
 		}
 	}
@@ -358,7 +358,7 @@ func TestRemoveCornerCases(t *testing.T) {
 }
 
 func TestRemoveIANAv6(t *testing.T) {
-	b, _ := iprange.Parse("::/0")
+	b, _ := iprange.FromString("::/0")
 
 	var inner []iprange.IPRange
 	for _, s := range []string{