typecast - Convert data type without changing underlying data - MATLAB (original) (raw)

Convert data type without changing underlying data

Syntax

Description

[Y](#mw%5F41cb406f-0faa-44e5-a404-3738b57af96a) = typecast([X](#mw%5Fced815be-66c0-4b71-a2fa-75153be6418b),[newtype](#mw%5F6173da3a-ca31-4c10-a098-a31cb7763571)) converts the bit patterns of X to the data type specified bynewtype without changing the underlying data. X must be a full (nonsparse) vector or scalar.

example

[Y](#mw%5F41cb406f-0faa-44e5-a404-3738b57af96a) = typecast([X](#mw%5Fced815be-66c0-4b71-a2fa-75153be6418b),like=[p](#mw%5Fdc5a0135-b8a7-4598-9f24-b8ef4960e39a)) converts the bit patterns of X to the same data type and complexity (real or complex) as the prototype p. (since R2024b)

example

Examples

collapse all

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

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

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

X = 1×4 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.

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.

X = 1×4 int8 row vector

4d 3c 2b 1a

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

X = 1×3 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 = 1×12 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).

ans = 1×4 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 = 1×3 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 = 1×3 uint8 row vector

 1   255   255

X2 = 1×3 uint32 row vector

 1   255   255

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 = 1×4 uint8 row vector

2c 37 42 4d

Y = 1×2 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 = 1×2 uint16 row vector

2c37 424d

Since R2024b

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

X = 1×4

1.2000    2.0000    3.4000    4.0000

Create a complex number in double precision.

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 = 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 = 1×4

1.2000    2.0000    3.4000    4.0000

Input Arguments

collapse all

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

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.

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

Output Arguments

collapse all

Output array, returned as a scalar or vector.

Tips

• typecast is different from the MATLABcast 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

expand all

Usage notes and limitations:

• The newtype input argument must be a constant at code generation time.
• When you use typecast with inherited input port data types inMATLAB 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.
• For input argument X:
  • You must specify the input vector as a fixed-size or variable-length vector at code generation time. Either the first or the second dimension of the vector can be variable size. All other dimensions must have a fixed size of 1.
• Code generation does not support the like syntax.

Usage notes and limitations:

• The value of the data type argument must be lowercase.
• When you use typecast with inherited input port data types inMATLAB 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.

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

Version History

Introduced before R2006a

expand all

You can use typecast(X,like=p) to convert the bit patterns ofX 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 asp:

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").