numerictype

Create an embedded.numerictype object describing fixed-point or floating-point data type

Description

The numerictype object allows you to set properties that determine how a fi object interprets stored data as a real-world value.

Creation

Use the numerictype function described here to create a numerictype object.

Syntax

T = numerictype

T = numerictype(s)

T = numerictype(s,w)

T = numerictype(s,w,f)

T = numerictype(s,w,slope,bias)

T = numerictype(s,w,slopeadjustmentfactor,fixedexponent,bias)

T = numerictype(___,PropertyName=Value)

T = numerictype(T1,PropertyName=Value)

T = numerictype('typename')

T = numerictype(a)

Description

T = numerictype creates a default numerictype object.

T = numerictype(s) creates a fixed-point numerictype object with unspecified scaling, a signed property value s, and a 16-bit word length.

T = numerictype(s,w) creates a fixed-point numerictype object with unspecified scaling, a signed property value s, and word length w.

T = numerictype(s,w,f) creates a fixed-point numerictype object with binary point scaling, a signed property value s, word length w, and fraction length f.

T = numerictype(s,w,slope,bias) creates a fixed-point numerictype object with slope and bias scaling, a signed property value s, word length w, slope, and bias.

T = numerictype(s,w,slopeadjustmentfactor,fixedexponent,bias) creates a fixed-point numerictype object with slope and bias scaling, a signed property value s, word length w, slopeadjustmentfactor, fixedexponent, and bias.

T = numerictype(___,PropertyName=Value) allows you to set properties using name-value arguments. All properties that you do not specify a value for are assigned their default values.

T = numerictype(T1,PropertyName=Value) allows you to make a copy, T, of an existing numerictype object, T1, while modifying any or all of the property values.

T = numerictype('typename') creates a numerictype object with the same numeric attributes as the MATLAB^® or Simulink^® built-in data type typename.

T = numerictype(a) creates a numerictype object with the numeric type attributes of the fi object, a.

Input Arguments

s — Signedness

true or 1 (default) | false or 0 | []

Signedness of the numerictype object, specified as a numeric or logical 1 (true) or 0 (false).

Specify an empty array [] to automate signedness.

Example: T = numerictype(true)

Data Types: logical

w — Word length

16 (default) | positive integer

Word length, in bits, of the stored integer value, specified as a positive integer.

Example: T = numerictype(true,16)

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

f — Fraction length

15 (default) | integer

Fraction length in bits of the stored integer value of the fi object, specified as a scalar integer. The fraction length must be an integer in the range -65535 ≤ f ≤ 65535.

Example: T = numerictype(true,16,15)

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

slope — Slope

3.0518e-05 (default) | finite floating-point number greater than zero

Slope, specified as a finite floating-point number greater than zero.

The slope and the bias determine the scaling of a fixed-point number.

Note

$$slope=slopeadjustmentfactor\times {\text{2}}^{fixedexponent}$$

Changing one of these properties affects the others.

Example: T = numerictype(true,16,2^-2,4)

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

bias — Bias associated with object

0 (default) | floating-point number

Bias associated with the object, specified as a floating-point number.

The slope and the bias determine the scaling of a fixed-point number.

Example: T = numerictype(true,16,2^-2,4)

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

slopeadjustmentfactor — Slope adjustment factor

1 (default) | positive scalar

Slope adjustment factor, specified as a positive scalar.

The slope adjustment factor must be greater than or equal to 1 and less than 2. If you input a slopeadjustmentfactor outside this range, the numerictype object automatically applies a scaling normalization to the values of slopeadjustmentfactor and fixedexponent so that the revised slope adjustment factor is greater than or equal to 1 and less than 2, and maintains the value of the slope.

The slope adjustment is equivalent to the fractional slope of a fixed-point number.

Note

$$slope=slopeadjustmentfactor\times {\text{2}}^{fixedexponent}$$

Changing one of these properties affects the others.

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

fixedexponent — Fixed-point exponent

-15 (default) | integer

Fixed-point exponent associated with the object, specified as an integer.

Note

The FixedExponent property is the negative of the FractionLength. Changing one property changes the other.

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

typename — Data type name

char

