ptolemy.data.unit

Class UnitUtilities

java.lang.Object

ptolemy.data.unit.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

Modifier and Type	Method and 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.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.