Class: range

Represents an IP address or address range as created by new(), v4(), v6() or mac().

Instances carry the address, its family (4 for IPv4, 6 for IPv6 and 1 for MAC addresses) and a prefix size in bits (32 for IPv4, 128 for IPv6 and 48 for MAC addresses by default).

Instances provide a tostring() method which is also used by print() and string interpolation to render the address in canonical form, including the prefix size if it is smaller than the family's full width.

In addition, instances support property access through __get__() and __set__() metamethods:

Numeric keys read or write the individual address bytes, e.g. addr[0] reads the first address byte and addr[0] = 10 rewrites it. Negative indices count from the end of the address.
The bits property reads or writes the prefix size in bits.
The family property reads the address family (numeric AF_* value).
The scope property reads or writes the address scope (the numeric interface index) for IPv6 and MAC address instances.
The scopeid property reads or writes the address scope given an interface name or numeric index, silently ignoring non-link-local IPv6 addresses.
The netmask property reads the netmask as a string, e.g. "255.255.255.0" for a /24 prefix.
The host property reads the host address as a new range (full-width prefix).
The mapped4 property reads the mapped IPv4 address as a new range, or null if the instance is not an IPv6 mapped IPv4 address.
The unscopename property reads the interface name of the address scope (or an empty string if no scope is set).
The size property reads the number of addresses in this range, or null if the value does not fit into a 64 bit signed integer.

Example

const addr = netaddr.new('192.168.1.1/24');

addr.is4();        // true
addr.network();    // "192.168.1.0"
addr.maxhost();    // "192.168.1.254"

addr.bits;         // 24
addr[0];           // 192
addr.netmask;      // "255.255.255.0"
addr.host;         // netaddr.range "192.168.1.1"
addr.size;         // 256

addr[3] = 10;      // "192.168.1.10/24"
addr.bits = 16;    // "192.168.0.0/16"

print(addr);       // "192.168.0.0/16"

Properties

Name	Type	Attributes	Description
`bits`	number		The prefix size in bits (read/write). `32` for IPv4, `128` for IPv6, `48` for MAC addresses.
`family`	number		The address family (read-only): `4` for IPv4, `6` for IPv6, `1` for MAC addresses.
`scope`	number		The address scope as a numeric interface index (read/write). Only meaningful for IPv6 and MAC address instances.
`scopeid`	string	nullable	(nullable) The address scope as an interface name (read/write). Accepts an interface name or numeric index for assignment. `null` if no scope is set. Only meaningful for IPv6 and MAC address instances.
`netmask`	string		The netmask as a string, e.g. `"255.255.255.0"` (read-only).
`host`	range		The host address as a new range with a full-width prefix (read-only).
`mapped4`	range	nullable	(nullable) The mapped IPv4 address as a new range, or `null` if the instance is not an IPv6 mapped IPv4 address (read-only).
`unscopename`	string		The interface name of the address scope, or an empty string if no scope is set (read-only).
`size`	number	nullable	(nullable) The number of addresses in this range, or `null` if the value does not fit into a 64 bit signed integer (read-only).

Source: lib/netaddr.c, line 957
See: new()
v4()
v6()
mac()

Methods

get(key) → {number|string|null}

Property access for netaddr.range instances.

Invoked by the interpreter for property reads which do not match a method of this type, e.g. addr[0], addr.bits or addr.netmask.

The following keys are supported:

Key	Description
`0 .. n-1`	The individual address bytes, negative indices count from the end
`bits`	The prefix size in bits
`family`	The address family (`AF_INET`, `AF_INET6` or `AF_PACKET`)
`scope`	The address scope (numeric interface index) for IPv6 and MAC instances
`scopeid`	The address scope as an interface name (or `null` if not set)
`netmask`	The netmask as a string, e.g. `"255.255.255.0"`
`host`	The host address as a new range (full-width prefix)
`mapped4`	The mapped IPv4 address as a new range (or `null` if not a mapped IPv4)
`unscopename`	The interface name of the address scope (or an empty string)
`size`	The number of addresses in this range (or `null` if too large)

Parameters:

Name	Type	Description
`key`	number \| string	The property key to read.

Returns: number | string | null

Example

const addr = netaddr.new('192.168.1.1/24');

addr[0];       // 192
addr[-1];      // 1
addr.bits;     // 24
addr.family;   // 2
addr.netmask;  // "255.255.255.0"
addr.host;     // netaddr.range "192.168.1.1" (full-width prefix)
addr.size;     // 256

Source: lib/netaddr.c, line 2221

set(key, value) → {null}

Property assignment for netaddr.range instances.

