001/**
002 * LinearCombination -- Represents the interface for a linear combination of two or more
003 * objects.
004 *
005 * Copyright (C) 2015, Joseph A. Huwaldt All rights reserved.
006 *
007 * This library is free software; you can redistribute it and/or modify it under the terms
008 * of the GNU Lesser General Public License as published by the Free Software Foundation;
009 * either version 2.1 of the License, or (at your option) any later version.
010 *
011 * This library is distributed in the hope that it will be useful, but WITHOUT ANY
012 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
013 * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
014 *
015 * You should have received a copy of the GNU Lesser General Public License along with
016 * this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place -
017 * Suite 330, Boston, MA 02111-1307, USA. Or visit: http://www.gnu.org/licenses/lgpl.html
018 */
019package geomss.geom;
020
021import java.util.Collection;
022import java.util.List;
023
024/**
025 * Represents a linear combination made up of a list of two or more GeomElement objects. A
026 * linear combination is formed by a weighted linear addition of a list of one or more
027 * objects. For example: <code>B = W1*Obj_1 + ... + Wn*Obj_n</code> where W1 through Wn
028 * are scalar weights. The linear addition is done independently of physical dimension
029 * (each dimension is added separately) and the weighted addition is done in parameter
030 * space in appropriate: <code> B = W1*Srf_1(s,t) + ... + Wn*Srf_n(s,t)</code>.
031 *
032 * <p>
033 * Modified by: Joseph A. Huwaldt </p>
034 *
035 * @author Joseph A. Huwaldt, Date: September 10, 2015
036 * @version November 27, 2015
037 *
038 * @param <T> The type of this LinearCombination.
039 * @param <E> The type of elements contained in this LinearCombination.
040 */
041public interface LinearCombination<T extends LinearCombination, E extends GeomElement> extends GeometryList<T, E> {
042    
043    /**
044     * Returns an unmodifiable list view of the list of weights in this linear
045     * combination. Attempts to modify the returned collection result in an
046     * UnsupportedOperationException being thrown.
047     *
048     * @return the unmodifiable view over this list of weights.
049     */
050    public List<Double> unmodifiableWeightList();
051
052    /**
053     * Returns the linear combination weight at the specified position in this list.
054     *
055     * @param index index of weight to return (0 returns the 1st element, -1 returns the
056     *              last, -2 returns the 2nd from last, etc).
057     * @return the linear combination weight at the specified position in this linear
058     *         combination.
059     * @throws IndexOutOfBoundsException if the given index is out of range:
060     * <code>index > size()</code>
061     */
062    public Double getWeight(int index);
063    
064    /**
065     * Returns the first linear combination weight from this list.
066     *
067     * @return the first weight in this list.
068     */
069    public Double getFirstWeight();
070    
071    /**
072     * Returns the last linear combination weight from this list.
073     *
074     * @return the last weight in this list.
075     */
076    public Double getLastWeight();
077
078    /**
079     * Returns the range of linear combination weights in this list from the specified
080     * start and ending indexes as a List of double values.
081     *
082     * @param first index of the first element to return (0 returns the 1st element, -1
083     *              returns the last, etc).
084     * @param last  index of the last element to return (0 returns the 1st element, -1
085     *              returns the last, etc).
086     * @return A List made up of the weights in the given range from this
087     *         LinearComboCurve.
088     * @throws IndexOutOfBoundsException if the given index is out of range:
089     * <code>index &ge; size()</code>
090     */
091    public List<Double> getWeightRange(int first, int last);
092
093    /**
094     * Inserts the specified GeomElement at the specified position in this list. Shifts
095     * the element currently at that position (if any) and any subsequent elements to the
096     * right (adds one to their indices). Null values are ignored.
097     * <p>
098     * Note: If this method is used concurrent access must be synchronized (the table is
099     * not thread-safe).
100     * </p>
101     *
102     * @param index  the index at which the specified element is to be inserted. (0
103     *               returns the 1st element, -1 returns the last, -2 returns the 2nd from
104     *               last, etc).
105     * @param value  the element to be inserted. May not be null.
106     * @param weight the linear combination weight of the element to be inserted. May not
107     *               be null.
108     * @throws IndexOutOfBoundsException if <code>index > size()</code>
109     */
110    public void add(int index, E value, Double weight);
111   
112    /**
113     * Appends the specified GeomElement to the end of this list. Null values are ignored.
114     * <p>
115     * Note: If this method is used concurrent access must be synchronized (the table is
116     * not thread-safe).
117     * </p>
118     *
119     * @param value  the element to be appended to this list. May not be null.
120     * @param weight the linear combination weight of the element to be appended. May not
121     *               be null.
122     * @return true if this list changed as a result of this call.
123     * @throws DimensionException if the input element's dimensions are different from
124     * this list's dimensions.
125     */
126    public boolean add(E value, Double weight);
127
128    /**
129     * Appends all of the GeomElement objects in the specified collection to this list.
130     * The behavior of this operation is undefined if the specified collection is modified
131     * while the operation is in progress. (This implies that the behavior of this call is
132     * undefined if the specified collection is this collection, and this collection is
133     * nonempty.)
134     *
135     * @param elements the elements to be appended onto this list. May not be null.
136     * @param weights  the linear combination weights associated with all of the elements
137     *                 being appended. May not be null.
138     * @return <code>true</code> if this LinearComboCurve changed as a result of the call
139     */
140    public boolean addAll(Collection<? extends E> elements, Collection<Double> weights);
141
142    /**
143     * Inserts all of the GeomElement objects in the specified collection and their
144     * associated weights into this linear combination at the specified position. Shifts
145     * the element currently at that position (if any) and any subsequent elements to the
146     * right (increases their indices). The new elements will appear in this list in the
147     * order that they are returned by the specified collection's iterator. The behavior
148     * of this operation is unspecified if the specified collection is modified while the
149     * operation is in progress. (Note that this will occur if the specified collection is
150     * this list, and it's nonempty.)
151     *
152     * @param index    index at which to insert first element from the specified
153     *                 collection.
154     * @param elements the elements to be inserted into this linear combination. May not
155     *                 be null.
156     * @param weights  the linear combination weights associated with each element being
157     *                 inserted. May not be null.
158     * @return <code>true</code> if this LinearComboCurve changed as a result of the call
159     */
160    public boolean addAll(int index, Collection<? extends E> elements, Collection<Double> weights);
161
162    /**
163     * Replaces the weight at the specified position in this linear combination list with
164     * the specified weight. The GeomElement at that position is left unchanged. Null
165     * elements are ignored.
166     *
167     * @param index  The index of the weight to replace (0 returns the 1st element, -1
168     *               returns the last, -2 returns the 2nd from last, etc).
169     * @param weight The weight to be stored at the specified position. The GeomElement at
170     *               that position is left unchanged. May not be null.
171     * @return The weight previously at the specified position in this list.
172     * @throws java.lang.IndexOutOfBoundsException - if  <code>index > size()</code>
173     */
174    public Double setWeight(int index, Double weight);
175
176    /**
177     * Replaces the GeomElement and weight at the specified position in this linear
178     * combination with the specified GeomElement and weight. Null elements are ignored.
179     *
180     * @param index  The index of the element and weight to replace (0 returns the 1st
181     *               element, -1 returns the last, -2 returns the 2nd from last, etc).
182     * @param curve  The GeomElement to be stored at the specified position.
183     *                <code>null</code> elements are ignored.
184     * @param weight The weight to be stored at the specified position.  May not be null.
185     * @return The GeomElement previously at the specified position in this list. The
186     *         previous weight is lost.
187     * @throws java.lang.IndexOutOfBoundsException - if  <code>index > size()</code>
188     */
189    public E set(int index, E curve, Double weight);
190
191}