Create an IPv4 address from four octets. The first argument is the most significant octet. The last argument is the least significant. Since IP addresses are commonly written using dot-decimal notation, this is the recommended way to create an IP address. Additionally, it is used for the Show and Read instances of IPv4 to help keep things readable in GHCi.

>>> let addr = ipv4 192 168 1 1
>>> addr
ipv4 192 168 1 1
>>> getIPv4 addr
3232235777

An alias for the ipv4 smart constructor.

An uncurried variant of fromOctets.

Convert an IPv4 address into a quadruple of octets. The first element in the quadruple is the most significant octet. The last element is the least significant octet.

The IP address representing any host.

>>> any
ipv4 0 0 0 0

The local loopback IP address.

>>> loopback
ipv4 127 0 0 1

A useful and common alias for loopback.

>>> localhost
ipv4 127 0 0 1

The broadcast IP address.

>>> broadcast
ipv4 255 255 255 255

Checks to see if the IPv4 address belongs to a private network. The three private networks that are checked are 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16.

Checks to see if the IPv4 address belongs to a reserved network. This includes the three private networks that private checks along with several other ranges that are not used on the public Internet. The implementation of this function is optimized.

Checks to see if the IPv4 address is publicly routable.

public x == not (reserved x)

Encode an IPv4 address to Text using dot-decimal notation:

>>> T.putStrLn (encode (ipv4 192 168 2 47))
192.168.2.47

Decode an IPv4 address.

>>> decode "192.168.2.47"
Just (ipv4 192 168 2 47)

>>> decode "10.100.256.256"
Nothing

Encode an IPv4 address to a text Builder.

>>> builder (ipv4 192 168 2 47)
"192.168.2.47"

Parse an IPv4 address using a Reader.

>>> reader "192.168.2.47"
Right (ipv4 192 168 2 47,"")

>>> reader "192.168.2.470"
Left "All octets in an IPv4 address must be between 0 and 255"

Parse an IPv4 address using a Parser.

>>> AT.parseOnly parser "192.168.2.47"
Right (ipv4 192 168 2 47)

>>> AT.parseOnly parser "192.168.2.470"
Left "Failed reading: All octets in an IPv4 address must be between 0 and 255"

Decode ShortText as an IPv4 address.

>>> decodeShort "192.168.3.48"
Just (ipv4 192 168 3 48)

Encode an IPv4 address as ShortText.

>>> encodeShort (ipv4 192 168 5 99)
"192.168.5.99"

Encode an IPv4 address to a UTF-8 encoded ByteString.

>>> encodeUtf8 (ipv4 192 168 2 47)
"192.168.2.47"

Decode a UTF8-encoded ByteString into an IPv4.

>>> decodeUtf8 "192.168.2.47"
Just (ipv4 192 168 2 47)

Currently not terribly efficient since the implementation re-encodes the argument as UTF-16 text before decoding that IPv4 address from that. PRs to fix this are welcome.

Encode an IPv4 as a bytestring Builder

>>> Builder.toLazyByteString (builderUtf8 (fromOctets 192 168 2 12))
"192.168.2.12"

Parse an IPv4 using a Parser.

>>> AB.parseOnly parserUtf8 "192.168.2.47"
Right (ipv4 192 168 2 47)

>>> AB.parseOnly parserUtf8 "192.168.2.470"
Left "Failed reading: All octets in an ipv4 address must be between 0 and 255"

Decode UTF-8-encoded Bytes into an IPv4 address.

>>> decodeUtf8Bytes (Bytes.fromAsciiString "127.0.0.1")
Just (ipv4 127 0 0 1)

Parse UTF-8-encoded Bytes as an IPv4 address.

>>> Parser.parseBytes (parserUtf8Bytes ()) (Bytes.fromAsciiString "10.0.1.254")
Success (Slice {offset = 10, length = 0, value = ipv4 10 0 1 254})

Encode an IPv4 address as a unbounded byte array builder.

>>> Chunks.concat (UB.run 1 (byteArrayBuilderUtf8 (fromOctets 192 168 2 13)))
[0x31,0x39,0x32,0x2e,0x31,0x36,0x38,0x2e,0x32,0x2e,0x31,0x33]

Note that period is encoded by UTF-8 as 0x2e.

Encode an IPv4 address as a bounded byte array builder.

>>> BB.run Nat.constant (boundedBuilderUtf8 (fromOctets 192 168 2 14))
[0x31, 0x39, 0x32, 0x2e, 0x31, 0x36, 0x38, 0x2e, 0x32, 0x2e, 0x31, 0x34]

Note that period is encoded by UTF-8 as 0x2e.

Encode an IPv4 as a String.

Decode an IPv4 from a String.

Print an IPv4 using the textual encoding.

Smart constructor for IPv4Range. Ensures the mask is appropriately sized and sets masked bits in the IPv4 to zero.

Given an inclusive lower and upper ip address, create the smallest IPv4Range that contains the two. This is helpful in situations where input given as a range like 192.168.16.0-192.168.19.255 needs to be handled. This makes the range broader if it cannot be represented in CIDR notation.

>>> printRange $ fromBounds (fromOctets 192 168 16 0) (fromOctets 192 168 19 255)
192.168.16.0/22
>>> printRange $ fromBounds (fromOctets 10 0 5 7) (fromOctets 10 0 5 14)
10.0.5.0/28

Normalize an IPv4Range. The first result of this is that the IPv4 inside the IPv4Range is changed so that the insignificant bits are zeroed out. For example:

