Skip to content

stdlib-js/array-uint8c

About stdlib...

We believe in a future in which the web is a preferred environment for numerical computation. To help realize this future, we've built stdlib. stdlib is a standard library, with an emphasis on numerical and scientific computation, written in JavaScript (and C) for execution in browsers and in Node.js.

The library is fully decomposable, being architected in such a way that you can swap out and mix and match APIs and functionality to cater to your exact preferences and use cases.

When you use stdlib, you can be absolutely certain that you are using the most thorough, rigorous, well-written, studied, documented, tested, measured, and high-quality code out there.

To join us in bringing numerical computing to the web, get started by checking us out onGitHub,and please considerfinancially supporting stdlib.We greatly appreciate your continued support!

Uint8ClampedArray

NPM versionBuild StatusCoverage Status

Typed arrayconstructor which returns atyped arrayrepresenting an array of 8-bit unsigned integers in the platform byte order clamped to 0-255.

Installation

npm install @stdlib/array-uint8c

Alternatively,

  • To load the package in a website via ascripttag without installation and bundlers, use theES Moduleavailable on theesmbranch (seeREADME).
  • If you are using Deno, visit thedenobranch (seeREADMEfor usage intructions).
  • For use in Observable, or in browser/node environments, use theUniversal Module Definition (UMD)build available on theumdbranch (seeREADME).

Thebranches.mdfile summarizes the available branches and displays a diagram illustrating their relationships.

To view installation and usage instructions specific to each branch build, be sure to explicitly navigate to the respective README files on each branch, as linked to above.

Usage

varUint8ClampedArray=require('@stdlib/array-uint8c');

Uint8ClampedArray()

Atyped arrayconstructor which returns atyped arrayrepresenting an array of 8-bit unsigned integers in the platform byte order clamped to0-255.

vararr=newUint8ClampedArray();
// returns <Uint8ClampedArray>

Uint8ClampedArray( length )

Returns atyped arrayhaving a specified length.

vararr=newUint8ClampedArray(5);
// returns <Uint8ClampedArray>[ 0, 0, 0, 0, 0 ]

Uint8ClampedArray( typedarray )

Creates atyped arrayfrom anothertyped array.

varFloat32Array=require('@stdlib/array-float32');

vararr1=newFloat32Array([5.0,5.0,5.0]);
vararr2=newUint8ClampedArray(arr1);
// returns <Uint8ClampedArray>[ 5, 5, 5 ]

Uint8ClampedArray( obj )

Creates atyped arrayfrom an array-likeobjector iterable.

vararr=newUint8ClampedArray([5.0,5.0,5.0]);
// returns <Uint8ClampedArray>[ 5, 5, 5 ]

Uint8ClampedArray( buffer[, byteOffset[, length]] )

Returns atyped arrayview of anArrayBuffer.

varArrayBuffer=require('@stdlib/array-buffer');

varbuf=newArrayBuffer(4);
vararr=newUint8ClampedArray(buf,0,4);
// returns <Uint8ClampedArray>[ 0, 0, 0, 0 ]

Properties

Uint8ClampedArray.BYTES_PER_ELEMENT

Number of bytes per view element.

varnbytes=Uint8ClampedArray.BYTES_PER_ELEMENT;
// returns 1

Uint8ClampedArray.name

Typed arrayconstructor name.

varstr=Uint8ClampedArray.name;
// returns 'Uint8ClampedArray'

Uint8ClampedArray.prototype.buffer

Read-onlyproperty which returns theArrayBufferreferenced by thetyped array.

vararr=newUint8ClampedArray(5);
varbuf=arr.buffer;
// returns <ArrayBuffer>

Uint8ClampedArray.prototype.byteLength

Read-onlyproperty which returns the length (in bytes) of thetyped array.

vararr=newUint8ClampedArray(5);
varbyteLength=arr.byteLength;
// returns 5

Uint8ClampedArray.prototype.byteOffset

Read-onlyproperty which returns the offset (in bytes) of thetyped arrayfrom the start of itsArrayBuffer.

vararr=newUint8ClampedArray(5);
varbyteOffset=arr.byteOffset;
// returns 0

Uint8ClampedArray.prototype.BYTES_PER_ELEMENT

Number of bytes per view element.

