ipaddr.\+js is a small (1.\+9K minified and gzipped) library for manipulating IP addresses in Java\+Script environments. It runs on both Common\+JS runtimes (e.\+g. \href{http://nodejs.org}{\texttt{ nodejs}}) and in a web browser.

ipaddr.\+js allows you to verify and parse string representation of an IP address, match it against a CIDR range or range list, determine if it falls into some reserved ranges (examples include loopback and private ranges), and convert between IPv4 and IPv4-\/mapped IPv6 addresses.\hypertarget{md_sfcode_node_modules_ipaddr_js_README_autotoc_md12920}{}\doxysection{Installation}\label{md_sfcode_node_modules_ipaddr_js_README_autotoc_md12920}
{\ttfamily npm install ipaddr.\+js}

or

{\ttfamily bower install ipaddr.\+js}\hypertarget{md_sfcode_node_modules_ipaddr_js_README_autotoc_md12921}{}\doxysection{API}\label{md_sfcode_node_modules_ipaddr_js_README_autotoc_md12921}
ipaddr.\+js defines one object in the global scope\+: {\ttfamily ipaddr}. In Common\+JS, it is exported from the module\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{var ipaddr = require('ipaddr.js'); }

\end{DoxyCode}


The API consists of several global methods and two classes\+: ipaddr.\+IPv6 and ipaddr.\+IPv4.\hypertarget{md_sfcode_node_modules_ipaddr_js_README_autotoc_md12922}{}\doxysubsection{Global methods}\label{md_sfcode_node_modules_ipaddr_js_README_autotoc_md12922}
There are three global methods defined\+: {\ttfamily ipaddr.\+is\+Valid}, {\ttfamily ipaddr.\+parse} and {\ttfamily ipaddr.\+process}. All of them receive a string as a single parameter.

The {\ttfamily ipaddr.\+is\+Valid} method returns {\ttfamily true} if the address is a valid IPv4 or IPv6 address, and {\ttfamily false} otherwise. It does not throw any exceptions.

The {\ttfamily ipaddr.\+parse} method returns an object representing the IP address, or throws an {\ttfamily Error} if the passed string is not a valid representation of an IP address.

The {\ttfamily ipaddr.\+process} method works just like the {\ttfamily ipaddr.\+parse} one, but it automatically converts IPv4-\/mapped IPv6 addresses to their IPv4 counterparts before returning. It is useful when you have a Node.\+js instance listening on an IPv6 socket, and the {\ttfamily net.\+ivp6.\+bindv6only} sysctl parameter (or its equivalent on non-\/\+Linux OS) is set to 0. In this case, you can accept IPv4 connections on your IPv6-\/only socket, but the remote address will be mangled. Use {\ttfamily ipaddr.\+process} method to automatically demangle it.\hypertarget{md_sfcode_node_modules_ipaddr_js_README_autotoc_md12923}{}\doxysubsection{Object representation}\label{md_sfcode_node_modules_ipaddr_js_README_autotoc_md12923}
Parsing methods return an object which descends from {\ttfamily ipaddr.\+IPv6} or {\ttfamily ipaddr.\+IPv4}. These objects share some properties, but most of them differ.\hypertarget{md_sfcode_node_modules_ipaddr_js_README_autotoc_md12924}{}\doxysubsubsection{Shared properties}\label{md_sfcode_node_modules_ipaddr_js_README_autotoc_md12924}
One can determine the type of address by calling {\ttfamily addr.\+kind()}. It will return either {\ttfamily \char`\"{}ipv6\char`\"{}} or {\ttfamily \char`\"{}ipv4\char`\"{}}.

An address can be converted back to its string representation with {\ttfamily addr.\+to\+String()}. Note that this method\+:
\begin{DoxyItemize}
\item does not return the original string used to create the object (in fact, there is no way of getting that string)
\item returns a compact representation (when it is applicable)
\end{DoxyItemize}

A {\ttfamily match(range, bits)} method can be used to check if the address falls into a certain CIDR range. Note that an address can be (obviously) matched only against an address of the same type.

For example\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{var addr = ipaddr.parse("{}2001:db8:1234::1"{});}
\DoxyCodeLine{var range = ipaddr.parse("{}2001:db8::"{});}
\DoxyCodeLine{}
\DoxyCodeLine{addr.match(range, 32); // => true }

\end{DoxyCode}


Alternatively, {\ttfamily match} can also be called as {\ttfamily match(\mbox{[}range, bits\mbox{]})}. In this way, it can be used together with the {\ttfamily parse\+CIDR(string)} method, which parses an IP address together with a CIDR range.

For example\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{var addr = ipaddr.parse("{}2001:db8:1234::1"{});}
\DoxyCodeLine{}
\DoxyCodeLine{addr.match(ipaddr.parseCIDR("{}2001:db8::/32"{})); // => true }

\end{DoxyCode}


A {\ttfamily range()} method returns one of predefined names for several special ranges defined by IP protocols. The exact names (and their respective CIDR ranges) can be looked up in the source\+: \href{https://github.com/whitequark/ipaddr.js/blob/master/src/ipaddr.coffee\#L186}{\texttt{ IPv6 ranges}} and \href{https://github.com/whitequark/ipaddr.js/blob/master/src/ipaddr.coffee\#L71}{\texttt{ IPv4 ranges}}. Some common ones include {\ttfamily \char`\"{}unicast\char`\"{}} (the default one) and {\ttfamily \char`\"{}reserved\char`\"{}}.

You can match against your own range list by using {\ttfamily ipaddr.\+subnet\+Match(address, range\+List, default\+Name)} method. It can work with a mix of IPv6 or IPv4 addresses, and accepts a name-\/to-\/subnet map as the range list. For example\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{var rangeList = \{}
\DoxyCodeLine{  documentationOnly: [ ipaddr.parse('2001:db8::'), 32 ],}
\DoxyCodeLine{  tunnelProviders: [}
\DoxyCodeLine{    [ ipaddr.parse('2001:470::'), 32 ], // he.net}
\DoxyCodeLine{    [ ipaddr.parse('2001:5c0::'), 32 ]  // freenet6}
\DoxyCodeLine{  ]}
\DoxyCodeLine{\};}
\DoxyCodeLine{ipaddr.subnetMatch(ipaddr.parse('2001:470:8:66::1'), rangeList, 'unknown'); // => "{}tunnelProviders"{} }

\end{DoxyCode}


The addresses can be converted to their byte representation with {\ttfamily to\+Byte\+Array()}. (Actually, Java\+Script mostly does not know about byte buffers. They are emulated with arrays of numbers, each in range of 0..255.)


\begin{DoxyCode}{0}
\DoxyCodeLine{var bytes = ipaddr.parse('2a00:1450:8007::68').toByteArray(); // ipv6.google.com}
\DoxyCodeLine{bytes // => [42, 0x00, 0x14, 0x50, 0x80, 0x07, 0x00, <zeroes...>, 0x00, 0x68 ] }

\end{DoxyCode}


The {\ttfamily ipaddr.\+IPv4} and {\ttfamily ipaddr.\+IPv6} objects have some methods defined, too. All of them have the same interface for both protocols, and are similar to global methods.

{\ttfamily ipaddr.\+IPv\+X.\+is\+Valid(string)} can be used to check if the string is a valid address for particular protocol, and {\ttfamily ipaddr.\+IPv\+X.\+parse(string)} is the error-\/throwing parser.

{\ttfamily ipaddr.\+IPv\+X.\+is\+Valid(string)} uses the same format for parsing as the POSIX {\ttfamily inet\+\_\+ntoa} function, which accepts unusual formats like {\ttfamily 0xc0.\+168.\+1.\+1} or {\ttfamily 0x10000000}. The function {\ttfamily ipaddr.\+IPv4.\+is\+Valid\+Four\+Part\+Decimal(string)} validates the IPv4 address and also ensures that it is written in four-\/part decimal format.\hypertarget{md_sfcode_node_modules_ipaddr_js_README_autotoc_md12925}{}\doxysubsubsection{IPv6 properties}\label{md_sfcode_node_modules_ipaddr_js_README_autotoc_md12925}
Sometimes you will want to convert IPv6 not to a compact string representation (with the {\ttfamily \+::} substitution); the {\ttfamily to\+Normalized\+String()} method will return an address where all zeroes are explicit.

For example\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{var addr = ipaddr.parse("{}2001:0db8::0001"{});}
\DoxyCodeLine{addr.toString(); // => "{}2001:db8::1"{}}
\DoxyCodeLine{addr.toNormalizedString(); // => "{}2001:db8:0:0:0:0:0:1"{} }

\end{DoxyCode}


The {\ttfamily is\+IPv4\+Mapped\+Address()} method will return {\ttfamily true} if this address is an IPv4-\/mapped one, and {\ttfamily to\+IPv4\+Address()} will return an IPv4 object address.

To access the underlying binary representation of the address, use {\ttfamily addr.\+parts}.


\begin{DoxyCode}{0}
\DoxyCodeLine{var addr = ipaddr.parse("{}2001:db8:10::1234:DEAD"{});}
\DoxyCodeLine{addr.parts // => [0x2001, 0xdb8, 0x10, 0, 0, 0, 0x1234, 0xdead] }

\end{DoxyCode}


A IPv6 zone index can be accessed via {\ttfamily addr.\+zone\+Id}\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{var addr = ipaddr.parse("{}2001:db8::\%eth0"{});}
\DoxyCodeLine{addr.zoneId // => 'eth0' }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_ipaddr_js_README_autotoc_md12926}{}\doxysubsubsection{IPv4 properties}\label{md_sfcode_node_modules_ipaddr_js_README_autotoc_md12926}
{\ttfamily to\+IPv4\+Mapped\+Address()} will return a corresponding IPv4-\/mapped IPv6 address.

To access the underlying representation of the address, use {\ttfamily addr.\+octets}.


\begin{DoxyCode}{0}
\DoxyCodeLine{var addr = ipaddr.parse("{}192.168.1.1"{});}
\DoxyCodeLine{addr.octets // => [192, 168, 1, 1] }

\end{DoxyCode}


{\ttfamily prefix\+Length\+From\+Subnet\+Mask()} will return a CIDR prefix length for a valid IPv4 netmask or null if the netmask is not valid.


\begin{DoxyCode}{0}
\DoxyCodeLine{ipaddr.IPv4.parse('255.255.255.240').prefixLengthFromSubnetMask() == 28}
\DoxyCodeLine{ipaddr.IPv4.parse('255.192.164.0').prefixLengthFromSubnetMask()  == null }

\end{DoxyCode}


{\ttfamily subnet\+Mask\+From\+Prefix\+Length()} will return an IPv4 netmask for a valid CIDR prefix length.


\begin{DoxyCode}{0}
\DoxyCodeLine{ipaddr.IPv4.subnetMaskFromPrefixLength(24) == "{}255.255.255.0"{}}
\DoxyCodeLine{ipaddr.IPv4.subnetMaskFromPrefixLength(29) == "{}255.255.255.248"{} }

\end{DoxyCode}


{\ttfamily broadcast\+Address\+From\+CIDR()} will return the broadcast address for a given IPv4 interface and netmask in CIDR notation. 
\begin{DoxyCode}{0}
\DoxyCodeLine{ipaddr.IPv4.broadcastAddressFromCIDR("{}172.0.0.1/24"{}) == "{}172.0.0.255"{} }

\end{DoxyCode}
 {\ttfamily network\+Address\+From\+CIDR()} will return the network address for a given IPv4 interface and netmask in CIDR notation. 
\begin{DoxyCode}{0}
\DoxyCodeLine{ipaddr.IPv4.networkAddressFromCIDR("{}172.0.0.1/24"{}) == "{}172.0.0.0"{} }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_ipaddr_js_README_autotoc_md12927}{}\doxysubsubsection{Conversion}\label{md_sfcode_node_modules_ipaddr_js_README_autotoc_md12927}
IPv4 and IPv6 can be converted bidirectionally to and from network byte order (MSB) byte arrays.

The {\ttfamily from\+Byte\+Array()} method will take an array and create an appropriate IPv4 or IPv6 object if the input satisfies the requirements. For IPv4 it has to be an array of four 8-\/bit values, while for IPv6 it has to be an array of sixteen 8-\/bit values.

For example\+: 
\begin{DoxyCode}{0}
\DoxyCodeLine{var addr = ipaddr.fromByteArray([0x7f, 0, 0, 1]);}
\DoxyCodeLine{addr.toString(); // => "{}127.0.0.1"{} }

\end{DoxyCode}


or


\begin{DoxyCode}{0}
\DoxyCodeLine{var addr = ipaddr.fromByteArray([0x20, 1, 0xd, 0xb8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1])}
\DoxyCodeLine{addr.toString(); // => "{}2001:db8::1"{} }

\end{DoxyCode}


Both objects also offer a {\ttfamily to\+Byte\+Array()} method, which returns an array in network byte order (MSB).

For example\+: 
\begin{DoxyCode}{0}
\DoxyCodeLine{var addr = ipaddr.parse("{}127.0.0.1"{});}
\DoxyCodeLine{addr.toByteArray(); // => [0x7f, 0, 0, 1] }

\end{DoxyCode}


or


\begin{DoxyCode}{0}
\DoxyCodeLine{var addr = ipaddr.parse("{}2001:db8::1"{});}
\DoxyCodeLine{addr.toByteArray(); // => [0x20, 1, 0xd, 0xb8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1] }

\end{DoxyCode}
 