3.4 Ranges and Units

3.4.1 Ranges

The annotations @range, @min, and @max can be used to restrict the possible values for a primitive member. For example:

struct Position {
    @range(min = 0, max = 200) int32 x;
    @min(50) @default(70) int32 y;
    @max(200) @default(80) int32 z;
};

The annotations are enforced at serialization/deserialization time, not when the value of an object is set. For example, assume the following Position: {x= -3, y= 60, z = 150}. If you try to publish a Position sample with this value, the DataWriter::write operation will fail with a DDS_RETCODE_ERROR. If a DataReader receives this sample, the sample will be lost with the reason DDS_LOST_BY_DESERIALIZATION_FAILURE and it will not be provided to the application. In both cases, you will see a log message indicating that x was outside its valid range.

The range annotations can be applied to the following types: octet, int8, uint8, int16, uint16, int32, uint32, int64, uint64, float, double. These annotations are not supported in long double.

If you specify a @default value for a member that is outside the valid range, the code generation will fail. For example:

struct Position {
    @default(300) @range(min = 0, max = 200) int32 x; // Failure. Default outside valid range
    @min(50) @default(70) int32 y;
    @max(200) @default(80) int32 z;
};

3.4.2 Units

The @unit annotation can be used to specify the unit(s) of measurement associated with the value of a member. For example:

struct Position {
    @unit("mm") int32 x;
    @unit("mm") int32 y;
    @unit("mm") int32 z;
};

The annotation can be applied to aliases and members of any kind, not only primitive ones. For example, it could be used to annotate the alias to an array:

@unit("mm, mm, mm")
typedef int32 Coordinates[3];
 
struct Position {
    Coordinates coordinates;
};

In this example, the use of a comma-separated list is an application-specific convention to indicate the unit of each element of the array.

The middleware does not currently enforce any explicit syntax on the value of @unit, nor does it use the value in any way other than making it available through type descriptors. However, it is recommended that you use standardized abbreviations defined by BIPM (http://www.bipm.org/en/measurement-units/) whenever applicable.

3.4.3 Restrictions

  • For performance reasons, the range annotations are not currently applied to samples of types marked with @language_binding(FLAT_DATA). The annotations can be used for the type members, but they are only informational.
  • The range annotations are not currently supported for sequences or arrays. Using a typedef with the range annotations to work around this restriction is also not supported.
  • The TypeCode API (DynamicType API in Modern C++) does not provide a public API to obtain the value of the @range, @min, and @max annotations.