vararr=newUint8ClampedArray(5);
varnbytes=arr.BYTES_PER_ELEMENT;
// returns 1

Uint8ClampedArray.prototype.length

Read-onlyproperty which returns the number of view elements.

vararr=newUint8ClampedArray(5);
varlen=arr.length;
// returns 5

Methods

Uint8ClampedArray.from( src[, map[, thisArg]] )

Creates a new typed array from an array-likeobjector an iterable.

vararr=Uint8ClampedArray.from([1,2]);
// returns <Uint8ClampedArray>[ 1, 2 ]

To invoke a function for eachsrcvalue, provide a callback function.

functionmapFcn(v){
returnv*2;
}

vararr=Uint8ClampedArray.from([1,2],mapFcn);
// returns <Uint8ClampedArray>[ 2, 4 ]

A callback function is provided two arguments:

  • value:source value
  • index:source index

To set the callback execution context, provide athisArg.

functionmapFcn(v){
this.count+=1;
returnv*2;
}

varctx={
'count':0
};

vararr=Uint8ClampedArray.from([1,2],mapFcn,ctx);
// returns <Uint8ClampedArray>[ 2, 4 ]

varn=ctx.count;
// returns 2

Uint8ClampedArray.of( element0[, element1[,...elementN]] )

Creates a new typed array from a variable number of arguments.

vararr=Uint8ClampedArray.of(1,2);
// returns <Uint8ClampedArray>[ 1, 2 ]

Uint8ClampedArray.prototype.copyWithin( target, start[, end] )

Copies a sequence of elements within an array starting atstartand ending atend(non-inclusive) to the position starting attarget.

vararr=newUint8ClampedArray([1,2,3,4,5]);

// Copy the last two elements to the first two elements:
arr.copyWithin(0,3);

varv=arr[0];
// returns 4

v=arr[1];
// returns 5

By default,endequals the number of array elements (i.e., one more than the last array index). To limit the sequence length, provide anendargument.

vararr=newUint8ClampedArray([1,2,3,4,5]);

// Copy the first two elements to the last two elements:
arr.copyWithin(3,0,2);

varv=arr[3];
// returns 1

v=arr[4];
// returns 2

When atarget,start,and/orendindex is negative, the respective index is determined relative to the last array element. The following example achieves the same behavior as the previous example:

vararr=newUint8ClampedArray([1,2,3,4,5]);

// Copy the first two elements to the last two elements:
arr.copyWithin(-2,-5,-3);

varv=arr[3];
// returns 1

v=arr[4];
// returns 2

Uint8ClampedArray.prototype.entries()

Returns an iterator for iterating over array key-value pairs.

vararr=newUint8ClampedArray([1,2]);

// Create an iterator:
varit=arr.entries();

// Iterate over key-value pairs...
varv=it.next().value;
// returns [ 0, 1 ]

v=it.next().value;
// returns [ 1, 2 ]

varbool=it.next().done;
// returns true

Uint8ClampedArray.prototype.every( predicate[, thisArg] )

Tests whether all array elements pass a test implemented by apredicatefunction.

functionpredicate(v){
return(v<=1);
}

vararr=newUint8ClampedArray([1,2]);

varbool=arr.every(predicate);
// returns false

Apredicatefunction is provided three arguments:

  • value:array element
  • index:array index
  • arr:array on which the method is invoked

To set the callback execution context, provide athisArg.

functionpredicate(v){
this.count+=1;
return(v>=1);
}

varctx={
'count':0
};

vararr=newUint8ClampedArray([1,2]);

varbool=arr.every(predicate,ctx);
// returns true

varn=ctx.count;
// returns 2

Uint8ClampedArray.prototype.fill( value[, start[, end]] )

Fills an array from astartindex to anendindex (non-inclusive) with a providedvalue.

vararr=newUint8ClampedArray(2);

// Set all array elements to the same value:
arr.fill(2);

varv=arr[0];
// returns 2

v=arr[1];
// returns 2

// Set all array elements starting from the first index to the same value:
arr.fill(3,1);

v=arr[0];
// returns 2

v=arr[1];
// returns 3

// Set all array elements, except the last element, to the same value:
arr.fill(4,0,arr.length-1);

v=arr[0];
// returns 4

