Module:IP/doc

Module:IP is a library for working with IP addresses and subnets. It can handle both IPv4 and IPv6. The library exports four classes, IPAddress, Subnet, IPv4Collection, and IPv6Collection.

IPAddress
The IPAddress class is used to work with single IP addresses. To create a new IPAddress object:

The ipString variable can be a valid IPv4 or IPv6 address.

Examples:

If a non-IP string or an invalid IP address is passed to the function, that returns an error. If you want to check whether a given string is an IP address and continue the procedure in the caller module, use pcall.

IPAddress objects can be compared with relational operators:

You can use tostring on them (this is equivalent to using getIP):

You can also concatenate them:

IPAddress objects have several methods, outlined below.

getIP
Returns a string representation of the IP address. IPv6 addresses are abbreviated if possible.

Examples:

getVersion
Returns the version of the IP protocol being used. This is "IPv4" for IPv4 addresses, and "IPv6" for IPv6 addresses.

Examples:

isIPv4
Returns true if the IP address is an IPv4 address, and false otherwise.

Examples:

isIPv6
Returns true if the IP address is an IPv6 address, and false otherwise.

Examples:

isInSubnet
Returns true if the IP address is in the subnet subnet, and false otherwise. subnet may be a Subnet object or a CIDR string.

Examples:

getSubnet
Returns a Subnet object for the subnet with a bit length of bitLength which contains the current IP. The bitLength parameter must be an integer between 0 and 32 for IPv4 addresses, or an integer between 0 and 128 for IPv6 addresses.

Examples:

getNextIP
Returns a new IPAddress object equivalent to the current IP address incremented by one. The IPv4 address "255.255.255.255" rolls around to "0.0.0.0", and the IPv6 address "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff" rolls around to "::".

Examples:

getPreviousIP
Returns a new IPAddress object equivalent to the current IP address decremented by one. The IPv4 address "0.0.0.0" rolls around to "255.255.255.255", and the IPv6 address "::" rolls around to "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff".

Examples:

Subnet
The Subnet class is used to work with subnetworks of IPv4 or IPv6 addresses. To create a new Subnet object:

cidrString must be a valid IPv4 or IPv6 CIDR string.

Subnet objects can be compared for equality:

You can use tostring on them (this is equivalent to getCIDR):

You can also concatenate them:

Subnet objects have several methods, outlined below.

getPrefix
Returns an IPAddress object for the lowest IP address in the subnet.

Examples:

getHighestIP
Returns an IPAddress object for the highest IP address in the subnet.

Examples:

getBitLength
Returns the bit length of the subnet. This is an integer between 0 and 32 for IPv4 addresses, or an integer between 0 and 128 for IPv6 addresses.

Examples:

getCIDR
Returns a CIDR string representation of the subnet.

Examples:

getVersion
Returns the version of the IP protocol being used. This is "IPv4" for IPv4 addresses, and "IPv6" for IPv6 addresses.

Examples:

isIPv4
Returns true if the subnet is using IPv4, and false otherwise.

Examples:

isIPv6
Returns true if the subnet is using IPv6, and false otherwise.

Examples:

containsIP
Returns true if the subnet contains the IP address ip, and false otherwise. ip can be an IP address string, or an IPAddress object.

Examples:

overlapsSubnet
Returns true if the current subnet overlaps with subnet, and false otherwise. subnet can be a CIDR string or a subnet object.

Examples:

walk
The walk method iterates over all of the IPAddress objects in the subnet.

Examples:

IPv4Collection
The IPv4Collection class is used to work with several different IPv4 addresses and IPv4 subnets. To create a new IPv4Collection object:

IPv4Collection objects have several methods, outlined below.

getVersion
Returns the string "IPv4".

addIP
Adds an IP to the collection. The IP can be either a string or an IPAddress object.

Examples:

This method is chainable:

addSubnet
Adds a subnet to the collection. The subnet can be either a CIDR string or a Subnet object.

Examples:

This method is chainable:

addFromString
Extracts any IPv4 addresses and IPv4 CIDR subnets from str and adds them to the collection. Any text that is not an IPv4 address or CIDR subnet is ignored.

Examples:

This method is chainable:

containsIP
Returns true if the collection contains the specified IP; otherwise returns false. The ip parameter can be a string or an IPAddress object.

Examples:

getRanges
Returns a sorted array of IP pairs equivalent to the collection. Each IP pair is an array representing a contiguous range of IP addresses from pair[1] to pair[2] inclusive. pair[1] and pair[2] are IPAddress objects.

Examples:

overlapsSubnet
Returns true, obj if subnet overlaps this collection, where obj is the first IPAddress or Subnet object overlapping the subnet. Otherwise, returns false. subnet can be a CIDR string or a Subnet object.

Examples:

IPv6Collection
The IPv6Collection class is used to work with several different IPv6 addresses and IPv6 subnets. IPv6Collection objects are directly analogous to IPv4Collection objects: they contain the same methods and work the same way, but all IP addresses and subnets added to it must be IPv6, not IPv4.

To create a new IPv6Collection object: