Mercurial > hg > CbC > CbC_gcc
comparison gcc/ada/libgnat/g-bytswa.ads @ 111:04ced10e8804
gcc 7
author | kono |
---|---|
date | Fri, 27 Oct 2017 22:46:09 +0900 |
parents | |
children | 84e7813d76e9 |
comparison
equal
deleted
inserted
replaced
68:561a7518be6b | 111:04ced10e8804 |
---|---|
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-2017, 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; |