({{, (RefLink[NumericArray, paclet:ref/NumericArray])[array,type]
creates a numeric array of the specified type.}, {, (RefLink[NumericArray, paclet:ref/NumericArray])[array,type,method]
uses method to convert numbers into type.}})

OpenersNotesSection(Spacer1)Details and Options

(RefLink[NumericArray, paclet:ref/NumericArray]) provides the most compact representation of array to reduce memory usage and enhance speed of execution.

The input array can be a full list of any depth containing machine-sized integers and machine-sized approximate real and complex numbers.

Possible settings for type include:

(RefLink[NumericArray, paclet:ref/NumericArray])[array,type] clips values to the range supported by type and rounds reals to integers, if necessary.

Other conversion method settings include:

For complex numbers, the method is applied separately to real and imaginary parts.

(RefLink[NumericArray, paclet:ref/NumericArray]) is treated as a raw object by functions like (RefLink[AtomQ, paclet:ref/AtomQ]) and for purposes of pattern matching.

(RefLink[Normal, paclet:ref/Normal])[NumericArray[…]] yields the list of values in the numeric array.

Functions such as (RefLink[Length, paclet:ref/Length]), (RefLink[Equal, paclet:ref/Equal]) and (RefLink[First, paclet:ref/First]) work with (RefLink[NumericArray, paclet:ref/NumericArray]) objects.

Functions such as (RefLink[Part, paclet:ref/Part]), (RefLink[Take, paclet:ref/Take]) and (RefLink[Drop, paclet:ref/Drop]) can be used to take or drop parts of a (RefLink[NumericArray, paclet:ref/NumericArray]) object.

Functions such as (RefLink[ListPlot, paclet:ref/ListPlot]), (RefLink[ArrayPlot, paclet:ref/ArrayPlot]) and (RefLink[BarChart, paclet:ref/BarChart]) can visualize a (RefLink[NumericArray, paclet:ref/NumericArray]) object.

OpenersPrimaryExamplesSection(Spacer1)Examples  (26)

OpenersExampleSection0(Spacer1)Basic Examples  (2)

Create a vector of byte size integers:

NumericArray[Range[100], "UnsignedInteger8"]

Convert a matrix of reals to a numeric array:

NumericArray[RandomReal[1,{5,5}], "Real64"]

Convert back to a regular list:

Normal[%]

OpenersExampleSection1(Spacer1)Scope  (20)

OpenersExampleSubsection0(Spacer1)Basic Uses  (6)

Create a numeric array from a list using a specific type:

NumericArray[{1,2,3,4}, "Real32"]

Specify the conversion method to fit numbers in the desired type:

NumericArray[{1,2,3,$MaxMachineNumber},"Real32","ClipAndCoerce"]

Create a 2D numeric array:

NumericArray[{{1,2},{3,4}},"UnsignedInteger8"]

Convert (RefLink[ByteArray, paclet:ref/ByteArray]) to (RefLink[NumericArray, paclet:ref/NumericArray]):

ba=ByteArray[{1,2,3,4}];

NumericArray[ba,"UnsignedInteger8"]

Convert (RefLink[SparseArray, paclet:ref/SparseArray]) to (RefLink[NumericArray, paclet:ref/NumericArray]):

s=SparseArray[{{1,1}->1,{2,2}->2,{3,3}->3,{4,4}->4}]

NumericArray[s,"UnsignedInteger8"]

Convert (RefLink[StructuredArray, paclet:ref/StructuredArray]) to (RefLink[NumericArray, paclet:ref/NumericArray]):

s = SymmetrizedArray[{{i_,i_,i_,i_}->1,{i_,i_,j_,j_}:> i+j},{4,4,4,4}, {Symmetric[{1,2,3,4}]}]

NumericArray[s,"UnsignedInteger8"]

OpenersExampleSubsection1(Spacer1)NumericArray Types  (3)

OpenersExampleSubsubsection0(Spacer1)Integers  (1)

Create an 8-bit unsigned integer numeric array:

NumericArray[{0,1,2},"UnsignedInteger8"]//Normal

For a larger integer, use a larger integer type:

NumericArray[{0,1000,2000},"UnsignedInteger16"]//Normal

Clip large values into a smaller integer type:

NumericArray[{0,1000,2000},"UnsignedInteger8","ClipAndCoerce"]//Normal

Real numbers can be rounded when converted into an integer type:

NumericArray[{.1,1.1,2.1},"UnsignedInteger8","Round"]//Normal

OpenersExampleSubsubsection1(Spacer1)Reals  (1)

Create a 32-bit real numeric array:

NumericArray[{.1,1.1,2.1},"Real32"]//Normal

Coerce exact numbers into reals:

NumericArray[{1/3,2/3},"Real32","Coerce"]//Normal

OpenersExampleSubsubsection2(Spacer1)Complexes  (1)

Create a complex numeric array:

NumericArray[{1+2I},"ComplexReal32"]//Normal