v=arr[1];
// returns 3

When astartand/orendindex is negative, the respective index is determined relative to the last array element.

vararr=newUint8ClampedArray(2);

// Set all array elements, except the last element, to the same value:
arr.fill(2,-arr.length,-1);

varv=arr[0];
// returns 2

v=arr[1];
// returns 0

Uint8ClampedArray.prototype.filter( predicate[, thisArg] )

Creates a new array (of the same data type as the host array) which includes those elements for which apredicatefunction returns a truthy value.

functionpredicate(v){
return(v>=2);
}

vararr1=newUint8ClampedArray([1,2,3]);

vararr2=arr1.filter(predicate);
// returns <Uint8ClampedArray>[ 2, 3 ]

If apredicatefunction does not return a truthy value for any array element, the method returns an empty array.

functionpredicate(v){
return(v>=10);
}

vararr1=newUint8ClampedArray([1,2,3]);

vararr2=arr1.filter(predicate);
// returns <Uint8ClampedArray>[]

Apredicatefunction is provided three arguments:

  • value:array element
  • index:array index
  • arr:array on which the method is invoked

To set the callback execution context, provide athisArg.

functionpredicate(v){
this.count+=1;
return(v>=2);
}

varctx={
'count':0
};

vararr1=newUint8ClampedArray([1,2,3]);

vararr2=arr1.filter(predicate,ctx);

varn=ctx.count;
// returns 3

Uint8ClampedArray.prototype.find( predicate[, thisArg] )

Returns the first array element for which a providedpredicatefunction returns a truthy value.

functionpredicate(v){
return(v>2);
}

vararr=newUint8ClampedArray([1,2,3]);

varv=arr.find(predicate);
// returns 3

If apredicatefunction does not return a truthy value for any array element, the method returnsundefined.

functionpredicate(v){
return(v<1);
}

vararr=newUint8ClampedArray([1,2,3]);

varv=arr.find(predicate);
// returns undefined

Apredicatefunction is provided three arguments:

  • value:array element
  • index:array index
  • arr:array on which the method is invoked

To set the callback execution context, provide athisArg.

functionpredicate(v){
this.count+=1;
return(v>2);
}

varctx={
'count':0
};

vararr=newUint8ClampedArray([1,2,3]);

varv=arr.find(predicate,ctx);
// returns 3

varn=ctx.count;
// returns 3

Uint8ClampedArray.prototype.findIndex( predicate[, thisArg] )

Returns the index of the first array element for which a providedpredicatefunction returns a truthy value.

functionpredicate(v){
return(v>=3);
}

vararr=newUint8ClampedArray([1,2,3]);

varidx=arr.findIndex(predicate);
// returns 2

If apredicatefunction does not return a truthy value for any array element, the method returns-1.

functionpredicate(v){
return(v<1);
}

vararr=newUint8ClampedArray([1,2,3]);

varidx=arr.findIndex(predicate);
// returns -1

Apredicatefunction is provided three arguments:

  • value:array element
  • index:array index
  • arr:array on which the method is invoked

To set the callback execution context, provide athisArg.

functionpredicate(v){
this.count+=1;
return(v>=3);
}

varctx={
'count':0
};

vararr=newUint8ClampedArray([1,2,3]);

varidx=arr.findIndex(predicate,ctx);
// returns 2

varn=ctx.count;
// returns 3

Uint8ClampedArray.prototype.forEach( fcn[, thisArg] )

Invokes a callback for each array element.

vararr=newUint8ClampedArray([1,2,3]);

varstr='';

functionfcn(v,i){
str+=i+':'+v;
if(i<arr.length-1){
str+=' ';
}
}

arr.forEach(fcn);

console.log(str);
// => '0:1 1:2 2:3'

The callback is provided three arguments:

  • value:array element
  • index:array index
  • arr:array on which the method is invoked

To set the callback execution context, provide athisArg.

functionfcn(){
this.count+=1;
}

varctx={
'count':0
};

vararr=newUint8ClampedArray([1,2,3]);

arr.forEach(fcn,ctx);

varn=ctx.count;
// returns 3

Uint8ClampedArray.prototype.includes( searchElement[, fromIndex] )

Returns abooleanindicating whether an array includes a search element.