Data type name of a built-in data type, specified as a character vector or string. Use this input argument to create a numerictype object with the same data type and scaling attributes as the type specified.

The following input types are supported:

• MATLAB data type name strings — 'half', 'single', 'double', 'int8', 'int16', 'int32', 'int64', 'uint8', 'uint16', 'uint32', 'uint64', 'logical'

• Simulink data type name strings (not aliases) — 'bool', 'sfix16_En3', etc.

Example: T = numerictype('single')

Data Types: char | string

Properties

numerictype object properties define the data type and scaling attributes of a fixed-point object. All properties of a numerictype object are writable.

The properties of the numerictype object can also be specified as name-value arguments when constructing a fi object. However, the numerictype properties of a fi object become read-only after the fi object has been created. Any numerictype properties of a fi object that are unspecified at the time of fi object creation are automatically set to their default values.

Bias — Bias

0 (default) | floating-point number

Bias, specified as a floating-point number.

The slope and bias determine the scaling of a fixed-point number.

Example: T = numerictype('DataTypeMode','Fixed-point: slope and bias scaling','Bias',4)

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

DataType — Data type category

'Fixed' (default) | 'Boolean' | 'Double' | 'ScaledDouble' | 'Single' | 'Half'

Data type category, specified as one of these values:

• 'Fixed' – Fixed-point or integer data type

• 'Boolean' – Built-in MATLAB Boolean data type

• 'Double' – Built-in MATLAB double data type

• 'ScaledDouble' – Scaled double data type

• 'Single' – Built-in MATLAB single data type

• 'Half' – MATLAB half-precision data type

Example: T = numerictype('Double')

Data Types: char

DataTypeMode — Data type and scaling mode

'Fixed-point: binary point scaling' (default) | 'Fixed-point: slope and bias scaling' | 'Fixed-point: unspecified scaling' | 'Scaled double: binary point scaling' | 'Scaled double: slope and bias scaling' | 'Scaled double: unspecified scaling' | 'Double' | 'Single' | 'Half' | 'Boolean'

Data type and scaling mode associated with the object, specified as one of these values:

• 'Fixed-point: binary point scaling' – Fixed-point data type and scaling defined by the word length and fraction length

• 'Fixed-point: slope and bias scaling' – Fixed-point data type and scaling defined by the slope and bias

• 'Fixed-point: unspecified scaling' – Fixed-point data type with unspecified scaling

• 'Scaled double: binary point scaling' – Double data type with fixed-point word length and fraction length information retained

• 'Scaled double: slope and bias scaling' – Double data type with fixed-point slope and bias information retained

• 'Scaled double: unspecified scaling' – Double data type with unspecified fixed-point scaling

• 'Double' – Built-in double

• 'Single' – Built-in single

• 'Half' – MATLAB half-precision data type

• 'Boolean' – Built-in boolean

Example: T = numerictype('DataTypeMode','Fixed-point: binary point scaling')

Data Types: char

DataTypeOverride — Data type override settings

'Inherit' (default) | 'Off'

Data type override settings, specified as one of these values:

• 'Inherit' – Turn on DataTypeOverride

• 'Off' – Turn off DataTypeOverride

Note

The DataTypeOverride property is not visible when its value is set to the default, 'Inherit'.

Example: T = numerictype('DataTypeOverride','Off')

Data Types: char

FixedExponent — Fixed-point exponent

-15 (default) | integer

Fixed-point exponent associated with the object, specified as an integer.

Note

The FixedExponent property is the negative of the FractionLength. Changing one property changes the other.

Example: T = numerictype('FixedExponent',-12)

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

FractionLength — Fraction length of the stored integer value

best precision (default) | integer

Fraction length, in bits, of the stored integer value, specified as an integer.

The default value is the best precision fraction length based on the value of the object and the word length.

Note

The FractionLength property is the negative of the FixedExponent. Changing one property changes the other.

Example: T = numerictype('FractionLength',12)

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

Scaling — Fixed-point scaling mode

'BinaryPoint' (default) | 'SlopeBias' | 'Unspecified'

Fixed-point scaling mode of the object, specified as one of these values:

