1------------------------------------------------------------------------------
2--                                                                          --
3--                         GNAT RUN-TIME COMPONENTS                         --
4--                                                                          --
5--                A D A . S T R I N G S . W I D E _ M A P S                 --
6--                                                                          --
7--                                 S p e c                                  --
8--                                                                          --
9--          Copyright (C) 1992-2021, Free Software Foundation, Inc.         --
10--                                                                          --
11-- This specification is derived from the Ada Reference Manual for use with --
12-- GNAT. The copyright notice above, and the license provisions that follow --
13-- apply solely to the  contents of the part following the private keyword. --
14--                                                                          --
15-- GNAT is free software;  you can  redistribute it  and/or modify it under --
16-- terms of the  GNU General Public License as published  by the Free Soft- --
17-- ware  Foundation;  either version 3,  or (at your option) any later ver- --
18-- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
19-- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
20-- or FITNESS FOR A PARTICULAR PURPOSE.                                     --
21--                                                                          --
22-- As a special exception under Section 7 of GPL version 3, you are granted --
23-- additional permissions described in the GCC Runtime Library Exception,   --
24-- version 3.1, as published by the Free Software Foundation.               --
25--                                                                          --
26-- You should have received a copy of the GNU General Public License and    --
27-- a copy of the GCC Runtime Library Exception along with this program;     --
28-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
29-- <http://www.gnu.org/licenses/>.                                          --
30--                                                                          --
31-- GNAT was originally developed  by the GNAT team at  New York University. --
32-- Extensive contributions were provided by Ada Core Technologies Inc.      --
33--                                                                          --
34------------------------------------------------------------------------------
35
36with Ada.Finalization;
37
38package Ada.Strings.Wide_Maps is
39   pragma Preelaborate;
40
41   -------------------------------------
42   -- Wide Character Set Declarations --
43   -------------------------------------
44
45   type Wide_Character_Set is private;
46   pragma Preelaborable_Initialization (Wide_Character_Set);
47   --  Representation for a set of Wide_Character values:
48
49   Null_Set : constant Wide_Character_Set;
50
51   ------------------------------------------
52   -- Constructors for Wide Character Sets --
53   ------------------------------------------
54
55   type Wide_Character_Range is record
56      Low  : Wide_Character;
57      High : Wide_Character;
58   end record;
59   --  Represents Wide_Character range Low .. High
60
61   type Wide_Character_Ranges is
62     array (Positive range <>) of Wide_Character_Range;
63
64   function To_Set
65     (Ranges : Wide_Character_Ranges) return Wide_Character_Set;
66
67   function To_Set
68     (Span : Wide_Character_Range) return Wide_Character_Set;
69
70   function To_Ranges
71     (Set : Wide_Character_Set) return Wide_Character_Ranges;
72
73   ---------------------------------------
74   -- Operations on Wide Character Sets --
75   ---------------------------------------
76
77   function "=" (Left, Right : Wide_Character_Set) return Boolean;
78
79   function "not"
80     (Right : Wide_Character_Set) return Wide_Character_Set;
81
82   function "and"
83     (Left, Right : Wide_Character_Set) return Wide_Character_Set;
84
85   function "or"
86     (Left, Right : Wide_Character_Set) return Wide_Character_Set;
87
88   function "xor"
89     (Left, Right : Wide_Character_Set) return Wide_Character_Set;
90
91   function "-"
92     (Left, Right : Wide_Character_Set) return Wide_Character_Set;
93
94   function Is_In
95     (Element : Wide_Character;
96      Set     : Wide_Character_Set) return Boolean;
97
98   function Is_Subset
99     (Elements : Wide_Character_Set;
100      Set      : Wide_Character_Set) return Boolean;
101
102   function "<="
103     (Left  : Wide_Character_Set;
104      Right : Wide_Character_Set) return Boolean
105   renames Is_Subset;
106
107   subtype Wide_Character_Sequence is Wide_String;
108   --  Alternative representation for a set of character values
109
110   function To_Set
111     (Sequence : Wide_Character_Sequence) return Wide_Character_Set;
112
113   function To_Set
114     (Singleton : Wide_Character) return Wide_Character_Set;
115
116   function To_Sequence
117     (Set : Wide_Character_Set) return Wide_Character_Sequence;
118
119   -----------------------------------------
120   -- Wide Character Mapping Declarations --
121   -----------------------------------------
122
123   type Wide_Character_Mapping is private;
124   pragma Preelaborable_Initialization (Wide_Character_Mapping);
125   --  Representation for a wide character to wide character mapping:
126
127   function Value
128     (Map     : Wide_Character_Mapping;
129      Element : Wide_Character) return Wide_Character;
130
131   Identity : constant Wide_Character_Mapping;
132
133   ---------------------------------
134   -- Operations on Wide Mappings --
135   ---------------------------------
136
137   function To_Mapping
138     (From, To : Wide_Character_Sequence) return Wide_Character_Mapping;
139
140   function To_Domain
141     (Map : Wide_Character_Mapping) return Wide_Character_Sequence;
142
143   function To_Range
144     (Map : Wide_Character_Mapping) return Wide_Character_Sequence;
145
146   type Wide_Character_Mapping_Function is
147      access function (From : Wide_Character) return Wide_Character;
148
149private
150   package AF renames Ada.Finalization;
151
152   ------------------------------------------
153   -- Representation of Wide_Character_Set --
154   ------------------------------------------
155
156   --  A wide character set is represented as a sequence of wide character
157   --  ranges (i.e. an object of type Wide_Character_Ranges) in which the
158   --  following hold:
159
160   --    The lower bound is 1
161   --    The ranges are in order by increasing Low values
162   --    The ranges are non-overlapping and discontigous
163
164   --  A character value is in the set if it is contained in one of the
165   --  ranges. The actual Wide_Character_Set value is a controlled pointer
166   --  to this Wide_Character_Ranges value. The use of a controlled type
167   --  is necessary to prevent storage leaks.
168
169   type Wide_Character_Ranges_Access is access all Wide_Character_Ranges;
170
171   type Wide_Character_Set is new AF.Controlled with record
172      Set : Wide_Character_Ranges_Access;
173   end record;
174
175   pragma Finalize_Storage_Only (Wide_Character_Set);
176   --  This avoids useless finalizations, and, more importantly avoids
177   --  incorrect attempts to finalize constants that are statically
178   --  declared here and in Ada.Strings.Wide_Maps, which is incorrect.
179
180   overriding procedure Initialize (Object : in out Wide_Character_Set);
181   overriding procedure Adjust     (Object : in out Wide_Character_Set);
182   overriding procedure Finalize   (Object : in out Wide_Character_Set);
183
184   Null_Range : aliased constant Wide_Character_Ranges := [];
185
186   Null_Set : constant Wide_Character_Set :=
187                (AF.Controlled with
188                 Set => Null_Range'Unrestricted_Access);
189
190   ----------------------------------------------
191   -- Representation of Wide_Character_Mapping --
192   ----------------------------------------------
193
194   --  A wide character mapping is represented as two strings of equal
195   --  length, where any character appearing in Domain is mapped to the
196   --  corresponding character in Rangev. A character not appearing in
197   --  Domain is mapped to itself. The characters in Domain are sorted
198   --  in ascending order.
199
200   --  The actual Wide_Character_Mapping value is a controlled record
201   --  that contains a pointer to a discriminated record containing the
202   --  range and domain values.
203
204   --  Note: this representation is canonical, and the values stored in
205   --  Domain and Rangev are exactly the values that are returned by the
206   --  functions To_Domain and To_Range. The use of a controlled type is
207   --  necessary to prevent storage leaks.
208
209   type Wide_Character_Mapping_Values (Length : Natural) is record
210      Domain : Wide_Character_Sequence (1 .. Length);
211      Rangev : Wide_Character_Sequence (1 .. Length);
212   end record;
213
214   type Wide_Character_Mapping_Values_Access is
215     access all Wide_Character_Mapping_Values;
216
217   type Wide_Character_Mapping is new AF.Controlled with record
218      Map : Wide_Character_Mapping_Values_Access;
219   end record;
220
221   pragma Finalize_Storage_Only (Wide_Character_Mapping);
222   --  This avoids useless finalizations, and, more importantly avoids
223   --  incorrect attempts to finalize constants that are statically
224   --  declared here and in Ada.Strings.Wide_Maps, which is incorrect.
225
226   overriding procedure Initialize (Object : in out Wide_Character_Mapping);
227   overriding procedure Adjust     (Object : in out Wide_Character_Mapping);
228   overriding procedure Finalize   (Object : in out Wide_Character_Mapping);
229
230   Null_Map : aliased constant Wide_Character_Mapping_Values :=
231                 (Length => 0,
232                  Domain => "",
233                  Rangev => "");
234
235   Identity : constant Wide_Character_Mapping :=
236                (AF.Controlled with
237                 Map => Null_Map'Unrestricted_Access);
238
239end Ada.Strings.Wide_Maps;
240