001package com.hfg.math.units;
002
003import com.hfg.util.StringUtil;
004
005import java.util.regex.Matcher;
006import java.util.regex.Pattern;
007
008//------------------------------------------------------------------------------
009/**
010 Interface for unit-independent angle measurement.
011 For an example of use, see DmlGradientFill.
012 <div>
013  @author J. Alex Taylor, hairyfatguy.com
014 </div>
015 */
016//------------------------------------------------------------------------------
017// com.hfg XML/HTML Coding Library
018//
019// This library is free software; you can redistribute it and/or
020// modify it under the terms of the GNU Lesser General Public
021// License as published by the Free Software Foundation; either
022// version 2.1 of the License, or (at your option) any later version.
023//
024// This library is distributed in the hope that it will be useful,
025// but WITHOUT ANY WARRANTY; without even the implied warranty of
026// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
027// Lesser General Public License for more details.
028//
029// You should have received a copy of the GNU Lesser General Public
030// License along with this library; if not, write to the Free Software
031// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
032//
033// J. Alex Taylor, President, Founder, CEO, COO, CFO, OOPS hairyfatguy.com
034// jataylor@hairyfatguy.com
035//------------------------------------------------------------------------------
036
037public interface Angle
038{
039
040   public float to(AngleUnits inUnits);
041
042   public int toInt(AngleUnits inUnits);
043
044   public void scale(float inScalingFactor);
045
046   public static final Pattern MEASUREMENT_PATTERN = Pattern.compile("(\\-?[\\d\\.]+)(\\w+)?");
047
048   //--------------------------------------------------------------------------
049   /**
050    Function for converting a string representation of an angle into its appropriate object.
051    @param inStringValue  the string representation (ex: "10deg", "12rad", or "17.5")
052    @param inDefaultUnits  the units to use if the string representation is unit-less.
053    @return a Angle-implementing object
054    */
055   public static Angle allocate(String inStringValue, AngleUnits inDefaultUnits)
056   {
057      if (! StringUtil.isSet(inStringValue))
058      {
059         throw new RuntimeException("No String value sent to Angle.allocate()!");
060      }
061
062      inStringValue = inStringValue.trim();
063
064      Matcher m = MEASUREMENT_PATTERN.matcher(inStringValue);
065      if (! m.matches())
066      {
067         throw new RuntimeException(StringUtil.singleQuote(inStringValue) + " could not be interpreted by Angle.allocate()!");
068      }
069
070      float floatVal = Float.parseFloat(m.group(1));
071      Angle angle = null;
072      AngleUnits units = AngleUnits.valueOf(m.group(2));
073      if (null == units)
074      {
075         units = inDefaultUnits;
076      }
077
078      if (units.equals(AngleUnits.degrees))
079      {
080         angle = new Degrees(floatVal);
081      }
082      else if (units.equals(AngleUnits.radians))
083      {
084         angle = new Radians(floatVal);
085      }
086
087      return angle;
088   }
089}