001/*
002 *   GeometryList  -- Interface in common to all geometry element lists.
003 *
004 *   Copyright (C) 2002-2025, by Joseph A. Huwaldt
005 *   All rights reserved.
006 *   
007 *   This library is free software; you can redistribute it and/or
008 *   modify it under the terms of the GNU Lesser General Public
009 *   License as published by the Free Software Foundation; either
010 *   version 2 of the License, or (at your option) any later version.
011 *   
012 *   This library is distributed in the hope that it will be useful,
013 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
014 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
015 *   Library General Public License for more details.
016 *
017 *  You should have received a copy of the GNU Lesser General Public License
018 *  along with this program; if not, write to the Free Software
019 *  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
020 *  Or visit:  http://www.gnu.org/licenses/lgpl.html
021 **/
022package geomss.geom;
023
024import java.util.List;
025import javax.measure.converter.ConversionException;
026import javax.measure.quantity.Length;
027import javax.measure.unit.Unit;
028
029/**
030 * Partial implementation of a named list of {@link GeomElement} objects. The list
031 * will not accept the addition of <code>null</code> elements.
032 * 
033 * <p> Modified by: Joseph A. Huwaldt   </p>
034 * 
035 * @author Joseph A. Huwaldt, Date: March 31, 2000
036 * @version February 17, 2025
037 * 
038 * @param <T> The type of this list.
039 * @param <E> The type of elements contained in this list.
040 */
041public interface GeometryList<T extends GeometryList, E extends GeomElement>
042        extends GeomElement<T>, List<E>, Transformable<T> {
043
044    /**
045     * Returns the equivalent to this list object but stated in the specified
046     * unit.
047     *
048     * @param unit the length unit of the list object to be returned.
049     * @return an equivalent to this list object but stated in the specified unit.
050     * @throws ConversionException if the the input unit is not a length unit.
051     */
052    @Override
053    public T to(Unit<Length> unit) throws ConversionException;
054
055    /**
056     * Return a copy of this list converted to the specified number of physical
057     * dimensions. If the number of dimensions is greater than this element,
058     * then zeros are added to the additional dimensions. If the number of
059     * dimensions is less than this element, then the extra dimensions are
060     * simply dropped (truncated). If the new dimensions are the same as the
061     * dimension of this element, then this element is simply returned.
062     *
063     * @param newDim The dimension of the list element to return.
064     * @return This list element converted to the new dimensions.
065     */
066    @Override
067    public T toDimension(int newDim);
068
069    /**
070     * Returns <code>true</code> if this list actually contains any geometry and
071     * <code>false</code> if this list is empty or contains only non-geometry
072     * items such as empty lists.
073     * 
074     * @return true if this list actually contains geometry.
075     */
076    public boolean containsGeometry();
077
078    /**
079     * Returns the range of elements in this list from the specified start and
080     * ending indexes.
081     *
082     * @param first index of the first element to return (0 returns the 1st
083     * element, -1 returns the last, etc).
084     * @param last index of the last element to return (0 returns the 1st
085     * element, -1 returns the last, etc).
086     * @return the list of elements in the given range from this list.
087     * @throws IndexOutOfBoundsException if the given index is out of range:
088     * <code>index &gt; size()</code>
089     */
090    public T getRange(int first, int last);
091
092    /**
093     * Returns the first element from this list.
094     *
095     * @return the first element in this list.
096     */
097    public E getFirst();
098
099    /**
100     * Returns the last element from this list.
101     *
102     * @return the last element in this list.
103     */
104    public E getLast();
105
106    /**
107     * Returns the element with the specified name from this list.
108     *
109     * @param name The name of the element we are looking for in the list.
110     * @return The element matching the specified name. If the specified element
111     *  name isn't found in the list, then <code>null</code> is returned.
112     */
113    public E get(String name);
114
115    /**
116     * Removes the element with the specified name from this list. Shifts any
117     * subsequent elements to the left (subtracts one from their indices).
118     * Returns the element that was removed from the list.
119     *
120     * @param name the name of the element to remove.
121     * @return the element previously at the specified position.
122     */
123    public E remove(String name);
124
125    /**
126     * Appends all of the elements in the specified list of arguments to this
127     * geometry element list.
128     *
129     * @param array elements to be inserted into this collection. May not be null.
130     * @return <code>true</code> if this collection changed as a result of the call.
131     */
132    public boolean add(E... array);
133
134    /**
135     * Inserts all of the {@link GeomElement} objects in the specified list of
136     * arguments into this list at the specified position. Shifts the element
137     * currently at that position (if any) and any subsequent elements to the
138     * right (increases their indices). The new elements will appear in this
139     * list in the order that they are appeared in the array.
140     *
141     * @param index index at which to insert first element from the specified array.
142     * @param array elements to be inserted into this collection. May not be null.
143     * @return <code>true</code> if this collection changed as a result of the call.
144     */
145    public boolean add(int index, E... array);
146
147    /**
148     * Appends all of the elements in the specified array to this geometry
149     * element list. The behavior of this operation is undefined if the
150     * specified collection is modified while the operation is in progress.
151     *
152     * @param arr elements to be inserted into this collection. May not be null.
153     * @return <code>true</code> if this collection changed as a result of the call.
154     */
155    public boolean addAll(E[] arr);
156    
157    /**
158     * Inserts all of the {@link GeomElement} objects in the specified
159     * array into this list at the specified position. Shifts the element
160     * currently at that position (if any) and any subsequent elements to the
161     * right (increases their indices). The new elements will appear in this
162     * list in the order that they are returned by the specified collection's
163     * iterator.
164     *
165     * @param index index at which to insert first element from the specified
166     *  collection.
167     * @param arr elements to be inserted into this collection. May not be null.
168     * @return <code>true</code> if this collection changed as a result of the call.
169     */
170    public boolean addAll(int index, E[] arr);
171    
172    /**
173     * Returns an unmodifiable list view associated to this list. Attempts to
174     * modify the returned collection result in an UnsupportedOperationException
175     * being thrown.
176     *
177     * @return the unmodifiable view over this list.
178     */
179    public List<E> unmodifiableList();
180
181    /**
182     * Returns a new {@link GeomList} with the elements in this list.
183     *
184     * @return A new GeomList with the elements in this list.
185     */
186    public GeomList<E> getAll();
187
188    /**
189     * Returns a new {@link GeomList} with the elements in this list in reverse
190     * order.
191     *
192     * @return A new list with the elements in this list in reverse order.
193     */
194    public T reverse();
195
196    /**
197     * Return the index to the 1st geometry element in this list with the
198     * specified name. Objects with <code>null</code> names are ignored.
199     *
200     * @param name The name of the geometry element to find in this list
201     * @return The index to the named geometry element or -1 if it is not found.
202     */
203    public int getIndexFromName(String name);
204
205}