typecast

Convert data type without changing underlying data

Syntax

Y = typecast(X,newtype)

Y = typecast(X,"like",p)

Description

Y = typecast(X,newtype) converts the bit patterns of X to the data type specified by newtype without changing the underlying data. X must be a full (nonsparse) vector or scalar.

Y = typecast(X,"like",p) converts the bit patterns of X to the same data type and complexity (real or complex) as the prototype p. (since R2024b)

Examples

Convert Integer to Unsigned Integer of Same Storage Size

Convert an integer to an unsigned integer of the same storage size.

X = int16(-1)

X = int16

-1

Y = typecast(X,"uint16")

Y = uint16

65535

Show the bit patterns in hexadecimal representation. Converting the data type by using typecast does not change the underlying data.

format hex
X

X = int16
   ffff

Y = typecast(X,"uint16")

Y = uint16
   ffff

Convert 8-Bit Integer to Single Precision

Create a 1-by-4 vector of 8-bit integers.

X = int8([77 60 43 26])

X = 1x4 int8 row vector

   77   60   43   26

Convert the four 8-bit integers, which use 4 bytes (32 bits) of storage, to a single-precision number that also uses 4 bytes of storage.

Y = typecast(X,"single")

Y = single

3.5411e-23

Show the bit patterns in hexadecimal representation. In hexadecimal notation, 1 byte (8 bits) is represented by two digits. The typecast function rearranges the bit patterns without modifying the data.

format hex
X

X = 1x4 int8 row vector

   4d   3c   2b   1a

Y = typecast(X,"single")

Y = single
   1a2b3c4d

Convert 32-Bit Integer to 8-Bit Integer

Create a 1-by-3 vector of 32-bit unsigned integers.

X = uint32([1 255 256])

X = 1x3 uint32 row vector

     1   255   256

Cast X into 8-bit unsigned integers using typecast. Each 32-bit value is divided into four 8-bit segments. Running this code on a little-endian system produces the following results.

Y = typecast(X,"uint8")

Y = 1x12 uint8 row vector

     1     0     0     0   255     0     0     0     0     1     0     0

The third element of X, 256, exceeds the maximum value that 8 bits can hold. The converted value in Y(9) thus overflows to Y(10).

Y(9:12)

ans = 1x4 uint8 row vector

   0   1   0   0

You can convert Y back to 32-bit unsigned integers without changing the underlying data.

X2 = typecast(Y,"uint32")

X2 = 1x3 uint32 row vector

     1   255   256

Compare the output of typecast and the output of cast to see the difference between the two functions.

Z = cast(X,"uint8")

Z = 1x3 uint8 row vector

     1   255   255

X2 = cast(Z,"uint32")

X2 = 1x3 uint32 row vector

     1   255   255

Convert 8-Bit Integer to 16-Bit Integer

Casts integers from a smaller data type (uint8) into a larger one (uint16). Use hexadecimal representation to show the rearrangement of the bit patterns. The typecast function returns the output in little-endian style, combining the four 8-bit segments of the input data to produce two 16-bit segments.

format hex
X = uint8([44 55 66 77])

X = 1x4 uint8 row vector

   2c   37   42   4d

Y = typecast(X,"uint16")

Y = 1x2 uint16 row vector

   372c   4d42

You can convert the little-endian output to big-endian (and vice versa) using the swapbytes function.

Y = swapbytes(typecast(X,"uint16"))

Y = 1x2 uint16 row vector

   2c37   424d

Convert Between Real and Complex Numbers

Since R2024b

Create a 1-by-4 vector of real numbers in double precision.

X = [1.2 2 3.4 4]

X = 1×4

    1.2000    2.0000    3.4000    4.0000

Create a complex number in double precision.

p = 1i

p = 
0.0000 + 1.0000i

Convert X to the same data type and complexity as the variable p. The result is a vector of two complex numbers in double precision.

Y = typecast(X,"like",p)

Y = 1×2 complex

   1.2000 + 2.0000i   3.4000 + 4.0000i

Convert Y back to the same data type and complexity as X. The result is a vector of the four original numbers in X.

X2 = typecast(Y,"like",X)

X2 = 1×4

    1.2000    2.0000    3.4000    4.0000

Input Arguments

X — Input array

scalar | vector

Input array, specified as a scalar or vector.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical (since R2024b) | char (since R2024b)
Complex Number Support: Yes

newtype — New data type

"single" | "double" | "int8" | "int16" | "int32" | "int64" | "uint8" | "uint16" | "uint32" | "uint64" | "logical" | "char"

New data type, specified as "single", "double", "int8", "int16", "int32", "int64", "uint8", "uint16", "uint32", "uint64", "logical", or "char".

If the bit size of newtype is n times larger than the bit size of each element of X, then X must contain a multiple of n elements to convert X to the data type newtype. Otherwise, MATLAB^® throws an error.

p — Prototype

scalar | vector

Prototype, specified as a scalar or vector.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char
Complex Number Support: Yes

Tips

• typecast is different from the MATLAB cast function in that it does not alter the input data. typecast always returns the same number of bytes in the output Y as in the input X. For example, casting the 16-bit integer 1000 to uint8 with typecast returns the full 16 bits in two 8-bit segments (3 and 232), thus keeping the original value (3*256 + 232 = 1000). The cast function, on the other hand, truncates the input value to 255.

• The format of typecast output can differ depending on the system you use. Some computer systems store data starting with the least significant byte (an ordering called little-endian), while others start with the most significant byte (called big-endian). You can use the swapbytes function to reverse the byte ordering from little-endian to big-endian (and vice versa).

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• The value of the data type argument must be lowercase.

• When you use typecast with inherited input port data types in MATLAB Function blocks, the software can throw a size error. To avoid this error, specify the block input port data types explicitly.

• Integer input or result classes must map directly to a C type on the target hardware.

• The input must be a variable-length vector or a fixed-size vector. See Variable-Sizing Restrictions for Code Generation of Toolbox Functions (MATLAB Coder).

• The output vector always has the same orientation as the input vector.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Usage notes and limitations:

• The value of the data type argument must be lowercase.

• When you use typecast with inherited input port data types in MATLAB Function blocks, the software can throw a size error. To avoid this error, specify the block input port data types explicitly.

• Integer input or result classes must map directly to a C type on the target hardware.

• The input must be a variable-length vector or a fixed-size vector.

• The output vector always has the same orientation as the input vector.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The typecast function supports GPU array input with these usage notes and limitations:

• Complex and logical inputs are not supported.

• "like" syntax is not supported.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

Usage notes and limitations:

• Complex and logical inputs are not supported.

• "like" syntax is not supported.

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a

R2024b: Data type conversion using "like" syntax and support for logical, character vector, and complex inputs

You can use typecast(X,"like",p) to convert the bit patterns of X to the same data type and complexity (real or complex) as the prototype p. For example, convert the bit patterns of a double-precision number to the same data type and complexity as p:

p = int32(2 + 3i);
Y = typecast(2.5,"like",p)

Y =

  int32

            0 +   1074003968i

Starting in R2024b, you can also convert from and to logical or character vector data types. For example, typecast(int16(65),"char") converts the bit patterns of the v integer 65 to the character 'A'. Additionally, you can convert the bit patterns of a complex input X, for example, typecast(2+3i,"single").