    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    }