Coerce exact real and imaginary parts of a complex number into reals:

NumericArray[{1/3+2/3I},"ComplexReal32","Coerce"]//Normal

OpenersExampleSubsection2(Spacer1)Converting between NumericArray Objects  (2)

Convert an "Integer8" array to "Real32":

na=NumericArray[{-100, 0, 5, 120},"Integer8"]

NumericArray[na,"Real32"]

If numbers cannot be represented in the new type, specify a conversion method:

na=NumericArray[{-100, 0, 5, 120},"Integer8"]

NumericArray[na,"UnsignedInteger8","ClipAndCoerce"]

OpenersExampleSubsection3(Spacer1)Operating on a NumericArray  (9)

OpenersExampleSubsubsection3(Spacer1)Array Properties  (3)

(RefLink[ByteCount, paclet:ref/ByteCount]) of a numeric array:

na=NumericArray[{1,2,3,4}, "UnsignedInteger8"];
ByteCount[na]

(RefLink[Dimensions, paclet:ref/Dimensions]):

na=NumericArray[{1,2,3,4}, "UnsignedInteger8"];
Dimensions[na]

(RefLink[ArrayDepth, paclet:ref/ArrayDepth]):

na=NumericArray[{1,2,3,4}, "UnsignedInteger8"];
ArrayDepth[na]

OpenersExampleSubsubsection4(Spacer1)Structural Operations  (6)

Flatten a numeric array:

na=NumericArray[{{1,2},{3,4}}, "UnsignedInteger8"]

Flatten[na]

(RefLink[Normal, paclet:ref/Normal]) converts a numeric array to a (RefLink[List, paclet:ref/List]):

na=NumericArray[{1,2,3,4}, "UnsignedInteger8"];
Normal[na]

Apply (RefLink[Join, paclet:ref/Join]) to numeric array objects:

na=NumericArray[{1,2,3,4}, "UnsignedInteger8"];
Join[na,na]

Use (RefLink[Part, paclet:ref/Part]) to take a part of a numeric array:

NumericArray[Range[100], "UnsignedInteger8"][[1]]

Use (RefLink[Take, paclet:ref/Take]) to take a part of a numeric array:

na=NumericArray[{1,2,3,4}, "UnsignedInteger8"];
Take[na,{2,3}]

Apply (RefLink[Drop, paclet:ref/Drop]) to elements of a numeric array:

na=NumericArray[{1,2,3,4}, "UnsignedInteger8"];
Drop[na,2]

OpenersExampleSection2(Spacer1)Properties & Relations  (2)

Byte count of a (RefLink[NumericArray, paclet:ref/NumericArray]) is less than the equivalent list of random integers:

ByteCount[r=RandomInteger[255,{10,10}]]

ByteCount[NumericArray[r, "UnsignedInteger8"]]

(RefLink[Normal, paclet:ref/Normal]) can convert a (RefLink[NumericArray, paclet:ref/NumericArray]) to a normal expression:

Normal[NumericArray[Range[10], "UnsignedInteger8"]]

OpenersExampleSection3(Spacer1)Possible Issues  (2)

Some conversion methods may not give numbers suitable for the new type:

na=NumericArray[{-100, 0, 5, 120.5},"Real32"]

NumericArray[na,"Integer8","ClipAndCoerce"]

Use a conversion that yields numbers supported by the new type:

NumericArray[na,"Integer8","ClipAndRound"]

Currently, the smallest negative integer cannot be stored in a (RefLink[NumericArray, paclet:ref/NumericArray]) for any signed integer type.

Try to store -(2^7) in an (StringTypeLink["Integer8", paclet:ref/format/Integer8]) numeric array:

NumericArray[{-128},"Integer8"]

Use the "ClipAndCoerce" method to automatically clip the smallest negative integer:

NumericArray[{-128},"Integer8","ClipAndCoerce"]

({{DocumentationFooterIconsRelatedFunction.png, ({{See Also}, {(RefLink[List, paclet:ref/List])  ▪  (RefLink[ByteArray, paclet:ref/ByteArray])  ▪  (RefLink[Normal, paclet:ref/Normal])  ▪  (RefLink[NumericArrayType, paclet:ref/NumericArrayType])  ▪  (RefLink[NumericArrayQ, paclet:ref/NumericArrayQ])  ▪  (RefLink[SparseArray, paclet:ref/SparseArray])  ▪  (RefLink[Image, paclet:ref/Image])  ▪  (RefLink[Audio, paclet:ref/Audio])}})}})

({{DocumentationFooterIconsRelatedGuide.png, ({{Related Guides}, {▪(RefLinkPlain[Binary Data, paclet:guide/BinaryData])}, {▪(RefLinkPlain[Encoding and Decoding Data for Neural Networks, paclet:guide/NetEncoderDecoder])}, {▪(RefLinkPlain[List Manipulation, paclet:guide/ListManipulation])}})}})