CustomFloat

Numeric object with a custom floating-point data type

Since R2020a

Description

Use a CustomFloat object to define a floating-point numeric data type with specified word length and mantissa length. Floating-point data types defined by a CustomFloat object adhere to the IEEE 754-2008 standard. For more information on floating-point data types, see Floating-Point Numbers.

Creation

Syntax

x = CustomFloat(v)

x = CustomFloat(v, type)

x = CustomFloat(v, WordLength, MantissaLength)

x = CustomFloat(v, WordLength, MantissaLength, 'typecast')

x = CustomFloat(cf)

Description

x = CustomFloat(v) returns a CustomFloat object with value v. The output object has the same word length, mantissa length, and exponent length as input v.

x = CustomFloat(v, type) returns a CustomFloat object with value v and floating-point type specified by type.

x = CustomFloat(v, WordLength, MantissaLength) returns a CustomFloat object with the specified word length and mantissa length.

x = CustomFloat(v, WordLength, MantissaLength, 'typecast') returns a CustomFloat object with the bit pattern of v and the specified mantissa length. The word length must match the word length of the input v.

x = CustomFloat(cf) returns a CustomFloat object with value and data type properties of CustomFloat object cf.

Input Arguments

v — Value of object

scalar | vector | matrix | multi-dimensional array

The value of the CustomFloat object, specified as a scalar, vector, matrix, or multi-dimensional array.

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

type — Floating-point type of object

'double' | 'single' | 'half'

Floating-point data type of CustomFloat object, specified as either 'double', 'single', or 'half'.

The properties of these types are summarized in the following table.

Type	Word Length	Mantissa Length
double	64	52
single	32	23
half	16	10

Data Types: char

cf — Custom floating-point type

CustomFloat object

Custom floating-point type, specified as a CustomFloat object.

Properties

ExponentBias — Offset value for the exponent

scalar integer

Scalar integer representing the offset value for the exponent.

This property cannot be changed directly, however you can change this property by changing the WordLength and MantissaLength properties, which influence the ExponentLength property. The ExponentBias for a floating-point data type is computed through the following equation:

ExponentBias = 2e-1-1

(1)

where e represents the ExponentLength.

Data Types: double

ExponentLength — Number of bits representing the exponent

scalar integer less than 31

Number of bits representing the exponent. You cannot edit this property directly, however you can change the exponent length by changing the MantissaLength and WordLength properties.

The ExponentLength, MantissaLength, and WordLength properties are related through the following equation:

WordLength = 1+MantissaLength+ExponentLength

(2)

ExponentLength must be less than 31 bits.

Data Types: double

MantissaLength — Number of bits representing the mantissa

scalar integer

Number of bits representing the mantissa, specified as a scalar integer.

The ExponentLength, MantissaLength, and WordLength properties are related through the following equation.

WordLength = 1+MantissaLength+ExponentLength

(3)

Note

ExponentLength must be less than 31 bits.

Example: custfloat.MantissaLength = 14;

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | fi

WordLength — Total number of bits in the data type

scalar integer

Total number of bits in the data type, specified as a scalar integer.

The ExponentLength, MantissaLength, and WordLength properties are related through the following equation.

WordLength = 1+MantissaLength+ExponentLength

(4)

Note

ExponentLength must be less than 31 bits.

Example: custfloat.WordLength = 28;

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | fi

Object Functions

Math and Arithmetic

abs	Absolute value and complex magnitude
ceil	Round toward positive infinity
complex	Create complex array
conj	Complex conjugate
cosh	Hyperbolic cosine
exp	Exponential
fix	Round toward zero
floor	Round toward negative infinity
fma	Multiply and add using fused multiply add approach
hypot	Square root of sum of squares (hypotenuse)
ldivide	Left array division
log	Natural logarithm
log2	Base 2 logarithm and floating-point number dissection
log10	Common logarithm (base 10)
minus	Subtraction
mod	Remainder after division (modulo operation)
mtimes	Matrix multiplication
ndims	Number of array dimensions
plus	Add numbers, append strings
pow10	Base 10 power and scale half-precision numbers
pow2	Base 2 exponentiation and scaling of floating-point numbers
power	Element-wise power
rdivide	Right array division
real	Real part of complex number
rem	Remainder after division
round	Round to nearest decimal or integer
rsqrt	Reciprocal square root
sqrt	Square root
tanh	Hyperbolic tangent
times	Multiplication
uminus	Unary minus
uplus	Unary plus

Data Types

