classDocs / IPv6

IPv6

classsharedsource

Object → IPv6

An object that represents an Internet Protocol v6 address as eight 16-bit groups.

Groups are stored in the array part of the object, address[ 1 ] is the most significant group.

Supports tostring (compressed RFC 5952 form), comparison operators (==, <, <=), the length operator (#address is always 8) and unary minus (-address is the bitwise NOT of the address).

Constructor

IPv6(group1: integer?, group2: integer?, group3: integer?, group4: integer?, group5: integer?, group6: integer?, group7: integer?, group8: integer?): IPv6

Fields

Name	Type	Description
`[ 1 ]`	`integer`	The first group. <0-65535>
`[ 2 ]`	`integer`	The second group. <0-65535>
`[ 3 ]`	`integer`	The third group. <0-65535>
`[ 4 ]`	`integer`	The fourth group. <0-65535>
`[ 5 ]`	`integer`	The fifth group. <0-65535>
`[ 6 ]`	`integer`	The sixth group. <0-65535>
`[ 7 ]`	`integer`	The seventh group. <0-65535>
`[ 8 ]`	`integer`	The eighth group. <0-65535>

Static functions

`fromIPv4`	Creates an IPv4-mapped IPv6 address (::ffff:a.b.c.d) from an IPv4 address.
`fromPrefix`	Returns the network mask address for a given CIDR prefix length.
`is6to4`	Returns whether the address is a 6to4 address (2002::/16, RFC 3056).
`isBenchmarking`	Returns whether the address is reserved for network benchmarking (2001:2::/48, RFC 5180).
`isDiscard`	Returns whether the address is a discard-only address (100::/64, RFC 6666).
`isDocumentation`	Returns whether the address is reserved for documentation and examples (2001:db8::/32, RFC 3849).
`isLinkLocal`	Returns whether the address is a link-local unicast address (fe80::/10, RFC 4291).
`isMulticast`	Returns whether the address is a multicast address (ff00::/8, RFC 4291).
`isSiteLocal`	Returns whether the address is a site-local unicast address (fec0::/10).
`isTeredo`	Returns whether the address is a Teredo address (2001::/32, RFC 4380).
`isUniqueLocal`	Returns whether the address is a unique-local address (fc00::/7, RFC 4193).
`parse`	Parses an IPv6 address string with an optional CIDR prefix length, e.g. 2001:db8::1/32.

#IPv6.fromIPv4

sharednodiscardsource

function IPv6.fromIPv4(ipv4_address: IPv4): IPv6

Creates an IPv4-mapped IPv6 address (::ffff:a.b.c.d) from an IPv4 address.

lua

print( IPv6.fromIPv4( 0x7F000001 ) ) -- ::ffff:7f00:1

Parameters

Name	Type	Description
`ipv4_address`	`IPv4`	The IPv4 address.

Returns

Type	Name	Description
`IPv6`	`ipv6_address`	The IPv4-mapped IPv6 address.

#IPv6.fromPrefix

sharednodiscardsource

function IPv6.fromPrefix(prefix: integer): IPv6

Returns the network mask address for a given CIDR prefix length.

lua

print( IPv6.fromPrefix( 64 ) ) -- ffff:ffff:ffff:ffff::

Parameters

Name	Type	Description
`prefix`	`integer`	The CIDR prefix length. <0-128>, throws an error if out of range.

Returns

Type	Name	Description
`IPv6`	`mask_address`	The network mask address.

#IPv6.is6to4

sharedsource

function IPv6.is6to4(): boolean

Returns whether the address is a 6to4 address (2002::/16, RFC 3056).

Returns

Type	Name	Description
`boolean`

#IPv6.isBenchmarking

sharedsource

function IPv6.isBenchmarking(): boolean

Returns whether the address is reserved for network benchmarking (2001:2::/48, RFC 5180).

Returns

Type	Name	Description
`boolean`

#IPv6.isDiscard

sharedsource

function IPv6.isDiscard(): boolean

Returns whether the address is a discard-only address (100::/64, RFC 6666).

Returns

Type	Name	Description
`boolean`

#IPv6.isDocumentation

sharedsource

function IPv6.isDocumentation(): boolean

Returns whether the address is reserved for documentation and examples (2001:db8::/32, RFC 3849).

Returns

Type	Name	Description
`boolean`

#IPv6.isLinkLocal

sharedsource

function IPv6.isLinkLocal(): boolean

Returns whether the address is a link-local unicast address (fe80::/10, RFC 4291).

Returns

Type	Name	Description
`boolean`

#IPv6.isMulticast

sharedsource

function IPv6.isMulticast(): boolean

Returns whether the address is a multicast address (ff00::/8, RFC 4291).

Returns

Type	Name	Description
`boolean`

#IPv6.isSiteLocal

sharedsource

function IPv6.isSiteLocal(): boolean

Returns whether the address is a site-local unicast address (fec0::/10).

Site-local addresses are deprecated by RFC 3879, but still recognized.

Returns

Type	Name	Description
`boolean`

#IPv6.isTeredo

sharedsource

function IPv6.isTeredo(): boolean

Returns whether the address is a Teredo address (2001::/32, RFC 4380).

Returns

Type	Name	Description
`boolean`

#IPv6.isUniqueLocal

sharedsource

function IPv6.isUniqueLocal(): boolean

Returns whether the address is a unique-local address (fc00::/7, RFC 4193).

Returns

Type	Name	Description
`boolean`

#IPv6.parse

sharednodiscardsource

function IPv6.parse(ipv6_str: string, start_position?: integer, end_position?: integer): IPv6, integer

Parses an IPv6 address string with an optional CIDR prefix length, e.g. 2001:db8::1/32.

Handles the :: zero-groups compression.

Embedded IPv4 notation (::ffff:1.2.3.4) and zone indices (fe80::1%eth0) are not supported.

Throws an error if a group is empty, contains invalid characters or more than 4 hex digits, the address has a wrong number of groups or more than one ::, or the prefix length is not an integer in range 0-128.

Parameters

Name	Type	Description
`ipv6_str`	`string`	The IPv6 address string to parse.
`start_position`optional	`integer`	The start position in the ipv6 string.
`end_position`optional	`integer`	The end position in the ipv6 string.

Returns

Type	Name	Description
`IPv6`	`address`	The parsed IP address.
`integer`	`prefix_length`	The CIDR prefix length. <0-128>, `128` if not specified.

Methods

`cidr`	Returns the network address and the last address of the network for a given CIDR prefix length.
`groups`	Returns the groups of the address, from the most significant to the least significant.
`inRange`	Returns whether the address is within a given network.
`isGlobalUnicast`	Returns whether the address is a global unicast address.
`isIPv4Compatible`	Returns whether the address is an IPv4-compatible IPv6 address (::a.b.c.d).
`isIPv4Mapped`	Returns whether the address is an IPv4-mapped IPv6 address (::ffff:a.b.c.d, RFC 4291).
`isLoopback`	Returns whether the address is the loopback address (::1).
`isPrivate`	Returns whether the address belongs to a private or local-use range.
`isPublic`	Returns whether the address is globally routable, i.e. a global unicast address that is not reserved.
`isReserved`	Returns whether the address belongs to a special-purpose range.
`isUnspecified`	Returns whether the address is the unspecified address (::).
`reversePointer`	Returns the reverse DNS pointer (ip6.arpa) of the address.
`toIPv4`	Extracts the embedded IPv4 address from an IPv4-mapped or IPv4-compatible address.
`toString`	Returns the string representation of the address in compressed RFC 5952 form.

#IPv6:cidr

sharednodiscardsource

function IPv6:cidr(prefix_length: integer): IPv6, IPv6

Returns the network address and the last address of the network for a given CIDR prefix length.

IPv6 has no broadcast, the "broadcast" address is just the last address of the network.

lua

local address, prefix_length = IPv6.parse( "2001:db8::1/32" )
local network, broadcast = address:cidr( prefix_length ) -- 2001:db8::, 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff

Parameters

Name	Type	Description
`prefix_length`	`integer`	The CIDR prefix length. <0-128>, throws an error if out of range.

Returns

Type	Name	Description
`IPv6`	`network_address`	The network (first) address.
`IPv6`	`broadcast_address`	The last address of the network.

#IPv6:groups

sharednodiscardsource

function IPv6:groups(): integer, integer, integer, integer, integer, integer, integer, integer

Returns the groups of the address, from the most significant to the least significant.

Returns

Type	Name	Description
`integer`	`group1`	The first group. <0-65535>
`integer`	`group2`	The second group. <0-65535>
`integer`	`group3`	The third group. <0-65535>
`integer`	`group4`	The fourth group. <0-65535>
`integer`	`group5`	The fifth group. <0-65535>
`integer`	`group6`	The sixth group. <0-65535>
`integer`	`group7`	The seventh group. <0-65535>
`integer`	`group8`	The eighth group. <0-65535>

#IPv6:inRange

sharednodiscardsource

function IPv6:inRange(network: IPv6, broadcast: IPv6): boolean

Returns whether the address is within a given network.

lua

local network, broadcast = IPv6.parse( "2001:db8::" ):cidr( 32 )
IPv6.parse( "2001:db8::1" ):inRange( network, broadcast ) -- true

Parameters

Name	Type	Description
`network`	`IPv6`	The network (first) address.
`broadcast`	`IPv6`	The last address of the network.

Returns

Type	Name	Description
`boolean`	`in_range`	`true` if the address is within the network, `false` otherwise.

#IPv6:isGlobalUnicast

sharednodiscardsource

function IPv6:isGlobalUnicast(): boolean

Returns whether the address is a global unicast address.

Any address that is not multicast, unspecified, loopback, link-local, site-local or unique-local.

Returns

Type	Name	Description
`boolean`	`is_global_unicast`	`true` if the address is a global unicast address, `false` otherwise.

#IPv6:isIPv4Compatible

sharednodiscardsource

function IPv6:isIPv4Compatible(): boolean

Returns whether the address is an IPv4-compatible IPv6 address (::a.b.c.d).

IPv4-compatible addresses are deprecated by RFC 4291.

The unspecified (::) and loopback (::1) addresses are not considered IPv4-compatible.

Returns

Type	Name	Description
`boolean`	`is_ipv4_compatible`	`true` if the address is an IPv4-compatible address, `false` otherwise.

#IPv6:isIPv4Mapped

sharednodiscardsource

function IPv6:isIPv4Mapped(): boolean

Returns whether the address is an IPv4-mapped IPv6 address (::ffff:a.b.c.d, RFC 4291).

Returns

Type	Name	Description
`boolean`	`is_ipv4_mapped`	`true` if the address is an IPv4-mapped address, `false` otherwise.

#IPv6:isLoopback

sharednodiscardsource

function IPv6:isLoopback(): boolean

Returns whether the address is the loopback address (::1).

Returns

Type	Name	Description
`boolean`	`is_loopback`	`true` if the address is the loopback address, `false` otherwise.

#IPv6:isPrivate

sharednodiscardsource

function IPv6:isPrivate(): boolean

Returns whether the address belongs to a private or local-use range.

Includes the unspecified, loopback, link-local, site-local, unique-local and discard-only addresses.

Returns

Type	Name	Description
`boolean`	`is_private`	`true` if the address is private, `false` otherwise.

#IPv6:isPublic

sharednodiscardsource

function IPv6:isPublic(): boolean

Returns whether the address is globally routable, i.e. a global unicast address that is not reserved.

Returns

Type	Name	Description
`boolean`	`is_public`	`true` if the address is public, `false` otherwise.

#IPv6:isReserved

sharednodiscardsource

function IPv6:isReserved(): boolean

Returns whether the address belongs to a special-purpose range.

Includes the documentation, benchmarking, IPv4-mapped, IPv4-compatible, 6to4 and Teredo addresses.

Returns

Type	Name	Description
`boolean`	`is_reserved`	`true` if the address is reserved, `false` otherwise.

#IPv6:isUnspecified

sharednodiscardsource

function IPv6:isUnspecified(): boolean

Returns whether the address is the unspecified address (::).

Returns

Type	Name	Description
`boolean`	`is_unspecified`	`true` if the address is the unspecified address, `false` otherwise.

#IPv6:reversePointer

sharednodiscardsource

function IPv6:reversePointer(): string

Returns the reverse DNS pointer (ip6.arpa) of the address.

lua

IPv6.parse( "2001:db8::1" ):reversePointer()
-- "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa"

Returns

Type	Name	Description
`string`	`ptr`	The reverse DNS pointer of the address.

#IPv6:toIPv4

sharednodiscardsource

function IPv6:toIPv4(): IPv4

Extracts the embedded IPv4 address from an IPv4-mapped or IPv4-compatible address.

The last two groups are always returned as an IPv4 address, even if the address is not IPv4-mapped or IPv4-compatible, so validate the address before calling this method.

lua

local address = IPv6.parse( "::ffff:7f00:1" )
if address:isIPv4Mapped() then
    print( ipv4.toString( address:toIPv4() ) ) -- 127.0.0.1
end

Returns

Type	Name	Description
`IPv4`	`ipv4_address`	The embedded IPv4 address.

#IPv6:toString

sharednodiscardsource

function IPv6:toString(): string

Returns the string representation of the address in compressed RFC 5952 form.

Same as tostring( address ).

lua

IPv6( 0x2001, 0xdb8, 0, 0, 0, 0, 0, 1 ):toString() -- "2001:db8::1"

Returns

Type	Name	Description
`string`	`str`	The string representation of the address.