Attribute Scalar_Storage_Order (GNAT Reference Manual)

### 4.57 Attribute Scalar_Storage_Order ¶

For every array or record type `S`, the representation attribute `Scalar_Storage_Order` denotes the order in which storage elements that make up scalar components are ordered within S. The value given must be a static expression of type System.Bit_Order. The following is an example of the use of this feature:

    --  Component type definitions

    subtype Yr_Type is Natural range 0 .. 127;
    subtype Mo_Type is Natural range 1 .. 12;
    subtype Da_Type is Natural range 1 .. 31;

    --  Record declaration

    type Date is record
       Years_Since_1980 : Yr_Type;
       Month            : Mo_Type;
       Day_Of_Month     : Da_Type;
    end record;

    --  Record representation clause

    for Date use record
       Years_Since_1980 at 0 range 0  ..  6;
       Month            at 0 range 7  .. 10;
       Day_Of_Month     at 0 range 11 .. 15;
    end record;

    --  Attribute definition clauses

    for Date'Bit_Order use System.High_Order_First;
    for Date'Scalar_Storage_Order use System.High_Order_First;
    --  If Scalar_Storage_Order is specified, it must be consistent with
    --  Bit_Order, so it's best to always define the latter explicitly if
    --  the former is used.

Other properties are as for the standard representation attribute `Bit_Order` defined by Ada RM 13.5.3(4). The default is `System.Default_Bit_Order`.

For a record type `T`, if `T'Scalar_Storage_Order` is specified explicitly, it shall be equal to `T'Bit_Order`. Note: this means that if a `Scalar_Storage_Order` attribute definition clause is not confirming, then the type’s `Bit_Order` shall be specified explicitly and set to the same value.

Derived types inherit an explicitly set scalar storage order from their parent types. This may be overridden for the derived type by giving an explicit scalar storage order for it. However, for a record extension, the derived type must have the same scalar storage order as the parent type.

A component of a record type that is itself a record or an array and that does not start and end on a byte boundary must have have the same scalar storage order as the record type. A component of a bit-packed array type that is itself a record or an array must have the same scalar storage order as the array type.

No component of a type that has an explicit `Scalar_Storage_Order` attribute definition may be aliased.

A confirming `Scalar_Storage_Order` attribute definition clause (i.e. with a value equal to `System.Default_Bit_Order`) has no effect.

If the opposite storage order is specified, then whenever the value of a scalar component of an object of type `S` is read, the storage elements of the enclosing machine scalar are first reversed (before retrieving the component value, possibly applying some shift and mask operations on the enclosing machine scalar), and the opposite operation is done for writes.

In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components are relaxed. Instead, the following rules apply:

- the underlying storage elements are those at positions `(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)`
- the sequence of underlying storage elements shall have a size no greater than the largest machine scalar
- the enclosing machine scalar is defined as the smallest machine scalar starting at a position no greater than `position + first_bit / storage_element_size` and covering storage elements at least up to `position + (last_bit + storage_element_size - 1) / storage_element_size`
- the position of the component is interpreted relative to that machine scalar.

If no scalar storage order is specified for a type (either directly, or by inheritance in the case of a derived type), then the default is normally the native ordering of the target, but this default can be overridden using pragma `Default_Scalar_Storage_Order`.

If a component of `T` is itself of a record or array type, the specified `Scalar_Storage_Order` does ‘not’ apply to that nested type: an explicit attribute definition clause must be provided for the component type as well if desired.

Representation changes that explicitly or implicitly toggle the scalar storage order are not supported and may result in erroneous execution of the program, except when performed by means of an instance of `Ada.Unchecked_Conversion`.

In particular, overlays are not supported and a warning is given for them:

    type Rec_LE is record
       I : Integer;
    end record;

    for Rec_LE use record
       I at 0 range 0 .. 31;
    end record;

    for Rec_LE'Bit_Order use System.Low_Order_First;
    for Rec_LE'Scalar_Storage_Order use System.Low_Order_First;

    type Rec_BE is record
       I : Integer;
    end record;

    for Rec_BE use record
       I at 0 range 0 .. 31;
    end record;

    for Rec_BE'Bit_Order use System.High_Order_First;
    for Rec_BE'Scalar_Storage_Order use System.High_Order_First;

    R_LE : Rec_LE;

    R_BE : Rec_BE;
    for R_BE'Address use R_LE'Address;

`warning: overlay changes scalar storage order [enabled by default]`

In most cases, such representation changes ought to be replaced by an instantiation of a function or procedure provided by `GNAT.Byte_Swapping`.

Note that the scalar storage order only affects the in-memory data representation. It has no effect on the representation used by stream attributes.

Note that debuggers may be unable to display the correct value of scalar components of a type for which the opposite storage order is specified.