Byte Manipulation

Tra la la...

Types

Bytes

A Bytes is any object which is an Array or TypedArray with each value in the valid byte range (i.e. between 0 and 255 inclusive), or is an Object with a length property where each indexed property is in the valid byte range.

BytesLike

A BytesLike can be either a Bytes or a DataHexString.

DataHexString

A DataHexstring is identical to a HexString except that it has an even number of nibbles, and therefore is a valid representation of binary data as a string.

HexString

A Hexstring is a string which has a 0x prefix followed by any number of nibbles (i.e. case-insensitive hexadecimal characters, 0-9 and a-f).

Signature

Raw Signature inherits string<DataHexString<65>>

A Raw Signature is a common Signature format where the r, s and v are concatenated into a 65 byte (130 nibble) DataHexString.

SignatureLike

A SignatureLike is similar to a Signature, except redundant properties may be omitted or it may be a Raw Signature.

For example, if _vs is specified, s and v may be omitted. Likewise, if recoveryParam is provided, v may be omitted (as in these cases the missing values can be computed).

Inspection

ethers.utils.isBytes( object ) boolean

Returns true if and only if object is a valid Bytes.

ethers.utils.isBytesLike( object ) boolean

Returns true if and only if object is a Bytes or DataHexString.

ethers.utils.isHexString( object , [ length ] ) boolean

Returns true if and only if object is a valid hex string. If length is specified and object is not a valid DataHexString of length bytes, an InvalidArgument error is thrown.

Converting between Arrays and Hexstrings

ethers.utils.arrayify( DataHexStringOrArrayish [ , options ] ) Uint8Array

Converts DataHexStringOrArrayish to a Uint8Array.

ethers.utils.hexlify( hexstringOrArrayish ) string< DataHexString >

Converts hexstringOrArrayish to a DataHexString.

ethers.utils.hexValue( aBigNumberish ) string< HexString >

Converts aBigNumberish to a HexString, with no unnecessary leading zeros.

Examples
// Convert a hexstring to a Uint8Array arrayify("0x1234") // Uint8Array [ 18, 52 ] // Convert an Array to a hexstring hexlify([1, 2, 3, 4]) // '0x01020304' // Convert an Object to a hexstring hexlify({ length: 2, "0": 1, "1": 2 }) // '0x0102' // Convert an Array to a hexstring hexlify([ 1 ]) // '0x01' // Convert a number to a stripped hex value hexValue(1) // '0x1' // Convert an Array to a stripped hex value hexValue([ 1, 2 ]) // '0x102'

Array Manipulation

ethers.utils.concat( arrayOfBytesLike ) Uint8Array

Concatenates all the BytesLike in arrayOfBytesLike into a single Uint8Array.

ethers.utils.stripZeros( aBytesLike ) Uint8Array

Returns a Uint8Array with all leading 0 bytes of aBtyesLike removed.

ethers.utils.zeroPad( aBytesLike , length ) Uint8Array

Returns a Uint8Array of the data in aBytesLike with 0 bytes prepended to length bytes long.

If aBytesLike is already longer than length bytes long, an InvalidArgument error will be thrown.

Hexstring Manipulation

ethers.utils.hexConcat( arrayOfBytesLike ) string< DataHexString >

Concatenates all the BytesLike in arrayOfBytesLike into a single DataHexString

ethers.utils.hexDataLength( aBytesLike ) string< DataHexString >

Returns the length (in bytes) of aBytesLike.

ethers.utils.hexDataSlice( aBytesLike , offset [ , endOffset ] ) string< DataHexString >

Returns a DataHexString representation of a slice of aBytesLike, from offset (in bytes) to endOffset (in bytes). If endOffset is omitted, the length of aBytesLike is used.

ethers.utils.hexStripZeros( aBytesLike ) string< HexString >

Returns a HexString representation of aBytesLike with all leading zeros removed.

ethers.utils.hexZeroPad( aBytesLike , length ) string< DataHexString >

Returns a DataHexString representation of aBytesLike padded to length bytes.

If aBytesLike is already longer than length bytes long, an InvalidArgument error will be thrown.

Signature Conversion

ethers.utils.joinSignature( aSignatureLike ) string< RawSignature >

Return the raw-format of aSignaturelike, which is 65 bytes (130 nibbles) long, concatenating the r, s and (normalized) v of a Signature.

ethers.utils.splitSignature( aSignatureLikeOrBytesLike ) Signature

Return the full expanded-format of aSignaturelike or a raw-format DataHexString. Any missing properties will be computed.

Random Bytes

ethers.utils.randomBytes( length ) Uint8Array

Return a new Uint8Array of length random bytes.

ethers.utils.shuffled( array ) Array< any >

Return a copy of array shuffled using Fisher-Yates Shuffle.

Examples
utils.randomBytes(8) // Uint8Array [ 60, 180, 107, 93, 23, 68, 138, 40 ] const data = [ 1, 2, 3, 4, 5, 6, 7 ]; // Returns a new Array utils.shuffled(data); // [ // 7, // 5, // 2, // 4, // 3, // 6, // 1 // ] // The Original is unscathed... data // [ // 1, // 2, // 3, // 4, // 5, // 6, // 7 // ]