Invoked by the interpreter for property writes, e.g. addr[0] = 10 or addr.bits = 16.

The following keys are supported:

Numeric keys write the individual address bytes (value range 0..255, negative indices count from the end of the address).
The bits key sets the prefix size in bits (0..32 for IPv4, 0..128 for IPv6, 0..48 for MAC addresses).
The scope key sets the address scope (numeric interface index) for IPv6 and MAC address instances.
The scopeid key sets the address scope to the given interface name or numeric index for IPv6 and MAC address instances.
The host, mapped4, unscopename and size keys are read-only computed properties; writes to them are silently ignored.

Writes to other keys or with invalid values are silently ignored.

Parameters:

Name	Type	Description
`key`	number \| string	The property key to write.
`value`	number	The value to assign.

Returns: null

Always returns null, the return value is discarded by the interpreter.

Example

const addr = netaddr.new('192.168.1.1/24');

addr[3] = 10;     // "192.168.1.10/24"
addr[-1] = 10;    // "192.168.1.10/24"
addr.bits = 16;   // "192.168.1.10/16"

Source: lib/netaddr.c, line 2366

add(amount, inplaceopt) → {range|boolean|null}

Add the given amount to this CIDR instance. If the result would overflow the maximum address space, the result is set to the highest possible address.

Parameters:

Name	Type	Description
`amount`	number \| string \| range	A numeric value, an `netaddr.range` instance or a string convertible by `new()`.
`inplace`	boolean	(optional) If `true`, modify this instance instead of returning a new derived CIDR instance.

Returns: range | boolean | null

When adding inplace: true if the addition succeeded or false when the addition overflowed. When deriving a new CIDR: a new instance representing the value of this instance plus the added amount or the highest possible address if the addition overflowed the available address space. Returns null if the amount argument is not convertible.

Example

const addr = netaddr.new('192.168.1.1/24');
addr.add(250);          // "192.168.1.251/24"
addr.add('0.0.99.0');   // "192.168.100.1/24"

addr.add(256, true);    // true
addr;                   // "192.168.2.1/24"

addr.add('255.0.0.0', true);  // false (overflow)
addr;                         // "255.255.255.255/24"

const addr6 = netaddr.new('fe80::221:63f:fe75:aa17/64');
addr6.add(256);          // "fe80::221:63f:fe75:ab17/64"

const mac = netaddr.new('00:14:22:01:23:45');
mac.add(256);            // "00:14:22:01:24:45"

Source: lib/netaddr.c, line 1935

broadcast(maskopt) → {range}nullable

Derive the broadcast address of this CIDR instance.

Constructs a CIDR instance representing the broadcast address of this instance. The used prefix size can be overridden by the optional mask parameter.

This function has no effect on IPv6 or MAC address instances, it will return null in this case.

Parameters:

Name	Type	Description
`mask`	number \| string	(optional) A number containing the number of bits (`0..32` for IPv4) or a string containing a valid netmask.

Returns: range

A new CIDR instance representing the broadcast address if this instance is an IPv4 range, else null

Example

const range = netaddr.new('172.19.37.45/16');
range.broadcast();            // "172.19.255.255"
range.broadcast(24);          // "172.19.37.255"
range.broadcast('255.0.0.0'); // "172.255.255.255"

Source: lib/netaddr.c, line 1560

contains(addr) → {boolean}nullable

Test whether this CIDR contains the given range.

Parameters:

Name	Type	Description
`addr`	string \| range	An `netaddr.range` instance or a string convertible by `new()` to test.

Returns: boolean

true if this instance fully contains the given address, else false. Returns null if the argument cannot be converted to a CIDR instance.

Example

const range = netaddr.new('10.24.0.0/255.255.0.0');
range.contains('10.24.5.1');  // true
range.contains('::1');        // false
range.contains('10.0.0.0/8'); // false

const range6 = netaddr.new('fe80::/10');
range6.contains('fe80::221:63f:fe75:aa17/64');         // true
range6.contains('fd9b:6b3:c5:0:221:63f:fe75:aa17/64'); // false

const intel_macs = netaddr.MAC('C0:B6:F9:00:00:00/24');
intel_macs.contains('C0:B6:F9:A3:C:11');  // true
intel_macs.contains('64:66:B3:47:E1:B9'); // false

Source: lib/netaddr.c, line 1781

equal(addr) → {boolean}nullable

Checks whether this CIDR instance is equal to the given argument.

Parameters:

Name	Type	Description
`addr`	string \| range	An `netaddr.range` instance or a string convertible by `new()` to compare against.

Returns: boolean

