1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME COMPONENTS --
5 -- G N A T . B Y T E _ S W A P P I N G --
9 -- Copyright (C) 2006-2012, AdaCore --
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. --
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. --
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/>. --
27 -- GNAT was originally developed by the GNAT team at New York University. --
28 -- Extensive contributions were provided by Ada Core Technologies Inc. --
30 ------------------------------------------------------------------------------
32 -- Simple routines for swapping the bytes of 16-, 32-, and 64-bit objects
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.
41 -- An example of proper usage follows:
44 -- type Short_Integer is range -32768 .. 32767;
45 -- for Short_Integer'Size use 16; -- for confirmation
47 -- X : Short_Integer := 16#7FFF#;
49 -- function Swapped is new Byte_Swapping.Swapped2 (Short_Integer);
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
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;
74 -- Similarly, a constrained array type is also acceptable:
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);
88 -- A properly-sized record type will also be acceptable, and so forth
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.
96 -- subtype String16 is String (1 .. 16);
98 -- function Swapped is new Byte_Swapping.Swapped8 (String16);
99 -- -- Instantiation generates a compiler warning about
100 -- -- mismatched sizes
105 -- S := "ABCDEFGHDEADBEEF";
109 -- -- the following assignment results in garbage in S after the
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.
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:
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;
134 -- Swap2 (S2'Address);
137 -- Swap4 (S4'Address);
140 -- Swap8 (S8'Address);
144 -- If an object of a type larger than N is passed, the remaining bytes of the
145 -- object are undisturbed. For example:
148 -- subtype String16 is String (1 .. 16);
151 -- for S'Alignment use 8;
154 -- S := "ABCDEFGHDEADBEEF";
156 -- Swap8 (S'Address);
162 package GNAT.Byte_Swapping is
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.
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
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
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
192 procedure Swap2 (Location : System.Address);
193 -- Swap the first 2 bytes of the object starting at the address specified
196 procedure Swap4 (Location : System.Address);
197 -- Swap the first 4 bytes of the object starting at the address specified
200 procedure Swap8 (Location : System.Address);
201 -- Swap the first 8 bytes of the object starting at the address specified
204 pragma Inline (Swap2, Swap4, Swap8, Swapped2, Swapped4, Swapped8);
206 end GNAT.Byte_Swapping;