cidrv6Addresses - mod.ts - @hertzg/ip documentation

function cidrv6Addresses



cidrv6Addresses(cidr: Cidrv6,
options?: { offset?: number | bigint; count?: number | bigint; step?: number | bigint;  }
): Generator<bigint>

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 (last address for positive step, network for negative step).

IPv6 blocks can be enormous. A /64 has 2^64 addresses. Use count or iterate lazily to avoid memory issues.

Examples

Default behavior - iterate from offset 0

import { assertEquals } from "@std/assert";
import { cidrv6Addresses, parseCidrv6 } from "@hertzg/ip/cidrv6";
import { stringifyAddressv6 } from "@hertzg/ip/addressv6";

const cidr = parseCidrv6("fd00::/120"); // 256 IPs: ::0 to ::ff

// Get first 5 IPs (offset=0 by default, starts at network address)
const first5 = Array.from(cidrv6Addresses(cidr, { count: 5 }));
assertEquals(first5.map(stringifyAddressv6), [
  "fd00::", "fd00::1", "fd00::2", "fd00::3", "fd00::4",
]);

Limiting with count parameter

import { assertEquals } from "@std/assert";
import { cidrv6Addresses, parseCidrv6 } from "@hertzg/ip/cidrv6";
import { parseAddressv6 } from "@hertzg/ip/addressv6";

const cidr = parseCidrv6("fd00::/120");

// Get first 3 IPs starting at network address
const first3 = Array.from(cidrv6Addresses(cidr, { offset: 0, count: 3 }));
assertEquals(first3, [
  parseAddressv6("fd00::0").address,
  parseAddressv6("fd00::1").address,
  parseAddressv6("fd00::2").address,
]);

Custom step for even IPs

import { assertEquals } from "@std/assert";
import { cidrv6Addresses, parseCidrv6 } from "@hertzg/ip/cidrv6";
import { parseAddressv6 } from "@hertzg/ip/addressv6";

const cidr = parseCidrv6("fd00::/120");

// Get every other IP (even addresses)
const evenIps = Array.from(cidrv6Addresses(cidr, { offset: 0, count: 5, step: 2 }));
assertEquals(evenIps, [
  parseAddressv6("fd00::0").address,
  parseAddressv6("fd00::2").address,
  parseAddressv6("fd00::4").address,
  parseAddressv6("fd00::6").address,
  parseAddressv6("fd00::8").address,
]);

Negative step for reverse iteration

import { assertEquals } from "@std/assert";
import { cidrv6Addresses, parseCidrv6 } from "@hertzg/ip/cidrv6";
import { parseAddressv6 } from "@hertzg/ip/addressv6";

const cidr = parseCidrv6("fd00::/120");

// Get 5 IPs counting backwards from offset 10
const backwards = Array.from(cidrv6Addresses(cidr, { offset: 10, count: 5, step: -1 }));
assertEquals(backwards, [
  parseAddressv6("fd00::a").address,
  parseAddressv6("fd00::9").address,
  parseAddressv6("fd00::8").address,
  parseAddressv6("fd00::7").address,
  parseAddressv6("fd00::6").address,
]);

CIDR boundary handling

import { assertEquals } from "@std/assert";
import { cidrv6Addresses, parseCidrv6 } from "@hertzg/ip/cidrv6";

const cidr = parseCidrv6("fd00::/125"); // Only 8 IPs: ::0 to ::7

// Requesting more IPs than available stops at CIDR boundary
const ips = Array.from(cidrv6Addresses(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(cidrv6Addresses(cidr, { offset: 3, count: 10, step: -1 }));
assertEquals(reverseIps.length, 4); // ::3, ::2, ::1, ::0

Parameters



cidr: Cidrv6

The CIDR block to generate addresses from

optional



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

Optional configuration for address generation

Return Type

Generator<bigint>

A generator yielding IP addresses as bigints (may yield less than count if CIDR boundary is reached)