>>> printRange $ normalize $ IPv4Range (fromOctets 192 168 1 19) 24
192.168.1.0/24
>>> printRange $ normalize $ IPv4Range (fromOctets 192 168 1 163) 28
192.168.1.160/28

The second effect of this is that the mask length is lowered to be 32 or smaller. Working with IPv4Ranges that have not been normalized does not cause any issues for this library, although other applications may reject such ranges (especially those with a mask length above 32).

Note that normalize is idempotent, that is:

normalize r == (normalize . normalize) r

Checks to see if an IPv4 address belongs in the IPv4Range.

>>> let ip = fromOctets 10 10 1 92
>>> contains (IPv4Range (fromOctets 10 0 0 0) 8) ip
True
>>> contains (IPv4Range (fromOctets 10 11 0 0) 16) ip
False

Typically, element-testing functions are written to take the element as the first argument and the set as the second argument. This is intentionally written the other way for better performance when iterating over a collection. For example, you might test elements in a list for membership like this:

>>> let r = IPv4Range (fromOctets 10 10 10 6) 31
>>> mapM_ (P.print . contains r) (take 5 $ iterate succ $ fromOctets 10 10 10 5)
False
True
True
False
False

The implementation of contains ensures that (with GHC), the bitmask creation and range normalization only occur once in the above example. They are reused as the list is iterated.

This is provided to mirror the interface provided by Data.Set. It behaves just like contains but with flipped arguments.

member ip r == contains r ip

The inclusive lower bound of an IPv4Range. This is conventionally understood to be the broadcast address of a subnet. For example:

>>> T.putStrLn $ encode $ lowerInclusive $ IPv4Range (ipv4 10 10 1 160) 25
10.10.1.128

Note that the lower bound of a normalized IPv4Range is simply the ip address of the range:

lowerInclusive r == ipv4RangeBase (normalize r)

The inclusive upper bound of an IPv4Range.

>>> T.putStrLn $ encode $ upperInclusive $ IPv4Range (ipv4 10 10 1 160) 25
10.10.1.255

Convert an IPv4Range into a list of the IPv4 addresses that are in it.

>>> let r = IPv4Range (fromOctets 192 168 1 8) 30
>>> mapM_ (T.putStrLn . encode) (toList r)
192.168.1.8
192.168.1.9
192.168.1.10
192.168.1.11

A stream-polymorphic generator over an IPv4Range. For more information, see How to build library-agnostic streaming sources.

The RFC1918 24-bit block. Subnet mask: 10.0.0.0/8

The RFC1918 20-bit block. Subnet mask: 172.16.0.0/12

The RFC1918 16-bit block. Subnet mask: 192.168.0.0/16

Encode an IPv4Range as Text.

>>> encodeRange (IPv4Range (ipv4 172 16 0 0) 12)
"172.16.0.0/12"

Decode an IPv4Range from Text.

>>> decodeRange "172.16.0.0/12"
Just (IPv4Range {ipv4RangeBase = ipv4 172 16 0 0, ipv4RangeLength = 12})
>>> decodeRange "192.168.25.254/16"
Just (IPv4Range {ipv4RangeBase = ipv4 192 168 0 0, ipv4RangeLength = 16})

Encode an IPv4Range to a Builder.

>>> builderRange (IPv4Range (ipv4 172 16 0 0) 12)
"172.16.0.0/12"

Parse an IPv4Range using a Parser.

>>> AT.parseOnly parserRange "192.168.25.254/16"
Right (IPv4Range {ipv4RangeBase = ipv4 192 168 0 0, ipv4RangeLength = 16})

Print an IPv4Range. Helper function that exists mostly for testing purposes.

Parse UTF-8-encoded Bytes into an IPv4Range. This requires the mask to be present.

>>> maybe (putStrLn "nope") printRange $ Parser.parseBytesMaybe (parserRangeUtf8Bytes ()) (Bytes.fromAsciiString "192.168.0.0/16")
192.168.0.0/16
>>> maybe (putStrLn "nope") printRange $ Parser.parseBytesMaybe (parserRangeUtf8Bytes ()) (Bytes.fromAsciiString "10.10.10.1")
nope

See parserRangeUtf8BytesLenient for a variant that treats a missing mask as a /32 mask.

Variant of parserRangeUtf8Bytes that allows the mask to be omitted. An omitted mask is treated as a /32 mask.

>>> maybe (putStrLn "nope") printRange $ Parser.parseBytesMaybe (parserRangeUtf8BytesLenient ()) (Bytes.fromAsciiString "192.168.0.0/16")
192.168.0.0/16
>>> maybe (putStrLn "nope") printRange $ Parser.parseBytesMaybe (parserRangeUtf8BytesLenient ()) (Bytes.fromAsciiString "10.10.10.1")
10.10.10.1/32

A 32-bit Internet Protocol version 4 address. To use this with the network library, it is necessary to use Network.Socket.htonl to convert the underlying Word32 from host byte order to network byte order.

Unboxed variant of IPv4. Before GHC 8.10, this is implemented as a type synonym. Portable use of this type requires treating it as though it were opaque. Use box and unbox to convert between this and the lifted IPv4.

The length should be between 0 and 32. These bounds are inclusive. This expectation is not in any way enforced by this library because it does not cause errors. A mask length greater than 32 will be treated as if it were 32.

Convert an unboxed IPv4 address to a boxed one.

Convert a boxed IPv4 address to an unboxed one.

Variant of parserUtf8Bytes with unboxed result type.