Editing Module:IP/doc (section)

== IPAddress ==

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

<syntaxhighlight lang="lua">
local ipAddress = IPAddress.new(ipString)
</syntaxhighlight>

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

Examples:

<syntaxhighlight lang="lua">
local ipv4Address = IPAddress.new('1.2.3.4')
local ipv6Address = IPAddress.new('2001:db8::ff00:12:3456')
</syntaxhighlight>

IPAddress objects can be compared with relational operators:

<syntaxhighlight lang="lua">
-- Equality
IPAddress.new('1.2.3.4') == IPAddress.new('1.2.3.4') -- true
IPAddress.new('1.2.3.4') == IPAddress.new('1.2.3.5') -- false

-- Less than / greater than
IPAddress.new('1.2.3.4') < IPAddress.new('1.2.3.5')  -- true
IPAddress.new('1.2.3.4') > IPAddress.new('1.2.3.5')  -- false
IPAddress.new('1.2.3.4') <= IPAddress.new('1.2.3.5') -- true
IPAddress.new('1.2.3.4') <= IPAddress.new('1.2.3.4') -- true
</syntaxhighlight>

You can use tostring on them (this is equivalent to using [[#getIP|getIP]]):

<syntaxhighlight lang="lua">
tostring(IPAddress.new('1.2.3.4'))                -- "1.2.3.4"
tostring(IPAddress.new('2001:db8::ff00:12:3456')) -- "2001:db8::ff00:12:3456"

-- Expanded IPv6 addresses are abbreviated:
tostring(IPAddress.new('2001:db8:0:0:0:0:0:0'))   -- "2001:db8::"
</syntaxhighlight>

You can also concatenate them:

<syntaxhighlight lang="lua">
IPAddress.new('1.2.3.4') .. ' foo'                   -- "1.2.3.4 foo"
IPAddress.new('1.2.3.4') .. IPAddress.new('5.6.7.8') -- "1.2.3.45.6.7.8"
</syntaxhighlight>

IPAddress objects have several methods, outlined below.

=== getIP ===

<syntaxhighlight lang="lua">
ipAddress:getIP()
</syntaxhighlight>

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

Examples:

<syntaxhighlight lang="lua">
IPAddress.new('1.2.3.4'):getIP()                -- "1.2.3.4"
IPAddress.new('2001:db8::ff00:12:3456'):getIP() -- "2001:db8::ff00:12:3456"
IPAddress.new('2001:db8:0:0:0:0:0:0'):getIP()   -- "2001:db8::"
</syntaxhighlight>

=== getVersion ===

<syntaxhighlight lang="lua">
ipAddress: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">
IPAddress.new('1.2.3.4'):getVersion()                -- "IPv4"
IPAddress.new('2001:db8::ff00:12:3456'):getVersion() -- "IPv6"
</syntaxhighlight>

=== isIPv4 ===

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

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

Examples:

<syntaxhighlight lang="lua">
IPAddress.new('1.2.3.4'):isIPv4()                -- true
IPAddress.new('2001:db8::ff00:12:3456'):isIPv4() -- false
</syntaxhighlight>

=== isIPv6 ===

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

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

Examples:

<syntaxhighlight lang="lua">
IPAddress.new('1.2.3.4'):isIPv6()                -- false
IPAddress.new('2001:db8::ff00:12:3456'):isIPv6() -- true
</syntaxhighlight>

=== isInSubnet ===

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

Returns true if the IP address is in the subnet <var>subnet</var>, and false otherwise. <var>subnet</var> may be a [[#Subnet|Subnet object]] or a [[CIDR]] string.

Examples:

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

=== getSubnet ===

<syntaxhighlight lang="lua">
ipAddress:getSubnet(bitLength)
</syntaxhighlight>

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

Examples:

<syntaxhighlight lang="lua">
IPAddress.new('1.2.3.4'):getSubnet(24) -- Equivalent to Subnet.new('1.2.3.0/24')
</syntaxhighlight>

=== getNextIP ===

<syntaxhighlight lang="lua">
ipAddress:getNextIP()
</syntaxhighlight>

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:

<syntaxhighlight lang="lua">
IPAddress.new('1.2.3.4'):getNextIP()                -- Equivalent to IPAddress.new('1.2.3.5')
IPAddress.new('2001:db8::ff00:12:3456'):getNextIP() -- Equivalent to IPAddress.new('2001:db8::ff00:12:3457')
IPAddress.new('255.255.255.255'):getNextIP()        -- Equivalent to IPAddress.new('0.0.0.0')
</syntaxhighlight>

=== getPreviousIP ===

<syntaxhighlight lang="lua">
ipAddress:getPreviousIP()
</syntaxhighlight>

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:

<syntaxhighlight lang="lua">
IPAddress.new('1.2.3.4'):getPreviousIP()                -- Equivalent to IPAddress.new('1.2.3.3')
IPAddress.new('2001:db8::ff00:12:3456'):getPreviousIP() -- Equivalent to IPAddress.new('2001:db8::ff00:12:3455')
IPAddress.new('0.0.0.0'):getPreviousIP()                -- Equivalent to IPAddress.new('255.255.255.255')
</syntaxhighlight>