ip

package
v0.0.9-alpha Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 21, 2024 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Overview

IP addresses as numeric types. IP address Family types act as factories for Address values - obtain using V4 or V6. Interfaces in this package cannot be implemented outside it.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func FromBigInt 

func FromBigInt[A Address[A]](family Family[A], i *big.Int) (A, error)

Converts big integer to Address. Returns error if value out of range for address family.

func FromBytes 

func FromBytes(address ...byte) (any, error)

Parse IP address bytes from unknown family

Example 
package main

import (
	"github.com/ipfreely-uk/go/ip"
)

func main() {
	address, err := ip.FromBytes(192, 0, 2, 1)
	if err != nil {
		println("Not address:", err)
	}
	switch a := address.(type) {
	case ip.Addr4:
		println("IPv4 address:", a.String())
	case ip.Addr6:
		println("IPv6 address", a.String())
	}
}

Output:

func MaxAddress 

func MaxAddress[A Address[A]](fam Family[A]) A

Maximum address for family

func MinAddress 

func MinAddress[A Address[A]](fam Family[A]) A

Zero address for family.

func MustFromBytes 

func MustFromBytes(address ...byte) any

As FromBytes but panics on error

Example 
package main

import (
	"net/netip"

	"github.com/ipfreely-uk/go/ip"
)

func main() {
	nip := netip.MustParseAddr("2001:db8::")

	address := ip.MustFromBytes(nip.AsSlice()...)

	switch a := address.(type) {
	case ip.Addr4:
		println("IPv4 address:", a.String())
	case ip.Addr6:
		println("IPv6 address", a.String())
	}
}

Output:

func MustParse 

func MustParse[A Address[A]](family Family[A], candidate string) A

As Parse but panics on error

func MustParseUnknown 

func MustParseUnknown(candidate string) any

As ParseUnknown but panics on error

func Next 

func Next[A Address[A]](address A) A

Increments argument by one with overflow

func Parse 

func Parse[A Address[A]](family Family[A], candidate string) (A, error)

Parses address string

func ParseUnknown 

func ParseUnknown(candidate string) (any, error)

Parse IP address string from unknown family

Example 
package main

import (
	"github.com/ipfreely-uk/go/ip"
)

func main() {
	examples := []string{"2001:db8::1", "192.0.2.1", "foobar"}
	for _, s := range examples {
		address, err := ip.ParseUnknown(s)
		if err != nil {
			println("Not address:", err)
		}
		switch a := address.(type) {
		case ip.Addr4:
			println("IPv4 address:", a.String())
		case ip.Addr6:
			println("IPv6 address:", a.String())
		}
	}
}

Output:

func Prev 

func Prev[A Address[A]](address A) A

Decrements argument by one with underflow

func ToBigInt 

func ToBigInt[A Address[A]](address A) *big.Int

Converts any Address to big integer

Example 
package main

import (
	"math/big"

	"github.com/dustin/go-humanize"
	"github.com/ipfreely-uk/go/ip"
)

func main() {
	printNumberOfAddresses(ip.MinAddress(ip.V4()), ip.MaxAddress(ip.V4()))
	printNumberOfAddresses(ip.MinAddress(ip.V6()), ip.MaxAddress(ip.V6()))
}

func printNumberOfAddresses[A ip.Address[A]](first, last A) {
	diff := last.Subtract(first)

	n := ip.ToBigInt(diff)
	rangeSize := n.Add(n, big.NewInt(1))

	println(first.String(), "-", last.String(), "=", humanize.BigComma(rangeSize))
}

Output:

Types

type Addr4 

type Addr4 struct {
	// contains filtered or unexported fields
}

Immutable 32bit unsigned integer IP Address representation

func (Addr4) Add 

func (a Addr4) Add(addend Addr4) Addr4

Addition with overflow

func (Addr4) And 

func (a Addr4) And(operand Addr4) Addr4

Bitwise AND

func (Addr4) Bytes 

func (a Addr4) Bytes() []byte

Returns 4 byte slice

func (Addr4) Compare 

func (a Addr4) Compare(other Addr4) int

func (Addr4) Divide 

func (a Addr4) Divide(denominator Addr4) Addr4

Division

func (Addr4) Family 

func (a Addr4) Family() Family[Addr4]

Returns V4

func (Addr4) Float64 

func (a Addr4) Float64() float64

func (Addr4) LeadingZeros 

func (a Addr4) LeadingZeros() int

func (Addr4) Mod 

func (a Addr4) Mod(denominator Addr4) Addr4

Modulus

func (Addr4) Multiply 

func (a Addr4) Multiply(multiplicand Addr4) Addr4

Multiplication with overflow

func (Addr4) Not 

func (a Addr4) Not() Addr4

Bitwise NOT

func (Addr4) Or 

func (a Addr4) Or(operand Addr4) Addr4

Bitwise OR

func (Addr4) Shift 

func (a Addr4) Shift(bits int) Addr4

Bitwise shift

