@lazy-num/float-from-buffer
從位元組緩衝區 (Buffer) 中讀取隨機位元組，並轉換為 [0, 1) 區間的雙精度浮點數 (Double-precision Float)。
適合用於以密碼學亂數 (Cryptographic Random Bytes) 產生均勻分布的浮點數，實作方式參考下方「相關資源」中的連結。
特色 (Features)
- 將緩衝區 (Buffer) 內的 7 個位元組組合成 53 bits 精度的浮點數，回傳值落在
[0, 1) - 支援
offset參數，可從緩衝區的任意位置開始讀取 - 輸入長度不足或
offset不合法時丟出RangeError - 同時提供 32 bits 精度的替代實作，以及
readUInt32LE/readUInt32BE等底層讀取工具 - 同時輸出 CommonJS 與 ESM 兩種格式，並附帶 TypeScript 型別宣告
安裝 (Installation)
yarn add @lazy-num/float-from-buffer
yarn-tool add @lazy-num/float-from-buffer
yt add @lazy-num/float-from-buffer使用方式 (Usage)
CommonJS
const floatFromBuffer = require('@lazy-num/float-from-buffer');
// 7 個隨機位元組 → [0, 1) 的浮點數
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x9a, 0xbc, 0xde]);
console.log(floatFromBuffer(buf));
console.log(floatFromBuffer(buf, 0));ESM
import floatFromBuffer from '@lazy-num/float-from-buffer';
const buf = new Uint8Array([0x12, 0x34, 0x56, 0x78, 0x9a, 0xbc, 0xde]);
console.log(floatFromBuffer(buf));例外 (Exception)
const floatFromBuffer = require('@lazy-num/float-from-buffer');
// 緩衝區長度不足時會丟出 RangeError
try
{
floatFromBuffer(Buffer.alloc(3));
}
catch (e)
{
console.error(e instanceof RangeError); // true
console.error(e.message);
}API 文件 (API Documentation)
floatFromBuffer(buf, offset = 0)
主要 API。驗證緩衝區長度後，回傳由位元組組成的雙精度浮點數 (Double-precision Float)。
| 參數 (Parameter) | 型別 (Type) | 預設值 | 說明 |
|---|---|---|---|
buf |
ArrayLike<number> |
— | 存放亂數位元組的緩衝區，例如 Buffer 或 Uint8Array |
offset |
number |
0 |
讀取的起始位置，會先以 Math.floor() 取整數 |
- 回傳 (Returns)：
number，值域為[0, 1) - 丟出 (Throws)：
RangeError— 當buf.length < FLOAT_ENTROPY_BYTES + offset或offset < 0
亦為預設匯出 (Default Export)。
_floatFromBuffer(buf, offset = 0)
不進行長度驗證的內部實作 (Internal Implementation)，會讀取 offset 開始的 7 個位元組：
- 第 1 個位元組取低 5 bits（
% 32），其餘 6 個位元組各取 8 bits，合計 53 bits 精度 - 以連除
/ 256的方式歸一化到[0, 1)
請自行確認緩衝區長度足夠，否則會讀到 undefined 而產生 NaN。
_floatFromBuffer2(buf, offset = 0)
32 bits 精度的替代實作 (Alternative Implementation)：讀取一個大端序 (Big-endian) 的 uint32 後除以 2^32，回傳同樣位於 [0, 1) 的浮點數，但精度較低。
readUInt32LE(buf, offset = 0)
以小端序 (Little-endian) 讀取 4 個位元組，回傳無號 32 位整數 (uint32)。offset 會以 >>> 0 轉為無號整數。
readUInt32BE(buf, offset = 0)
以大端序 (Big-endian) 讀取 4 個位元組，回傳無號 32 位整數 (uint32)。offset 會以 >>> 0 轉為無號整數。
開發 (Development)
本套件為 monorepo（pnpm + lerna）中的套件，常用指令：
pnpm run build # 以 tsdx 建置 dist/，並產生 dist/index.d.ts
pnpm run test:jest # 執行 Jest 測試
pnpm run lint # 執行 ESLint變更日誌 (Changelog)
請參閱 CHANGELOG.md。