true if this CIDR is equal to the given address, else false. Returns null if the argument cannot be converted to a CIDR instance.

Example

const addr = netaddr.new('192.168.1.1');
addr.equal(addr);                 // true
addr.equal('192.168.1.1');        // true
addr.equal(netaddr.new('::1'));        // false

const addr6 = netaddr.new('::1');
addr6.equal('0:0:0:0:0:0:0:1/64');  // true

const mac = netaddr.new('00:14:22:01:23:45');
mac.equal('0:14:22:1:23:45');  // true

Source: lib/netaddr.c, line 1348

higher(addr) → {boolean}nullable

Checks whether this CIDR instance is higher than the given argument.

The comparison follows these rules:

An IPv4 address is always lower than an IPv6 address and IPv6 addresses are considered lower than MAC addresses
Prefix sizes are ignored

Parameters:

Name	Type	Description
`addr`	string \| range	An `netaddr.range` instance or a string convertible by `new()` to compare against.

Returns: boolean

true if this CIDR is higher than the given address, else false. Returns null if the argument cannot be converted to a CIDR instance.

Example

const addr = netaddr.new('192.168.1.1');
addr.higher(addr);                        // false
addr.higher('10.10.10.10/24');            // true
addr.higher(netaddr.new('::1'));               // false
addr.higher(netaddr.new('192.168.200.1'));     // false
addr.higher(netaddr.new('00:14:22:01:23:45')); // false

Source: lib/netaddr.c, line 1306

is4() → {boolean}

Checks whether the CIDR instance is an IPv4 address range.

Returns: boolean

true if the CIDR is an IPv4 range, else false

Source: lib/netaddr.c, line 1056

is4linklocal() → {boolean}

Checks whether the CIDR instance is an IPv4 link local (Zeroconf) address.

Returns: boolean

true if the entire range of this CIDR lies within the range 169.254.0.0-169.254.255.255, else false

Example

const addr = netaddr.new('169.254.34.125');
addr.is4linklocal();  // true

Source: lib/netaddr.c, line 1097

is4rfc1918() → {boolean}

Checks whether the CIDR instance is within the private RFC1918 address space.

Returns: boolean

true if the entire range of this CIDR lies within one of the ranges 10.0.0.0-10.255.255.255, 172.16.0.0-172.31.0.0 or 192.168.0.0-192.168.255.255, else false

Example

const addr = netaddr.new('192.168.45.2/24');
addr.is4rfc1918();  // true

Source: lib/netaddr.c, line 1071

is6() → {boolean}

Checks whether the CIDR instance is an IPv6 address range.

Returns: boolean

true if the CIDR is an IPv6 range, else false

Source: lib/netaddr.c, line 1121

is6linklocal() → {boolean}

Checks whether the CIDR instance is an IPv6 link local address.

Returns: boolean

true if the entire range of this CIDR lies within the fe80::/10 range, else false

Example

const addr = netaddr.new('fe92:53a:3216:af01:221:63ff:fe75:aa17/64');
addr.is6linklocal();  // true

Source: lib/netaddr.c, line 1136

is6mapped4() → {boolean}

Checks whether the CIDR instance is an IPv6 mapped IPv4 address.

Returns: boolean

true if the address is an IPv6 mapped IPv4 address in the form ::ffff:1.2.3.4

Example

const addr = netaddr.new('::ffff:192.168.1.1');
addr.is6mapped4();  // true

Source: lib/netaddr.c, line 1177

ismac() → {boolean}

Checks whether the CIDR instance is an ethernet MAC address range.

Returns: boolean

true if the CIDR is a MAC address range, else false

Source: lib/netaddr.c, line 1197

ismaclocal() → {boolean}

Checks whether the CIDR instance is a locally administered (LAA) MAC address.

Returns: boolean

true if the MAC address sets the locally administered bit

Example

const mac = netaddr.new('02:C0:FF:EE:00:01');
mac.ismaclocal();  // true

Source: lib/netaddr.c, line 1213

ismacmcast() → {boolean}

Checks whether the CIDR instance is a multicast MAC address.

Returns: boolean

true if the MAC address sets the multicast bit

Example

const mac = netaddr.new('01:00:5E:7F:00:10');
mac.ismacmcast();  // true

Source: lib/netaddr.c, line 1235

lower(addr) → {boolean}nullable

Checks whether this CIDR instance is lower than the given argument.

The comparison follows these rules:

An IPv4 address is always lower than an IPv6 address and IPv6 addresses are considered lower than MAC addresses
Prefix sizes are ignored

Parameters:

