_section: Byte Manipulation

While there are many high-level APIs for interacting with
Ethereum, such as [Contracts](Contract) and [Providers](Provider),
a lot of the low level access requires byte manipulation
operations.

Many of these operations are used internally, but can also be
used to help normalize binary data representations from the
output of various functions and methods.

_subsection: Types

_heading: Bytes @<Bytes>

A **Bytes** is any object which is an
[Array](link-js-array) or [TypedArray](link-js-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.

_heading: BytesLike @<BytesLike>

A **BytesLike** can be either a [[Bytes]] or a [[DataHexString]].

_heading: 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.

_heading: HexString @<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``).

_heading: Signature @<Signature>

- **r** and **s** --- The x co-ordinate of **r** and the **s** value of the signature
- **v** --- The parity of the y co-ordinate of **r**
- **_vs** --- The [compact representation](link-eip-2098) of the **s** and **v**
- **recoveryParam** --- The normalized (i.e. 0 or 1) value of **v**

_heading: Raw Signature @<signature-raw> @inherit<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]].


_heading: SignatureLike @<SignatureLike>

A **SignatureLike** is similar to a [[Signature]], except redundant properties
may be omitted or it may be a [[signature-raw]].

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).


_subsection: Inspection

_property: ethers.utils.isBytes(object) => boolean  @<utils-isBytes> @SRC<bytes>
Returns true if and only if //object// is a valid [[Bytes]].

_property: ethers.utils.isBytesLike(object) => boolean  @<utils-isBytesLike> @SRC<bytes>
Returns true if and only if //object// is a [[Bytes]] or [[DataHexString]].

_property: ethers.utils.isHexString(object, [ length ] ) => boolean  @<utils-isHexString> @SRC<bytes>
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.


_subsection: Converting between Arrays and Hexstrings

_property: ethers.utils.arrayify(DataHexStringOrArrayish [ , options ]) => Uint8Array  @<utils-arrayify> @SRC<bytes>
Converts //DataHexStringOrArrayish// to a Uint8Array.

_property: ethers.utils.hexlify(hexstringOrArrayish) => string<[[DataHexString]]>  @<utils-hexlify> @SRC<bytes>
Converts //hexstringOrArrayish// to a [[DataHexString]].

_property: ethers.utils.hexValue(aBigNumberish) => string<[[HexString]]>  @<utils-hexValue> @SRC<bytes>
Converts //aBigNumberish// to a [[HexString]], with no __unnecessary__ leading
zeros.

_code: Examples @lang<javascript>

// Convert a hexstring to a Uint8Array
arrayify("0x1234")
//!

// Convert an Array to a hexstring
hexlify([1, 2, 3, 4])
//!

// Convert an Object to a hexstring
hexlify({ length: 2, "0": 1, "1": 2 })
//!

// Convert an Array to a hexstring
hexlify([ 1 ])
//!

// Convert a number to a stripped hex value
hexValue(1)
//!

// Convert an Array to a stripped hex value
hexValue([ 1, 2 ])
//!


_subsection: Array Manipulation

_property: ethers.utils.concat(arrayOfBytesLike) => Uint8Array  @<utils-concat> @SRC<bytes>
Concatenates all the [[BytesLike]] in //arrayOfBytesLike// into a single Uint8Array.

_property: ethers.utils.stripZeros(aBytesLike) => Uint8Array  @<utils-stripZeros> @SRC<bytes>
Returns a Uint8Array with all leading ``0`` bytes of //aBtyesLike// removed.

_property: ethers.utils.zeroPad(aBytesLike, length) => Uint8Array  @<utils-zeroPad> @SRC<bytes>
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.


_subsection: Hexstring Manipulation

_property: ethers.utils.hexConcat(arrayOfBytesLike) => string<[[DataHexString]]>  @<utils-hexConcat> @SRC<bytes>
Concatenates all the [[BytesLike]] in //arrayOfBytesLike// into a single [[DataHexString]]

_property: ethers.utils.hexDataLength(aBytesLike) => string<[[DataHexString]]>  @<utils-hexDataLength> @SRC<bytes>
Returns the length (in bytes) of //aBytesLike//.

_property: ethers.utils.hexDataSlice(aBytesLike, offset [ , endOffset ] ) => string<[[DataHexString]]>  @<utils-hexDataSlice> @SRC<bytes>
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.

_property: ethers.utils.hexStripZeros(aBytesLike) => string<[[HexString]]>  @<utils-hexStripZeros> @SRC<bytes>
Returns a [[HexString]] representation of //aBytesLike// with all
leading zeros removed.

_property: ethers.utils.hexZeroPad(aBytesLike, length) => string<[[DataHexString]]>  @<utils-hexZeroPad> @SRC<bytes>
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.


_subsection: Signature Conversion

_property: ethers.utils.joinSignature(aSignatureLike) => string<[RawSignature](signature-raw)>  @<utils-joinSignature> @SRC<bytes>
Return the raw-format of //aSignaturelike//, which is 65 bytes (130 nibbles)
long, concatenating the **r**, **s** and (normalized) **v** of a Signature.

_property: ethers.utils.splitSignature(aSignatureLikeOrBytesLike) => [[Signature]]  @<utils-splitSignature> @SRC<bytes>
Return the full expanded-format of //aSignaturelike// or a raw-format [[DataHexString]].
Any missing properties will be computed.

_subsection: Random Bytes

_property: ethers.utils.randomBytes(length) => Uint8Array  @<utils-randomBytes> @SRC<random/random>
Return a new Uint8Array of //length// random bytes.

_property: ethers.utils.shuffled(array) => Array<any>  @<utils-shuffled> @SRC<random>
Return a copy of //array// shuffled using [[link-wiki-shuffle]].

_code: Examples @lang<javascript>

utils.randomBytes(8)
//!

const data = [ 1, 2, 3, 4, 5, 6, 7 ];

// Returns a new Array
utils.shuffled(data);
//!

// The Original is unscathed...
data
//!