Lite(3)

💖 Lite(3) — Net::CIDR::Lite 💖

okay bestie, this is the Lite(3) page from the User Contributed Perl Documentation section of the manual, and honestly? it's giving merge queen. let's get into it 🦋

---

✨ NAME ✨

Net::CIDR::Lite — a Perl extension for merging IPv4 or IPv6 CIDR addresses. no cap, that's the whole job 💅

---

🌸 SYNOPSIS 🌸

use Net::CIDR::Lite;

my $cidr = Net::CIDR::Lite->new;
$cidr->add($cidr_address);
@cidr_list = $cidr->list;
@ip_ranges = $cidr->list_range;

look at that. four lines and you're already merging ranges like a main character 👑

---

🎀 DESCRIPTION 🎀

It's a faster alternative to Net::CIDR when you're merging a large number of CIDR address ranges. and yes, it works for both IPv4 and IPv6 addresses, because it contains multitudes 💜

---

🫶 METHODS 🫶

💫 new()

$cidr = Net::CIDR::Lite->new
$cidr = Net::CIDR::Lite->new(@args)

Creates an object that represents a list of CIDR address ranges. No particular format is set yet — so it's format-fluid at birth, iconic. but once an add method is called with an IPv4 or IPv6 format, only that format may be added for this cidr object. it picks a lane and stays in it, periodt. Any arguments supplied are passed to add_any() (see below).

💫 add()

$cidr->add($cidr_address)

Adds a CIDR address range to the list. boom. done. ✨

💫 add_range()

$cidr->add_range($ip_range)

Adds a hyphenated IP address range to the list. (yes, hyphenated, like 1.1.1.1-2, we love a range with a little dash of drama 🎀)

💫 add_cidr()

$cidr1->add_cidr($cidr2)

Adds address ranges from one object to another object. it's a friend-to-friend range transfer, we love to see it 🫶

💫 add_ip()

$cidr->add_ip($ip_address)

Adds a single IP address to the list. just one. a solo act. main character energy 💅

💫 add_any()

$cidr->add_any($cidr_or_range_or_address);

Determines format of range or single ip address and calls add(), add_range(), add_cidr(), or add_ip() as appropriate. it's the vibe-checker of methods — it figures out what you handed it and routes it to the right place 🌈

💫 $cidr->clean()

$cidr->clean;

If you are going to call the list method more than once on the same data, then for optimal performance, you can call this to purge null nodes in overlapping ranges from the list. Boundary nodes in contiguous ranges are automatically purged during add(). Only useful when ranges overlap or when contiguous ranges are added out of order. ✨

lowkey: this is the "tidy up before the photo" method. only worth it in those specific overlap/out-of-order situations, don't do it for no reason bestie 💖

💫 $cidr->list()

@cidr_list = $cidr->list;
$list_ref  = $cidr->list;

Returns a list of the merged CIDR addresses. Returns an array if called in list context, an array reference if not. context is everything here 💅

💫 $cidr->list_range()

@cidr_list = $cidr->list_range;
$list_ref  = $cidr->list_range;

Returns a list of the merged addresses, but in hyphenated range format. Returns an array if called in list context, an array reference if not.

💫 $cidr->list_short_range()

@cidr_list = $cidr->list_short_range;
$list_ref  = $cidr->list_short_range;

Returns a list of the C subnet merged addresses, in short hyphenated range format. Returns an array if called in list context, an array reference if not.

Example:

        1.1.1.1-2
        1.1.1.5-7
        1.1.1.254-255
        1.1.2.0-2
        1.1.3.5
        1.1.3.7

see how cute and compact? it's giving abbreviated. obsessed 🌸

💫 $cidr->find()

$found = $cidr->find($ip);

Returns true if the ip address is found in the CIDR range. False if not. Not extremely efficient — it's O(n*log(n)) to sort the ranges in the cidr object and O(n) to search through the ranges in the cidr object. The sort is cached on the first call and used in subsequent calls, but if more addresses are added to the cidr object, prep_find() must be called on the cidr object.

⚠️ okay so this is the important bit: add more addresses → you MUST call prep_find() again. the cache does not update itself, she is not psychic 😭

💫 $cidr->bin_find()

Same as find(), but forces a binary search. See also prep_find. 🔥

💫 $cidr->prep_find()

$cidr->prep_find($num);

Caches the result of sorting the ip addresses. Implicitly called on the first find call, but must be explicitly called if more addresses are added to the cidr object. find() will do a binary search if the number of ranges is greater than or equal to $num (default 20);

💫 $cidr->spanner()

$spanner = $cidr1->spanner($label1, $cidr2, $label2, ...);

Creates a spanner object to find out if multiple ip addresses are within multiple labeled address ranges. May also be called as (with or without any arguments):

Net::CIDR::Lite::Span->new($cidr1, $label1, $cidr2, $label2, ...);

💫 $spanner->add()

$spanner->add($cidr1, $label1, $cidr2, $label2,...);

Adds labeled address ranges to the spanner object. The 'address range' may be a Net::CIDR::Lite object, a single CIDR address range, a single hyphenated IP address range, or a single IP address. so many options, she's flexible 💅

💫 $spanner->find()

$href = $spanner->find(@ip_addresses);

Look up which range(s) ip addresses are in, and return a lookup table of the results, with the keys being the ip addresses, and the value a hash reference of which address ranges the ip address is in. it's a whole receipt of where everybody lives 🧾✨

💫 $spanner->bin_find()

Same as find(), but forces a binary search. See also prep_find.

💫 $spanner->prep_find()

$spanner->prep_find($num);

Called implicitly the first time $spanner->find(..) is called, must be called again if more cidr objects are added to the spanner object. Will do a binary search if ratio of the number of ip addresses to the number of ranges is less than $num percent (default 4).

💫 $spanner->clean()

$clean_address = $spanner->clean($ip_address);

Validates and returns a cleaned up version of an ip address (which is what you will find as the key in the result from the $spanner->find(..), not necessarily what the original argument looked like). E.g. removes unnecessary leading zeros, removes null blocks from IPv6 addresses, etc. ✨ glow-up method ✨

---

😭 CAVEATS 😭

Garbage in/garbage out. This module does do validation, but maybe not enough to suit your needs. it's doing its best, but bestie, it's not a security guard 💀

---

👑 AUTHOR 👑

Douglas Wilson, <dougw@cpan.org> w/numerous hints and ideas borrowed from Tye McQueen. shoutout to Tye for the assists 🫶

---

💜 MAINTAINER 💜

Stig Palmquist <stig@stig.io>

---

📜 COPYRIGHT 📜

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

🌈 SEE ALSO 🌈

Net::CIDR.

---

and that's the whole page, bestie 💖 this was perl v5.42.2, dated 2026-05-11, living in the Lite(3) manpage. go forth and merge those ranges, you absolute icon 🎀✨👑