Package ptolemy.data.unit

Class UnitUtilities

  • public class UnitUtilities
extends java.lang.Object
    A set of manipulation routines that are useful for factoring most of the difficulty of dealing with units out of individual token classes. Furthermore, having these as static methods which do not depend on token classes can improve generated code. Generally, the methods in this class manipulate arrays of integers, where each index in the array corresponds to a different category of units, and the value of each element in the array corresponds to the factor in that unit. Generally, multiplying two tokens adds adds their units, dividing two tokens subtracts their units, and adding and subtracting tokens assert that the units are the same.

    Note that a null units array is considered to be a 'unitless' value to reduce memory allocation for tokens that have no units. In other words, the exponent associated with each unit category is zero. In general, the methods in this class return null whenever a unitless unit array is encountered.

    Since:
    Ptolemy II 0.2
    Version:
    $Id$
    Author:
    Steve Neuendorffer
    Pt.AcceptedRating:
    Red (cxh)
    Pt.ProposedRating:
    Red (cxh)

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static int[] addUnitsArray​(int[] units1, int[] units2)
      Add the given unit arrays, and return the result in a new array.
      static boolean areUnitArraysEqual​(int[] units1, int[] units2)
      Return true if the units of this token are the same as that of the argument token.
      static java.util.ArrayList categoryList()
      Return a copy of the category list.
      static int[] copyUnitsArray​(int[] units)
      Return a copy of the given units array.
      static java.lang.String getBaseUnitName​(int categoryIndex)
      Return the name of the base unit of the specified category.
      static int getNumCategories()
      Return the number of currently registered categories.
      static int getUnitCategoryIndex​(java.lang.String categoryName)
      Return the index assigned to the specified unit category.
      static boolean isUnitless​(int[] exponents)
      Return true if the given unit array is null, or the exponents for each index are zero.
      static int[] newUnitArrayInCategory​(int index)
      Return a new units array that has the element at the given index set to one.
      static void registerUnitCategory​(java.lang.String categoryName)
      Register the specified unit category name.
      static void resetUnitCategories()
      Reset the internal state of the UnitSystem.
      static int[] subtractUnitsArray​(int[] units1, int[] units2)
      Subtract the given unit arrays and return the result in a new array.
      static java.lang.String summarizeUnitCategories()
      Return a string representation of the UnitSystem.
      static java.lang.String unitsString​(int[] units)
      Return the string representation of the given array of units.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • addUnitsArray

        public static int[] addUnitsArray​(int[] units1,
                                  int[] units2)
        Add the given unit arrays, and return the result in a new array. The size of the returned array will be the maximum of the size of the two input arrays, or null if both input arrays are unitless.
        Parameters:
        units1 - The first array of units.
        units2 - The second array of units.
        Returns:
        The unit sum of the two arrays.

      • areUnitArraysEqual

        public static boolean areUnitArraysEqual​(int[] units1,
                                         int[] units2)
        Return true if the units of this token are the same as that of the argument token. If both tokens do not have units, return true.
        Parameters:
        units1 - The first array of units.
        units2 - The second array of units.
        Returns:
        True if the units of this token is the same as that of the argument token; false otherwise.

      • categoryList

        public static java.util.ArrayList categoryList()
        Return a copy of the category list.
        Returns:
        a copy of the category list

      • copyUnitsArray

        public static int[] copyUnitsArray​(int[] units)
        Return a copy of the given units array. If the given array is unitless, then return null.
        Parameters:
        units - The given array of units.
        Returns:
        An int array that is a copy of the unit category exponents of this token.

      • getBaseUnitName

        public static java.lang.String getBaseUnitName​(int categoryIndex)
        Return the name of the base unit of the specified category.
        Parameters:
        categoryIndex - The index of the unit category.
        Returns:
        The name of the base unit of the category.

      • getNumCategories

        public static int getNumCategories()
        Return the number of currently registered categories.
        Returns:
        the number of currently registered categories.

      • getUnitCategoryIndex

        public static int getUnitCategoryIndex​(java.lang.String categoryName)
        Return the index assigned to the specified unit category.
        Parameters:
        categoryName - The unit category.
        Returns:
        The index assigned to the category.

      • isUnitless

        public static boolean isUnitless​(int[] exponents)
        Return true if the given unit array is null, or the exponents for each index are zero.
        Parameters:
        exponents - The unit array to be checked.
        Returns:
        true if the given unit array is unitless.

      • newUnitArrayInCategory

        public static int[] newUnitArrayInCategory​(int index)
        Return a new units array that has the element at the given index set to one.
        Parameters:
        index - The unit category index.
        Returns:
        a new unit array in the specified category

      • registerUnitCategory

        public static void registerUnitCategory​(java.lang.String categoryName)
        Register the specified unit category name. If the category is not already registered, assign a unique index for the category. This method is static, so a category added here will be available throughout the system.

        Note that the UnitCategory(NamedObj, String) constructor calls this method.

        Parameters:
        categoryName - The unit categoryName to be registered.

      • resetUnitCategories

        public static void resetUnitCategories()
        Reset the internal state of the UnitSystem. This method is only useful for testing, and should not be called under most circumstances, since it will cause any previously created UnitTokens to have incorrect units.

      • subtractUnitsArray

        public static int[] subtractUnitsArray​(int[] units1,
                                       int[] units2)
        Subtract the given unit arrays and return the result in a new array.
        Parameters:
        units1 - The first array of units.
        units2 - The second array of units.
        Returns:
        The unit difference of the two arrays.

      • summarizeUnitCategories

        public static java.lang.String summarizeUnitCategories()
        Return a string representation of the UnitSystem.
        Returns:
        A string representation of the UnitSystem

      • unitsString

        public static java.lang.String unitsString​(int[] units)
        Return the string representation of the given array of units. The general format of the returned string is "(l_1 * l_2 * ... * l_m) / (s_1 * s_2 * ... * s_n)". For example: "(meter * kilogram) / (second * second)". If m or n is 1, then the parenthesis above or below "/" is omitted. For example: "meter / second". If there is no term above "/", the format becomes "1 / (s_1 * s_2 * ... * s_n)". For example: "1 / meter". If the unit array is unitless, then return an empty string.
        Parameters:
        units - the given array of units.
        Returns:
        A string representation of the given units array.