    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.geometry.euclidean.threed;
    019
    020    import java.text.FieldPosition;
    021    import java.text.NumberFormat;
    022    import java.text.ParsePosition;
    023    import java.util.Locale;
    024
    025    import org.apache.commons.math3.exception.MathParseException;
    026    import org.apache.commons.math3.geometry.Vector;
    027    import org.apache.commons.math3.geometry.VectorFormat;
    028    import org.apache.commons.math3.util.CompositeFormat;
    029
    030    /**
    031     * Formats a 3D vector in components list format "{x; y; z}".
    032     * <p>The prefix and suffix "{" and "}" and the separator "; " can be replaced by
    033     * any user-defined strings. The number format for components can be configured.</p>
    034     * <p>White space is ignored at parse time, even if it is in the prefix, suffix
    035     * or separator specifications. So even if the default separator does include a space
    036     * character that is used at format time, both input string "{1;1;1}" and
    037     * " { 1 ; 1 ; 1 } " will be parsed without error and the same vector will be
    038     * returned. In the second case, however, the parse position after parsing will be
    039     * just after the closing curly brace, i.e. just before the trailing space.</p>
    040     *
    041     * @version $Id: Vector3DFormat.java 1416643 2012-12-03 19:37:14Z tn $
    042     */
    043    public class Vector3DFormat extends VectorFormat<Euclidean3D> {
    044
    045        /**
    046         * Create an instance with default settings.
    047         * <p>The instance uses the default prefix, suffix and separator:
    048         * "{", "}", and "; " and the default number format for components.</p>
    049         */
    050        public Vector3DFormat() {
    051            super(DEFAULT_PREFIX, DEFAULT_SUFFIX, DEFAULT_SEPARATOR,
    052                  CompositeFormat.getDefaultNumberFormat());
    053        }
    054
    055        /**
    056         * Create an instance with a custom number format for components.
    057         * @param format the custom format for components.
    058         */
    059        public Vector3DFormat(final NumberFormat format) {
    060            super(DEFAULT_PREFIX, DEFAULT_SUFFIX, DEFAULT_SEPARATOR, format);
    061        }
    062
    063        /**
    064         * Create an instance with custom prefix, suffix and separator.
    065         * @param prefix prefix to use instead of the default "{"
    066         * @param suffix suffix to use instead of the default "}"
    067         * @param separator separator to use instead of the default "; "
    068         */
    069        public Vector3DFormat(final String prefix, final String suffix,
    070                             final String separator) {
    071            super(prefix, suffix, separator, CompositeFormat.getDefaultNumberFormat());
    072        }
    073
    074        /**
    075         * Create an instance with custom prefix, suffix, separator and format
    076         * for components.
    077         * @param prefix prefix to use instead of the default "{"
    078         * @param suffix suffix to use instead of the default "}"
    079         * @param separator separator to use instead of the default "; "
    080         * @param format the custom format for components.
    081         */
    082        public Vector3DFormat(final String prefix, final String suffix,
    083                             final String separator, final NumberFormat format) {
    084            super(prefix, suffix, separator, format);
    085        }
    086
    087        /**
    088         * Returns the default 3D vector format for the current locale.
    089         * @return the default 3D vector format.
    090         */
    091        public static Vector3DFormat getInstance() {
    092            return getInstance(Locale.getDefault());
    093        }
    094
    095        /**
    096         * Returns the default 3D vector format for the given locale.
    097         * @param locale the specific locale used by the format.
    098         * @return the 3D vector format specific to the given locale.
    099         */
    100        public static Vector3DFormat getInstance(final Locale locale) {
    101            return new Vector3DFormat(CompositeFormat.getDefaultNumberFormat(locale));
    102        }
    103
    104        /**
    105         * Formats a {@link Vector3D} object to produce a string.
    106         * @param vector the object to format.
    107         * @param toAppendTo where the text is to be appended
    108         * @param pos On input: an alignment field, if desired. On output: the
    109         *            offsets of the alignment field
    110         * @return the value passed in as toAppendTo.
    111         */
    112        @Override
    113        public StringBuffer format(final Vector<Euclidean3D> vector, final StringBuffer toAppendTo,
    114                                   final FieldPosition pos) {
    115            final Vector3D v3 = (Vector3D) vector;
    116            return format(toAppendTo, pos, v3.getX(), v3.getY(), v3.getZ());
    117        }
    118
    119        /**
    120         * Parses a string to produce a {@link Vector3D} object.
    121         * @param source the string to parse
    122         * @return the parsed {@link Vector3D} object.
    123         * @throws MathParseException if the beginning of the specified string
    124         * cannot be parsed.
    125         */
    126        @Override
    127        public Vector3D parse(final String source) throws MathParseException {
    128            ParsePosition parsePosition = new ParsePosition(0);
    129            Vector3D result = parse(source, parsePosition);
    130            if (parsePosition.getIndex() == 0) {
    131                throw new MathParseException(source,
    132                                             parsePosition.getErrorIndex(),
    133                                             Vector3D.class);
    134            }
    135            return result;
    136        }
    137
    138        /**
    139         * Parses a string to produce a {@link Vector3D} object.
    140         * @param source the string to parse
    141         * @param pos input/ouput parsing parameter.
    142         * @return the parsed {@link Vector3D} object.
    143         */
    144        @Override
    145        public Vector3D parse(final String source, final ParsePosition pos) {
    146            final double[] coordinates = parseCoordinates(3, source, pos);
    147            if (coordinates == null) {
    148                return null;
    149            }
    150            return new Vector3D(coordinates[0], coordinates[1], coordinates[2]);
    151        }
    152
    153    }