typecast

Convert data type without changing underlying data

Syntax

Y = typecast(X,type)

Description

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

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

   77   60   43   26

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

   44   55   66   77

Y = typecast(X,'uint16')

Y = 1x2 uint16 row vector

   14124   19778

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

   11319   16973

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

type — New data type

'single' | 'double' | 'int8' | 'int16' | 'int32' | 'int64' | 'uint8' | 'uint16' | 'uint32' | 'uint64'

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

If the bit size of type 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 type. Otherwise, MATLAB^® throws an error.

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

This function fully supports GPU arrays. 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™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).