Uint8Array

  • Revision slug: Web/JavaScript/Typed_arrays/Uint8Array
  • Revision title: Uint8Array
  • Revision id: 444791
  • Created:
  • Creator: jyasskin
  • Is current revision? No
  • Comment Fixed specification link.

Revision Content

{{ gecko_minversion_header("2.0") }}{{ draft() }}

The Uint8Array type represents an array of 8-bit unsigned integers.

Once established, you can reference elements in the array using the object's methods, or using standard array index syntax (that is, using bracket notation).

Constructors

Note: In these methods, TypedArray represents any of the typed array object types.
Uint8Array Uint8Array(unsigned long length);
Uint8Array Uint8Array(TypedArray array);
Uint8Array Uint8Array(sequence<type> array);
Uint8Array Uint8Array(ArrayBuffer buffer, optional unsigned long byteOffset, optional unsigned long length);

Method overview

Note: In these methods, TypedArray represents any of the typed array object types.
void set(TypedArray array, optional unsigned long offset);
void set(type[] array, optional unsigned long offset);
Uint8Array subarray(long begin, optional long end);

Attributes

Attribute Type Description
buffer ArrayBuffer The ArrayBuffer object used to contain the TypedArray datas. Read only.
byteOffset unsigned long The index at wich starts the TypedArray in it underlying ArrayBuffer. Read only.
length unsigned long The number of entries in the array; for these 8-bit values, this is the same as the size of the array in bytes. Read only.

Constants

Element size

Constant Value Description
BYTES_PER_ELEMENT 1 The size, in bytes, of each array element.

Constructor

Returns a new Uint8Array object.

Uint8Array Uint8Array(
  unsigned long length
);

Uint8Array Uint8Array(
  TypedArray array
);

Uint8Array Uint8Array(
  sequence<type> array
);

Uint8Array Uint8Array(
  ArrayBuffer buffer,
  optional unsigned long byteOffset,
  optional unsigned long length
);
Parameters
length
The number of elements in the byte array. If unspecified, length of the array view will match the buffer's length.
array
An object of any of the typed array types (such as Int32Array), or a sequence of objects of a particular type, to copy into a new ArrayBuffer. Each value in the source array is converted to an 8-bit unsigned integer before being copied into the new array.
buffer
An existing ArrayBuffer to use as the storage for the new Uint8Array object.
byteOffset
The offset, in bytes, to the first byte in the specified buffer for the new view to reference. If not specified, the Uint8Array's view of the buffer will start with the first byte.
Return value

A new Uint8Array object representing the specified data buffer.

Notes

The first form of the constructor, accepting only a length, creates a new ArrayBuffer object that can hold the specified number of signed 8-bit integers, then creates and returns a typed array view referring to that new buffer. The length must be specified in this case.

The second form creates a new ArrayBuffer object that is a duplicate of the specified array, except with each element in the new array converted to an 8-bit signed integer.

The third form of the constructor likewise creates a new ArrayBuffer object that is a duplicate of the specified JavaScript array, with each element in the new array converted to an 8-bit signed integer.

The final form of the constructor creates a new Uint8Array object, using the specified ArrayBuffer as its storage. This lets you access the existing buffer in a different format. If specified, the byteOffset and length parameters let you create the new view to only a portion of the buffer.

Exceptions thrown
INDEX_SIZE_ERR
The specified byteOffset isn't a multiple of the element size, or the byteOffset and length result in the specified view extending past the end of the buffer.

Methods

set()

Sets multiple values in the typed array, reading input values from a specified array.

void set(
  TypedArray array,
  optional unsigned long offset
);

void set(
  type[] array,
  optional unsigned long offset
);
Parameters
array
An array from which to copy values. All values from the source array are copied into the target array, unless the length of the source array plus the offset exceeds the length of the target array, in which case an exception is thrown. If the source array is a typed array, the two arrays may share the same underlying ArrayBuffer; the browser will intelligently copy the source range of the buffer to the destination range.
offset {{ optional_inline() }}
The offset into the target array at which to begin writing values from the source array. If you omit this value, 0 is assumed (that is, the source array will overwrite values in the target array starting at index 0).

subarray()

Returns a new Uint8Array view on the ArrayBuffer store for this Uint8Array object.

