0
# Address Conversion
1

2
Functions for converting IP addresses between different representations including strings, buffers, and long integers with support for both IPv4 and IPv6 addresses.
3

4
## Capabilities
5

6
### Buffer Conversion
7

8
#### toBuffer
9

10
Converts an IP address string to a Buffer representation.
11

12
```javascript { .api }
13
/**
14
 * Converts IP address string to Buffer
15
 * @param {string} ip - IPv4 or IPv6 address string
16
 * @param {Buffer} [buff] - Optional pre-allocated buffer to write to
17
 * @param {number} [offset=0] - Optional offset position in buffer
18
 * @returns {Buffer} Buffer containing IP address bytes (4 bytes for IPv4, 16 bytes for IPv6)
19
 * @throws {Error} Throws error for invalid IP address format
20
 */
21
function toBuffer(ip, buff, offset);
22
```
23

24
**Usage Examples:**
25

26
```javascript
27
const ip = require('ip');
28

29
// Convert IPv4 to buffer
30
const ipv4Buffer = ip.toBuffer('127.0.0.1');
31
console.log(ipv4Buffer); // <Buffer 7f 00 00 01>
32

33
// Convert IPv6 to buffer
34
const ipv6Buffer = ip.toBuffer('::1');
35
console.log(ipv6Buffer.length); // 16
36

37
// Convert to existing buffer at offset
38
const buffer = Buffer.alloc(128);
39
ip.toBuffer('192.168.1.1', buffer, 64);
40
console.log(buffer.slice(64, 68)); // <Buffer c0 a8 01 01>
41

42
// IPv6 mapped IPv4
43
const mappedBuffer = ip.toBuffer('::ffff:127.0.0.1');
44
console.log(mappedBuffer.toString('hex')); // '00000000000000000000ffff7f000001'
45
```
46

47
#### toString
48

49
Converts a Buffer to IP address string representation.
50

51
```javascript { .api }
52
/**
53
 * Converts Buffer to IP address string
54
 * @param {Buffer} buff - Buffer containing IP address bytes
55
 * @param {number} [offset=0] - Starting position in buffer
56
 * @param {number} [length] - Number of bytes to read (4 for IPv4, 16 for IPv6)
57
 * @returns {string} String representation of IP address
58
 */
59
function toString(buff, offset, length);
60
```
61

62
**Usage Examples:**
63

64
```javascript
65
const ip = require('ip');
66

67
// Convert IPv4 buffer to string
68
const ipv4Buffer = Buffer.from([127, 0, 0, 1]);
69
console.log(ip.toString(ipv4Buffer)); // '127.0.0.1'
70

71
// Convert IPv6 buffer to string
72
const ipv6Buffer = Buffer.alloc(16);
73
ipv6Buffer[15] = 1; // ::1
74
console.log(ip.toString(ipv6Buffer)); // '::1'
75

76
// Convert with offset and length
77
const buffer = Buffer.from([0, 0, 0, 0, 192, 168, 1, 1]);
78
console.log(ip.toString(buffer, 4, 4)); // '192.168.1.1'
79
```
80

81
### Long Integer Conversion (IPv4 only)
82

83
#### toLong
84

85
Converts IPv4 address string to 32-bit unsigned integer.
86

87
```javascript { .api }
88
/**
89
 * Converts IPv4 address string to 32-bit unsigned integer
90
 * @param {string} ip - IPv4 address string (e.g., '127.0.0.1')
91
 * @returns {number} 32-bit unsigned integer representation
92
 */
93
function toLong(ip);
94
```
95

96
**Usage Examples:**
97

98
```javascript
99
const ip = require('ip');
100

101
console.log(ip.toLong('127.0.0.1')); // 2130706433
102
console.log(ip.toLong('192.168.1.1')); // 3232235777
103
console.log(ip.toLong('255.255.255.255')); // 4294967295
104
```
105

106
#### fromLong
107

108
Converts 32-bit unsigned integer to IPv4 address string.
109

110
```javascript { .api }
111
/**
112
 * Converts 32-bit unsigned integer to IPv4 address string
113
 * @param {number} ipl - 32-bit unsigned integer
114
 * @returns {string} IPv4 address string
115
 */
116
function fromLong(ipl);
117
```
118

119
**Usage Examples:**
120

121
```javascript
122
const ip = require('ip');
123

124
console.log(ip.fromLong(2130706433)); // '127.0.0.1'
125
console.log(ip.fromLong(3232235777)); // '192.168.1.1'
126
console.log(ip.fromLong(4294967295)); // '255.255.255.255'
127

128
// Round-trip conversion
129
const originalIp = '10.0.0.1';
130
const longForm = ip.toLong(originalIp);
131
const backToString = ip.fromLong(longForm);
132
console.log(backToString); // '10.0.0.1'
133
```
134

135
#### normalizeToLong
136

137
Normalizes various IPv4 address formats to 32-bit unsigned integer, supporting decimal, octal, hexadecimal, and abbreviated notations.
138

139
```javascript { .api }
140
/**
141
 * Normalizes various IPv4 formats to 32-bit unsigned integer
142
 * @param {string} addr - IPv4 address in various formats
143
 * @returns {number} 32-bit unsigned integer or -1 for invalid input
144
 */
145
function normalizeToLong(addr);
146
```
147

148
**Usage Examples:**
149

150
```javascript
151
const ip = require('ip');
152

153
// Standard decimal notation
154
console.log(ip.normalizeToLong('127.0.0.1')); // 2130706433
155

156
// Abbreviated formats
157
console.log(ip.normalizeToLong('127.1')); // 2130706433 (127.0.0.1)
158
console.log(ip.normalizeToLong('127.0.1')); // 2130706433 (127.0.0.1)
159

160
// Hexadecimal notation
161
console.log(ip.normalizeToLong('0x7f.0x0.0x0.0x1')); // 2130706433
162
console.log(ip.normalizeToLong('0x7f000001')); // 2130706433
163

164
// Octal notation (digits 0-7 after leading zero)
165
console.log(ip.normalizeToLong('010.0.0.01')); // 134217729 (8.0.0.1)
166

167
// Invalid formats return -1
168
console.log(ip.normalizeToLong('256.1.1.1')); // -1
169
console.log(ip.normalizeToLong('019.0.0.1')); // -1 (invalid octal)
170
console.log(ip.normalizeToLong('0xGG.0.0.1')); // -1 (invalid hex)
171
```