WOLFRAM

Wolfram Language & System Documentation Center
Wolfram Language Home Page »

NumericArray
✖
NumericArray

[Experimental]

✖
NumericArray[array,type]

creates a numeric array of the specified type.

✖
NumericArray[array,type,method]

uses method to convert numbers into type.

Details and Options

  • 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:
  • "Integer8"signed 8-bit integers from through 127
    "UnsignedInteger8"integers 0 through 255
    "Integer16"signed 16-bit integers from through
    "UnsignedInteger16"integers 0 through 65535
    "Integer32"signed 32-bit integers from through
    "UnsignedInteger32"integers 0 through
    "Integer64"signed 64-bit integers from through
    "UnsignedInteger64"integers 0 through
    "Real32"single-precision real (32-bit)
    "Real64"double-precision real (64-bit)
    "ComplexReal32"single-precision complex
    "ComplexReal64"double-precision complex
  • NumericArray[array,type] clips values to the range supported by type and rounds reals to integers, if necessary.
  • Other conversion method settings include:
  • "Check"checks values to be compatible with type
    "Coerce"coerces to type
    "Round"rounds reals to integers
    "ClipAndCheck"clips to the range and checks for compatible type
    "ClipAndCoerce"clips to the range and coerces to type
    "ClipAndRound"clips to the range and rounds reals to integers
  • For complex numbers, the method is applied separately to real and imaginary parts.
  • NumericArray is treated as a raw object by functions like AtomQ and for purposes of pattern matching.
  • Normal[NumericArray[…]] yields the list of values in the numeric array.
  • Functions such as Length, Equal and First work with NumericArray objects.
  • Functions such as Part, Take and Drop can be used to take or drop parts of a NumericArray object.
  • Functions such as ListPlot, ArrayPlot and BarChart can visualize a NumericArray object.

Examples

open allclose all

Basic Examples  (2)Summary of the most common use cases

Create a vector of byte size integers:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-gy3xe8
Out[1]=1

Convert a matrix of reals to a numeric array:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-m7j44
Out[1]=1

Convert back to a regular list:

In[2]:=2
✖
https://wolfram.com/xid/0bdpylfkq-7tq7wm
Out[2]=2

Scope  (20)Survey of the scope of standard use cases

Basic Uses  (6)

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

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-pq8ly4
Out[1]=1

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

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-km3lsw
Out[1]=1

Create a 2D numeric array:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-0spxak
Out[1]=1

Convert ByteArray to NumericArray:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-gu1njh
In[2]:=2
✖
https://wolfram.com/xid/0bdpylfkq-e6kll
Out[2]=2

Convert SparseArray to NumericArray:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-ilm62h
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0bdpylfkq-fe9oth
Out[2]=2

Convert SymmetrizedArray to NumericArray:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-ezoilb
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0bdpylfkq-6vofx
Out[2]=2

NumericArray Types  (3)

Integers  (1)

Create an 8-bit unsigned integer numeric array:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-ecbdpu
Out[1]=1

For a larger integer, use a larger integer type:

In[2]:=2
✖
https://wolfram.com/xid/0bdpylfkq-8p3ksg
Out[2]=2

Clip large values into a smaller integer type:

In[3]:=3
✖
https://wolfram.com/xid/0bdpylfkq-321lrj
Out[3]=3

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

In[4]:=4
✖
https://wolfram.com/xid/0bdpylfkq-9cyb3l
Out[4]=4

Reals  (1)

Create a 32-bit real numeric array:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-5eahhv
Out[1]=1

Coerce exact numbers into reals:

In[2]:=2
✖
https://wolfram.com/xid/0bdpylfkq-43z9ao
Out[2]=2

Complexes  (1)

Create a complex numeric array:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-i2dsya
Out[1]=1

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

In[2]:=2
✖
https://wolfram.com/xid/0bdpylfkq-glivn2
Out[2]=2

