JavaScript の Uint8ClampedArray

JavaScript の型付き配列 (Typed Array) は要素の型毎に Int8Array、Uint16Array のような種類があります。

その中に、 Uint8ClampedArray というタイプの型付き配列があります。

他の型は「要素の型名」＋「Array(配列)」という名前です。しかし、Uint8ClampedArray だけ「Clamped」という文字があります。

ここでは Uint8ClampedArray の意味を説明し、サンプルコードで動作確認します。

Uint8Array でのオーバーフローの発生

「8ビット符号なし整数」の型付き配列としては、 Uint8Array があります。

「8ビット符号なし整数」ですから、 0 から 255 までの範囲の整数値を表すことができます。

let a1 = new Uint8Array(4)
a1[0] = 1
a1[1] = 2
a1[2] = 3
a1[3] = 4
console.log(a1)
// Uint8Array [ 1, 2, 3, 4 ]

しかし、8ビット符号なし整数の範囲外の数値をセットした場合には、オーバーフローが発生します。

let a1 = new Uint8Array(4)
a1[0] = -1
a1[1] = 0
a1[2] = 255
a1[3] = 256
console.log(a1)
// Uint8Array [ 255, 0, 255, 0 ]

このように -1 という数値を設定した箇所は 255 として認識され、 256 という数値を設定し箇所は 0 となります。

Uint8ClampedArray では、オーバーフロー発生時の動作が異なります。

クランプとは？

英語でクランプ (clamp) というと、次の絵のような留め具のことを指します。

クランプで物を固定することも、動詞で「クランプする」という言い方をします。クランプで留められた状態は「クランプされた (clamped)」ということになります。

"Clamped (クランプされた)" 8ビット符号なし整数値の配列 (Array) では、0 から 255 の範囲に数値を抑えこみ固定する、という動作になります。

Uint8ClampedArray とは

Uint8ClampedArray では、「8ビット符号なし整数」の範囲 (つまり 0 から 255) を超えた数値を、 0 または 255 に置き直します。

0 より小さい値は 0 に置き換え、 255 より大きい数値は 255 に置き換えます。

数値のビット表現に従って何もせずに数値のオーバーフローを発生させるのではなく、 Uint8ClampedArray では有効な数値の範囲に値を押さえ込むようになります。

次の例では -1 や 256 などの、 8ビット符号なし整数値の範囲外の数値をセットしたときに、 Uint8ClampedArray でどのように値が格納されるか確認しています。

let a2 = new Uint8ClampedArray(4)
a2[0] = -1
a2[1] = 0
a2[2] = 255
a2[3] = 256
console.log(a2)
// Uint8ClampedArray [ 0, 0, 255, 255 ]

Uint8ClampedArray ではオーバーフローせずに、最寄りの範囲内の値としてセットされていることが確認できます。