001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 package org.apache.commons.math3.linear;
019
020 import java.text.FieldPosition;
021 import java.text.NumberFormat;
022 import java.text.ParsePosition;
023 import java.util.ArrayList;
024 import java.util.List;
025 import java.util.Locale;
026
027 import org.apache.commons.math3.exception.MathParseException;
028 import org.apache.commons.math3.util.CompositeFormat;
029
030 /**
031 * Formats a {@code nxm} matrix in components list format
032 * "{{a<sub>0</sub><sub>0</sub>,a<sub>0</sub><sub>1</sub>, ...,
033 * a<sub>0</sub><sub>m-1</sub>},{a<sub>1</sub><sub>0</sub>,
034 * a<sub>1</sub><sub>1</sub>, ..., a<sub>1</sub><sub>m-1</sub>},{...},{
035 * a<sub>n-1</sub><sub>0</sub>, a<sub>n-1</sub><sub>1</sub>, ...,
036 * a<sub>n-1</sub><sub>m-1</sub>}}".
037 * <p>The prefix and suffix "{" and "}", the row prefix and suffix "{" and "}",
038 * the row separator "," and the column separator "," can be replaced by any
039 * user-defined strings. The number format for components can be configured.</p>
040 *
041 * <p>White space is ignored at parse time, even if it is in the prefix, suffix
042 * or separator specifications. So even if the default separator does include a space
043 * character that is used at format time, both input string "{{1,1,1}}" and
044 * " { { 1 , 1 , 1 } } " will be parsed without error and the same matrix will be
045 * returned. In the second case, however, the parse position after parsing will be
046 * just after the closing curly brace, i.e. just before the trailing space.</p>
047 *
048 * <p><b>Note:</b> the grouping functionality of the used {@link NumberFormat} is
049 * disabled to prevent problems when parsing (e.g. 1,345.34 would be a valid number
050 * but conflicts with the default column separator).</p>
051 *
052 * @since 3.1
053 * @version $Id: RealMatrixFormat.java 1364793 2012-07-23 20:46:28Z tn $
054 */
055 public class RealMatrixFormat {
056
057 /** The default prefix: "{". */
058 private static final String DEFAULT_PREFIX = "{";
059 /** The default suffix: "}". */
060 private static final String DEFAULT_SUFFIX = "}";
061 /** The default row prefix: "{". */
062 private static final String DEFAULT_ROW_PREFIX = "{";
063 /** The default row suffix: "}". */
064 private static final String DEFAULT_ROW_SUFFIX = "}";
065 /** The default row separator: ",". */
066 private static final String DEFAULT_ROW_SEPARATOR = ",";
067 /** The default column separator: ",". */
068 private static final String DEFAULT_COLUMN_SEPARATOR = ",";
069 /** Prefix. */
070 private final String prefix;
071 /** Suffix. */
072 private final String suffix;
073 /** Row prefix. */
074 private final String rowPrefix;
075 /** Row suffix. */
076 private final String rowSuffix;
077 /** Row separator. */
078 private final String rowSeparator;
079 /** Column separator. */
080 private final String columnSeparator;
081 /** The format used for components. */
082 private final NumberFormat format;
083
084 /**
085 * Create an instance with default settings.
086 * <p>The instance uses the default prefix, suffix and row/column separator:
087 * "[", "]", ";" and ", " and the default number format for components.</p>
088 */
089 public RealMatrixFormat() {
090 this(DEFAULT_PREFIX, DEFAULT_SUFFIX, DEFAULT_ROW_PREFIX, DEFAULT_ROW_SUFFIX,
091 DEFAULT_ROW_SEPARATOR, DEFAULT_COLUMN_SEPARATOR, CompositeFormat.getDefaultNumberFormat());
092 }
093
094 /**
095 * Create an instance with a custom number format for components.
096 * @param format the custom format for components.
097 */
098 public RealMatrixFormat(final NumberFormat format) {
099 this(DEFAULT_PREFIX, DEFAULT_SUFFIX, DEFAULT_ROW_PREFIX, DEFAULT_ROW_SUFFIX,
100 DEFAULT_ROW_SEPARATOR, DEFAULT_COLUMN_SEPARATOR, format);
101 }
102
103 /**
104 * Create an instance with custom prefix, suffix and separator.
105 * @param prefix prefix to use instead of the default "{"
106 * @param suffix suffix to use instead of the default "}"
107 * @param rowPrefix row prefix to use instead of the default "{"
108 * @param rowSuffix row suffix to use instead of the default "}"
109 * @param rowSeparator tow separator to use instead of the default ";"
110 * @param columnSeparator column separator to use instead of the default ", "
111 */
112 public RealMatrixFormat(final String prefix, final String suffix,
113 final String rowPrefix, final String rowSuffix,
114 final String rowSeparator, final String columnSeparator) {
115 this(prefix, suffix, rowPrefix, rowSuffix, rowSeparator, columnSeparator,
116 CompositeFormat.getDefaultNumberFormat());
117 }
118
119 /**
120 * Create an instance with custom prefix, suffix, separator and format
121 * for components.
122 * @param prefix prefix to use instead of the default "{"
123 * @param suffix suffix to use instead of the default "}"
124 * @param rowPrefix row prefix to use instead of the default "{"
125 * @param rowSuffix row suffix to use instead of the default "}"
126 * @param rowSeparator tow separator to use instead of the default ";"
127 * @param columnSeparator column separator to use instead of the default ", "
128 * @param format the custom format for components.
129 */
130 public RealMatrixFormat(final String prefix, final String suffix,
131 final String rowPrefix, final String rowSuffix,
132 final String rowSeparator, final String columnSeparator,
133 final NumberFormat format) {
134 this.prefix = prefix;
135 this.suffix = suffix;
136 this.rowPrefix = rowPrefix;
137 this.rowSuffix = rowSuffix;
138 this.rowSeparator = rowSeparator;
139 this.columnSeparator = columnSeparator;
140 this.format = format;
141 // disable grouping to prevent parsing problems
142 this.format.setGroupingUsed(false);
143 }
144
145 /**
146 * Get the set of locales for which real vectors formats are available.
147 * <p>This is the same set as the {@link NumberFormat} set.</p>
148 * @return available real vector format locales.
149 */
150 public static Locale[] getAvailableLocales() {
151 return NumberFormat.getAvailableLocales();
152 }
153
154 /**
155 * Get the format prefix.
156 * @return format prefix.
157 */
158 public String getPrefix() {
159 return prefix;
160 }
161
162 /**
163 * Get the format suffix.
164 * @return format suffix.
165 */
166 public String getSuffix() {
167 return suffix;
168 }
169
170 /**
171 * Get the format prefix.
172 * @return format prefix.
173 */
174 public String getRowPrefix() {
175 return rowPrefix;
176 }
177
178 /**
179 * Get the format suffix.
180 * @return format suffix.
181 */
182 public String getRowSuffix() {
183 return rowSuffix;
184 }
185
186 /**
187 * Get the format separator between rows of the matrix.
188 * @return format separator for rows.
189 */
190 public String getRowSeparator() {
191 return rowSeparator;
192 }
193
194 /**
195 * Get the format separator between components.
196 * @return format separator between components.
197 */
198 public String getColumnSeparator() {
199 return columnSeparator;
200 }
201
202 /**
203 * Get the components format.
204 * @return components format.
205 */
206 public NumberFormat getFormat() {
207 return format;
208 }
209
210 /**
211 * Returns the default real vector format for the current locale.
212 * @return the default real vector format.
213 */
214 public static RealMatrixFormat getInstance() {
215 return getInstance(Locale.getDefault());
216 }
217
218 /**
219 * Returns the default real vector format for the given locale.
220 * @param locale the specific locale used by the format.
221 * @return the real vector format specific to the given locale.
222 */
223 public static RealMatrixFormat getInstance(final Locale locale) {
224 return new RealMatrixFormat(CompositeFormat.getDefaultNumberFormat(locale));
225 }
226
227 /**
228 * This method calls {@link #format(RealMatrix,StringBuffer,FieldPosition)}.
229 *
230 * @param m RealMatrix object to format.
231 * @return a formatted matrix.
232 */
233 public String format(RealMatrix m) {
234 return format(m, new StringBuffer(), new FieldPosition(0)).toString();
235 }
236
237 /**
238 * Formats a {@link RealMatrix} object to produce a string.
239 * @param matrix the object to format.
240 * @param toAppendTo where the text is to be appended
241 * @param pos On input: an alignment field, if desired. On output: the
242 * offsets of the alignment field
243 * @return the value passed in as toAppendTo.
244 */
245 public StringBuffer format(RealMatrix matrix, StringBuffer toAppendTo,
246 FieldPosition pos) {
247
248 pos.setBeginIndex(0);
249 pos.setEndIndex(0);
250
251 // format prefix
252 toAppendTo.append(prefix);
253
254 // format rows
255 final int rows = matrix.getRowDimension();
256 for (int i = 0; i < rows; ++i) {
257 toAppendTo.append(rowPrefix);
258 for (int j = 0; j < matrix.getColumnDimension(); ++j) {
259 if (j > 0) {
260 toAppendTo.append(columnSeparator);
261 }
262 CompositeFormat.formatDouble(matrix.getEntry(i, j), format, toAppendTo, pos);
263 }
264 toAppendTo.append(rowSuffix);
265 if (i < rows - 1) {
266 toAppendTo.append(rowSeparator);
267 }
268 }
269
270 // format suffix
271 toAppendTo.append(suffix);
272
273 return toAppendTo;
274 }
275
276 /**
277 * Parse a string to produce a {@link RealMatrix} object.
278 *
279 * @param source String to parse.
280 * @return the parsed {@link RealMatrix} object.
281 * @throws MathParseException if the beginning of the specified string
282 * cannot be parsed.
283 */
284 public RealMatrix parse(String source) {
285 final ParsePosition parsePosition = new ParsePosition(0);
286 final RealMatrix result = parse(source, parsePosition);
287 if (parsePosition.getIndex() == 0) {
288 throw new MathParseException(source,
289 parsePosition.getErrorIndex(),
290 Array2DRowRealMatrix.class);
291 }
292 return result;
293 }
294
295 /**
296 * Parse a string to produce a {@link RealMatrix} object.
297 *
298 * @param source String to parse.
299 * @param pos input/ouput parsing parameter.
300 * @return the parsed {@link RealMatrix} object.
301 */
302 public RealMatrix parse(String source, ParsePosition pos) {
303 int initialIndex = pos.getIndex();
304
305 final String trimmedPrefix = prefix.trim();
306 final String trimmedSuffix = suffix.trim();
307 final String trimmedRowPrefix = rowPrefix.trim();
308 final String trimmedRowSuffix = rowSuffix.trim();
309 final String trimmedColumnSeparator = columnSeparator.trim();
310 final String trimmedRowSeparator = rowSeparator.trim();
311
312 // parse prefix
313 CompositeFormat.parseAndIgnoreWhitespace(source, pos);
314 if (!CompositeFormat.parseFixedstring(source, trimmedPrefix, pos)) {
315 return null;
316 }
317
318 // parse components
319 List<List<Number>> matrix = new ArrayList<List<Number>>();
320 List<Number> rowComponents = new ArrayList<Number>();
321 for (boolean loop = true; loop;){
322
323 if (!rowComponents.isEmpty()) {
324 CompositeFormat.parseAndIgnoreWhitespace(source, pos);
325 if (!CompositeFormat.parseFixedstring(source, trimmedColumnSeparator, pos)) {
326 if (trimmedRowSuffix.length() != 0 &&
327 !CompositeFormat.parseFixedstring(source, trimmedRowSuffix, pos)) {
328 return null;
329 } else {
330 CompositeFormat.parseAndIgnoreWhitespace(source, pos);
331 if (CompositeFormat.parseFixedstring(source, trimmedRowSeparator, pos)) {
332 matrix.add(rowComponents);
333 rowComponents = new ArrayList<Number>();
334 continue;
335 } else {
336 loop = false;
337 }
338 }
339 }
340 } else {
341 CompositeFormat.parseAndIgnoreWhitespace(source, pos);
342 if (trimmedRowPrefix.length() != 0 &&
343 !CompositeFormat.parseFixedstring(source, trimmedRowPrefix, pos)) {
344 return null;
345 }
346 }
347
348 if (loop) {
349 CompositeFormat.parseAndIgnoreWhitespace(source, pos);
350 Number component = CompositeFormat.parseNumber(source, format, pos);
351 if (component != null) {
352 rowComponents.add(component);
353 } else {
354 if (rowComponents.isEmpty()) {
355 loop = false;
356 } else {
357 // invalid component
358 // set index back to initial, error index should already be set
359 pos.setIndex(initialIndex);
360 return null;
361 }
362 }
363 }
364
365 }
366
367 if (!rowComponents.isEmpty()) {
368 matrix.add(rowComponents);
369 }
370
371 // parse suffix
372 CompositeFormat.parseAndIgnoreWhitespace(source, pos);
373 if (!CompositeFormat.parseFixedstring(source, trimmedSuffix, pos)) {
374 return null;
375 }
376
377 // do not allow an empty matrix
378 if (matrix.isEmpty()) {
379 pos.setIndex(initialIndex);
380 return null;
381 }
382
383 // build vector
384 double[][] data = new double[matrix.size()][];
385 int row = 0;
386 for (List<Number> rowList : matrix) {
387 data[row] = new double[rowList.size()];
388 for (int i = 0; i < rowList.size(); i++) {
389 data[row][i] = rowList.get(i).doubleValue();
390 }
391 row++;
392 }
393 return MatrixUtils.createRealMatrix(data);
394 }
395 }