gcc/ada/g-bytswa.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT RUN-TIME COMPONENTS                         --
   4 --                                                                          --
   5 --                    G N A T . B Y T E _ S W A P P I N G                   --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --                      Copyright (C) 2006, AdaCore                         --
  10 --                                                                          --
  11 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  12 -- terms of the  GNU General Public License as published  by the Free Soft- --
  13 -- ware  Foundation;  either version 2,  or (at your option) any later ver- --
  14 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  15 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  16 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  17 -- for  more details.  You should have  received  a copy of the GNU General --
  18 -- Public License  distributed with GNAT;  see file COPYING.  If not, write --
  19 -- to  the  Free Software Foundation,  51  Franklin  Street,  Fifth  Floor, --
  20 -- Boston, MA 02110-1301, USA.                                              --
  21 --                                                                          --
  22 -- As a special exception,  if other files  instantiate  generics from this --
  23 -- unit, or you link  this unit with other files  to produce an executable, --
  24 -- this  unit  does not  by itself cause  the resulting  executable  to  be --
  25 -- covered  by the  GNU  General  Public  License.  This exception does not --
  26 -- however invalidate  any other reasons why  the executable file  might be --
  27 -- covered by the  GNU Public License.                                      --
  28 --                                                                          --
  29 -- GNAT was originally developed  by the GNAT team at  New York University. --
  30 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  31 --                                                                          --
  32 ------------------------------------------------------------------------------
  33
  34 --  Simple routines for swapping the bytes of 16-, 32-, and 64-bit objects.
  35
  36 --  The generic functions should be instantiated with types that
  37 --  are of a size in bytes corresponding to the name of the generic. For
  38 --  example, a 2-byte integer type would be compatible with Swapped2, 4-byte
  39 --  integer with Swapped4, and so on. Failure to do so will result in a
  40 --  warning when compiling the instantiation; this warning should be heeded.
  41 --  Ignoring this warning can result in unexpected results.
  42
  43 --  An example of proper usage follows:
  44
  45 --     declare
  46 --        type Short_Integer is range -32768 .. 32767;
  47 --        for Short_Integer'Size use 16; -- for confirmation
  48
  49 --        X : Short_Integer := 16#7FFF#;
  50
  51 --        function Swapped is new Byte_Swapping.Swapped2 (Short_Integer);
  52
  53 --     begin
  54 --        Put_Line (X'Img);
  55 --        X := Swapped (X);
  56 --        Put_Line (X'Img);
  57 --     end;
  58
  59 --  Note that the generic actual types need not be scalars, but must be
  60 --  'definite' types. They can, for example, be constrained subtypes of
  61 --  unconstrained array types as long as the size is correct. For instance,
  62 --  a subtype of String with length of 4 would be compatible with the
  63 --  Swapped4 generic:
  64
  65 --     declare
  66 --        subtype String4 is String (1 .. 4);
  67 --        function Swapped is new Byte_Swapping.Swapped4 (String4);
  68 --        S : String4 := "ABCD";
  69 --     begin
  70 --        Put_Line (S);
  71 --        S := Swapped (S);
  72 --        Put_Line (S);
  73 --     end;
  74
  75 --  Similarly, a constrained array type is also acceptable:
  76
  77 --     declare
  78 --        type Mask is array (0 .. 15) of Boolean;
  79 --        for Mask'Component_Size use Boolean'Size;
  80 --        X : Mask := (0 .. 7 => True, others => False);
  81 --        function Swapped is new Byte_Swapping.Swapped2 (Mask);
  82 --     begin
  83 --        ...
  84 --        X := Swapped (X);
  85 --        ...
  86 --     end;
  87
  88 --  A properly-sized record type will also be acceptable, and so forth.
  89
  90 --  However, as described, a size mismatch must be avoided. In the following
  91 --  we instantiate one of the generics with a type that is too large. The
  92 --  result of the function call is undefined, such that assignment to an
  93 --  object can result in garbage values.
  94
  95 --     Wrong: declare
  96 --        subtype String16 is String (1 .. 16);
  97
  98 --        function Swapped is new Byte_Swapping.Swapped8 (String16);
  99 --        --  Instantiation generates a compiler warning about
 100 --        --  mismatched sizes
 101
 102 --        S : String16;
 103
 104 --     begin
 105 --        S := "ABCDEFGHDEADBEEF";
 106 --
 107 --        Put_Line (S);
 108 --
 109 --        --  the following assignment results in garbage in S after the
 110 --        --  first 8 bytes
 111 --
 112 --        S := Swapped (S);
 113 --
 114 --        Put_Line (S);
 115 --     end Wrong;
 116
 117 --  When the size of the type is larger than 8 bytes, the use of the
 118 --  non-generic procedures is an alternative because no function result is
 119 --  involved; manipulation of the object is direct.
 120
 121 --  The procedures are passed the address of an object to manipulate. They will
 122 --  swap the first N bytes of that object corresponding to the name of the
 123 --  procedure.  For example:
 124
 125 --     declare
 126 --        S2 : String := "AB";
 127 --        for S2'Alignment use 2;
 128 --        S4 : String := "ABCD";
 129 --        for S4'Alignment use 4;
 130 --        S8 : String := "ABCDEFGH";
 131 --        for S8'Alignment use 8;
 132
 133 --     begin
 134 --        Swap2 (S2'Address);
 135 --        Put_Line (S2);
 136
 137 --        Swap4 (S4'Address);
 138 --        Put_Line (S4);
 139
 140 --        Swap8 (S8'Address);
 141 --        Put_Line (S8);
 142 --     end;
 143
 144 --  If an object of a type larger than N is passed, the remaining
 145 --  bytes of the object are undisturbed.  For example:
 146
 147 --     declare
 148 --        subtype String16 is String (1 .. 16);
 149
 150 --        S : String16;
 151 --        for S'Alignment use 8;
 152
 153 --     begin
 154 --        S  := "ABCDEFGHDEADBEEF";
 155 --        Put_Line (S);
 156 --        Swap8 (S'Address);
 157 --        Put_Line (S);
 158 --     end;
 159
 160 with System;
 161
 162 package GNAT.Byte_Swapping is
 163    pragma Pure;
 164
 165    --  NB: all the routines in this package treat the application objects as
 166    --  unsigned (modular) types of a size in bytes corresponding to the routine
 167    --  name. For example, the generic function Swapped2 manipulates the object
 168    --  passed to the formal parameter Input as a value of an unsigned type that
 169    --  is 2 bytes long. Therefore clients are responsible for the compatibility
 170    --  of application types manipulated by these routines and these modular
 171    --  types, in terms of both size and alignment. This requirement applies to
 172    --  the generic actual type passed to the generic formal type Item in the
 173    --  generic functions, as well as to the type of the object implicitly
 174    --  designated by the address passed to the non-generic procedures. Use of
 175    --  incompatible types can result in implementation- defined effects.
 176
 177    generic
 178       type Item is limited private;
 179    function Swapped2 (Input : Item) return Item;
 180    --  Return the 2-byte value of Input with the bytes swapped
 181
 182    generic
 183       type Item is limited private;
 184    function Swapped4 (Input : Item) return Item;
 185    --  Return the 4-byte value of Input with the bytes swapped
 186
 187    generic
 188       type Item is limited private;
 189    function Swapped8 (Input : Item) return Item;
 190    --  Return the 8-byte value of Input with the bytes swapped
 191
 192    procedure Swap2 (Location : System.Address);
 193    --  Swap the first 2 bytes of the object starting at the address specified
 194    --  by Location.
 195
 196    procedure Swap4 (Location : System.Address);
 197    --  Swap the first 4 bytes of the object starting at the address specified
 198    --  by Location.
 199
 200    procedure Swap8 (Location : System.Address);
 201    --  Swap the first 8 bytes of the object starting at the address specified
 202    --  by Location.
 203
 204    pragma Inline (Swap2, Swap4, Swap8, Swapped2, Swapped4, Swapped8);
 205
 206 end GNAT.Byte_Swapping;