Converting between NumericArray Objects  (2)

Convert an "Integer8" array to "Real32":

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-brz958
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0bdpylfkq-ioqvvg
Out[2]=2

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

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-0e07y7
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0bdpylfkq-ox6t37
Out[2]=2

Operating on a NumericArray  (9)

Array Properties  (3)

ByteCount of a numeric array:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-enclyw
Out[1]=1

Dimensions:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-npzi71
Out[1]=1

ArrayDepth:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-d6hdts
Out[1]=1

Structural Operations  (6)

Flatten a numeric array:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-bteoru
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0bdpylfkq-lma1im
Out[2]=2

Normal converts a numeric array to a List:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-j6yr5f
Out[1]=1

Apply Join to numeric array objects:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-df604o
Out[1]=1

Use Part to take a part of a numeric array:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-d1gexg
Out[1]=1

Use Take to take a part of a numeric array:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-cugul3
Out[1]=1

Apply Drop to elements of a numeric array:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-eljny2
Out[1]=1

Properties & Relations  (2)Properties of the function, and connections to other functions

Byte count of a NumericArray is less than the equivalent list of random integers:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-db690e
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0bdpylfkq-bazdgh
Out[2]=2

Normal can convert a NumericArray to a normal expression:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-dgmwn
Out[1]=1

Possible Issues  (2)Common pitfalls and unexpected behavior

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

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-w6l8pt
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0bdpylfkq-df0vqn
Out[2]=2

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

In[3]:=3
✖
https://wolfram.com/xid/0bdpylfkq-pbz6mw
Out[3]=3

The default conversion method will fail when the input array contains numbers that are out of range for the specified type.

Try to store in an "Integer8" numeric array:

In[1]:=1
✖
https://wolfram.com/xid/0bdpylfkq-5wd655
Out[1]=1

Use the "ClipAndCoerce" method to automatically clip to the smallest "Integer8":

In[2]:=2
✖
https://wolfram.com/xid/0bdpylfkq-j65o6c
Out[2]=2
Wolfram Research (2019), NumericArray, Wolfram Language function, https://reference.wolfram.com/language/ref/NumericArray.html.
✖
Wolfram Research (2019), NumericArray, Wolfram Language function, https://reference.wolfram.com/language/ref/NumericArray.html.

Text

Wolfram Research (2019), NumericArray, Wolfram Language function, https://reference.wolfram.com/language/ref/NumericArray.html.

✖
Wolfram Research (2019), NumericArray, Wolfram Language function, https://reference.wolfram.com/language/ref/NumericArray.html.

CMS

Wolfram Language. 2019. "NumericArray." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/NumericArray.html.

✖
Wolfram Language. 2019. "NumericArray." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/NumericArray.html.

APA

Wolfram Language. (2019). NumericArray. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/NumericArray.html

✖
Wolfram Language. (2019). NumericArray. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/NumericArray.html

BibTeX

@misc{reference.wolfram_2025_numericarray, author="Wolfram Research", title="{NumericArray}", year="2019", howpublished="\url{https://reference.wolfram.com/language/ref/NumericArray.html}", note=[Accessed: 15-April-2025 ]}

✖
@misc{reference.wolfram_2025_numericarray, author="Wolfram Research", title="{NumericArray}", year="2019", howpublished="\url{https://reference.wolfram.com/language/ref/NumericArray.html}", note=[Accessed: 15-April-2025 ]}

BibLaTeX

@online{reference.wolfram_2025_numericarray, organization={Wolfram Research}, title={NumericArray}, year={2019}, url={https://reference.wolfram.com/language/ref/NumericArray.html}, note=[Accessed: 15-April-2025 ]}

✖
@online{reference.wolfram_2025_numericarray, organization={Wolfram Research}, title={NumericArray}, year={2019}, url={https://reference.wolfram.com/language/ref/NumericArray.html}, note=[Accessed: 15-April-2025 ]}