Uint8Array subarray(
  long begin,
  optional long end
);
Parameters
begin
The offset to the first element in the array to be referenced by the new Uint8Array object.
end {{ optional_inline() }}
The offset to the element after last element in the array to be referenced by the new Uint8Array object; if not specified, all elements from the one specified by begin to the end of the array are included in the new view.
Notes

The range specified by begin and end is clamped to the valid index range for the current array; if the computed length of the new array would be negative, it's clamped to zero. If either begin or end is negative, it refers to an index from the end of the array instead of from the beginning.

Note: Keep in mind that this is creating a new view on the existing buffer; changes to the new object's contents will impact the original object and vice versa.

Getting an Uint8Array from existing data

From an ArrayBuffer

var myArray = new Uint8Array(myArrayBuffer);

From a Base64-encoded string

Please, read this paragraph.

See also

{{ languages( { "ja": "ja/JavaScript_typed_arrays/Uint8Array"} ) }}

Revision Source

<p>{{ gecko_minversion_header("2.0") }}{{ draft() }}</p>
<p>The <code>Uint8Array</code> type represents an array of 8-bit unsigned integers.</p>
<p>Once established, you can reference elements in the array using the object's methods, or using standard array index syntax (that is, using bracket notation).</p>
<h2 id="Constructors">Constructors</h2>
<div class="note">
  <strong>Note:</strong> In these methods, <code><em>TypedArray</em></code> represents any of the <a href="/en/JavaScript_typed_arrays/ArrayBufferView#Typed_array_subclasses" title="en/JavaScript typed arrays/ArrayBufferView#Typed array subclasses">typed array object types</a>.</div>
<table class="standard-table">
  <tbody>
    <tr>
      <td><code>Uint8Array <a href="/en/JavaScript_typed_arrays/Uint8Array#Int8Array%28%29" title="en/JavaScript typed arrays/Uint8Array#Int8Array()">Uint8Array</a>(unsigned long length);</code></td>
    </tr>
    <tr>
      <td><code>Uint8Array </code><code><a href="/en/JavaScript_typed_arrays/Uint8Array#Int8Array%28%29" title="en/JavaScript typed arrays/Uint8Array#Int8Array()">Uint8Array</a></code><code>(<em>TypedArray</em> array);</code></td>
    </tr>
    <tr>
      <td><code>Uint8Array </code><code><a href="/en/JavaScript_typed_arrays/Uint8Array#Int8Array%28%29" title="en/JavaScript typed arrays/Uint8Array#Int8Array()">Uint8Array</a></code><code>(sequence&lt;type&gt; array);</code></td>
    </tr>
    <tr>
      <td><code>Uint8Array </code><code><a href="/en/JavaScript_typed_arrays/Uint8Array#Int8Array%28%29" title="en/JavaScript typed arrays/Uint8Array#Int8Array()">Uint8Array</a></code><code>(ArrayBuffer buffer, optional unsigned long byteOffset, optional unsigned long length);</code></td>
    </tr>
  </tbody>
</table>
<h2 id="Method_overview" name="Method_overview">Method overview</h2>
<div class="note">
  <strong>Note:</strong> In these methods, <code><em>TypedArray</em></code> represents any of the <a href="/en/JavaScript_typed_arrays/ArrayBufferView#Typed_array_subclasses" title="en/JavaScript typed arrays/ArrayBufferView#Typed array subclasses">typed array object types</a>.</div>
<table class="standard-table">
  <tbody>
    <tr>
      <td><code>void <a href="/en/JavaScript_typed_arrays/Int8Array#set%28%29" title="en/JavaScript typed arrays/Int8Array#set()">set</a>(<em>TypedArray</em> array, optional unsigned long offset);</code></td>
    </tr>
    <tr>
      <td><code>void <a href="/en/JavaScript_typed_arrays/Int8Array#set%28%29" title="en/JavaScript typed arrays/Int8Array#set()">set</a>(type[] array, optional unsigned long offset);</code></td>
    </tr>
    <tr>
      <td><code>Uint8Array <a href="/en/JavaScript_typed_arrays/Int8Array#subarray%28%29" title="en/JavaScript typed arrays/Int8Array#subarray()">subarray</a>(long begin, optional long end);</code></td>
    </tr>
  </tbody>
