Editing Module:IP/doc (section)

== IPv4Collection ==

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

<syntaxhighlight lang="lua">
local collection = IPv4Collection.new()
</syntaxhighlight>

IPv4Collection objects have several methods, outlined below.

=== getVersion ===

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

Returns the string "IPv4".

=== addIP ===

<syntaxhighlight lang="lua">
collection:addIP(ip)
</syntaxhighlight>

Adds an IP to the collection. The IP can be either a string or an [[#IPAddress|IPAddress]] object.

Examples:

<syntaxhighlight lang="lua">
collection:addIP('1.2.3.4')
collection:addIP(IPAddress.new('1.2.3.4'))
</syntaxhighlight>

This method is chainable:

<syntaxhighlight lang="lua">
collection:addIP('1.2.3.4'):addIP('5.6.7.8')
</syntaxhighlight>

=== addSubnet ===

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

Adds a subnet to the collection. The subnet can be either a [[CIDR]] string or a [[#Subnet|Subnet]] object.

Examples:

<syntaxhighlight lang="lua">
collection:addSubnet('1.2.3.0/24')
collection:addSubnet(Subnet.new('1.2.3.0/24'))
</syntaxhighlight>

This method is chainable:

<syntaxhighlight lang="lua">
collection:addSubnet('1.2.0.0/24'):addSubnet('1.2.1.0/24')
</syntaxhighlight>

=== addFromString ===

<syntaxhighlight lang="lua">
collection:addFromString(str)
</syntaxhighlight>

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

Examples:

<syntaxhighlight lang="lua">
collection:addFromString('Add some IPs and subnets: 1.2.3.4 1.2.3.5 2001:0::f foo 1.2.4.0/24')
</syntaxhighlight>

This method is chainable:

<syntaxhighlight lang="lua">
collection:addFromString('foo 1.2.3.4'):addFromString('bar 5.6.7.8')
</syntaxhighlight>

=== containsIP ===

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

Returns true if the collection contains the specified IP; otherwise returns false. The <var>ip</var> parameter can be a string or an [[#IPAddress|IPAddress]] object.

Examples:

<syntaxhighlight lang="lua">
collection:containsIP('1.2.3.4')
collection:containsIP(IPAddress.new('1.2.3.4'))
</syntaxhighlight>

=== getRanges ===

<syntaxhighlight lang="lua">
collection:getRanges()
</syntaxhighlight>

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|IPAddress]] objects.

Examples:

<syntaxhighlight lang="lua">
collection:addSubnet('1.2.0.0/24')
collection:addSubnet('1.2.1.0/24')
collection:addSubnet('1.2.10.0/24')
mw.logObject(collection:getRanges())
-- Logs the following:
-- table#1 {
--   table#2 {
--     1.2.0.0,
--     1.2.1.255,
--   },
--   table#3 {
--     1.2.10.0,
--     1.2.10.255,
--   },
-- } 
</syntaxhighlight>

=== overlapsSubnet ===

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

Returns true, obj if <var>subnet</var> overlaps this collection, where obj is the first [[#IPAddress|IPAddress]] or [[#Subnet|Subnet]] object overlapping the subnet. Otherwise, returns false. <var>subnet</var> can be a CIDR string or a [[#Subnet|Subnet]] object.

Examples:

<syntaxhighlight lang="lua">
collection:addIP('1.2.3.4')
collection:overlapsSubnet('1.2.3.0/24') -- true, IPAddress.new('1.2.3.4')
collection:overlapsSubnet('1.2.4.0/24') -- false
</syntaxhighlight>