libraryDocs / ipv4

ipv4

librarysharedsource

Provides utility functions for working with Internet Protocol v4 addresses as integers.

Addresses are plain unsigned 32-bit integers (IPv4), so they can be compared, sorted and used as table keys directly.

Networks are described by a prefix length (0-32) or by a pair of network and broadcast addresses, which can be obtained with ipv4.cidr.

Classes & types

type

ipv4.NetworkVar

Fields

Name	Type	Description
`isLinkLocal`		Returns whether an IP address is a link-local address (`169.254.0.0/16`, RFC 3927).
`isLoopback`		Returns whether an IP address is a loopback address (`127.0.0.0/8`, RFC 1122).
`isMulticast`		Returns whether an IP address is a multicast address (`224.0.0.0/4`, RFC 5771).
`isReserved`		Returns whether an IP address is reserved for future use (`240.0.0.0/4`, RFC 1112).
`isShared`		Returns whether an IP address is in the shared address space used by carrier-grade NAT (`100.64.0.0/10`, RFC 6598).
`isBenchmarking`		Returns whether an IP address is reserved for network benchmarking (`198.18.0.0/15`, RFC 2544).

Functions

`ipv4.cdir`	Returns the network address and broadcast address for a given IPv4 address and CIDR prefix length.
`ipv4.cidr`	Returns the network address and broadcast address for a given IPv4 address and CIDR prefix length.
`ipv4.class`	Returns the classful network class of the given IP address.
`ipv4.count`	Returns the number of addresses in a network.
`ipv4.fromOctets`	Builds an IPv4 address from octets.
`ipv4.fromPrefix`	Returns the subnet mask address for a given CIDR prefix length.
`ipv4.inRange`	Returns whether an IP address is within a given network.
`ipv4.isBroadcast`	Returns whether an IP address is the limited broadcast address (255.255.255.255).
`ipv4.isDocumentation`	Returns whether an IP address is reserved for documentation and examples (192.0.2.0/24, 198.51.100.0/24 and 203.0.113.0…
`ipv4.isPrivate`	Returns whether the given IP address is private, i.e. not globally reachable.
`ipv4.isPublic`	Returns whether the given IP address is public, i.e. not private.
`ipv4.isUnspecified`	Returns whether an IP address is the unspecified address (0.0.0.0).
`ipv4.mask`	Returns the subnet mask address of a network, e.g. 255.255.255.0 for a /24 network.
`ipv4.octets`	Returns the octets of an IPv4 address, from the most significant to the least significant.
`ipv4.parse`	Parses an IPv4 address string with an optional CIDR prefix length, e.g. 192.168.0.1/24.
`ipv4.range`	Returns the first and last usable host addresses of a network.
`ipv4.reversePointer`	Returns the reverse DNS pointer (in-addr.arpa) of an IPv4 address.
`ipv4.toString`	Returns the string representation of an IPv4 address in dotted-decimal notation.
`ipv4.wildcard`	Returns the wildcard (inverted subnet mask) address of a network, e.g. 0.0.0.255 for a /24 network.

#ipv4.cdir

sharednodiscarddeprecatedsource

function ipv4.cdir(ip_address: IPv4, prefix_length: integer): IPv4, IPv4

Deprecated. Use ipv4.cidr instead, this is a misspelled alias kept for compatibility.

Returns the network address and broadcast address for a given IPv4 address and CIDR prefix length.

Parameters

Name	Type	Description
`ip_address`	`IPv4`	The IP address.
`prefix_length`	`integer`	The CIDR prefix length. <0-32>

Returns

Type	Name	Description
`IPv4`	`network_address`	The network (first) address.
`IPv4`	`broadcast_address`	The broadcast (last) address.

#ipv4.cidr

sharednodiscardsource

function ipv4.cidr(ip_address: IPv4, prefix_length: integer): IPv4, IPv4

Returns the network address and broadcast address for a given IPv4 address and CIDR prefix length.

lua

ipv4.cidr( ipv4.parse( "192.168.1.42/24" ) ) -- 192.168.1.0, 192.168.1.255

Parameters

Name	Type	Description
`ip_address`	`IPv4`	The IP address.
`prefix_length`	`integer`	The CIDR prefix length. <0-32>, throws an error if out of range.

Returns

Type	Name	Description
`IPv4`	`network_address`	The network (first) address.
`IPv4`	`broadcast_address`	The broadcast (last) address.

#ipv4.class

sharednodiscardsource

function ipv4.class(ip_address: IPv4): IPv4.Class

Returns the classful network class of the given IP address.

A: 0.0.0.0 - 127.255.255.255
B: 128.0.0.0 - 191.255.255.255
C: 192.0.0.0 - 223.255.255.255
D: 224.0.0.0 - 239.255.255.255 (multicast)
E: 240.0.0.0 - 255.255.255.255 (reserved)

Parameters

Name	Type	Description
`ip_address`	`IPv4`	The IP address.

Returns

Type	Name	Description
`IPv4.Class`	`class`	The class of the IP address.

#ipv4.count

sharednodiscardsource

function ipv4.count(network_address: IPv4, broadcast_address: IPv4): integer, integer

Returns the number of addresses in a network.

Parameters

Name	Type	Description
`network_address`	`IPv4`	The network address.
`broadcast_address`	`IPv4`	The broadcast address.

Returns

Type	Name	Description
`integer`	`total_count`	The total number of addresses in the network.
`integer`	`usable_count`	The number of usable host addresses in the network, excluding the network and broadcast addresses.

#ipv4.fromOctets

sharednodiscardsource

function ipv4.fromOctets(a: integer, b: integer, c: integer, d: integer): IPv4

Builds an IPv4 address from octets.

Octets out of the 0-255 range are clamped.

lua

ipv4.fromOctets( 127, 0, 0, 1 ) -- 0x7F000001

Parameters

Name	Type	Description
`a`	`integer`	The first octet. <0-255>
`b`	`integer`	The second octet. <0-255>
`c`	`integer`	The third octet. <0-255>
`d`	`integer`	The fourth octet. <0-255>

Returns

Type	Name	Description
`IPv4`	`ip_address`	The IP address.

#ipv4.fromPrefix

sharednodiscardsource

function ipv4.fromPrefix(prefix_length: integer): IPv4

Returns the subnet mask address for a given CIDR prefix length.

Prefix lengths out of the 0-32 range are clamped.

lua

ipv4.fromPrefix( 24 ) -- 0xFFFFFF00 (255.255.255.0)

Parameters

Name	Type	Description
`prefix_length`	`integer`	The CIDR prefix length. <0-32>

Returns

Type	Name	Description
`IPv4`	`mask_address`	The subnet mask address.

#ipv4.inRange

sharednodiscardsource

function ipv4.inRange(ip_address: IPv4, network_address: IPv4, broadcast_address: IPv4): boolean

Returns whether an IP address is within a given network.

Parameters

Name	Type	Description
`ip_address`	`IPv4`	The IP address.
`network_address`	`IPv4`	The network address.
`broadcast_address`	`IPv4`	The broadcast address.

Returns

Type	Name	Description
`boolean`	`in_range`	`true` if the IP address is within the network, `false` otherwise.

#ipv4.isBroadcast

sharednodiscardsource

function ipv4.isBroadcast(ip_address: IPv4): boolean

Returns whether an IP address is the limited broadcast address (255.255.255.255).

Parameters

Name	Type	Description
`ip_address`	`IPv4`	The IP address to check.

Returns

Type	Name	Description
`boolean`	`is_broadcast`	`true` if the IP address is the limited broadcast address, `false` otherwise.

#ipv4.isDocumentation

sharednodiscardsource

function ipv4.isDocumentation(ip_address: IPv4): boolean

Returns whether an IP address is reserved for documentation and examples (192.0.2.0/24, 198.51.100.0/24 and 203.0.113.0/24, RFC 5737).

Parameters

Name	Type	Description
`ip_address`	`IPv4`	The IP address to check.

Returns

Type	Name	Description
`boolean`	`is_documentation`	`true` if the IP address is a documentation address, `false` otherwise.

#ipv4.isPrivate

sharednodiscardsource

function ipv4.isPrivate(ip_address: IPv4): boolean

Returns whether the given IP address is private, i.e. not globally reachable.

Follows the IANA IPv4 Special-Purpose Address Registry, the same way as Python's ipaddress.IPv4Address.is_private.

The shared address space (100.64.0.0/10) is not considered private.

Parameters

Name	Type	Description
`ip_address`	`IPv4`	The IP address.

Returns

Type	Name	Description
`boolean`	`is_private`	`true` if the IP address is private, `false` otherwise.

#ipv4.isPublic

sharednodiscardsource

function ipv4.isPublic(ip_address: IPv4): boolean

Returns whether the given IP address is public, i.e. not private.

Note that the shared address space (100.64.0.0/10) is considered public by this function.

Parameters

Name	Type	Description
`ip_address`	`IPv4`	The IP address.

Returns

Type	Name	Description
`boolean`	`is_public`	`true` if the IP address is public, `false` otherwise.

#ipv4.isUnspecified

sharednodiscardsource

function ipv4.isUnspecified(ip_address: IPv4): boolean

Returns whether an IP address is the unspecified address (0.0.0.0).

Parameters

Name	Type	Description
`ip_address`	`IPv4`	The IP address to check.

Returns

Type	Name	Description
`boolean`	`is_unspecified`	`true` if the IP address is the unspecified address, `false` otherwise.

#ipv4.mask

sharednodiscardsource

function ipv4.mask(network_address: IPv4, broadcast_address: IPv4): IPv4

Returns the subnet mask address of a network, e.g. 255.255.255.0 for a /24 network.

Parameters

Name	Type	Description
`network_address`	`IPv4`	The network address.
`broadcast_address`	`IPv4`	The broadcast address.

Returns

Type	Name	Description
`IPv4`	`mask_address`	The subnet mask address.

#ipv4.octets

sharednodiscardsource

function ipv4.octets(ip_address: IPv4): integer, integer, integer, integer

Returns the octets of an IPv4 address, from the most significant to the least significant.

lua

ipv4.octets( 0x7F000001 ) -- 127, 0, 0, 1

Parameters

Name	Type	Description
`ip_address`	`IPv4`	The IP address.

Returns

Type	Name	Description
`integer`	`a`	The first octet. <0-255>
`integer`	`b`	The second octet. <0-255>
`integer`	`c`	The third octet. <0-255>
`integer`	`d`	The fourth octet. <0-255>

#ipv4.parse

sharednodiscardsource

function ipv4.parse(ipv4_str: string, start_position?: integer, end_position?: integer): IPv4, integer

Parses an IPv4 address string with an optional CIDR prefix length, e.g. 192.168.0.1/24.

Each octet supports:

Hexadecimal: prefixed with 0x or 0X (e.g., 0x7F), a bare 0x is 0.
Octal: prefixed with 0 followed by octal digits (e.g., 0177).
Decimal: standard base-10 digits (e.g., 127).

Addresses with fewer than 4 octets are accepted, the last given octet becomes the last octet of the address, e.g. 127.1 is parsed as 127.0.0.1.

The prefix length must be decimal digits only.

Throws an error if an octet is empty, contains invalid characters, is out of range or there are more than 4 octets, or if the prefix length is empty, contains invalid characters or is greater than 32.

Parameters

Name	Type	Description
`ipv4_str`	`string`	The IPv4 address string to parse.
`start_position`optional	`integer`	The start position in the ipv4 string.
`end_position`optional	`integer`	The end position in the ipv4 string.

Returns

Type	Name	Description
`IPv4`	`ip_address`	The parsed IP address.
`integer`	`prefix_length`	The CIDR prefix length. <0-32>, `32` if not specified.

#ipv4.range

sharednodiscardsource

function ipv4.range(network_address: IPv4, broadcast_address: IPv4): IPv4, IPv4

Returns the first and last usable host addresses of a network.

The network and broadcast addresses are excluded, so the result is meaningless for /31 and /32 networks.

Parameters

Name	Type	Description
`network_address`	`IPv4`	The network address.
`broadcast_address`	`IPv4`	The broadcast address.

Returns

Type	Name	Description
`IPv4`	`first`	The first usable address in the network.
`IPv4`	`last`	The last usable address in the network.

#ipv4.reversePointer

sharednodiscardsource

function ipv4.reversePointer(ip_address: IPv4): string

Returns the reverse DNS pointer (in-addr.arpa) of an IPv4 address.

lua

ipv4.reversePointer( 0x7F000001 ) -- "1.0.0.127.in-addr.arpa"

Parameters

Name	Type	Description
`ip_address`	`IPv4`	The IP address.

Returns

Type	Name	Description
`string`	`ptr`	The reverse DNS pointer of the IP address.

#ipv4.toString

sharednodiscardsource

function ipv4.toString(ip_address: IPv4): string

Returns the string representation of an IPv4 address in dotted-decimal notation.

lua

ipv4.toString( 0x7F000001 ) -- "127.0.0.1"

Parameters

Name	Type	Description
`ip_address`	`IPv4`	The IP address.

Returns

Type	Name	Description
`string`	`str`	The string representation of the IP address.

#ipv4.wildcard

sharednodiscardsource

function ipv4.wildcard(network_address: IPv4, broadcast_address: IPv4): IPv4

Returns the wildcard (inverted subnet mask) address of a network, e.g. 0.0.0.255 for a /24 network.

Parameters

Name	Type	Description
`network_address`	`IPv4`	The network address.
`broadcast_address`	`IPv4`	The broadcast address.

Returns

Type	Name	Description
`IPv4`	`wildcard_address`	The wildcard address.