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-2008 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 "AS IS", 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 of 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