Add examples and documentation!

dimensional/examples/1-Use-The-Force.md

@@ -0,0 +1,7 @@
+One day, you step onto a scale to determine your weight. It reads the number **150**. What is this number? It is the **force** you are applying on to the scale. Europeans would be terrified to see this number, but Americans wouldn't even think twice. See, in the United States, scales read out units of **pounds** where in Europe, it would read out units of **kilograms**. What would a European scale say your weight is?
+
+Now, here's an interesting predicament - pounds are units of **force** whereas kilograms are units of **mass**, which are completely different **dimensions**. In reality, a European scale is also measuring the force you apply, but in a different unit, called **Newtons**.
+
+> It just so happens that pounds are *also* units of mass, and on Earth, one pound of force equals one pound of mass. We'll get to this later.
+
+So now that we know a European scale is actually measuring Newtons, what value would that be for \\\(150 [lb]\\\)? Based on results from plugging it into an online conversion calculator, I expect to see around \\\(667 [N]\\\). Let's see if it checks out.

dimensional/examples/1-Use-The-Force.mjs

@@ -0,0 +1,16 @@
+import { Q, U } from 'dimensional';
+
+// Weight is actually a force - not a mass!
+// Therefore, units must be in pounds of force
+const weight_lbs = Q(150, U({ pound_force: 1 }));
+
+// We can easily obtain our weight in Newtons
+// with a simple conversion using Quantity.as(unit)
+const weight_N = weight_lbs.as(U({ Newton: 1 }));
+
+// Print out the results of the conversion
+console.log(weight_lbs.toString() + '=' + weight_N.toString());
+
+// In case we want the raw value...
+const weight_N_value = weight_N.value;
+console.log('Raw value = ' + weight_N_value);

dimensional/examples/2-Quantity-Math.md

@@ -0,0 +1,19 @@
+Great, our first example checks out! But like I mentioned, European scales don't actually read out in Newtons, but in kilograms. Remember the relationship between force and mass from your physics class?
+
+$$F=ma$$
+
+$$\text{Force}=\text{mass}\times\text{acceleration}$$
+
+We know the value of force and want to solve for mass. What would the acceleration be? This is the acceleration due to Earth's gravity. A good way to visualize that number is drop something (light weight, be safe!) and watch it fall. Notice how it speeds up as it falls - the "speed up" is the acceleration. We call this value \\\(g\\\). On Earth, \\\(g\approx 9.81 [m/s^{2}]\\\) in SI units.
+
+$$m=\frac{F}{g}$$
+
+We could convert \\\(g\\\) to US units, but there's no need, since `dimensional` will handle all unit conversions internally.
+
+When we divide force by acceleration, the units from force and acceleration will persist. We'll end up with a rather strange unit like this:
+
+$$\frac{lb_{f}}{\frac{m}{s^{2}}}=\frac{lb_{f}s^{2}}{m}$$
+
+What are the dimensions on this unit? We can run a quick dimensional analysis using `Quantity.Unit.Dimension.toString()` to get a human-readable representation of our physical base dimensions. Believe it or not, the dimension of that unit is just mass! That means, we can convert quantities with that unit to any unit of mass.
+
+From plugging it into an online calculator, I expect the result to be about \\\(68 [kg]\\\).

dimensional/examples/2-Quantity-Math.mjs

@@ -0,0 +1,20 @@
+import { Q, U } from 'dimensional';
+
+// This is our weight from the previous example
+const weight_lbs = Q(150, U({ pound_force: 1 }));
+
+// Define Earth's gravity at sea level in SI units
+const gravity = Q(9.81, U({ meter: 1, second: -2 }));
+
+// Remember `F=ma`? Rearrange to `m=F/a`
+const mass = weight_lbs.over(gravity);
+
+// The units persist through the operation, unless if they cancel
+// So we'll get `lbf*s^2/m` ... which is not the most useful unit
+console.log(mass.toString());
+
+// What are the dimensions on this weird unit?
+console.log('dim=' + mass.unit.dimension.toString());
+
+// We can use the Quantity.as(unit) method to convert to kg
+console.log(mass.as(U({ kilogram: 1 })).toString());