dlist.list source code

1 // Written in the D programming language.
2 /**
3 Main interface to implement lists with the DList API.
4 
5 This module provides an abstraction between the implementation and the API
6 
7 Copyright: Copyright 2019 Ernesto Castellotti <erny.castell@gmail.com>
8 License:   $(HTTP https://www.mozilla.org/en-US/MPL/2.0/, Mozilla Public License - Version 2.0).
9 Authors:   $(HTTP github.com/ErnyTech, Ernesto Castellotti)
10 */
11 module dlist.list;
12 
13 import dlist.baselist;
14 
15 /**
16  * The abstract class from which all DList implementations must be based, contains the standard APIs for using DList
17  */
18 interface List(T) {
19     /**
20      * Adds the specified item to the end of the list.
21      *
22      * This function could cause a memory reallocation if the capacity of the list is not sufficient to contain the item to be added.
23      *
24      * Params:
25      *      elem = element to add to the list
26      */
27     void add(T elem) @nogc;
28     
29     /**
30      * Adds the specified item to the list to the specified index.
31      *
32      * This function could cause a memory reallocation if the capacity of the list is not sufficient to contain the item to be added or index <= 
33 length of the list.
34      *
35      * Params:
36      *      index = index in which to place the element
37      *      elem = element to add to the list
38      */
39     void add(size_t index, T elem) @nogc;
40     
41     /**
42      * Adds the elements contained in the array passed to the function at the end of the list.
43      *
44      * This function could cause a memory reallocation if the capacity of the list is not sufficient to contain the items.
45      *
46      * Params:
47      *      otherArray = the array that contains the elements to add to the list
48      */
49     void addAll(T[] otherArray) @nogc;
50     
51     /**
52      * Adds the elements contained in the array passed to the function the list to the specified index.
53      * The first element of the array will be inserted at the specified index, then the other indexes of the other elements will be incremental
54      *
55      * This function could cause a memory reallocation if the capacity of the list is not sufficient to contain the items or index <= 
56 length of the list.
57      *
58      * Params:
59      *      index = index in which to place the elements
60      *      otherArray = the array that contains the elements to add to the list
61      */
62     void addAll(size_t index, T[] otherArray) @nogc;
63     
64     /**
65      * Adds the elements contained in the DList passed to the function at the end of the list
66      *
67      * This function could cause a memory reallocation if the capacity of the list is not sufficient to contain the items
68      *
69      * Params:
70      *      otherList = the DList that contains the elements to add to the list
71      */
72     void addAll(List!T otherList) @nogc;
73 
74     /**
75      * Adds the elements contained in the DList passed to the function the list to the specified index.
76      * The first element of the DList will be inserted at the specified index, then the other indexes of the other elements will be incremental
77      *
78      * This function could cause a memory reallocation if the capacity of the list is not sufficient to contain the items or index <= 
79 length of the list.
80      *
81      * Params:
82      *      index = index in which to place the elements
83      *      otherList = the DList that contains the elements to add to the list
84      */
85     void addAll(size_t index, List!T otherList) @nogc;
86     
87     /**
88      * Returns the current capacity of the list.
89      * This capacity is not the maximum that the DList can obtain, it only indicates the current availability without allocating further memory
90      *
91      * Returns:
92      *      the capacity of the array
93      */
94     size_t capacity() @nogc;
95     
96     /**
97      * Removes all the elements of the array and deallocate all the memory.
98      */
99     void clear() @nogc;
100     
101     /**
102      * Returns true if the specified element is contained within the list.
103      *
104      * Params:
105      *      elem = element whose presence in this list must be tested
106      *
107      * Returns:
108      *      true if this list contains the specified element
109      */
110     bool contains(T elem) @nogc;
111     
112     /**
113      * Returns true if the specified elements in the array are contained within the list.
114      *
115      * Params:
116      *      otherArray = array containing the elements to be tested
117      *
118      * Returns:
119      *      true if this list contains the specified elements
120      */
121     bool containsAll(T[] otherArray) @nogc;
122     
123     /**
124      * Returns true if the specified elements in the DList are contained within the list.
125      *
126      * Params:
127      *      otherList = DList containing the elements to be tested
128      *
129      * Returns:
130      *      true if this list contains the specified elements
131      */
132     bool containsAll(List!T otherList) @nogc;
133     
134     /**
135      * Returns the element contained in the list at the specified index.
136      *
137      * Params:
138      *      index = the position of the list from which to take the element
139      *
140      * Returns:
141      *      the element contained in the specified index
142      */
143     T get(size_t index) @nogc;
144     
145     /**
146      * Returns by reference the element contained in the list at the specified index.
147      *
148      * Params:
149      *      index = the position of the list from which to take the element
150      *
151      * Returns:
152      *      the element contained in the specified index by reference
153      */
154     ref T getRef(size_t index) @nogc;
155     
156     /**
157      * Returns the index of the first occurrence of the specified element in this list, or -1 if this list does not contain the element.
158      *
159      * Params:
160      *      elem = element to search for
161      *
162      * Returns:
163      *      the index of the first occurrence of the specified element or -1 if this list does not contain the element
164      */
165     long indexOf(T elem) @nogc;
166     
167     /**
168      * Returns true if no element is present in the list.
169      *
170      * Returns:
171      *      true if no element is present in the list
172      */
173     bool isEmpty() @nogc;
174     
175     /**
176      * Returns the index of the last occurrence of the specified element in this list, or -1 if this list does not contain the element.
177      *
178      * Params:
179      *      elem = element to search for
180      *
181      * Returns:
182      *      the index of the last occurrence of the specified element or -1 if this list does not contain the element
183      */
184     long lastIndexOf(T elem) @nogc;
185     
186     /**
187      * Returns the number of items in the list.
188      *
189      * Returns:
190      *      the number of items in the list
191      */
192     size_t length() @nogc;
193     
194     /**
195      * Remove the element at the specified index.
196      *
197      * This function could cause a memory reallocation.
198      *
199      * Params:
200      *      index = the index of the element to be removed
201      */
202     void remove(size_t index) @nogc;
203     
204     /**
205      * Removes all the elements contained in the array from the list (looking for their index).
206      *
207      * This function could cause a memory reallocation.
208      *
209      * Params:
210      *      otherArray = the array of items that need to be removed
211      */
212     void removeAll(T[] otherArray) @nogc;
213     
214     /**
215      * Removes all the elements contained in the DList from the list (looking for their index).
216      *
217      * This function could cause a memory reallocation.
218      *
219      * Params:
220      *      otherList = the DList of items that need to be removed
221      */
222     void removeAll(List!T otherList) @nogc;
223     
224     /**
225      * Asks the implementation of the list to increase the capacity of the list than specified, the implementation MAY increase the allocated memory but it is NOT REQUIRED to do so.
226      * It is possible that in some implementations this method is simply ignored.
227      *
228      * This function could cause a memory reallocation.
229      *
230      * Params:
231      *      numReserve = the amount of capacity to be increased
232      */
233     void reserve(size_t numReserve);
234     
235     /**
236      * Replaces the element at the specified position with the specified element.
237      *
238      * Params:
239      *      index = the position of the element to be replaced
240      *      elem = the element that must be stored at the specified position
241      */
242     void set(size_t index, T elem) @nogc;
243     
244     /**
245      * Generate and return an array from the specified portion of the list.
246      *
247      * Params:
248      *      indexFrom = the initial index from which to start the array
249      *      toIndex = the final index from which to finish the array
250      *
251      * Returns:
252      *      the array specified by the range of index
253      */
254     T[] subArray(size_t indexFrom, size_t toIndex) @nogc;
255     
256     /**
257      * Returns an array containing all the elements of the list
258      *
259      * Returns:
260      *      an array containing all the elements of the list
261      */
262     T[] toArray() @nogc;
263 
264     mixin ListOperatorOverload!T;
265 }