</table>
<h2 id="Attributes">Attributes</h2>
<table class="standard-table" style="width: auto;">
  <tbody>
    <tr>
      <td class="header">Attribute</td>
      <td class="header">Type</td>
      <td class="header">Description</td>
    </tr>
    <tr>
      <td>buffer</td>
      <td>ArrayBuffer</td>
      <td>The ArrayBuffer object used to contain the TypedArray datas.&nbsp;<strong>Read only.</strong></td>
    </tr>
    <tr>
      <td>byteOffset</td>
      <td>unsigned long</td>
      <td>The index at wich starts the TypedArray in it underlying ArrayBuffer.&nbsp;<strong>Read only.</strong></td>
    </tr>
    <tr>
      <td>length</td>
      <td>unsigned long</td>
      <td>The number of entries in the array; for these 8-bit values, this is the same as the size of the array in bytes. <strong>Read only.</strong></td>
    </tr>
  </tbody>
</table>
<h2 id="Constants" name="Constants">Constants</h2>
<h3 id="Element_size">Element size</h3>
<table class="standard-table">
  <tbody>
    <tr>
      <td class="header">Constant</td>
      <td class="header">Value</td>
      <td class="header">Description</td>
    </tr>
    <tr>
      <td><code>BYTES_PER_ELEMENT</code></td>
      <td>1</td>
      <td>The size, in bytes, of each array element.</td>
    </tr>
  </tbody>
</table>
<h2 id="Constructor">Constructor</h2>
<p>Returns a new Uint8Array object.</p>
<pre>
Uint8Array Uint8Array(
&nbsp; unsigned long length
);

Uint8Array Uint8Array(
&nbsp; <em>TypedArray</em> array
);

Uint8Array Uint8Array(
&nbsp; sequence&lt;type&gt; array
);

Uint8Array Uint8Array(
&nbsp; ArrayBuffer buffer,
&nbsp; optional unsigned long byteOffset,
&nbsp; optional unsigned long length
);
</pre>
<h6 id="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>length</code></dt>
  <dd>
    The number of elements in the byte array. If unspecified, length of the array view will match the buffer's length.</dd>
  <dt>
    <code>array</code></dt>
  <dd>
    An object of any of the typed array types (such as <code>Int32Array</code>), or a sequence of objects of a particular type, to copy into a new <a href="/en/JavaScript_typed_arrays/ArrayBuffer" title="en/JavaScript typed arrays/ArrayBuffer"><code>ArrayBuffer</code></a>. Each value in the source array is converted to an 8-bit unsigned integer before being copied into the new array.</dd>
  <dt>
    <code>buffer</code></dt>
  <dd>
    An existing <a href="/en/JavaScript_typed_arrays/ArrayBuffer" title="en/JavaScript typed arrays/ArrayBuffer"><code>ArrayBuffer</code></a> to use as the storage for the new <code>Uint8Array</code> object.</dd>
  <dt>
    <code>byteOffset</code></dt>
  <dd>
    The offset, in bytes, to the first byte in the specified buffer for the new view to reference. If not specified, the <code>Uint8Array</code>'s view of the buffer will start with the first byte.</dd>
</dl>
<h6 id="Return_value">Return value</h6>
<p>A new <code>Uint8Array</code> object representing the specified data buffer.</p>
<h6 id="Notes">Notes</h6>
<p>The first form of the constructor, accepting only a length, creates a new <a href="/en/JavaScript_typed_arrays/ArrayBuffer" title="en/JavaScript typed arrays/ArrayBuffer"><code>ArrayBuffer</code></a> object that can hold the specified number of signed 8-bit integers, then creates and returns a typed array view referring to that new buffer. The <code>length</code> must be specified in this case.</p>
<p>The second form creates a new <a href="/en/JavaScript_typed_arrays/ArrayBuffer" title="en/JavaScript typed arrays/ArrayBuffer"><code>ArrayBuffer</code></a> object that is a duplicate of the specified array, except with each element in the new array converted to an 8-bit signed integer.</p>
<p>The third form of the constructor likewise creates a new <a href="/en/JavaScript_typed_arrays/ArrayBuffer" title="en/JavaScript typed arrays/ArrayBuffer"><code>ArrayBuffer</code></a> object that is a duplicate of the specified JavaScript array, with each element in the new array converted to an 8-bit signed integer.</p>
<p>The final form of the constructor creates a new <code>Uint8Array</code> object, using the specified <a href="/en/JavaScript_typed_arrays/ArrayBuffer" title="en/JavaScript typed arrays/ArrayBuffer"><code>ArrayBuffer</code></a> as its storage. This lets you access the existing buffer in a different format. If specified, the <code>byteOffset</code> and <code>length</code> parameters let you create the new view to only a portion of the buffer.</p>
<h6 id="Exceptions_thrown">Exceptions thrown</h6>
<dl>
  <dt>
    <code>INDEX_SIZE_ERR</code></dt>
  <dd>
    The specified <code>byteOffset</code> isn't a multiple of the element size, or the <code>byteOffset</code> and <code>length</code> result in the specified view extending past the end of the buffer.</dd>
