001    package org.LiveGraph.dataCache;
002    
003    import java.util.List;
004    
005    /**
006     * This class defines a dataset and encapsulates related data; a dataset holds one
007     * data value for each of the data series held in the cache and corresponds to a data
008     * row in the underlying data file.
009     * 
010     * <p style="font-size:smaller;">This product includes software developed by the
011     *    <strong>LiveGraph</strong> project and its contributors.<br />
012     *    (<a href="http://www.live-graph.org" target="_blank">http://www.live-graph.org</a>)<br />
013     *    Copyright (c) 2007 G. Paperin.<br />
014     *    All rights reserved.
015     * </p>
016     * <p style="font-size:smaller;">File: DataSet.java</p> 
017     * <p style="font-size:smaller;">Redistribution and use in source and binary forms, with or
018     *    without modification, are permitted provided that the following terms and conditions are met:
019     * </p>
020     * <p style="font-size:smaller;">1. Redistributions of source code must retain the above
021     *    acknowledgement of the LiveGraph project and its web-site, the above copyright notice,
022     *    this list of conditions and the following disclaimer.<br />
023     *    2. Redistributions in binary form must reproduce the above acknowledgement of the
024     *    LiveGraph project and its web-site, the above copyright notice, this list of conditions
025     *    and the following disclaimer in the documentation and/or other materials provided with
026     *    the distribution.<br />
027     *    3. All advertising materials mentioning features or use of this software or any derived
028     *    software must display the following acknowledgement:<br />
029     *    <em>This product includes software developed by the LiveGraph project and its
030     *    contributors.<br />(http://www.live-graph.org)</em><br />
031     *    4. All advertising materials distributed in form of HTML pages or any other technology
032     *    permitting active hyper-links that mention features or use of this software or any
033     *    derived software must display the acknowledgment specified in condition 3 of this
034     *    agreement, and in addition, include a visible and working hyper-link to the LiveGraph
035     *    homepage (http://www.live-graph.org).
036     * </p>
037     * <p style="font-size:smaller;">THIS SOFTWARE IS PROVIDED &quot;AS IS&quot;, WITHOUT WARRANTY
038     *    OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
039     *    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND  NONINFRINGEMENT. IN NO EVENT SHALL
040     *    THE AUTHORS, CONTRIBUTORS OR COPYRIGHT  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
041     *    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING  FROM, OUT OF OR
042     *    IN CONNECTION WITH THE SOFTWARE OR THE USE OR  OTHER DEALINGS IN THE SOFTWARE.
043     * </p>
044     * 
045     * @author Greg Paperin (<a href="http://www.paperin.org" target="_blank">http://www.paperin.org</a>)
046     * @version {@value org.LiveGraph.LiveGraph#version}
047     */
048    public class DataSet implements Comparable<Integer> {
049    
050    /**
051     * Possible default return values; a default return value is used when a dataset
052     * is queried for a value at an invalid index or when the index was valid, but
053     * corresponding value in the underlying data file could not be interpreted as a
054     * legal data value. 
055     */
056    public static enum DefRetValue {
057    
058            NotANum(Double.NaN), Zero(0.0), MinusOne(-1.0), One(1.0);
059    
060            private double actualValue = Double.NEGATIVE_INFINITY;
061            private DefRetValue(double actVal) { actualValue = actVal; }
062            public double doubleValue() { return actualValue; }
063    } // enum DefRetValue
064    
065    /**
066     * The currently used default rteturn value. A default return value is used when a dataset
067     * is queried for a value at an invalid index or when the index was valid, but
068     * corresponding value in the underlying data file could not be interpreted as a
069     * legal data value. 
070     */
071    public static DefRetValue returnValueForIllegalIndex = DefRetValue.NotANum;
072    
073    /**
074     * Values of this dataset.
075     */
076    private Double [] values = null;
077    
078    /**
079     * The index of the data row represented by this dataset in the original file.
080     * The file index applies to datasets only. For instance, the first data row
081     * in a file will have {@code dataFileIndex = 0}, although it will probably
082     * not be the very first row in the file because several comment and info rows
083     * as well as a column label might preceed it. 
084     */
085    private int dataFileIndex = -1;
086    
087    /**
088     * Constructor.
089     * @param values Dava values for this set.
090     * @param dataFileIndex The dafa file index of this set.
091     * @see #dataFileIndex
092     */
093    public DataSet(List<Double> values, int dataFileIndex) {
094            this.dataFileIndex = dataFileIndex;
095            this.values = new Double[values.size()];
096            values.toArray(this.values);    
097    }
098    
099    /**
100     * Constructor.
101     * @param values Dava values for this set.
102     * @param dataFileIndex The dafa file index of this set.
103     * @see #dataFileIndex
104     */
105    public DataSet(double [] values, int dataFileIndex) {
106            this.dataFileIndex = dataFileIndex;
107            this.values = new Double[values.length];
108            int i = 0;
109            for (double v : values)
110                    this.values[i++] = new Double(v);       
111    }
112    
113    /**
114     * Constructor.
115     * @param values Dava values for this set.
116     * @param dataFileIndex The dafa file index of this set.
117     * @see #dataFileIndex
118     */
119    public DataSet(Double [] values, int dataFileIndex) {
120            this.dataFileIndex = dataFileIndex;
121            this.values = new Double[values.length];        
122            System.arraycopy(values, 0, this.values, 0, values.length);     
123    }
124    
125    /**
126     * @return The index of the data row represented by this dataset in the original file.
127     * (The file index applies to datasets only. For instance, the first data row
128     * in a file will have {@code dataFileIndex = 0}, although it will probably
129     * not be the very first row in the file because several comment and info rows
130     * as well as a column label might preceed it.) 
131     */
132    public int getDataFileIndex() {
133            return dataFileIndex;
134    }
135    
136    /**
137     * Compares this set with an integer on the basis on the set's {@link #dataFileIndex}.
138     * @param dataFileIndex An integer representing a potential data file index.
139     * @return A value {@code < 0} if this dataset preceeded the specified index in the data file;
140     * a value {@code > 0} if this dataset followed the specified index in the data file;
141     * {@code 0} if this dataset was located at specified index in the data file.
142     * @see #dataFileIndex
143     */
144    public int compareTo(Integer dataFileIndex) {
145            return this.getDataFileIndex() - dataFileIndex;
146    }
147    
148    /**
149     * @param seriesIndex A data series index (0 based data column number).
150     * @return The data values at the specified index.
151     */
152    public double getValue(int seriesIndex) {
153            try {
154                    Double val = values[seriesIndex];
155                    if (null == val)
156                            return returnValueForIllegalIndex.doubleValue();
157                    return val.doubleValue();
158            } catch (ArrayIndexOutOfBoundsException e) {
159                    if (seriesIndex < 0)
160                            throw e;
161                    return returnValueForIllegalIndex.doubleValue();
162            }
163    }
164    
165    /**
166     * @return A string representation if this dataset.
167     */
168    @Override 
169    public String toString() {
170            StringBuffer buf = new StringBuffer();
171            buf.append("{");
172            buf.append(Integer.toString(getDataFileIndex()));
173            buf.append(": ");
174            buf.append("(");
175            for (int i = 0; i < values.length; i++) {
176                    if (0 < i)
177                            buf.append(", ");
178                    buf.append(Double.toString(getValue(i)));
179            }
180            buf.append(")");
181            buf.append("}");
182            return buf.toString();
183    }
184    
185    } // class DataSet