• 'BinaryPoint' – Scaling for the numerictype object is defined by the fraction length.

• 'SlopeBias' – Scaling for the numerictype object is defined by the slope and bias.

• 'Unspecified' – Temporary setting that is only allowed at numerictype object creation, and allows for the automatic assignment of a best-precision binary point scaling.

Example: T = numerictype('Scaling','BinaryPoint')

Data Types: char

Signed — Whether the object is signed

true or 1 (default) | false or 0

Whether the object is signed, specified as a numeric or logical 1 (true) or 0 (false).

Note

Although the Signed property is still supported, the Signedness property always appears in the numerictype object display. If you choose to change or set the signedness of your numerictype object using the Signed property, MATLAB updates the corresponding value of the Signedness property.

Example: T = numerictype('Signed',true)

Data Types: logical

Signedness — Whether the object is signed

'Signed' (default) | 'Unsigned' | 'Auto'

Whether the object is signed, specified as one of these values:

• 'Signed' – Signed

• 'Unsigned' – Unsigned

• 'Auto' – Unspecified sign

Note

Although you can create numerictype objects with an unspecified sign (Signedness: Auto), all fixed-point numerictype objects must have a Signedness of Signed or Unsigned. If you use a numerictype object with Signedness: Auto to construct a numerictype object, the Signedness property of the numerictype object automatically defaults to Signed.

Example: T = numerictype('Signedness','Signed')

Data Types: char

Slope — Slope

3.0518e-05 (default) | finite, positive floating-point number

Slope, specified as a finite, positive floating-point number.

The slope and bias determine the scaling of a fixed-point number.

Note

$$slope=slopeadjustmentfactor\times {\text{2}}^{fixedexponent}$$

Changing one of these properties affects the others.

Example: T = numerictype('DataTypeMode','Fixed-point: slope and bias scaling','Slope',2^-2)

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

SlopeAdjustmentFactor — Slope adjustment factor

1 (default) | positive scalar

Slope adjustment factor, specified as a positive scalar.

The slope adjustment factor must be greater than or equal to 1 and less than 2. If you input a slopeadjustmentfactor outside this range, the numerictype object automatically applies a scaling normalization to the values of slopeadjustmentfactor and fixedexponent so that the revised slope adjustment factor is greater than or equal to 1 and less than 2, and maintains the value of the slope.

The slope adjustment is equivalent to the fractional slope of a fixed-point number.

Note

$$slope=slopeadjustmentfactor\times {\text{2}}^{fixedexponent}$$

Changing one of these properties affects the others.

Example: T = numerictype('DataTypeMode','Fixed-point: slope and bias scaling','SlopeAdjustmentFactor',1.5)

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

WordLength — Word length of the stored integer value

16 (default) | positive integer

Word length, in bits, of the stored integer value, specified as a positive integer.

Example: T = numerictype('WordLength',16)

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

Examples

Create a Default numerictype Object

This example shows how to create a numerictype object with default property settings.

T = numerictype

T = 
          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 16
        FractionLength: 15

Create a Signed numerictype Object with Default Word Length and Scaling

This example shows how to create a signed or unsigned numerictype object with the default word length and scaling.

Set the signedness argument, s, to 1 to create a signed numerictype object. Omit the arguments for word length, w, and fraction length, f.

T = numerictype(1)

T = 
          DataTypeMode: Fixed-point: unspecified scaling
            Signedness: Signed
            WordLength: 16

The object is signed, with a word length of 16 bits and unspecified scaling.

Create an unsigned numerictype object by setting the signedness argument to 0.

T = numerictype(0)

T = 
          DataTypeMode: Fixed-point: unspecified scaling
            Signedness: Unsigned
            WordLength: 16

The object has the default word length of 16 bits and unspecified scaling.

Create a numerictype Object with Unspecified Scaling

This example shows how to create a numerictype object with a 32-bit word length and unspecified scaling by omitting the fraction length argument, f.

T = numerictype(1,32)

T = 
          DataTypeMode: Fixed-point: unspecified scaling
            Signedness: Signed
            WordLength: 32

The object is signed.

Create a numerictype Object with Specified Word and Fraction Length