</dl>
<h2 id="Methods">Methods</h2>
<h3 id="set()">set()</h3>
<p>Sets multiple values in the typed array, reading input values from a specified array.</p>
<pre>
void set(
&nbsp; <em>TypedArray</em> array,
&nbsp; optional unsigned long offset
);

void set(
&nbsp; type[] array,
&nbsp; optional unsigned long offset
);
</pre>
<h6 id="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>array</code></dt>
  <dd>
    An array from which to copy values. All values from the source array are copied into the target array, unless the length of the source array plus the offset exceeds the length of the target array, in which case an exception is thrown. If the source array is a typed array, the two arrays may share the same underlying <code><a href="/en/JavaScript_typed_arrays/ArrayBuffer" title="en/JavaScript typed arrays/ArrayBuffer">ArrayBuffer</a></code>; the browser will intelligently copy the source range of the buffer to the destination range.</dd>
  <dt>
    offset {{ optional_inline() }}</dt>
  <dd>
    The offset into the target array at which to begin writing values from the source <code>array</code>. If you omit this value, 0 is assumed (that is, the source <code>array</code> will overwrite values in the target array starting at index 0).</dd>
</dl>
<h3 id="subarray()">subarray()</h3>
<p>Returns a new <code>Uint8Array</code> view on the <a href="/en/JavaScript_typed_arrays/ArrayBuffer" title="en/JavaScript typed arrays/ArrayBuffer"><code>ArrayBuffer</code></a> store for this <code>Uint8Array</code> object.</p>
<pre>
Uint8Array subarray(
&nbsp; long begin,
&nbsp; optional long end
);
</pre>
<h6 id="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>begin</code></dt>
  <dd>
    The offset to the first element in the array to be referenced by the new <code>Uint8Array</code> object.</dd>
  <dt>
    <code>end</code> {{ optional_inline() }}</dt>
  <dd>
    The offset to the element after last element in the array to be referenced by the new <code>Uint8Array</code> object; if not specified, all elements from the one specified by <code>begin</code> to the end of the array are included in the new view.</dd>
</dl>
<h6 id="Notes">Notes</h6>
<p>The range specified by <code>begin</code> and <code>end</code> is clamped to the valid index range for the current array; if the computed length of the new array would be negative, it's clamped to zero. If either begin or end is negative, it refers to an index from the end of the array instead of from the beginning.</p>
<div class="note">
  <strong>Note:</strong> Keep in mind that this is creating a new view on the existing buffer; changes to the new object's contents will impact the original object and vice versa.</div>
<h2 id="Getting_an_Uint8Array_from_existing_data">Getting an <code>Uint8Array</code> from existing data</h2>
<h3 id="From_an_ArrayBuffer">From an <code>ArrayBuffer</code></h3>
<pre class="brush: js">
var myArray = new Uint8Array(myArrayBuffer);</pre>
<h3 id="From_a_Base64-encoded_string">From a Base64-encoded string</h3>
<p>Please, read <a href="/en-US/docs/Web/JavaScript/Base64_encoding_and_decoding#Appendix.3A_Decode_a_Base64_string_to_Uint8Array_or_ArrayBuffer" title="/en-US/docs/Web/JavaScript/Base64_encoding_and_decoding#Appendix.3A_Decode_a_Base64_string_to_Uint8Array_or_ArrayBuffer">this paragraph</a>.</p>
<h2 id="See_also">See also</h2>
<ul>
  <li><a class="link-https" href="https://www.khronos.org/registry/typedarray/specs/latest/" title="https://cvs.khronos.org/svn/repos/registry/trunk/public/webgl/doc/spec/TypedArray-spec.html">Typed Array Specification</a></li>
  <li><a href="/en/JavaScript_typed_arrays" title="en/JavaScript typed arrays">JavaScript typed arrays</a></li>
</ul>
<p>{{ languages( { "ja": "ja/JavaScript_typed_arrays/Uint8Array"} ) }}</p>
Revert to this revision