0
# IEEE754
1

2
IEEE754 is a lightweight JavaScript library for reading and writing IEEE754 floating point numbers from/to Buffer objects or array-like structures. It implements the IEEE Standard for Floating-Point Arithmetic (IEEE 754) with precise control over floating-point number encoding and decoding, supporting different endianness, mantissa lengths, and byte counts.
3

4
## Package Information
5

6
- **Package Name**: ieee754
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install ieee754`
10

11
## Core Imports
12

13
```javascript
14
const ieee754 = require('ieee754');
15
```
16

17
For ES modules:
18

19
```javascript
20
import * as ieee754 from 'ieee754';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const ieee754 = require('ieee754');
27

28
// Create a buffer to work with
29
const buffer = Buffer.alloc(4);
30

31
// Write a 32-bit float (single precision)
32
const value = 42.42;
33
ieee754.write(buffer, value, 0, true, 23, 4);
34

35
// Read the 32-bit float back
36
const readValue = ieee754.read(buffer, 0, true, 23, 4);
37
console.log(readValue); // 42.42000007629395
38

39
// Working with 64-bit doubles
40
const doubleBuffer = Buffer.alloc(8);
41
const doubleValue = 12345.123456789;
42

43
// Write a 64-bit double (double precision)
44
ieee754.write(doubleBuffer, doubleValue, 0, true, 52, 8);
45

46
// Read the 64-bit double back
47
const readDouble = ieee754.read(doubleBuffer, 0, true, 52, 8);
48
console.log(readDouble); // 12345.123456789
49
```
50

51
## Architecture
52

53
IEEE754 implements low-level binary operations for floating-point number encoding and decoding:
54

55
- **Binary Representation**: Converts floating-point numbers to/from their binary IEEE754 representation
56
- **Configurable Precision**: Supports different mantissa lengths and byte counts for various precision levels
57
- **Endianness Control**: Handles both little-endian and big-endian byte ordering
58
- **Standards Compliance**: Follows IEEE 754 specification including special value handling (Infinity, NaN, denormalized numbers)
59

60
## Capabilities
61

62
### Reading IEEE754 Numbers
63

64
Reads an IEEE754 floating point number from a buffer or array-like object.
65

66
```javascript { .api }
67
/**
68
 * Reads an IEEE754 floating point number from a buffer
69
 * @param {Buffer|Uint8Array|Array} buffer - Buffer or array-like object containing the data
70
 * @param {number} offset - Offset into the buffer to start reading
71
 * @param {boolean} isLE - Whether to use little-endian byte order
72
 * @param {number} mLen - Mantissa length in bits
73
 * @param {number} nBytes - Number of bytes to read
74
 * @returns {number} The parsed floating point value
75
 */
76
function read(buffer, offset, isLE, mLen, nBytes);
77
```
78

79
**Usage Examples:**
80

81
```javascript
82
const ieee754 = require('ieee754');
83

84
// Read a 32-bit float (single precision)
85
const buffer32 = Buffer.from([0x42, 0x28, 0xF5, 0xC3]); // Little-endian representation
86
const float32 = ieee754.read(buffer32, 0, true, 23, 4);
87

88
// Read a 64-bit double (double precision)
89
const buffer64 = Buffer.alloc(8);
90
buffer64.writeDoubleLE(3.141592653589793, 0);
91
const float64 = ieee754.read(buffer64, 0, true, 52, 8);
92

93
// Read big-endian format
94
const bigEndianBuffer = Buffer.from([0xC3, 0xF5, 0x28, 0x42]);
95
const bigEndianFloat = ieee754.read(bigEndianBuffer, 0, false, 23, 4);
96
```
97

98
### Writing IEEE754 Numbers
99

100
Writes an IEEE754 floating point number to a buffer or array-like object.
101

102
```javascript { .api }
103
/**
104
 * Writes an IEEE754 floating point number to a buffer
105
 * @param {Buffer|Uint8Array|Array} buffer - Buffer or array-like object to write to
106
 * @param {number} value - The floating point value to write
107
 * @param {number} offset - Offset into the buffer to start writing
108
 * @param {boolean} isLE - Whether to use little-endian byte order
109
 * @param {number} mLen - Mantissa length in bits
110
 * @param {number} nBytes - Number of bytes to write
111
 * @returns {void} Modifies the buffer in-place
112
 */