vararr=newUint8ClampedArray([1,2,3]);

varbool=arr.includes(3);
// returns true

bool=arr.includes(0);
// returns false

By default, the method searches the entire array (fromIndex = 0). To begin searching from a specific array index, provide afromIndex.

vararr=newUint8ClampedArray([1,2,3]);

varbool=arr.includes(1,1);
// returns false

When afromIndexis negative, the starting index is resolved relative to the last array element.

vararr=newUint8ClampedArray([1,2,3]);

varbool=arr.includes(1,-2);
// returns false

Uint8ClampedArray.prototype.indexOf( searchElement[, fromIndex] )

Returns the index of the first array element strictly equal to a search element.

vararr=newUint8ClampedArray([1,2,3]);

varidx=arr.indexOf(3);
// returns 2

idx=arr.indexOf(0);
// returns -1

By default, the method searches the entire array (fromIndex = 0). To begin searching from a specific array index, provide afromIndex.

vararr=newUint8ClampedArray([1,2,3]);

varidx=arr.indexOf(1,1);
// returns -1

When afromIndexis negative, the starting index is resolved relative to the last array element.

vararr=newUint8ClampedArray([1,2,3]);

varidx=arr.indexOf(1,-2);
// returns -1

Uint8ClampedArray.prototype.join( [separator] )

Serializes an array by joining all array elements as a string.

vararr=newUint8ClampedArray([1,2,3]);

varstr=arr.join();
// returns '1,2,3'

By default, the method delineates array elements using a comma,.To specify a custom separator, provide aseparatorstring.

vararr=newUint8ClampedArray([1,2,3]);

varstr=arr.join('|');
// returns '1|2|3'

Uint8ClampedArray.prototype.keys()

Returns an iterator for iterating over array keys.

vararr=newUint8ClampedArray([1,2]);

// Create an iterator:
varit=arr.keys();

// Iterate over keys...
varv=it.next().value;
// returns 0

v=it.next().value;
// returns 1

varbool=it.next().done;
// returns true

Uint8ClampedArray.prototype.lastIndexOf( searchElement[, fromIndex] )

Returns the index of the last array element strictly equal to a search element, iterating from right to left.

vararr=newUint8ClampedArray([1,0,2,0,1]);

varidx=arr.lastIndexOf(0);
// returns 3

idx=arr.lastIndexOf(3);
// returns -1

By default, the method searches the entire array (fromIndex = -1). To begin searching from a specific array index, provide afromIndex.

vararr=newUint8ClampedArray([1,0,2,0,1]);

varidx=arr.lastIndexOf(0,2);
// returns 1

When afromIndexis negative, the starting index is resolved relative to the last array element.

vararr=newUint8ClampedArray([1,0,2,0,1]);

varidx=arr.lastIndexOf(0,-3);
// returns 1

Uint8ClampedArray.prototype.map( fcn[, thisArg] )

Maps each array element to an element in a new array having the same data type as the host array.

functionfcn(v){
returnv*2;
}

vararr1=newUint8ClampedArray([1,2,3]);

vararr2=arr1.map(fcn);
// returns <Uint8ClampedArray>[ 2, 4, 6 ]

A callback is provided three arguments:

  • value:array element
  • index:array index
  • arr:array on which the method is invoked

To set the callback execution context, provide athisArg.

functionfcn(v){
this.count+=1;
returnv*2;
}

varctx={
'count':0
};

vararr1=newUint8ClampedArray([1,2,3]);

vararr2=arr1.map(fcn,ctx);

varn=ctx.count;
// returns 3

Uint8ClampedArray.prototype.reduce( fcn[, initialValue] )

Applies a function against an accumulator and each element in an array and returns the accumulated result.

functionfcn(acc,v){
returnacc+(v*v);
}

vararr=newUint8ClampedArray([2,1,3]);

varv=arr.reduce(fcn);
// returns 12

If not provided an initial value, the method invokes a provided function with the first array element as the first argument and the second array element as the second argument.

If provided an initial value, the method invokes a provided function with the initial value as the first argument and the first array element as the second argument.

functionfcn(acc,v){
returnacc+(v*v);
}

vararr=newUint8ClampedArray([2,1,3]);

varv=arr.reduce(fcn,0);
// returns 14

