Added units and dimensions to the design document

1 files changed, 23 insertions, 0 deletions

diff --git a/docs/design.org b/docs/design.org
index 383a707..41713eb 100644
--- a/docs/design.org
+++ b/docs/design.org
@@ -11,8 +11,31 @@
 * Unit System Design
   Any code related to the backend unit system is stored in the ~sevenUnits.unit~ package.
 ** Dimensions
+   Dimensions represent what a unit is measuring, such as length, time, or energy.  Dimensions are represented as an [[*ObjectProduct][ObjectProduct]]<BaseDimension>, where ~BaseDimension~ is a very simple class (its only properties are a name and a symbol) which represents the dimension of a base unit; these base dimensions can be multiplied to create all other Dimensions.
 ** Unit Classes
+   Units are internally represented by the abstract class ~Unit~.  All units have an [[*ObjectProduct][ObjectProduct]]<BaseUnit> (referred to as the base) that they are based on, a dimension (ObjectProduct<BaseDimension>), one or more names and a symbol (these last two bits of data are contained in the ~NameSymbol~ class).  The dimension is calculated from the base unit when needed; the variable is just a cache.  It has two constructors: a package-private one used to make ~BaseUnit~ instances, and a protected one used to make general units (for other subclasses of ~Unit~).  All unit classes are immutable.
+
+   Units also have two conversion functions - one which converts from a value expressed in this unit to its base unit, and another which converts from a value expressed in the base unit to this unit.  In ~Unit~, they are defined as two abstract methods.  This allows you to convert from any unit to any other (as long as they have the same base, i.e. you aren't converting metres to pounds).  To convert from A to B, first convert from A to its base, then convert from the base to B.
+
+   ~BaseUnit~ represents a unit that all other units are defined by.  All of the units used by this system are defined by seven SI ~BaseUnit~ instances (metre, second, kilogram, ampere, kelvin, mole, candela; this is what 7Units is named after) and two non-SI ~BaseUnit~ instances (US dollar and bit).  Because base units are themselves units (and should be able to be used as units), ~BaseUnit~ is a subclass of ~Unit~, using its own package-private constructor.
+
+   However, most units are instances of ~LinearUnit~, another subclass of ~Unit~.  ~LinearUnit~ represents a unit that is /a product of a base unit and a constant called the *conversion factor*/.  Most units you've ever used fall under this definition, the only common exceptions are degrees Celsius and Fahrenheit.  This simplicity allows the ~LinearUnit~ to do many things:
+   - It can implement conversion to and from the base as multiplying and dividing respectively by the conversion factor
+   - You can easily create new units by multiplying or dividing a ~LinearUnit~ by a number (for example, kilometre = metre * 1000).  This can be easily implemented as multiplying this unit's conversion factor by the multiplier and returning a new ~LinearUnit~ with that conversion factor factor.
+   - You can add or subtract two ~LinearUnit~ instances to create a third (as long as they have the same base) by adding or subtracting the conversion factor.
+   - You can multiply or divide any two ~LinearUnit~ instances to create a third by multiplying or dividing the bases and conversion factors.
+   - Note that any operations will return a unit without name(s) or a symbol.  All unit classes have a ~withName~ method that returns a copy of them with different names and/or a different symbol (all of this info is contained in the ~NameSymbol~ class)
+
+   There are a few more classes which play small roles in the unit system:
+   - Unitlike :: A class that is like a unit, but its "value" can be any class.  The only use of this class right now is to implement ~MultiUnit~, a combination of units (like "foot + inch", commonly used in North America for measuring height); its "value" is a list of numbers.
+   - FunctionalUnit :: A convenience class that implements the two conversion functions of ~Unit~ using ~DoubleUnaryOperator~ instances.  This is used internally to implement degrees Celsius and Fahrenheit.  There is also a version of this for ~Unitlike~, ~FunctionalUnitlike~.
+   - UnitValue :: A value expressed as a certain unit (such as "7 inches").  This class is used by the simple unit converter to represent units.  You can convert them between units.  There are also versions of this for ~LinearUnit~ and ~Unitlike~.
+   - Metric :: A static utility class with instances of all of the SI named units, the 9 base dimensions, SI prefixes, some common prefixed units like the kilometre, and a few non-SI units used commonly with them.
+   - BritishImperial :: A static utility class with instances of common units in the British Imperial system (not to be confused with the US Customary system, which is also called "Imperial"; it has the same unit names but the values of a few units are different).  This class and the US Customary is divided into static classes for each dimension, such as ~BritishImperial.Length~.
+   - USCustomary :: A static utility class with instances of common units in the US Customary system (not to be confused with the British Imperial system; it has the same unit names but the values of a few units are different).
 ** Prefixes
+   
+** The Unit Database
 * Utility Classes
   7Units has a few general "utility" classes.  They aren't directly related to units, but are used in the units system.
 ** ObjectProduct