This example shows how to create a signed numerictype object with binary-point scaling, a 32-bit word length, and 30-bit fraction length.

T = numerictype(1,32,30)

T = 
          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 32
        FractionLength: 30

Create a numerictype Object with Slope and Bias Scaling

This example shows how to create a numerictype object with slope and bias scaling. The real-world value of a slope and bias scaled number is represented by:

$$\text{realworldvalue}=\left(\text{slope}\times \text{stored}\text{integer}\right)+\text{bias}$$

Create a numerictype object that describes a signed, fixed-point data type with a word length of 16 bits, a slope of 2^-2, and a bias of 4.

T = numerictype(1,16,2^-2,4)

T = 
          DataTypeMode: Fixed-point: slope and bias scaling
            Signedness: Signed
            WordLength: 16
                 Slope: 0.25
                  Bias: 4

Alternatively, the slope can be represented by:

$$\text{slope}=\text{slopeadjustmentfactor}\times 2^{\text{fixedexponent}}$$

Create a numerictype object that describes a signed, fixed-point data type with a word length of 16 bits, a slope adjustment factor of 1, a fixed exponent of -2, and a bias of 4.

T = numerictype(1,16,1,-2,4)

T = 
          DataTypeMode: Fixed-point: slope and bias scaling
            Signedness: Signed
            WordLength: 16
                 Slope: 0.25
                  Bias: 4

Create a numerictype Object with Specified Property Values

This example shows how to use name-value arguments to set numerictype properties at object creation.

T = numerictype('Signed',true,...
    'DataTypeMode',...
    'Fixed-point: slope and bias scaling', ...
    'WordLength',32,...
    'Slope',2^-2,...
    'Bias',4)

T = 
          DataTypeMode: Fixed-point: slope and bias scaling
            Signedness: Signed
            WordLength: 32
                 Slope: 0.25
                  Bias: 4

Create a numerictype Object with Unspecified Signedness

This example shows how to create a numerictype object with an unspecified Signedness by using name-value arguments to set the Signedness property to Auto.

T = numerictype('Signedness','Auto')

T = 
          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Auto
            WordLength: 16
        FractionLength: 15

Create a numerictype Object with Specified Data Type

This example shows how to create a numerictype object with a specific data type by using arguments and name-value arguments.

T = numerictype(0,24,12,'DataType','ScaledDouble')

T = 
          DataTypeMode: Scaled double: binary point scaling
            Signedness: Unsigned
            WordLength: 24
        FractionLength: 12

The returned numerictype object, T, is unsigned, and has a word length of 24 bits, a fraction length of 12 bits, and a data type set to scaled double.

Create a numerictype Object from a Data Type Name String

This example shows how to create a numerictype object using the name of a built-in MATLAB® or Simulink® data type.

Create a numerictype object with the same data type and scaling attributes as the MATLAB data type int8.

T = numerictype('int8')

T = 
          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 8
        FractionLength: 0

Create a numerictype object with the same data type and scaling attributes as the Simulink data type sfix16_En3.

S = numerictype('sfix16_En3')

S = 
          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 16
        FractionLength: 3

Create a numerictype Object from a fi Object

This example shows you how to create a numerictype object from an existing fi object.

Create a fi object with default properties and no value specified.

a = fi

a = 

[]

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 16
        FractionLength: 15

Create a numerictype object using a as the input.

T = numerictype(a)

T = 
          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 16
        FractionLength: 15

T has the same numeric type attributes as a.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• Fixed-point signals coming in to a MATLAB Function block from Simulink are assigned a numerictype object that is populated with the signal's data type and scaling information.

• If the input signal to the numerictype function is not fixed-point, the function will return information about the data type of that signal.

• The numerictype function can be used to create numerictype objects in generated code.

• All numerictype object properties related to the data type must be constant.

HDL Code Generation
Generate VHDL, Verilog and SystemVerilog code for FPGA and ASIC designs using HDL Coder™.

Version History

Introduced before R2006a

R2021a: Inexact property names for fi, fimath, and numerictype objects not supported

In previous releases, inexact property names for fi, fimath, and numerictype objects would result in a warning. In R2021a, support for inexact property names was removed. Use exact property names instead.