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!
Typed arrayconstructor which returns atyped arrayrepresenting an array of 8-bit unsigned integers in the platform byte order clamped to 0-255.
npm install @stdlib/array-uint8c
Alternatively,
- To load the package in a website via a
script
tag without installation and bundlers, use theES Moduleavailable on theesm
branch (seeREADME). - If you are using Deno, visit the
deno
branch (seeREADMEfor usage intructions). - For use in Observable, or in browser/node environments, use theUniversal Module Definition (UMD)build available on the
umd
branch (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.
varUint8ClampedArray=require('@stdlib/array-uint8c');
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>
Returns atyped arrayhaving a specified length.
vararr=newUint8ClampedArray(5);
// returns <Uint8ClampedArray>[ 0, 0, 0, 0, 0 ]
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 ]
Creates atyped arrayfrom an array-likeobject
or iterable.
vararr=newUint8ClampedArray([5.0,5.0,5.0]);
// returns <Uint8ClampedArray>[ 5, 5, 5 ]
Returns atyped arrayview of anArrayBuffer
.
varArrayBuffer=require('@stdlib/array-buffer');
varbuf=newArrayBuffer(4);
vararr=newUint8ClampedArray(buf,0,4);
// returns <Uint8ClampedArray>[ 0, 0, 0, 0 ]
Number of bytes per view element.
varnbytes=Uint8ClampedArray.BYTES_PER_ELEMENT;
// returns 1
Typed arrayconstructor name.
varstr=Uint8ClampedArray.name;
// returns 'Uint8ClampedArray'
Read-onlyproperty which returns theArrayBuffer
referenced by thetyped array.
vararr=newUint8ClampedArray(5);
varbuf=arr.buffer;
// returns <ArrayBuffer>
Read-onlyproperty which returns the length (in bytes) of thetyped array.
vararr=newUint8ClampedArray(5);
varbyteLength=arr.byteLength;
// returns 5
Read-onlyproperty which returns the offset (in bytes) of thetyped arrayfrom the start of itsArrayBuffer
.
vararr=newUint8ClampedArray(5);
varbyteOffset=arr.byteOffset;
// returns 0
Number of bytes per view element.
vararr=newUint8ClampedArray(5);
varnbytes=arr.BYTES_PER_ELEMENT;
// returns 1
Read-onlyproperty which returns the number of view elements.
vararr=newUint8ClampedArray(5);
varlen=arr.length;
// returns 5
Creates a new typed array from an array-likeobject
or an iterable.
vararr=Uint8ClampedArray.from([1,2]);
// returns <Uint8ClampedArray>[ 1, 2 ]
To invoke a function for eachsrc
value, 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 valueindex
: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
Creates a new typed array from a variable number of arguments.
vararr=Uint8ClampedArray.of(1,2);
// returns <Uint8ClampedArray>[ 1, 2 ]
Copies a sequence of elements within an array starting atstart
and 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,end
equals the number of array elements (i.e., one more than the last array index). To limit the sequence length, provide anend
argument.
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/orend
index 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
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
Tests whether all array elements pass a test implemented by apredicate
function.
functionpredicate(v){
return(v<=1);
}
vararr=newUint8ClampedArray([1,2]);
varbool=arr.every(predicate);
// returns false
Apredicate
function is provided three arguments:
value
:array elementindex
:array indexarr
: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
Fills an array from astart
index to anend
index (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 astart
and/orend
index 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
Creates a new array (of the same data type as the host array) which includes those elements for which apredicate
function returns a truthy value.
functionpredicate(v){
return(v>=2);
}
vararr1=newUint8ClampedArray([1,2,3]);
vararr2=arr1.filter(predicate);
// returns <Uint8ClampedArray>[ 2, 3 ]
If apredicate
function 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>[]
Apredicate
function is provided three arguments:
value
:array elementindex
:array indexarr
: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
Returns the first array element for which a providedpredicate
function returns a truthy value.
functionpredicate(v){
return(v>2);
}
vararr=newUint8ClampedArray([1,2,3]);
varv=arr.find(predicate);
// returns 3
If apredicate
function 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
Apredicate
function is provided three arguments:
value
:array elementindex
:array indexarr
: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
Returns the index of the first array element for which a providedpredicate
function returns a truthy value.
functionpredicate(v){
return(v>=3);
}
vararr=newUint8ClampedArray([1,2,3]);
varidx=arr.findIndex(predicate);
// returns 2
If apredicate
function 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
Apredicate
function is provided three arguments:
value
:array elementindex
:array indexarr
: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
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 elementindex
:array indexarr
: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
Returns aboolean
indicating 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 afromIndex
is negative, the starting index is resolved relative to the last array element.
vararr=newUint8ClampedArray([1,2,3]);
varbool=arr.includes(1,-2);
// returns false
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 afromIndex
is negative, the starting index is resolved relative to the last array element.
vararr=newUint8ClampedArray([1,2,3]);
varidx=arr.indexOf(1,-2);
// returns -1
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 aseparator
string.
vararr=newUint8ClampedArray([1,2,3]);
varstr=arr.join('|');
// returns '1|2|3'
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
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 afromIndex
is 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
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 elementindex
:array indexarr
: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
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 resultvalue
:array elementindex
:array indexarr
:array on which the method is invoked
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 resultvalue
:array elementindex
:array indexarr
:array on which the method is invoked
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
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
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 abegin
index (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 anend
index (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 abegin
and/orend
index 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
Tests whether at least one array element passes a test implemented by apredicate
function.
functionpredicate(v){
return(v>=2);
}
vararr=newUint8ClampedArray([1,2]);
varbool=arr.some(predicate);
// returns true
Apredicate
function is provided three arguments:
value
:array elementindex
:array indexarr
: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
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,a
andb
,per invocation, and its return value determines the sort order as follows:
- If the comparison function returns a valuelessthan zero, then the method sorts
a
to an index lower thanb
(i.e.,a
should comebeforeb
). - If the comparison function returns a valuegreaterthan zero, then the method sorts
a
to an index higher thanb
(i.e.,b
should comebeforea
). - If the comparison function returnszero,then the relative order of
a
andb
shouldremain unchanged.
Creates a new typed array view over the same underlyingArrayBuffer
and 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 abegin
index (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 anend
index (exclusive).
vararr1=newUint8ClampedArray([1,2,3]);
vararr2=arr1.subarray(0,2);
// returns <Uint8ClampedArray>[ 1, 2 ]
varbool=(arr1.buffer===arr2.buffer);
// returns true
When abegin
and/orend
index 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>[]
Serializes an array as a locale-specificstring
.
vararr=newUint8ClampedArray([1,2,3]);
varstr=arr.toLocaleString();
// returns '1,2,3'
Serializes an array as astring
.
vararr=newUint8ClampedArray([1,2,3]);
varstr=arr.toString();
// returns '1,2,3'
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
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);
@stdlib/array-buffer
:ArrayBuffer.@stdlib/array-float32
:Float32Array.@stdlib/array-float64
:Float64Array.@stdlib/array-int16
:Int16Array.@stdlib/array-int32
:Int32Array.@stdlib/array-int8
:Int8Array.@stdlib/array-uint16
:Uint16Array.@stdlib/array-uint32
:Uint32Array.@stdlib/array-uint8
:Uint8Array.
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.
SeeLICENSE.
Copyright © 2016-2024. The StdlibAuthors.