cidrv4Addresses - mod.ts - @hertzg/ip documentation

function cidrv4Addresses



cidrv4Addresses(cidr: Cidrv4,
options?: { offset?: number; count?: number; step?: number;  }
): Generator<number>

Generates a range of IP addresses from a CIDR block.

Yields IP addresses starting at the specified offset from the network address. The offset is relative to the network address (offset 0 = network address). The step parameter controls the increment (positive or negative) between consecutive addresses. Only addresses within the CIDR block are yielded.

By default (when count is not specified), iterates through all addresses in the CIDR block from the offset to the boundary (broadcast for positive step, network for negative step).

Examples

Default behavior - iterate full CIDR block

import { assertEquals } from "@std/assert";
import { cidrv4Addresses, parseCidrv4 } from "@hertzg/ip/cidrv4";
import { stringifyAddressv4 } from "@hertzg/ip/addressv4";

const cidr = parseCidrv4("10.0.0.0/29"); // 8 IPs: .0 to .7

// By default, iterates from offset 0 (network address) to CIDR boundary
const all = Array.from(cidrv4Addresses(cidr));
assertEquals(all.map(stringifyAddressv4), [
  "10.0.0.0", "10.0.0.1", "10.0.0.2", "10.0.0.3",
  "10.0.0.4", "10.0.0.5", "10.0.0.6", "10.0.0.7",
]);
assertEquals(all.length, 8); // All 8 IPs in /29

// Skip network address by specifying offset 1
const usable = Array.from(cidrv4Addresses(cidr, { offset: 1 }));
assertEquals(usable.length, 7); // Skip network address

Limiting with count parameter

import { assertEquals } from "@std/assert";
import { cidrv4Addresses, parseCidrv4 } from "@hertzg/ip/cidrv4";
import { parseAddressv4 } from "@hertzg/ip/addressv4";

const cidr = parseCidrv4("192.168.1.0/24");

// Get first 3 IPs starting at network address
const first3 = Array.from(cidrv4Addresses(cidr, { offset: 0, count: 3 }));
assertEquals(first3, [
  parseAddressv4("192.168.1.0").address,
  parseAddressv4("192.168.1.1").address,
  parseAddressv4("192.168.1.2").address,
]);

// Get 5 IPs starting at offset 10
const offset10 = Array.from(cidrv4Addresses(cidr, { offset: 10, count: 5 }));
assertEquals(offset10[0], parseAddressv4("192.168.1.10").address);
assertEquals(offset10[4], parseAddressv4("192.168.1.14").address);

Custom step for even/odd IPs

import { assertEquals } from "@std/assert";
import { cidrv4Addresses, parseCidrv4 } from "@hertzg/ip/cidrv4";
import { parseAddressv4 } from "@hertzg/ip/addressv4";

const cidr = parseCidrv4("192.168.1.0/24");

// Get every other IP (even addresses)
const evenIps = Array.from(cidrv4Addresses(cidr, { offset: 0, count: 5, step: 2 }));
assertEquals(evenIps, [
  parseAddressv4("192.168.1.0").address,
  parseAddressv4("192.168.1.2").address,
  parseAddressv4("192.168.1.4").address,
  parseAddressv4("192.168.1.6").address,
  parseAddressv4("192.168.1.8").address,
]);

// Get odd addresses
const oddIps = Array.from(cidrv4Addresses(cidr, { offset: 1, count: 5, step: 2 }));
assertEquals(oddIps[0], parseAddressv4("192.168.1.1").address);
assertEquals(oddIps[1], parseAddressv4("192.168.1.3").address);

Negative step for reverse iteration

import { assertEquals } from "@std/assert";
import { cidrv4Addresses, parseCidrv4 } from "@hertzg/ip/cidrv4";
import { parseAddressv4 } from "@hertzg/ip/addressv4";

const cidr = parseCidrv4("192.168.1.0/24");

// Get 5 IPs counting backwards from offset 10
const backwards = Array.from(cidrv4Addresses(cidr, { offset: 10, count: 5, step: -1 }));
assertEquals(backwards, [
  parseAddressv4("192.168.1.10").address,
  parseAddressv4("192.168.1.9").address,
  parseAddressv4("192.168.1.8").address,
  parseAddressv4("192.168.1.7").address,
  parseAddressv4("192.168.1.6").address,
]);

CIDR boundary handling

import { assertEquals } from "@std/assert";
import { cidrv4Addresses, parseCidrv4 } from "@hertzg/ip/cidrv4";

const cidr = parseCidrv4("192.168.1.0/29"); // Only 8 IPs: .0 to .7

// Requesting more IPs than available stops at CIDR boundary
const ips = Array.from(cidrv4Addresses(cidr, { offset: 5, count: 10, step: 1 }));
assertEquals(ips.length, 3); // Only .5, .6, .7 are in range

// Negative step stops at CIDR start
const reverseIps = Array.from(cidrv4Addresses(cidr, { offset: 3, count: 10, step: -1 }));
assertEquals(reverseIps.length, 4); // .3, .2, .1, .0

Parameters



cidr: Cidrv4

The CIDR block to generate addresses from

optional



options: { offset?: number; count?: number; step?: number;  }

Optional configuration for address generation

Return Type

Generator<number>

A generator yielding IP addresses as 32-bit unsigned integers (may yield less than count if CIDR boundary is reached)