NAME

Net::IPAddress::Util::Collection - A collection of Net::IPAddress::Util::Range objects

VERSION

Version 3.033

SYNOPSIS

use Net::IPAddress::Util::Collection;

my $collection = Net::IPAddress::Util::Collection->new();

while (<>) {
  last if !defined($_);
  push @$collection, $_ if $_;
}

print join ', ', $collection->tight->as_ranges;

DESCRIPTION

Sometimes when dealing with IP Addresses, it can be nice to talk about groups of them as whole collections of addresses without worrying that the group is exactly a CIDR-compatible range, or even whether the group is contiguous.

This is what Net::IPAdress::Util::Collection is for. Objects of this class act as type-checked ARRAYREFs where every entry must be some kind of IP Address data (either a single address or an arbitrary range).

Knowing that the data within are type-checked (and knowing their specific type), we can do a few extra things to the ARRAYREF as a whole that we could not (read probably should not) do to general untyped arrays. Things such as sorting them via a Radix Sort (which is faster than Perl's builtin sort()), and being able to smoosh together IP ranges that touch or overlap. What is more, since we know all IP ranges are ultimately collections of CIDR-compatible ranges (even if any given range does not start / stop on a legal CIDR boundary) and use that knowledge to extract precisely the CIDRs that match the collection.

CLASS METHODS

new

Create a new Collection object. Takes zero or more arguments, each of which must be either a Net::IPAddress::Util::Range object, or something which can be coerced into one (such as a Net::IPAddress::Util object, or something which can in turn be used to construct one).

OBJECT METHODS

sorted

Return a clone of this object, sorted ascendingly by IP address. In the case of ranges that have the same lower address, ties are broken by the upper address.

compacted

Return a clone of this object, sorted ascendingly by IP address, with adjacent ranges combined together. This uses $self->sorted, so the same notice about sort order applies.

tight

Return a clone of this object, compacted and then split on precise legal CIDR boundaries. The number of CIDR-compatible ranges returned may be less than, more than, or in rare cases the same as the number of elements in the original Collection object. Such is the CIDR nature.

as_ranges

Returns an array of stringified (x .. y) style ranges.

as_cidrs

Returns an array of stringified CIDR-style strings. In the case where one element of the Collection cannot be legally represented as a CIDR, you will get in its place the smallest single legal CIDR that contains that element.

In other words, if you want complete accuracy, you will want to use:

$collection->tight->as_cidrs;

as_netmasks

Returns an array of stringified Netmask-style strings. In the case where one element of the Collection cannot be legally represented as a Netmask string, you will get in its place the smallest single legal Netmask string that contains that element.