113
function write(buffer, value, offset, isLE, mLen, nBytes);
114
```
115

116
**Usage Examples:**
117

118
```javascript
119
const ieee754 = require('ieee754');
120

121
// Write a 32-bit float (single precision)
122
const buffer32 = Buffer.alloc(4);
123
ieee754.write(buffer32, 42.42, 0, true, 23, 4);
124

125
// Write a 64-bit double (double precision)  
126
const buffer64 = Buffer.alloc(8);
127
ieee754.write(buffer64, 3.141592653589793, 0, true, 52, 8);
128

129
// Write in big-endian format
130
const bigEndianBuffer = Buffer.alloc(4);
131
ieee754.write(bigEndianBuffer, 123.456, 0, false, 23, 4);
132

133
// Write special values
134
const specialBuffer = Buffer.alloc(4);
135
ieee754.write(specialBuffer, Infinity, 0, true, 23, 4);
136
ieee754.write(specialBuffer, -Infinity, 0, true, 23, 4);
137
ieee754.write(specialBuffer, NaN, 0, true, 23, 4);
138
```
139

140
## Common Patterns
141

142
### Standard IEEE754 Formats
143

144
```javascript
145
const ieee754 = require('ieee754');
146

147
// 32-bit single precision float (IEEE 754 binary32)
148
// mLen: 23 (mantissa bits), nBytes: 4 (total bytes)
149
const buffer32 = Buffer.alloc(4);
150
ieee754.write(buffer32, 1.5, 0, true, 23, 4);
151
const value32 = ieee754.read(buffer32, 0, true, 23, 4);
152

153
// 64-bit double precision float (IEEE 754 binary64)  
154
// mLen: 52 (mantissa bits), nBytes: 8 (total bytes)
155
const buffer64 = Buffer.alloc(8);
156
ieee754.write(buffer64, 1.5, 0, true, 52, 8);
157
const value64 = ieee754.read(buffer64, 0, true, 52, 8);
158
```
159

160
### Endianness Handling
161

162
```javascript
163
const ieee754 = require('ieee754');
164
const buffer = Buffer.alloc(4);
165
const value = 42.0;
166

167
// Little-endian (most common on x86/x64)
168
ieee754.write(buffer, value, 0, true, 23, 4);
169
const littleEndian = ieee754.read(buffer, 0, true, 23, 4);
170

171
// Big-endian (network byte order)
172
ieee754.write(buffer, value, 0, false, 23, 4);
173
const bigEndian = ieee754.read(buffer, 0, false, 23, 4);
174
```
175

176
### Working with Typed Arrays
177

178
```javascript
179
const ieee754 = require('ieee754');
180

181
// Works with Uint8Array and other typed arrays
182
const uint8Array = new Uint8Array(4);
183
ieee754.write(uint8Array, 3.14159, 0, true, 23, 4);
184
const result = ieee754.read(uint8Array, 0, true, 23, 4);
185
```
186

187
## Error Handling
188

189
The library handles IEEE754 special values correctly:
190

191
- **Infinity**: Positive and negative infinity values are preserved
192
- **NaN**: Not-a-Number values are handled appropriately  
193
- **Zero**: Both positive and negative zero are supported
194
- **Denormalized numbers**: Subnormal values are handled according to IEEE754 specification
195

196
```javascript
197
const ieee754 = require('ieee754');
198
const buffer = Buffer.alloc(4);
199

200
// Special values
201
ieee754.write(buffer, Infinity, 0, true, 23, 4);
202
console.log(ieee754.read(buffer, 0, true, 23, 4)); // Infinity
203

204
ieee754.write(buffer, -Infinity, 0, true, 23, 4);
205
console.log(ieee754.read(buffer, 0, true, 23, 4)); // -Infinity
206

207
ieee754.write(buffer, NaN, 0, true, 23, 4);
208
console.log(ieee754.read(buffer, 0, true, 23, 4)); // NaN
209
```