1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
5 -- G N A T . A R R A Y _ S P L T --
9 -- Copyright (C) 2002-2003 Free Software Foundation, Inc. --
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. --
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. --
29 -- GNAT was originally developed by the GNAT team at New York University. --
30 -- Extensive contributions were provided by Ada Core Technologies Inc. --
32 ------------------------------------------------------------------------------
34 -- Useful array-manipulation routines: given a set of separators, split
35 -- an array wherever the separators appear, and provide direct access
36 -- to the resulting slices.
38 with Ada
.Finalization
;
42 -- Element of the array, this must be a discrete type
44 type Element_Sequence
is array (Positive range <>) of Element
;
45 -- The array which is a sequence of element.
47 type Element_Set
is private;
48 -- This type represent a set of elements. This set does not defined a
49 -- specific order of the elements. The conversion of a sequence to a
50 -- set and membership tests in the set is performed using the routines
51 -- To_Set and Is_In defined below.
53 with function To_Set
(Sequence
: Element_Sequence
) return Element_Set
;
54 -- Returns an Element_Set given an Element_Sequence. Duplicate elements
55 -- can be ignored during this conversion.
57 with function Is_In
(Item
: Element
; Set
: Element_Set
) return Boolean;
58 -- Returns True if Item is found in Set, False otherwise
60 package GNAT
.Array_Split
is
62 Index_Error
: exception;
63 -- Raised by all operations below if Index > Field_Count (S)
65 type Separator_Mode
is
67 -- In this mode the array is cut at each element in the separator
68 -- set. If two separators are contiguous the result at that position
72 -- In this mode contiguous separators are handled as a single
73 -- separator and no empty slice is created.
76 type Slice_Set
is private;
77 -- This type uses by-reference semantics. This is a set of slices as
78 -- returned by Create or Set routines below. The abstraction represents
79 -- a set of items. Each item is a part of the original string named a
80 -- Slice. It is possible to access individual slices by using the Slice
81 -- routine below. The first slice in the Set is at the position/index
82 -- 1. The total number of slices in the set is returned by Slice_Count.
86 From
: Element_Sequence
;
87 Separators
: Element_Sequence
;
88 Mode
: Separator_Mode
:= Single
);
89 -- Create a cut array object. From is the source array, and Separators
90 -- is a sequence of Element along which to split the array. The source
91 -- array is sliced at separator boundaries. The separators are not
92 -- included as part of the resulting slices.
96 From
: Element_Sequence
;
97 Separators
: Element_Set
;
98 Mode
: Separator_Mode
:= Single
);
99 -- Same as above but using a Element_Set
102 (S
: in out Slice_Set
;
103 Separators
: Element_Sequence
;
104 Mode
: Separator_Mode
:= Single
);
105 -- Change the set of separators. The source array will be split according
106 -- to this new set of separators.
109 (S
: in out Slice_Set
;
110 Separators
: Element_Set
;
111 Mode
: Separator_Mode
:= Single
);
112 -- Same as above but using a Element_Set
114 type Slice_Number
is new Natural;
115 -- Type used to count number of slices
117 function Slice_Count
(S
: Slice_Set
) return Slice_Number
;
118 pragma Inline
(Slice_Count
);
119 -- Returns the number of slices (fields) in S
123 Index
: Slice_Number
)
124 return Element_Sequence
;
125 pragma Inline
(Slice
);
126 -- Returns the slice at position Index. First slice is 1. If Index is 0
127 -- the whole array is returned including the separators (this is the
128 -- original source array).
130 type Position
is (Before
, After
);
131 -- Used to designate position of separator
133 type Slice_Separators
is array (Position
) of Element
;
134 -- Separators found before and after the slice
136 Array_End
: constant Element
;
137 -- This is the separator returned for the start or the end of the array
141 Index
: Slice_Number
)
142 return Slice_Separators
;
143 -- Returns the separators used to slice (front and back) the slice at
144 -- position Index. For slices at start and end of the original array, the
145 -- Array_End value is returned for the corresponding outer bound. In
146 -- Multiple mode only the element closest to the slice is returned.
147 -- if Index = 0, returns (Array_End, Array_End).
149 type Separators_Indexes
is array (Positive range <>) of Positive;
151 function Separators
(S
: Slice_Set
) return Separators_Indexes
;
152 -- Returns indexes of all separators used to slice original source array S
156 Array_End
: constant Element
:= Element
'First;
158 type Element_Access
is access Element_Sequence
;
160 type Counter
is access Natural;
162 type Indexes_Access
is access Separators_Indexes
;
164 type Slice_Info
is record
168 -- Starting/Ending position of a slice. This does not include separators.
170 type Slices_Indexes
is array (Slice_Number
range <>) of Slice_Info
;
171 type Slices_Access
is access Slices_Indexes
;
172 -- All indexes for fast access to slices. In the Slice_Set we keep only
173 -- the original array and the indexes where each slice start and stop.
175 type Slice_Set
is new Ada
.Finalization
.Controlled
with record
176 Ref_Counter
: Counter
; -- Reference counter, by-address sem
177 Source
: Element_Access
;
178 N_Slice
: Slice_Number
:= 0; -- Number of slices found
179 Indexes
: Indexes_Access
;
180 Slices
: Slices_Access
;
183 procedure Initialize
(S
: in out Slice_Set
);
184 procedure Adjust
(S
: in out Slice_Set
);
185 procedure Finalize
(S
: in out Slice_Set
);
187 end GNAT
.Array_Split
;