PowerShell: Byte arrays

Creating an array of bytes

Creating an array from a list of numerical literals

An array of bytes can simply be created by assigning an array of numbers (technically: bytes) to a typed variable:

[byte[]] $byte_array = 65,66,67,90

Of course, typically, such numbers come in hexadecimal form in which case they need to be prepended with 0x:

[byte[]] $another_array = 0x41, 0x42, 0x43, 0x5A

If the array of hexadecimal number comes from a source where it is not already prefixed and manually prefixing them is too tedious, a pipeline helps to convert the hexadecimal numbers to a byte:

[byte[]] $xyz = '41', '42', '43', '5A' | foreach-object { invoke-expression "0x$_" }

Because some of the values of the last example contain characters, these values had to be enclosed in quotes.

To make things easier, we can put such values into a string and create an array using the -split operator:

[byte[]] $abc = "41 42 43 5A" -split ' ' | foreach-object { invoke-expression "0x$_" }

Create an array of n elements, each initialized to 0

The following constructs create byte arrays, each of which has 10 elements and whose values are initialized to 0.

$array_1 = [byte[]]::new(10)
$array_2 = new-object byte[] 10
$array_3 = [System.Array]::CreateInstance([byte], 10)

Creating higher dimension arrays

The following constructs create arrays of higher dimensions:

[byte[,]] $four_by_eight = [System.Array]::CreateInstance([byte], @(4, 8))
[byte[,,,]] $b_3x4x5x6 = [byte[,,,]]::new(3,4,5,6)

Converting between strings and byte arrays

An instance that derives from System.Text.Encoding allows to convert between strings and byte arrays with the methods GetBytes() and GetString().

The following example gets the UTF-8 bytes for a given text, writes them to the console them and then converts them back to a string:

$enc        = [System.Text.Encoding]::UTF8
$byte_array = $enc.GetBytes('Hello World')
write-host    $byte_array
$text       = $enc.GetString($byte_array)

Converting between base types and byte arrays

The .NET type System.BitConverter allows to convert between base types and byte arrays (both directions).

File content as byte array

A file can be read into a byte array with the method [System.IO.File]::ReadAllBytes and written with [System.IO.File]::WriteAllBytes.

Alternatively, the get-content cmdLet can be used with -encoding byte -raw or -asByteStream to get a file's content as byte array.

Returning a byte array from a function

When I tried to write a function that returns a byte array, it turned out that this is not as intuitive as I hoped. Here is my naive approach:

function make-byteArray() {

  [outputType( [byte[]] )]

  [byte[]] $byteArray = new-object byte[] 2

   $byteArray[0] = 0
   $byteArray[1] = 1

   write-host "type of byteArray: $($byteArray.GetType().FullName)"

   return $byteArray
}

$x = make-byteArray
write-host "type of x: $($x.GetType().FullName)"

Github repository about-PowerShell, path: /language/type/array/byte/return-in-function/naive.ps1

When executed, this function returns an array of objects (System.Object[]) rather than an array of bytes:

type of byteArray: System.Byte[]
type of x: System.Object[]

Only a question on StackOverlow pointed my to the right direction. A byte array can be returned by prepending it with the unary comma operator:

#
# https://stackoverflow.com/a/61440166/180275
#
function make-byteArray() {

  [outputType( [byte[]] )]

  [byte[]] $byteArray = new-object byte[] 2

   $byteArray[0] = 0
   $byteArray[1] = 1

  ,$byteArray
}

$x = make-byteArray
write-host "type of x: $($x.GetType().FullName)"

Github repository about-PowerShell, path: /language/type/array/byte/return-in-function/unary-comma.ps1

An alternative is to use the write-output cmdlet with the -noEnumerate option:

#
# https://stackoverflow.com/a/61440506/180275
#
function make-byteArray() {

  [outputType( [byte[]] )]

  [byte[]] $byteArray = new-object byte[] 2

   $byteArray[0] = 0
   $byteArray[1] = 1

   write-output -noEnumerate $byteArray
}

$x = make-byteArray
write-host "type of x: $($x.GetType().FullName)"

Github repository about-PowerShell, path: /language/type/array/byte/return-in-function/write-output.ps1