func (Addr4) String 

func (a Addr4) String() string

func (Addr4) Subtract 

func (a Addr4) Subtract(addend Addr4) Addr4

Subtraction with underflow

func (Addr4) TrailingZeros 

func (a Addr4) TrailingZeros() int

func (Addr4) Xor 

func (a Addr4) Xor(operand Addr4) Addr4

Bitwise XOR

type Addr6 

type Addr6 struct {
	// contains filtered or unexported fields
}

Immutable 128bit unsigned integer IP Address representation

func (Addr6) Add 

func (a Addr6) Add(addend Addr6) Addr6

func (Addr6) And 

func (a Addr6) And(operand Addr6) Addr6

func (Addr6) Bytes 

func (a Addr6) Bytes() []byte

func (Addr6) Compare 

func (a Addr6) Compare(other Addr6) int

func (Addr6) Divide 

func (a Addr6) Divide(denominator Addr6) Addr6

func (Addr6) Family 

func (a Addr6) Family() Family[Addr6]

func (Addr6) Float64 

func (a Addr6) Float64() float64

func (Addr6) LeadingZeros 

func (a Addr6) LeadingZeros() int

func (Addr6) Mod 

func (a Addr6) Mod(denominator Addr6) Addr6

func (Addr6) Multiply 

func (a Addr6) Multiply(multiplicand Addr6) Addr6

func (Addr6) Not 

func (a Addr6) Not() Addr6

func (Addr6) Or 

func (a Addr6) Or(operand Addr6) Addr6

func (Addr6) Shift 

func (a Addr6) Shift(bits int) Addr6

func (Addr6) String 

func (a Addr6) String() string

func (Addr6) Subtract 

func (a Addr6) Subtract(subtrahend Addr6) Addr6

func (Addr6) TrailingZeros 

func (a Addr6) TrailingZeros() int

func (Addr6) Xor 

func (a Addr6) Xor(operand Addr6) Addr6

type Address 

type Address[A any] interface {

	// IP address family - [V4] or [V6]
	Family() Family[A]
	// Address as bytes
	Bytes() []byte
	// Addition with overflow
	Add(A) A
	// Subtraction with overflow
	Subtract(A) A
	// Multiplication with overflow
	Multiply(A) A
	// Division
	Divide(A) A
	// Modulus
	Mod(A) A
	// Bitwise NOT
	Not() A
	// Bitwise AND
	And(A) A
	// Bitwise OR
	Or(A) A
	// Bitwise XOR
	Xor(A) A
	// Bit shift. Use negative int for left shift; use positive int for right shift.
	Shift(int) A
	// Returns 1 if operand is less than this.
	// Returns -1 if operand is more than this.
	// Returns 0 if operand is equal.
	Compare(A) int
	// Equivalent to math/bits.LeadingZeros
	LeadingZeros() int
	// Equivalent to math/bits.TrailingZeros
	TrailingZeros() int
	// Canonical string form
	String() string
	// Approximation to float64
	Float64() float64
	// contains filtered or unexported methods
}

Generic IP address type.

type Family 

type Family[A any] interface {

	// IP address version
	Version() Version
	// Address width in bits - 32 or 128
	Width() int
	// Create address from bytes.
	// Returns error if slice is not [Width]/8 bytes.
	FromBytes(...byte) (A, error)
	// As FromBytes but panics on error
	MustFromBytes(...byte) A
	// Create address from unsigned integer.
	// All values are valid.
	FromInt(i uint32) A
	// contains filtered or unexported methods
}

IP address family. Obtain via V4 or V6.

func V4 

func V4() Family[Addr4]

IPv4 family of addresses

Example 
package main

import (
	"github.com/ipfreely-uk/go/ip"
)

func main() {
	address := ip.V4().MustFromBytes(203, 0, 113, 1)
	println(address.String())
}

Output:

func V6 

func V6() Family[Addr6]

IPv6 family of addresses

Example 
package main

import (
	"github.com/ipfreely-uk/go/ip"
)

func main() {
	family := ip.V6()
	bytes := make([]byte, family.Width()/8)
	bytes[0] = 0x20
	bytes[1] = 0x01
	bytes[2] = 0xDB
	bytes[3] = 0x80
	bytes[15] = 1

	address := family.MustFromBytes(bytes...)

	println(address.String())
}

Output:

type Version 

type Version uint8

Internet protocol version 

const (
	// Internet protocol version 4
	Version4 Version = 4
	// Internet protocol version 6
	Version6 Version = 6
)

Source Files

View all Source files

Directories

Path Synopsis
Compare ordered values
 Compare ordered values
Network ranges and IP address sets.
 Network ranges and IP address sets.
cidr
RFC-4632 Classless Inter-domain Routing notation handling https://www.rfc-editor.org/rfc/rfc4632
 RFC-4632 Classless Inter-domain Routing notation handling https://www.rfc-editor.org/rfc/rfc4632
Functions for working with subnets
 Functions for working with subnets

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.