JavaScript/Uint8ClampedArray

Uint8ClampedArray

概要

Uint8ClampedArray は、0 から 255 の範囲にクランプ（飽和）された 8 ビット符号なし整数型の配列です。この配列は、バッファ上で数値を効率的に操作するための型付き配列として、JavaScript の ECMAScript 仕様に基づき動作します。配列内の各要素は、指定された数値が範囲内に収まるように自動的に丸められます。

コンストラクタ

new Uint8ClampedArray(buffer [, byteOffset [, length]])
new Uint8ClampedArray(length)
new Uint8ClampedArray(typedArray)
new Uint8ClampedArray(iterable)

• 引数
  • buffer: ArrayBuffer または SharedArrayBuffer
  • byteOffset (オプション): バイト単位でのオフセット位置（デフォルトは 0）
  • length (オプション): 配列の要素数
  • typedArray: 既存の型付き配列を基にする
  • iterable: 配列や反復可能オブジェクト（Map や Set など）
• 戻り値: 指定された条件に基づく新しい Uint8ClampedArray

プロパティ

Uint8ClampedArray.BYTES_PER_ELEMENT

• 各要素のバイト長（固定値: 1）

Uint8ClampedArray.prototype.length

• 配列内の要素数を返す（読み取り専用）

Uint8ClampedArray.prototype.buffer

• 基盤となる ArrayBuffer を返す

Uint8ClampedArray.prototype.byteOffset

• ArrayBuffer 内の先頭位置をバイト単位で返す

Uint8ClampedArray.prototype.byteLength

• バッファの全体のバイト長を返す

メソッド

Uint8ClampedArray.prototype.set()

uint8ClampedArray.set(array [, offset])

• 引数
  • array: コピー元の配列（型付き配列または通常の配列）
  • offset (オプション): 書き込みの開始インデックス（デフォルトは 0）
• 戻り値: なし
• 説明: 指定された配列から要素をコピーして設定する

Uint8ClampedArray.prototype.subarray()

uint8ClampedArray.subarray(begin [, end])

• 引数
  • begin: 開始インデックス
  • end (オプション): 終了インデックス（デフォルトは配列の終端）
• 戻り値: 元の配列の部分範囲を共有する新しい Uint8ClampedArray

使用例

// Uint8ClampedArrayの作成
const buffer = new ArrayBuffer(16);
const uint8ClampedArray = new Uint8ClampedArray(buffer);

// 配列の要素を設定
uint8ClampedArray[0] = 300;  // クランプされて 255
uint8ClampedArray[1] = -50;  // クランプされて 0

console.log(uint8ClampedArray[0]); // 255
console.log(uint8ClampedArray[1]); // 0

// 値の丸めとクランプ処理
const value = 128.5;
const clampedValue = new Uint8ClampedArray([value]);

console.log(clampedValue[0]);  // 129 (銀行員の丸めが適用される)

注意点

• Uint8ClampedArray の各要素は、0 から 255 の範囲にクランプ（飽和）されます。範囲外の値が代入されると、その値は最も近い境界に丸められます。
• 値の丸めは、数値が 0.5 の倍数に近い場合に特定の方法で行われます。ECMAScript 仕様における「銀行員の丸め」（round half to even）が適用され、値が 0.5 に近い場合には、偶数に丸められます。具体的には、次のように処理されます:
  1. 値が NaN の場合、0 にクランプされます。
  2. 数値が範囲外の場合、最も近い範囲内の整数に丸められます。
  3. 例えば、値が 128.5 の場合、最も近い偶数 128 に丸められます（ただし、129 に丸められることもあります）。

関連オブジェクト

• JavaScript/Uint8Array
• JavaScript/TypedArray
• JavaScript/ArrayBuffer
• JavaScript/DataView

ブラウザサポート

• Chrome 4+
• Firefox 3.5+
• Safari 4+
• Edge 12+

仕様

• ECMAScript 2015 (ES6)