Specs

new(prefix()) :: t()

Creates a new prefix from address tuples/binaries or raises ArgumentError.

Use:

• a binary in CIDR-notation,
• a binary in EUI-48 or EUI-64 format (EUI-64 must be using hyphens !)
• an {ip_address/0, length}-tuple to truncate the bits to length.
• an ipv4 or ipv6 ip_address/0 tuple directly for a full address, or
• a Pfx.t/0 struct to create a new Pfx struct.

To avoid a possible ArgumentError, use Pfx.parse/1 or Pfx.parse/2 instead. To avoid applying the mask, use Pfx.address/1 then apply Pfx.new/1 if needed.

Binaries are processed by :inet.parse_address/1, so be aware of IPv4 shorthand notations that may yield surprising results, since digits are taken to be:

• d1.d2.d3.d4 -> d1.d2.d3.d4 (full address)
• d1.d2.d3 -> d1.d2.0.d3
• d1.d2 -> d1.0.0.d2
• d1 -> 0.0.0.d1

If :inet.parse_address/1 fails to create an IPv4 or IPv6 address, an attempt is made to parse the binary as an EUI-48 or EUI-64 MAC address. Parsing EUI's is somewhat relaxed, punctuation chars "-", ":", "." are interchangeable, but their positions should be correct.

Note that EUI-64's that use ":"-punctuation are indistinguishable from IPv6, e.g. "11:22:33:44:55:66:77:88". Use from_mac/1 when in doubt about punctuations used while parsing MAC addresses.

Examples

# from CIDR strings
iex> new("10.10.0.0")
%Pfx{bits: <<10, 10, 0, 0>>, maxlen: 32}

iex> new("10.10.10.10/16")
%Pfx{bits: <<10, 10>>, maxlen: 32}

# ipv6 string
iex> new("acdc:1976::/32")
%Pfx{bits: <<0xacdc::16, 0x1976::16>>, maxlen: 128}

# from an {address-tuple, length}
iex> new({{0xacdc, 0x1976, 0, 0, 0, 0, 0, 0}, 32})
%Pfx{bits: <<0xacdc::16, 0x1976::16>>, maxlen: 128}

iex> new({{10, 10, 0, 0}, 16})
%Pfx{bits: <<10, 10>>, maxlen: 32}

# from an address-tuple
iex> new({10, 10, 0, 0})
%Pfx{bits: <<10, 10, 0, 0>>, maxlen: 32}

# from a struct
iex> new(%Pfx{bits: <<10, 10>>, maxlen: 32})
%Pfx{bits: <<10, 10>>, maxlen: 32}

# 10.10/16 is interpreted as 10.0.0.10/16 (!)
iex> new("10.10/16")
%Pfx{bits: <<10, 0>>, maxlen: 32}

# some EUI-48's
iex> new("aa:bb:cc:dd:ee:ff")
%Pfx{bits: <<0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff>>, maxlen: 48}

iex> new("aa-bb-cc-dd-ee-ff")
%Pfx{bits: <<0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff>>, maxlen: 48}

iex> new("aabb.ccdd.eeff")
%Pfx{bits: <<0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff>>, maxlen: 48}

# keep only OUI
iex> new("aa-bb-cc-dd-ee-ff/24")
%Pfx{bits: <<0xaa, 0xbb, 0xcc>>, maxlen: 48}

# some EUI-64's
iex> new("11-22-33-44-55-66-77-88")
%Pfx{bits: <<0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88>>, maxlen: 64}

iex> new("1122.3344.5566.7788")
%Pfx{bits: <<0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88>>, maxlen: 64}

# but note the maxlen here ...
iex> new("11:22:33:44:55:66:77:88")
%Pfx{bits: <<0x11::16, 0x22::16, 0x33::16, 0x44::16, 0x55::16, 0x66::16, 0x77::16, 0x88::16>>, maxlen: 128}

iex> try do
...>   new("1.1.1.256")
...> rescue
...>   x -> Exception.message(x)
...> end
"expected an ipv4/ipv6 CIDR or EUI-48/64 string, got \"1.1.1.256\""

Specs

new(t() | bitstring(), non_neg_integer()) :: t()

Creates a new Pfx.t/0-prefix.

Create a new prefix from:

• from a bitstring and a maximum length, truncating the bits as needed,
• from a Pfx.t/0 prefix and a new maxlen, again truncating as needed,

Examples

iex> new(<<10, 10>>, 32)
%Pfx{bits: <<10, 10>>, maxlen: 32}

iex> new(<<10, 10>>, 8)
%Pfx{bits: <<10>>, maxlen: 8}

# changing 'maxlen' usually changes the prefix' meaning
iex> new(%Pfx{bits: <<10, 10>>, maxlen: 32}, 128)
%Pfx{bits: <<10, 10>>, maxlen: 128}