{@code
28 | * ImmutableList list = getList(); // [1, 2, 3, 4, 5]
29 | * list.get(1); // 2
30 | * list.get(3); // 4
31 | * list.get(-1); // 5
32 | * list.get(-3); // 3
33 | * list.get(-5); // 1;
34 | * list.get(0); // 1;
35 | * }
36 | *
37 | * If {@code index} is less than zero, then {@code list.get(index)} equals to {@code 38 | * list.get(list.size() - Math.abs(index))}
39 | * 40 | * @param index index of the element to return 41 | * @return the element at the specified position 42 | * @throws IndexOutOfBoundsException if the index is bigger than or equal to {@code list.size()} 43 | * or {@code list.size() - Math.abs(index)} is less than zero if 44 | * index is negative 45 | */ 46 | T get(int index); 47 | 48 | /** 49 | * Returns the first index of the specified element or {@link OptionalInt#empty()}, if element is 50 | * not found. 51 | * 52 | * @param element the searching element 53 | * @return the first index of the {@link OptionalInt#empty()} 54 | */ 55 | OptionalInt indexOf(T element); 56 | 57 | /** 58 | * Returns the last index of the specified element or {@link OptionalInt#empty()}, if element is 59 | * not found. 60 | * 61 | * @param element the searching element 62 | * @return the first index of the element or {@link OptionalInt#empty()} 63 | */ 64 | OptionalInt lastIndexOf(T element); 65 | 66 | /** 67 | * Returns sublist starting from {@code fromIndex}. Supports negative indices. 68 | * 69 | *{@code
70 | * ImmutableList list = getList(); // [1, 2, 3, 4, 5, 6]
71 | * list.slice(1); // [2, 3, 4, 5, 6]
72 | * list.slice(-2); // [5, 6]
73 | * list.slice(-4); // [3, 4, 5, 6]
74 | * }
75 | *
76 | * @param fromIndex start index (inclusively)
77 | * @return sublist
78 | * @throws IndexOutOfBoundsException if {@code fromIndex} is out of bounds
79 | * @see ImmutableList#slice(int, int, int)
80 | */
81 | ImmutableList{@code
89 | * ImmutableList list = getList(); // [1, 2, 3, 4, 5, 6]
90 | * list.slice(1, 3); // [2, 3]
91 | * list.slice(-3, -1); // [4, 5]
92 | * list.slice(5, 1); // [6, 5, 4, 3]
93 | * list.slice(-2, -6); // [5, 4, 3, 2]
94 | * }
95 | *
96 | * @param fromIndex start index (inclusively)
97 | * @param toIndex end index (exclusively)
98 | * @return sublist
99 | * @throws IndexOutOfBoundsException if {@code fromIndex} is out of bounds
100 | * @see ImmutableList#slice(int, int, int)
101 | */
102 | ImmutableList{@code
110 | * ImmutableList list = getList(); // [1, 2, 3, 4, 5, 6]
111 | * list.slice(0, 3, 1); // [1, 2, 3]
112 | * list.slice(-1, 2, -1); // [6, 5, 4]
113 | * list.slice(0, 6, 2); // [0, 3, 5]
114 | * }
115 | *
116 | * @param fromIndex start index (inclusively)
117 | * @param toIndex end index (exclusively)
118 | * @param stepSize the size of the step traversing
119 | * @return result sublist
120 | * @throws IndexOutOfBoundsException if {@code fromIndex} is out of bounds
121 | * @throws IllegalArgumentException if {@code stepSize} is zero
122 | * @see ImmutableList#get(int)
123 | */
124 | ImmutableList{@code
131 | * ImmutableList list = getList(); // [1, 2, 3, 4, 5, 6]
132 | * list.step(2); // [1, 3, 5]
133 | * list.step(-3); // [6, 3]
134 | * }
135 | *
136 | * @param stepSize the size of step traversing
137 | * @return stepped list
138 | * @throws IllegalArgumentException if {@code stepSize} is zero
139 | * @see ImmutableList#step(int, int)
140 | */
141 | default ImmutableList{@code
156 | * ImmutableList list = createList(); // [1, 2, 3, 4, 5, 6, 7]
157 | * ImmutableList newOne = list.step(0, 2) // [1, 3, 5, 7]
158 | * ImmutableList newTwo = list.step(1, 3) // [2, 5]
159 | * }
160 | *
161 | * Step size might be negative as well. It means backwards traversing.
162 | * 163 | *{@code
164 | * ImmutableList list = createList(); [1, 2, 3, 4, 5, 6, 7]
165 | * ImmutableList newOne = list.step(-1, -2) // [7, 5, 3, 1]
166 | * }
167 | *
168 | * @param fromIndex start index (might be negative)
169 | * @param stepSize the size of the step traversing
170 | * @return stepped list
171 | * @throws IndexOutOfBoundsException if fromIndex is out of bounds
172 | * @throws IllegalArgumentException if stepSize is zero
173 | * @see ImmutableList#get(int)
174 | */
175 | ImmutableList{@code
182 | * ImmutableList people = getPeople();
183 | * ImmutableList jobs = getJobs();
184 | *
185 | * ImmutableList> zipped =
186 | * people.zipWith(jobs);
187 | * }
188 | * If lists have different length, then at some position the key or the value will become 189 | * null.
190 | * 191 | * @param list provided list 192 | * @paramIt is strongly recommended to instantiate this map with only immutable keys and values in 13 | * order not to face with some unexpected mutations.
14 | * 15 | * @paramIf these two maps have any equal keys, {@code overrideBehaviour} function will be called to 138 | * resolve the conflict.
139 | * 140 | * @param mapToConcatWith the map whose pairs will be added to the current one 141 | * @param overrideBehaviour function is called every time when two same keys in two maps are 142 | * found. The first param is the key. The second param is the value from 143 | * the current map. The third param is the value from the given map. 144 | * Function returns the value that will be added to the final result. 145 | * @return new map with merged pairs 146 | * @throws NullPointerException if {@code map} is null or {@code overrideBehaviour} is null 147 | */ 148 | default ImmutableMap