source: trip-planner-front/node_modules/ipaddr.js/README.md@ 6c1585f

Last change on this file since 6c1585f was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 8.1 KB
Line 
1# ipaddr.js — an IPv6 and IPv4 address manipulation library [![Build Status](https://travis-ci.org/whitequark/ipaddr.js.svg)](https://travis-ci.org/whitequark/ipaddr.js)
2
3ipaddr.js is a small (1.9K minified and gzipped) library for manipulating
4IP addresses in JavaScript environments. It runs on both CommonJS runtimes
5(e.g. [nodejs]) and in a web browser.
6
7ipaddr.js allows you to verify and parse string representation of an IP
8address, match it against a CIDR range or range list, determine if it falls
9into some reserved ranges (examples include loopback and private ranges),
10and convert between IPv4 and IPv4-mapped IPv6 addresses.
11
12[nodejs]: http://nodejs.org
13
14## Installation
15
16`npm install ipaddr.js`
17
18or
19
20`bower install ipaddr.js`
21
22## API
23
24ipaddr.js defines one object in the global scope: `ipaddr`. In CommonJS,
25it is exported from the module:
26
27```js
28var ipaddr = require('ipaddr.js');
29```
30
31The API consists of several global methods and two classes: ipaddr.IPv6 and ipaddr.IPv4.
32
33### Global methods
34
35There are three global methods defined: `ipaddr.isValid`, `ipaddr.parse` and
36`ipaddr.process`. All of them receive a string as a single parameter.
37
38The `ipaddr.isValid` method returns `true` if the address is a valid IPv4 or
39IPv6 address, and `false` otherwise. It does not throw any exceptions.
40
41The `ipaddr.parse` method returns an object representing the IP address,
42or throws an `Error` if the passed string is not a valid representation of an
43IP address.
44
45The `ipaddr.process` method works just like the `ipaddr.parse` one, but it
46automatically converts IPv4-mapped IPv6 addresses to their IPv4 counterparts
47before returning. It is useful when you have a Node.js instance listening
48on an IPv6 socket, and the `net.ivp6.bindv6only` sysctl parameter (or its
49equivalent on non-Linux OS) is set to 0. In this case, you can accept IPv4
50connections on your IPv6-only socket, but the remote address will be mangled.
51Use `ipaddr.process` method to automatically demangle it.
52
53### Object representation
54
55Parsing methods return an object which descends from `ipaddr.IPv6` or
56`ipaddr.IPv4`. These objects share some properties, but most of them differ.
57
58#### Shared properties
59
60One can determine the type of address by calling `addr.kind()`. It will return
61either `"ipv6"` or `"ipv4"`.
62
63An address can be converted back to its string representation with `addr.toString()`.
64Note that this method:
65 * does not return the original string used to create the object (in fact, there is
66 no way of getting that string)
67 * returns a compact representation (when it is applicable)
68
69A `match(range, bits)` method can be used to check if the address falls into a
70certain CIDR range.
71Note that an address can be (obviously) matched only against an address of the same type.
72
73For example:
74
75```js
76var addr = ipaddr.parse("2001:db8:1234::1");
77var range = ipaddr.parse("2001:db8::");
78
79addr.match(range, 32); // => true
80```
81
82Alternatively, `match` can also be called as `match([range, bits])`. In this way,
83it can be used together with the `parseCIDR(string)` method, which parses an IP
84address together with a CIDR range.
85
86For example:
87
88```js
89var addr = ipaddr.parse("2001:db8:1234::1");
90
91addr.match(ipaddr.parseCIDR("2001:db8::/32")); // => true
92```
93
94A `range()` method returns one of predefined names for several special ranges defined
95by IP protocols. The exact names (and their respective CIDR ranges) can be looked up
96in the source: [IPv6 ranges] and [IPv4 ranges]. Some common ones include `"unicast"`
97(the default one) and `"reserved"`.
98
99You can match against your own range list by using
100`ipaddr.subnetMatch(address, rangeList, defaultName)` 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:
101
102```js
103var rangeList = {
104 documentationOnly: [ ipaddr.parse('2001:db8::'), 32 ],
105 tunnelProviders: [
106 [ ipaddr.parse('2001:470::'), 32 ], // he.net
107 [ ipaddr.parse('2001:5c0::'), 32 ] // freenet6
108 ]
109};
110ipaddr.subnetMatch(ipaddr.parse('2001:470:8:66::1'), rangeList, 'unknown'); // => "tunnelProviders"
111```
112
113The addresses can be converted to their byte representation with `toByteArray()`.
114(Actually, JavaScript mostly does not know about byte buffers. They are emulated with
115arrays of numbers, each in range of 0..255.)
116
117```js
118var bytes = ipaddr.parse('2a00:1450:8007::68').toByteArray(); // ipv6.google.com
119bytes // => [42, 0x00, 0x14, 0x50, 0x80, 0x07, 0x00, <zeroes...>, 0x00, 0x68 ]
120```
121
122The `ipaddr.IPv4` and `ipaddr.IPv6` objects have some methods defined, too. All of them
123have the same interface for both protocols, and are similar to global methods.
124
125`ipaddr.IPvX.isValid(string)` can be used to check if the string is a valid address
126for particular protocol, and `ipaddr.IPvX.parse(string)` is the error-throwing parser.
127
128`ipaddr.IPvX.isValid(string)` uses the same format for parsing as the POSIX `inet_ntoa` function, which accepts unusual formats like `0xc0.168.1.1` or `0x10000000`. The function `ipaddr.IPv4.isValidFourPartDecimal(string)` validates the IPv4 address and also ensures that it is written in four-part decimal format.
129
130[IPv6 ranges]: https://github.com/whitequark/ipaddr.js/blob/master/src/ipaddr.coffee#L186
131[IPv4 ranges]: https://github.com/whitequark/ipaddr.js/blob/master/src/ipaddr.coffee#L71
132
133#### IPv6 properties
134
135Sometimes you will want to convert IPv6 not to a compact string representation (with
136the `::` substitution); the `toNormalizedString()` method will return an address where
137all zeroes are explicit.
138
139For example:
140
141```js
142var addr = ipaddr.parse("2001:0db8::0001");
143addr.toString(); // => "2001:db8::1"
144addr.toNormalizedString(); // => "2001:db8:0:0:0:0:0:1"
145```
146
147The `isIPv4MappedAddress()` method will return `true` if this address is an IPv4-mapped
148one, and `toIPv4Address()` will return an IPv4 object address.
149
150To access the underlying binary representation of the address, use `addr.parts`.
151
152```js
153var addr = ipaddr.parse("2001:db8:10::1234:DEAD");
154addr.parts // => [0x2001, 0xdb8, 0x10, 0, 0, 0, 0x1234, 0xdead]
155```
156
157A IPv6 zone index can be accessed via `addr.zoneId`:
158
159```js
160var addr = ipaddr.parse("2001:db8::%eth0");
161addr.zoneId // => 'eth0'
162```
163
164#### IPv4 properties
165
166`toIPv4MappedAddress()` will return a corresponding IPv4-mapped IPv6 address.
167
168To access the underlying representation of the address, use `addr.octets`.
169
170```js
171var addr = ipaddr.parse("192.168.1.1");
172addr.octets // => [192, 168, 1, 1]
173```
174
175`prefixLengthFromSubnetMask()` will return a CIDR prefix length for a valid IPv4 netmask or
176null if the netmask is not valid.
177
178```js
179ipaddr.IPv4.parse('255.255.255.240').prefixLengthFromSubnetMask() == 28
180ipaddr.IPv4.parse('255.192.164.0').prefixLengthFromSubnetMask() == null
181```
182
183`subnetMaskFromPrefixLength()` will return an IPv4 netmask for a valid CIDR prefix length.
184
185```js
186ipaddr.IPv4.subnetMaskFromPrefixLength(24) == "255.255.255.0"
187ipaddr.IPv4.subnetMaskFromPrefixLength(29) == "255.255.255.248"
188```
189
190`broadcastAddressFromCIDR()` will return the broadcast address for a given IPv4 interface and netmask in CIDR notation.
191```js
192ipaddr.IPv4.broadcastAddressFromCIDR("172.0.0.1/24") == "172.0.0.255"
193```
194`networkAddressFromCIDR()` will return the network address for a given IPv4 interface and netmask in CIDR notation.
195```js
196ipaddr.IPv4.networkAddressFromCIDR("172.0.0.1/24") == "172.0.0.0"
197```
198
199#### Conversion
200
201IPv4 and IPv6 can be converted bidirectionally to and from network byte order (MSB) byte arrays.
202
203The `fromByteArray()` method will take an array and create an appropriate IPv4 or IPv6 object
204if the input satisfies the requirements. For IPv4 it has to be an array of four 8-bit values,
205while for IPv6 it has to be an array of sixteen 8-bit values.
206
207For example:
208```js
209var addr = ipaddr.fromByteArray([0x7f, 0, 0, 1]);
210addr.toString(); // => "127.0.0.1"
211```
212
213or
214
215```js
216var addr = ipaddr.fromByteArray([0x20, 1, 0xd, 0xb8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1])
217addr.toString(); // => "2001:db8::1"
218```
219
220Both objects also offer a `toByteArray()` method, which returns an array in network byte order (MSB).
221
222For example:
223```js
224var addr = ipaddr.parse("127.0.0.1");
225addr.toByteArray(); // => [0x7f, 0, 0, 1]
226```
227
228or
229
230```js
231var addr = ipaddr.parse("2001:db8::1");
232addr.toByteArray(); // => [0x20, 1, 0xd, 0xb8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1]
233```
Note: See TracBrowser for help on using the repository browser.