CKTIS / JavaScript
Uint8ClampedArray — bytes com valores limitados
Uint8ClampedArray é um array tipado que armazena números inteiros de 0 a 255. Ao escrever, limita os valores a esse intervalo e arredonda as fracções, em vez de os fazer voltar ao início como acontece com Uint8Array.
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
new Uint8ClampedArray(length)
new Uint8ClampedArray(values)
new Uint8ClampedArray(buffer)
new Uint8ClampedArray(buffer, byteOffset)
new Uint8ClampedArray(buffer, byteOffset, length)Uint8ClampedArray é um tipo padrão de ECMAScript: uma vista sobre um buffer cujos elementos ocupam um byte cada e representam números inteiros sem sinal de 0 a 255. Os valores lidos são do tipo Number; não é um Array normal.
As escritas aplicam ToUint8Clamp: os valores abaixo de 0 passam a 0, e os acima de 255 passam a 255. As fracções são arredondadas para o número inteiro mais próximo; em caso de empate exacto, arredonda-se para o número inteiro par. Assim, 2.5 passa a 2 e 3.5 a 4. Esta regra é diferente de Math.round. NaN passa a 0, Infinity a 255 e -Infinity a 0. Uint8Array, por sua vez, trunca as fracções e faz os números inteiros voltar ao início módulo 256.
new Uint8ClampedArray(length) cria elementos preenchidos com zeros, enquanto new Uint8ClampedArray(values) copia e converte os valores. A forma com buffer cria uma vista sobre a memória existente, sem copiar; só criar a vista não converte os bytes armazenados. O construtor requer new.
O exemplo mostra a limitação e o arredondamento durante a construção e uma atribuição posterior. A limitação aplica-se às escritas nos elementos, não aos cálculos efectuados sobre números lidos do array. É uma funcionalidade da linguagem, não uma API do browser; a especificação não é uma tabela de compatibilidade dos browsers.
Exemplos
const values = new Uint8ClampedArray([-20, 2.5, 3.5, 300, NaN]);
values[0] = 260;
console.log(JSON.stringify(Array.from(values)));Resultado
[255,2,4,255,0]
O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.