A callback is provided four arguments:

  • acc:accumulated result
  • value:array element
  • index:array index
  • arr:array on which the method is invoked

Uint8ClampedArray.prototype.reduceRight( fcn[, initialValue] )

Applies a function against an accumulator and each element in an array and returns the accumulated result, iterating from right to left.

functionfcn(acc,v){
returnacc+(v*v);
}

vararr=newUint8ClampedArray([2,1,3]);

varv=arr.reduceRight(fcn);
// returns 8

If not provided an initial value, the method invokes a provided function with the last array element as the first argument and the second-to-last array element as the second argument.

If provided an initial value, the method invokes a provided function with the initial value as the first argument and the last array element as the second argument.

functionfcn(acc,v){
returnacc+(v*v);
}

vararr=newUint8ClampedArray([2,1,3]);

varv=arr.reduce(fcn,0);
// returns 14

A callback is provided four arguments:

  • acc:accumulated result
  • value:array element
  • index:array index
  • arr:array on which the method is invoked

Uint8ClampedArray.prototype.reverse()

Reverses an arrayin-place(thus mutating the array on which the method is invoked).

vararr=newUint8ClampedArray([2,0,3]);

// Reverse the array:
arr.reverse();

varv=arr[0];
// returns 3

v=arr[1];
// returns 0

v=arr[2];
// returns 2

Uint8ClampedArray.prototype.set( arr[, offset] )

Sets array elements.

vararr=newUint8ClampedArray([1,2,3]);
// returns <Uint8ClampedArray>[ 1, 2, 3 ]

// Set the first two array elements:
arr.set([4,5]);

varv=arr[0];
// returns 4

v=arr[1];
// returns 5

By default, the method starts writing values at the first array index. To specify an alternative index, provide an indexoffset.

vararr=newUint8ClampedArray([1,2,3]);
// returns <Uint8ClampedArray>[ 1, 2, 3 ]

// Set the last two array elements:
arr.set([4,5],1);

varv=arr[1];
// returns 4

v=arr[2];
// returns 5

Uint8ClampedArray.prototype.slice( [begin[, end]] )

Copies array elements to a new array with the same underlying data type as the host array.

vararr1=newUint8ClampedArray([1,2,3]);

vararr2=arr1.slice();

varbool=(arr1===arr2);
// returns false

bool=(arr1.buffer===arr2.buffer);
// returns false

varv=arr2[0];
// returns 1

v=arr2[1];
// returns 2

v=arr2[2];
// returns 3

By default, the method copies elements beginning with the first array element. To specify an alternative array index at which to begin copying, provide abeginindex (inclusive).

vararr1=newUint8ClampedArray([1,2,3]);

vararr2=arr1.slice(1);

varlen=arr2.length;
// returns 2

varv=arr2[0];
// returns 2

v=arr2[1];
// returns 3

By default, the method copies all array elements afterbegin.To specify an alternative array index at which to end copying, provide anendindex (exclusive).

vararr1=newUint8ClampedArray([1,2,3]);

vararr2=arr1.slice(0,2);

varlen=arr2.length;
// returns 2

varv=arr2[0];
// returns 1

v=arr2[1];
// returns 2

When abeginand/orendindex is negative, the respective index is determined relative to the last array element.

vararr1=newUint8ClampedArray([1,2,3]);

vararr2=arr1.slice(-arr1.length,-1);

varlen=arr2.length;
// returns 2

varv=arr2[0];
// returns 1

v=arr2[1];
// returns 2

Uint8ClampedArray.prototype.some( predicate[, thisArg] )

Tests whether at least one array element passes a test implemented by apredicatefunction.

functionpredicate(v){
return(v>=2);
}

vararr=newUint8ClampedArray([1,2]);

varbool=arr.some(predicate);
// returns true

Apredicatefunction is provided three arguments:

  • value:array element
  • index:array index
  • arr:array on which the method is invoked

To set the callback execution context, provide athisArg.

functionpredicate(v){
this.count+=1;
return(v>=2);
}

varctx={
'count':0
};

vararr=newUint8ClampedArray([1,1]);

varbool=arr.some(predicate,ctx);
// returns false

varn=ctx.count;
// returns 2

