opusdev/vector-similarity-api

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 manipulating4IP addresses in JavaScript environments. It runs on both CommonJS runtimes5(e.g. [nodejs]) and in a web browser.6 7ipaddr.js allows you to verify and parse string representation of an IP8address, match it against a CIDR range or range list, determine if it falls9into some reserved ranges (examples include loopback and private ranges),10and convert between IPv4 and IPv4-mapped IPv6 addresses.11 12[nodejs]: http://nodejs.org13 14## Installation15 16`npm install ipaddr.js`17 18or19 20`bower install ipaddr.js`21 22## API23 24ipaddr.js defines one object in the global scope: `ipaddr`. In CommonJS,25it is exported from the module:26 27```js28var ipaddr = require('ipaddr.js');29```30 31The API consists of several global methods and two classes: ipaddr.IPv6 and ipaddr.IPv4.32 33### Global methods34 35There are three global methods defined: `ipaddr.isValid`, `ipaddr.parse` and36`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 or39IPv6 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 an43IP address.44 45The `ipaddr.process` method works just like the `ipaddr.parse` one, but it46automatically converts IPv4-mapped IPv6 addresses to their IPv4 counterparts47before returning. It is useful when you have a Node.js instance listening48on an IPv6 socket, and the `net.ivp6.bindv6only` sysctl parameter (or its49equivalent on non-Linux OS) is set to 0. In this case, you can accept IPv450connections on your IPv6-only socket, but the remote address will be mangled.51Use `ipaddr.process` method to automatically demangle it.52 53### Object representation54 55Parsing methods return an object which descends from `ipaddr.IPv6` or56`ipaddr.IPv4`. These objects share some properties, but most of them differ.57 58#### Shared properties59 60One can determine the type of address by calling `addr.kind()`. It will return61either `"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 is66   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 a70certain CIDR range.71Note that an address can be (obviously) matched only against an address of the same type.72 73For example:74 75```js76var addr = ipaddr.parse("2001:db8:1234::1");77var range = ipaddr.parse("2001:db8::");78 79addr.match(range, 32); // => true80```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 IP84address together with a CIDR range.85 86For example:87 88```js89var addr = ipaddr.parse("2001:db8:1234::1");90 91addr.match(ipaddr.parseCIDR("2001:db8::/32")); // => true92```93 94A `range()` method returns one of predefined names for several special ranges defined95by IP protocols. The exact names (and their respective CIDR ranges) can be looked up96in 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 using100`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```js103var rangeList = {104  documentationOnly: [ ipaddr.parse('2001:db8::'), 32 ],105  tunnelProviders: [106    [ ipaddr.parse('2001:470::'), 32 ], // he.net107    [ ipaddr.parse('2001:5c0::'), 32 ]  // freenet6108  ]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 with115arrays of numbers, each in range of 0..255.)116 117```js118var bytes = ipaddr.parse('2a00:1450:8007::68').toByteArray(); // ipv6.google.com119bytes // => [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 them123have 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 address126for 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#L186131[IPv4 ranges]: https://github.com/whitequark/ipaddr.js/blob/master/src/ipaddr.coffee#L71132 133#### IPv6 properties134 135Sometimes you will want to convert IPv6 not to a compact string representation (with136the `::` substitution); the `toNormalizedString()` method will return an address where137all zeroes are explicit.138 139For example:140 141```js142var 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-mapped148one, and `toIPv4Address()` will return an IPv4 object address.149 150To access the underlying binary representation of the address, use `addr.parts`.151 152```js153var 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```js160var addr = ipaddr.parse("2001:db8::%eth0");161addr.zoneId // => 'eth0'162```163 164#### IPv4 properties165 166`toIPv4MappedAddress()` will return a corresponding IPv4-mapped IPv6 address.167 168To access the underlying representation of the address, use `addr.octets`.169 170```js171var 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 or176null if the netmask is not valid.177 178```js179ipaddr.IPv4.parse('255.255.255.240').prefixLengthFromSubnetMask() == 28180ipaddr.IPv4.parse('255.192.164.0').prefixLengthFromSubnetMask()  == null181```182 183`subnetMaskFromPrefixLength()` will return an IPv4 netmask for a valid CIDR prefix length.184 185```js186ipaddr.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```js192ipaddr.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```js196ipaddr.IPv4.networkAddressFromCIDR("172.0.0.1/24") == "172.0.0.0"197```198 199#### Conversion200 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 object204if 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```js209var addr = ipaddr.fromByteArray([0x7f, 0, 0, 1]);210addr.toString(); // => "127.0.0.1"211```212 213or214 215```js216var 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```js224var addr = ipaddr.parse("127.0.0.1");225addr.toByteArray(); // => [0x7f, 0, 0, 1]226```227 228or229 230```js231var 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```234