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 018package org.apache.commons.math3.geometry.euclidean.threed; 019 020import java.text.FieldPosition; 021import java.text.NumberFormat; 022import java.text.ParsePosition; 023import java.util.Locale; 024 025import org.apache.commons.math3.exception.MathParseException; 026import org.apache.commons.math3.geometry.Vector; 027import org.apache.commons.math3.geometry.VectorFormat; 028import 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 * <p><b>Note:</b> using "," as a separator may interfere with the grouping separator 041 * of the default {@link NumberFormat} for the current locale. Thus it is advised 042 * to use a {@link NumberFormat} instance with disabled grouping in such a case.</p> 043 * 044 */ 045public class Vector3DFormat extends VectorFormat<Euclidean3D> { 046 047 /** 048 * Create an instance with default settings. 049 * <p>The instance uses the default prefix, suffix and separator: 050 * "{", "}", and "; " and the default number format for components.</p> 051 */ 052 public Vector3DFormat() { 053 super(DEFAULT_PREFIX, DEFAULT_SUFFIX, DEFAULT_SEPARATOR, 054 CompositeFormat.getDefaultNumberFormat()); 055 } 056 057 /** 058 * Create an instance with a custom number format for components. 059 * @param format the custom format for components. 060 */ 061 public Vector3DFormat(final NumberFormat format) { 062 super(DEFAULT_PREFIX, DEFAULT_SUFFIX, DEFAULT_SEPARATOR, format); 063 } 064 065 /** 066 * Create an instance with custom prefix, suffix and separator. 067 * @param prefix prefix to use instead of the default "{" 068 * @param suffix suffix to use instead of the default "}" 069 * @param separator separator to use instead of the default "; " 070 */ 071 public Vector3DFormat(final String prefix, final String suffix, 072 final String separator) { 073 super(prefix, suffix, separator, CompositeFormat.getDefaultNumberFormat()); 074 } 075 076 /** 077 * Create an instance with custom prefix, suffix, separator and format 078 * for components. 079 * @param prefix prefix to use instead of the default "{" 080 * @param suffix suffix to use instead of the default "}" 081 * @param separator separator to use instead of the default "; " 082 * @param format the custom format for components. 083 */ 084 public Vector3DFormat(final String prefix, final String suffix, 085 final String separator, final NumberFormat format) { 086 super(prefix, suffix, separator, format); 087 } 088 089 /** 090 * Returns the default 3D vector format for the current locale. 091 * @return the default 3D vector format. 092 */ 093 public static Vector3DFormat getInstance() { 094 return getInstance(Locale.getDefault()); 095 } 096 097 /** 098 * Returns the default 3D vector format for the given locale. 099 * @param locale the specific locale used by the format. 100 * @return the 3D vector format specific to the given locale. 101 */ 102 public static Vector3DFormat getInstance(final Locale locale) { 103 return new Vector3DFormat(CompositeFormat.getDefaultNumberFormat(locale)); 104 } 105 106 /** 107 * Formats a {@link Vector3D} object to produce a string. 108 * @param vector the object to format. 109 * @param toAppendTo where the text is to be appended 110 * @param pos On input: an alignment field, if desired. On output: the 111 * offsets of the alignment field 112 * @return the value passed in as toAppendTo. 113 */ 114 @Override 115 public StringBuffer format(final Vector<Euclidean3D> vector, final StringBuffer toAppendTo, 116 final FieldPosition pos) { 117 final Vector3D v3 = (Vector3D) vector; 118 return format(toAppendTo, pos, v3.getX(), v3.getY(), v3.getZ()); 119 } 120 121 /** 122 * Parses a string to produce a {@link Vector3D} object. 123 * @param source the string to parse 124 * @return the parsed {@link Vector3D} object. 125 * @throws MathParseException if the beginning of the specified string 126 * cannot be parsed. 127 */ 128 @Override 129 public Vector3D parse(final String source) throws MathParseException { 130 ParsePosition parsePosition = new ParsePosition(0); 131 Vector3D result = parse(source, parsePosition); 132 if (parsePosition.getIndex() == 0) { 133 throw new MathParseException(source, 134 parsePosition.getErrorIndex(), 135 Vector3D.class); 136 } 137 return result; 138 } 139 140 /** 141 * Parses a string to produce a {@link Vector3D} object. 142 * @param source the string to parse 143 * @param pos input/ouput parsing parameter. 144 * @return the parsed {@link Vector3D} object. 145 */ 146 @Override 147 public Vector3D parse(final String source, final ParsePosition pos) { 148 final double[] coordinates = parseCoordinates(3, source, pos); 149 if (coordinates == null) { 150 return null; 151 } 152 return new Vector3D(coordinates[0], coordinates[1], coordinates[2]); 153 } 154 155}