Name	Type	Description
`addr`	string \| range	An `netaddr.range` instance or a string convertible by `new()` to compare against.

Returns: boolean

true if this CIDR is lower than the given address, else false. Returns null if the argument cannot be converted to a CIDR instance.

Example

const addr = netaddr.new('192.168.1.1');
addr.lower(addr);                         // false
addr.lower('10.10.10.10/24');             // false
addr.lower(netaddr.new('::1'));                // true
addr.lower(netaddr.new('192.168.200.1'));      // true
addr.lower(netaddr.new('00:14:22:01:23:45'));  // true

Source: lib/netaddr.c, line 1264

mask(maskopt) → {range}

Derive the netmask of this CIDR instance.

Constructs a CIDR instance representing the netmask of this instance. The used prefix size can be overridden by the optional mask parameter.

Parameters:

Name	Type	Description
`mask`	number \| string	(optional) A number containing the number of bits (`0..32` for IPv4, `0..128` for IPv6 or `0..48` for MAC addresses) or a string containing a valid netmask.

Returns: range

A CIDR instance representing the netmask

Example

const range = netaddr.new('172.19.37.45/16');
range.mask();            // "255.255.0.0"
range.mask(24);          // "255.255.255.0"
range.mask('255.0.0.0'); // "255.0.0.0"

Source: lib/netaddr.c, line 1510

maxhost() → {range}

Derive the highest usable host address of this CIDR instance.

For IPv4 ranges this is the broadcast address minus one, except for point-to-point /31 ranges where the broadcast address itself is the last usable host; for IPv6 ranges the highest address in the range (the "broadcast" address); for host addresses and MAC addresses the address itself.

Returns: range

A new CIDR instance representing the highest usable host address of this instance

Example

const range = netaddr.new('172.19.37.45/16');
range.maxhost();  // "172.19.255.254"

Source: lib/netaddr.c, line 2079

minhost() → {range}

Derive the lowest usable host address of this CIDR instance.

For IPv4 ranges this is the network address plus one, except for point-to-point /31 ranges where the network address itself is the first usable host; for IPv6 ranges the lowest address in the range (the "network" address); for host addresses and MAC addresses the address itself.

Returns: range

A new CIDR instance representing the lowest usable host address of this instance

Example

const range = netaddr.new('172.19.37.45/16');
range.minhost();  // "172.19.0.1"

Source: lib/netaddr.c, line 2026

network(maskopt) → {range}

Derive the network address of this CIDR instance.

Returns a new CIDR instance representing the network address of this instance with all host parts masked out. The used prefix size can be overridden by the optional mask parameter.

Parameters:

Name	Type	Description
`mask`	number \| string	(optional) A number containing the number of bits (`0..32` for IPv4, `0..128` for IPv6 or `0..48` for MAC addresses) or a string containing a valid netmask.

Returns: range

A CIDR instance representing the network address

Example

const range = netaddr.new('192.168.62.243/255.255.0.0');
range.network();                // "192.168.0.0"
range.network(24);              // "192.168.62.0"
range.network('255.255.255.0'); // "192.168.62.0"

const range6 = netaddr.new('fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64');
range6.network();               // "fd9b:62b3:9cc5::"

Source: lib/netaddr.c, line 1459

prefix(maskopt) → {number}

Get or set the prefix size of this CIDR instance.

If the optional mask parameter is given, the prefix size of this CIDR is altered, else the current prefix size is returned.

Parameters:

Name	Type	Description
`mask`	number \| string	(optional) A number containing the number of bits (`0..32` for IPv4, `0..128` for IPv6 or `0..48` for MAC addresses) or a string containing a valid netmask.

Returns: number

The bit count of the (new) prefix size

Example

const range = netaddr.new('192.168.1.1/255.255.255.0');
range.prefix();  // 24

range.prefix(16);
range.prefix();  // 16

range.prefix('255.255.255.255');
range.prefix();  // 32

Source: lib/netaddr.c, line 1388

scoped() → {range}nullable

Derive the scoped address of this CIDR instance.

Constructs a copy of the given IPv6 or MAC address instance carrying the associated address scope, if any.

This function has no effect on IPv4 instances, it will return null in this case. If no scope is associated with the address, null is returned.

Returns: range

A new CIDR instance representing the scoped address

Example

const addr = netaddr.new('fe80::1234');
addr.scope = 2;
addr.scoped();  // "fe80::1234%eth0"  (if index 2 is eth0)

Source: lib/netaddr.c, line 1614

string() → {string}

Get the string representation of this CIDR instance.

Returns: string

A string representation of this CIDR

Example

