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-2011, 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 3,  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.                                     --
  17 --                                                                          --
  18 -- As a special exception under Section 7 of GPL version 3, you are granted --
  19 -- additional permissions described in the GCC Runtime Library Exception,   --
  20 -- version 3.1, as published by the Free Software Foundation.               --
  21 --                                                                          --
  22 -- You should have received a copy of the GNU General Public License and    --
  23 -- a copy of the GCC Runtime Library Exception along with this program;     --
  24 -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
  25 -- <http://www.gnu.org/licenses/>.                                          --
  26 --                                                                          --
  27 -- GNAT was originally developed  by the GNAT team at  New York University. --
  28 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  29 --                                                                          --
  30 ------------------------------------------------------------------------------
  31
  32 --  Simple routines for swapping the bytes of 16-, 32-, and 64-bit objects
  33
  34 --  The generic functions should be instantiated with types that are of a size
  35 --  in bytes corresponding to the name of the generic. For example, a 2-byte
  36 --  integer type would be compatible with Swapped2, 4-byte integer with
  37 --  Swapped4, and so on. Failure to do so will result in a warning when
  38 --  compiling the instantiation; this warning should be heeded. Ignoring this
  39 --  warning can result in unexpected results.
  40
  41 --  An example of proper usage follows:
  42
  43 --     declare
  44 --        type Short_Integer is range -32768 .. 32767;
  45 --        for Short_Integer'Size use 16; -- for confirmation
  46
  47 --        X : Short_Integer := 16#7FFF#;
  48
  49 --        function Swapped is new Byte_Swapping.Swapped2 (Short_Integer);
  50
  51 --     begin
  52 --        Put_Line (X'Img);
  53 --        X := Swapped (X);
  54 --        Put_Line (X'Img);
  55 --     end;
  56
  57 --  Note that the generic actual types need not be scalars, but must be
  58 --  'definite' types. They can, for example, be constrained subtypes of
  59 --  unconstrained array types as long as the size is correct. For instance,
  60 --  a subtype of String with length of 4 would be compatible with the
  61 --  Swapped4 generic:
  62
  63 --     declare
  64 --        subtype String4 is String (1 .. 4);
  65 --        function Swapped is new Byte_Swapping.Swapped4 (String4);
  66 --        S : String4 := "ABCD";
  67 --        for S'Alignment use 4;
  68 --     begin
  69 --        Put_Line (S);
  70 --        S := Swapped (S);
  71 --        Put_Line (S);
  72 --     end;
  73
  74 --  Similarly, a constrained array type is also acceptable:
  75
  76 --     declare
  77 --        type Mask is array (0 .. 15) of Boolean;
  78 --        for Mask'Alignment use 2;
  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 we
  91 --  instantiate one of the generics with a type that is too large. The result
  92 --  of the function call is undefined, such that assignment to an object can
  93 --  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 non-
 118 --  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 bytes of the
 145 --  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;