Uint8ClampedArray.prototype.sort( [compareFunction] )

Sorts an arrayin-place(thus mutating the array on which the method is invoked).

vararr=newUint8ClampedArray([2,3,0]);

// Sort the array (in ascending order):
arr.sort();

varv=arr[0];
// returns 0

v=arr[1];
// returns 2

v=arr[2];
// returns 3

By default, the method sorts array elements in ascending order. To impose a custom order, provide acompareFunction.

functiondescending(a,b){
returnb-a;
}

vararr=newUint8ClampedArray([2,3,0]);

// Sort the array (in descending order):
arr.sort(descending);

varv=arr[0];
// returns 3

v=arr[1];
// returns 2

v=arr[2];
// returns 0

The comparison function is provided two array elements,aandb,per invocation, and its return value determines the sort order as follows:

  • If the comparison function returns a valuelessthan zero, then the method sortsato an index lower thanb(i.e.,ashould comebeforeb).
  • If the comparison function returns a valuegreaterthan zero, then the method sortsato an index higher thanb(i.e.,bshould comebeforea).
  • If the comparison function returnszero,then the relative order ofaandbshouldremain unchanged.

Uint8ClampedArray.prototype.subarray( [begin[, end]] )

Creates a new typed array view over the same underlyingArrayBufferand with the same underlying data type as the host array.

vararr1=newUint8ClampedArray([1,2,3]);

vararr2=arr1.subarray();
// returns <Uint8ClampedArray>[ 1, 2, 3 ]

varbool=(arr1.buffer===arr2.buffer);
// returns true

By default, the method creates a typed array view beginning with the first array element. To specify an alternative array index at which to begin, provide abeginindex (inclusive).

vararr1=newUint8ClampedArray([1,2,3]);

vararr2=arr1.subarray(1);
// returns <Uint8ClampedArray>[ 2, 3 ]

varbool=(arr1.buffer===arr2.buffer);
// returns true

By default, the method creates a typed array view which includes all array elements afterbegin.To limit the number of array elements afterbegin,provide anendindex (exclusive).

vararr1=newUint8ClampedArray([1,2,3]);

vararr2=arr1.subarray(0,2);
// returns <Uint8ClampedArray>[ 1, 2 ]

varbool=(arr1.buffer===arr2.buffer);
// returns true

When abeginand/orendindex is negative, the respective index is determined relative to the last array element.

vararr1=newUint8ClampedArray([1,2,3]);

vararr2=arr1.subarray(-arr1.length,-1);
// returns <Uint8ClampedArray>[ 1, 2 ]

varbool=(arr1.buffer===arr2.buffer);
// returns true

If the method is unable to resolve indices to a non-empty array subsequence, the method returns an empty typed array.

vararr1=newUint8ClampedArray([1,2,3]);

vararr2=arr1.subarray(10,-1);
// returns <Uint8ClampedArray>[]

Uint8ClampedArray.prototype.toLocaleString( [locales[, options]] )

Serializes an array as a locale-specificstring.

vararr=newUint8ClampedArray([1,2,3]);

varstr=arr.toLocaleString();
// returns '1,2,3'

Uint8ClampedArray.prototype.toString()

Serializes an array as astring.

vararr=newUint8ClampedArray([1,2,3]);

varstr=arr.toString();
// returns '1,2,3'

Uint8ClampedArray.prototype.values()

Returns an iterator for iterating over array elements.

vararr=newUint8ClampedArray([1,2]);

// Create an iterator:
varit=arr.values();

// Iterate over array elements...
varv=it.next().value;
// returns 1

v=it.next().value;
// returns 2

varbool=it.next().done;
// returns true

Examples

varrandu=require('@stdlib/random-base-randu');
varround=require('@stdlib/math-base-special-round');
varctor=require('@stdlib/array-uint8c');

vararr;
vari;

arr=newctor(10);
for(i=0;i<arr.length;i++){
arr[i]=round(randu()*100.0);
}
console.log(arr);

See Also


Notice

This package is part ofstdlib,a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more.

For more information on the project, filing bug reports and feature requests, and guidance on how to developstdlib,see the main projectrepository.

Community

Chat


License

SeeLICENSE.

Copyright

Copyright © 2016-2024. The StdlibAuthors.