bin	Unsigned binary representation of stored integer of fi object
double	Double-precision arrays
fi	Construct fixed-point numeric object
int8	8-bit signed integer arrays
int16	16-bit signed integer arrays
int32	32-bit signed integer arrays
int64	64-bit signed integer arrays
isnan	Determine which array elements are NaN
isreal	Determine whether array uses complex storage
single	Single-precision arrays
uint8	8-bit unsigned integer arrays
uint16	16-bit unsigned integer arrays
uint32	32-bit unsigned integer arrays
uint64	64-bit unsigned integer arrays

Relational and Logical Operators

eq	Determine equality
ge	Determine greater than or equal to
gt	Determine greater than
le	Determine less than or equal to
lt	Determine less than
ne	Determine inequality

Array and Matrix Operations

cat	Concatenate arrays
ctranspose	Complex conjugate transpose
horzcat	Concatenate arrays horizontally
isfinite	Determine which array elements are finite
isinf	Determine which array elements are infinite
norm	Vector and matrix norms
numel	Number of array elements
reshape	Reshape array by rearranging existing elements
size	Array size
transpose	Transpose vector or matrix
vertcat	Concatenate arrays vertically

Language Fundamentals

disp	Display value of variable

Examples

Create a CustomFloat Object

This example shows how to create a CustomFloat object.

v = pi;
x = CustomFloat(v)

x = 
    3.1416


           Data Type: Floating-point: Double-precision
          WordLength:  64
      MantissaLength:  52
      ExponentLength:  11
        ExponentBias: 1023

Because the input to the CustomFloat constructor was a double, the data type of the CustomFloat object, x, is also a double. If the value passed in to the CustomFloat function is a single, then the resulting CustomFloat object will also have a single-precision floating-point data type.

v = single(pi);
x = CustomFloat(v)

x = 
    3.1416


           Data Type: Floating-point: Single-precision
          WordLength:  32
      MantissaLength:  23
      ExponentLength:   8
        ExponentBias: 127

Create a Half-Precision CustomFloat Object

To create a CustomFloat object with a specified floating-point data type, specify the data type as the second argument in the CustomFloat function.

v = pi;
x = CustomFloat(v,'half')

x = 
    3.1406


           Data Type: Floating-point: Half-precision
          WordLength:  16
      MantissaLength:  10
      ExponentLength:   5
        ExponentBias:  15

Create a CustomFloat Object with Specified Word Length and Mantissa Length

Specify a word length and a mantissa length in the CustomFloat function.

v = pi;
wl = 16;
ml = 4;
x = CustomFloat(v,wl,ml)

x = 
    3.1250


           Data Type: Floating-point: Custom-precision
          WordLength:  16
      MantissaLength:   4
      ExponentLength:  11
        ExponentBias: 1023

Compare the difference between the double-precision value and the value of the CustomFloat object as you change the mantissa length.

err = zeros(1,12);
for ml = 1:12
    x = CustomFloat(v,wl,ml);
    err(ml) = v-double(x);    
end

plot(err);
title('Error: v - double(x)');
ylabel('Error');
xlabel('Mantissa Length');

Typecast a Value to a New CustomFloat Data Type

Using the 'typecast' input argument, the CustomFloat function creates a CustomFloat object with the bit pattern of the input value, and the specified word length and mantissa length.

Define a single-precision value. Single-precision floating-point data types have a 32-bit word length and 23-bit mantissa length. View the binary representation of the single-precision value.

v = single(pi);
bit_pattern = bin(CustomFloat(v))

bit_pattern = 
'01000000010010010000111111011011'

Define a CustomFloat object that has the same bit pattern as the input value, but has a different mantissa length.

x = CustomFloat(v, 32, 20, 'typecast')

x = 
   50.1239


           Data Type: Floating-point: Custom-precision
          WordLength:  32
      MantissaLength:  20
      ExponentLength:  11
        ExponentBias: 1023

View the binary representation of the CustomFloat object, and compare it to the bit pattern of the single-precision input value.

bit_pattern2 = bin(x)

bit_pattern2 = 
'01000000010010010000111111011011'

same = strcmp(bit_pattern, bit_pattern2)

same = logical
   1

Limitations

The following functions, which support custom floating-point inputs, do not support complex custom floating-point inputs.

• ceil

• cosh

• exp

• fix

• floor

• ge

• gt

• hypot

• le

• log

• log10

• log2

• lt

• mod

• pow10

• pow2

• power

• rem

• round

• rsqrt

• sqrt

• tanh

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2020a