Editing Module:IP/doc (section)

== Subnet ==

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

<syntaxhighlight lang="lua">
local subnet = Subnet.new(cidrString)
</syntaxhighlight>

<var>cidrString</var> must be a valid IPv4 or IPv6 [[CIDR]] string.

Subnet objects can be compared for equality:

<syntaxhighlight lang="lua">
Subnet.new('1.2.3.0/24') == Subnet.new('1.2.3.0/24')                           -- true
Subnet.new('1.2.3.0/24') == Subnet.new('1.2.3.0/25')                           -- false
Subnet.new('1.2.3.0/24') == Subnet.new('2001:db8::ff00:12:0/112')              -- false
Subnet.new('2001:db8::ff00:12:0/112') == Subnet.new('2001:db8::ff00:12:0/112') -- true
Subnet.new('2001:db8:0:0:0:0:0:0/112') == Subnet.new('2001:db8::/112')         -- true
</syntaxhighlight>

You can use tostring on them (this is equivalent to [[#getCIDR|getCIDR]]):
<syntaxhighlight lang="lua">
tostring(Subnet.new('1.2.3.0/24'))               -- "1.2.3.0/24"
tostring(Subnet.new('2001:db8::ff00:12:0/112'))  -- "2001:db8::ff00:12:0/112"
tostring(Subnet.new('2001:db8:0:0:0:0:0:0/112')) -- "2001:db8::/112"
</syntaxhighlight>

You can also concatenate them:
<syntaxhighlight lang="lua">
Subnet.new('1.2.3.0/24') .. ' foo'                   -- "1.2.3.0/24 foo"
Subnet.new('1.2.3.0/24') .. Subnet.new('4.5.6.0/24') -- "1.2.3.0/244.5.6.0/24"
</syntaxhighlight>

Subnet objects have several methods, outlined below.

=== getPrefix ===

<syntaxhighlight lang="lua">
subnet:getPrefix()
</syntaxhighlight>

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

Examples:

<syntaxhighlight lang="lua">
Subnet.new('1.2.3.0/24'):getPrefix()              -- Equivalent to IPAddress.new('1.2.3.0')
Subnet.new('2001:db8::ff00:12:0/112'):getPrefix() -- Equivalent to IPAddress.new('2001:db8::ff00:12:0')
</syntaxhighlight>

=== getHighestIP ===

<syntaxhighlight lang="lua">
subnet:getHighestIP()
</syntaxhighlight>

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

Examples:

<syntaxhighlight lang="lua">
Subnet.new('1.2.3.0/24'):getHighestIP()              -- Equivalent to IPAddress.new('1.2.3.255')
Subnet.new('2001:db8::ff00:12:0/112'):getHighestIP() -- Equivalent to IPAddress.new('2001:db8::ff00:12:ffff')
</syntaxhighlight>

=== getBitLength ===

<syntaxhighlight lang="lua">
subnet:getBitLength()
</syntaxhighlight>

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:

<syntaxhighlight lang="lua">
Subnet.new('1.2.3.0/24'):getBitLength()              -- 24
Subnet.new('2001:db8::ff00:12:0/112'):getBitLength() -- 112
</syntaxhighlight>

=== getCIDR ===

<syntaxhighlight lang="lua">
subnet:getCIDR()
</syntaxhighlight>

Returns a [[CIDR]] string representation of the subnet.

Examples:

<syntaxhighlight lang="lua">
Subnet.new('1.2.3.0/24'):getCIDR()               -- "1.2.3.0/24"
Subnet.new('2001:db8::ff00:12:0/112'):getCIDR()  -- "2001:db8::ff00:12:0/112"
Subnet.new('2001:db8:0:0:0:0:0:0/112'):getCIDR() -- "2001:db8::/112"
</syntaxhighlight>

=== getVersion ===

<syntaxhighlight lang="lua">
subnet:getVersion()
</syntaxhighlight>

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

Examples:

<syntaxhighlight lang="lua">
Subnet.new('1.2.3.0/24'):getVersion()              -- "IPv4"
Subnet.new('2001:db8::ff00:12:0/112'):getVersion() -- "IPv6"
</syntaxhighlight>

=== isIPv4 ===

<syntaxhighlight lang="lua">
subnet:isIPv4()
</syntaxhighlight>

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

Examples:

<syntaxhighlight lang="lua">
Subnet.new('1.2.3.0/24'):isIPv4()              -- true
Subnet.new('2001:db8::ff00:12:0/112'):isIPv4() -- false
</syntaxhighlight>

=== isIPv6 ===

<syntaxhighlight lang="lua">
subnet:isIPv6()
</syntaxhighlight>

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

Examples:

<syntaxhighlight lang="lua">
Subnet.new('1.2.3.0/24'):isIPv6()              -- false
Subnet.new('2001:db8::ff00:12:0/112'):isIPv6() -- true
</syntaxhighlight>

=== containsIP ===

<syntaxhighlight lang="lua">
subnet:containsIP(ip)
</syntaxhighlight>

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

Examples:

<syntaxhighlight lang="lua">
Subnet.new('1.2.3.0/24'):containsIP('1.2.3.4')                             -- true
Subnet.new('1.2.3.0/24'):containsIP('1.2.4.4')                             -- false
Subnet.new('1.2.3.0/24'):containsIP(IPAddress.new('1.2.3.4'))              -- true
Subnet.new('2001:db8::ff00:12:0/112'):containsIP('2001:db8::ff00:12:3456') -- true
</syntaxhighlight>

=== overlapsSubnet ===

<syntaxhighlight lang="lua">
subnet:overlapsSubnet(subnet)
</syntaxhighlight>

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

Examples:

<syntaxhighlight lang="lua">
Subnet.new('1.2.3.0/24'):overlapsSubnet('1.2.0.0/16')                         -- true
Subnet.new('1.2.3.0/24'):overlapsSubnet('1.2.12.0/22')                        -- false
Subnet.new('1.2.3.0/24'):overlapsSubnet(Subnet.new('1.2.0.0/16'))             -- true
Subnet.new('2001:db8::ff00:12:0/112'):overlapsSubnet('2001:db8::ff00:0:0/96') -- true
</syntaxhighlight>

=== walk ===

<syntaxhighlight lang="lua">
subnet:walk()
</syntaxhighlight>

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

Examples:

<syntaxhighlight lang="lua">
for ipAddress in Subnet.new('192.168.0.0/30'):walk() do
	mw.log(tostring(ipAddress))
end
-- 192.168.0.0
-- 192.168.0.1
-- 192.168.0.2
-- 192.168.0.3
</syntaxhighlight>