const addr = netaddr.new('172.19.37.45/16');
addr.string();  // "172.19.37.45/16"

Source: lib/netaddr.c, line 2125

sub(amount, inplaceopt) → {range|boolean|null}

Subtract the given amount from this CIDR instance. If the result would underflow the lowest possible address, the result is set to the lowest possible address.

Parameters:

Name	Type	Description
`amount`	number \| string \| range	A numeric value, an `netaddr.range` instance or a string convertible by `new()`.
`inplace`	boolean	(optional) If `true`, modify this instance instead of returning a new derived CIDR instance.

Returns: range | boolean | null

When subtracting inplace: true if the subtraction succeeded or false when the subtraction underflowed. When deriving a new CIDR: a new instance representing the value of this instance minus the subtracted amount or the lowest address if the subtraction underflowed. Returns null if the amount argument is not convertible.

Example

const addr = netaddr.new('192.168.1.1/24');
addr.sub(256);         // "192.168.0.1/24"
addr.sub('0.168.0.0'); // "192.0.1.1/24"

addr.sub(256, true);   // true
addr;                  // "192.168.0.1/24"

addr.sub('255.0.0.0', true);  // false (underflow)
addr;                         // "0.0.0.0/24"

const addr6 = netaddr.new('fe80::221:63f:fe75:aa17/64');
addr6.sub(256);         // "fe80::221:63f:fe75:aa17/64"

const mac = netaddr.new('00:14:22:01:23:45');
mac.sub(256);           // "00:14:22:01:22:45"

Source: lib/netaddr.c, line 1981

tolinklocal() → {range}nullable

Derive the IPv6 link local address from this MAC address CIDR instance.

Constructs a CIDR instance representing the IPv6 link local address of the MAC address represented by this instance.

This function has no effect on IPv4 instances or IPv6 instances, it will return null in this case.

Returns: range

A new CIDR instance representing the IPv6 link local address

Example

const mac = netaddr.new('64:66:B3:47:E1:B9');
mac.tolinklocal();  // "fe80::6666:b3ff:fe47:e1b9"

Source: lib/netaddr.c, line 1731

tomac() → {range}nullable

Derive the MAC address of this IPv6 link local CIDR instance.

Constructs a CIDR instance representing the MAC address contained in the IPv6 link local address of this instance.

This function has no effect on IPv4 instances, MAC address instances or IPv6 instances which are not a link local address, it will return null in this case.

Returns: range

A new CIDR instance representing the MAC address if this instance is an IPv6 link local address, else null

Example

const addr = netaddr.new('fe80::6666:b3ff:fe47:e1b9');
addr.tomac();  // "64:66:B3:47:E1:B9"

Source: lib/netaddr.c, line 1680

tostring() → {string}

Get the string representation of this CIDR instance.

This method is invoked by print() and string interpolation to render the instance, see string().

Returns: string

A string representation of this CIDR

Example

const addr = netaddr.new('172.19.37.45/16');

print(addr);   // "172.19.37.45/16"
`${addr}`;     // "172.19.37.45/16"

Source: lib/netaddr.c, line 2144

unscoped() → {range}nullable

Derive the unscoped IPv6 address of this CIDR instance.

Constructs a copy of the given IPv6 CIDR instance and drops the associated address scope information.

This function has no effect on IPv4 instances or MAC address instances, it will return null in this case.

Returns: range

A new CIDR instance representing the unscoped IPv6 address

Example

const addr = netaddr.new('fe80::1234%eth0');
addr.unscoped();  // "fe80::1234"

Source: lib/netaddr.c, line 1647

Methods

__get__(key) → {number|string|null}

__set__(key, value) → {null}

add(amount, inplaceopt) → {range|boolean|null}

broadcast(maskopt) → {range}nullable

contains(addr) → {boolean}nullable

equal(addr) → {boolean}nullable

higher(addr) → {boolean}nullable

is4() → {boolean}

is4linklocal() → {boolean}

is4rfc1918() → {boolean}

is6() → {boolean}

is6linklocal() → {boolean}

is6mapped4() → {boolean}

ismac() → {boolean}

ismaclocal() → {boolean}

ismacmcast() → {boolean}

lower(addr) → {boolean}nullable

mask(maskopt) → {range}

maxhost() → {range}

minhost() → {range}

network(maskopt) → {range}

prefix(maskopt) → {number}

scoped() → {range}nullable

string() → {string}

sub(amount, inplaceopt) → {range|boolean|null}

tolinklocal() → {range}nullable

tomac() → {range}nullable

tostring() → {string}

unscoped() → {range}nullable

get(key) → {number|string|null}

set(key, value) → {null}