Docs update for 2.0 (#191)

Author: jscheiny

docs/builtin.md

@@ -1,6 +1,6 @@
 # Built-in Units
 
-While users can define their own unit system (see [Defining Quantities](defining-quantities.html)), Safe Units also comes with a large collection of built-in quantities and units based on the SI unit system.
+While users can [define their own unit system](unit-systems.html), Safe Units also comes with a large collection of built-in quantities and units based on the SI unit system.
 
 All quantities provided are generic and of the form `type Quantity<N = number>` so all quantity types will default to using `number` as the numeric type but may be passed another numeric type.
 
@@ -28,31 +28,17 @@ While plane and solid angles are defined as dimensionless in the SI specificatio
 
 The base units are only provided for `number` measures, but users can create the base units for a given measure type through:
 
-```ts
-type SpecialNumber = /* ... */;
-const numericOps: NumericOperations<SpecialNumber> = {/* ... */};
-const SpecialMeasure = createMeasureType(numericOps);
-const {
-    meters,
-    kilograms,
-    seconds,
-    amperes,
-    kelvin,
-    moles,
-    candelas,
-    radians,
-    steradians,
-    bits,
-} = createBaseUnits(SpecialMeasure);
+```example
+builtinBaseUnits.ts
 ```
 
-These versions of `meters`, `kilograms`, etc. will all operator on measures whose numeric types are `SpecialNumber`.
+These versions of `meters`, `kilograms`, etc. will all operate on measures whose numeric types are `BigNumber`.
 
 ## Provided Units
 
 A large number of built in quantities (e.g. distance, velocity, force and magnetic flux density) are provided. See [here](https://github.com/jscheiny/safe-units/blob/master/src/unit/quantities.ts) for a full list.
 
-Many units are provided from the metric, Imperial and U.S. customary unit systems. See [here](https://github.com/jscheiny/safe-units/tree/master/src/unit) for all of the units.
+Many units are provided from the SI, Imperial and U.S. customary unit systems. See [here](https://github.com/jscheiny/safe-units/tree/master/src/unit) for all of the units.
 
 Prefix functions are provided for both standard [SI prefixes](https://github.com/jscheiny/safe-units/blob/master/src/unit/metric.ts) and for [memory prefixes](https://github.com/jscheiny/safe-units/blob/master/src/unit/memory.ts).
 

docs/defining-quantities.md

@@ -0,0 +1,16 @@
+import { Length, NumericOperations, createMeasureType, createSIBaseUnits } from "safe-units";
+
+class BigNumber {
+    constructor(public value: string) {}
+}
+declare const numericOps: NumericOperations<BigNumber>;
+
+// START
+const BigNumberMeasure = createMeasureType<BigNumber>(numericOps);
+const { meters, kilograms, seconds, ...rest } = createSIBaseUnits(BigNumberMeasure);
+
+const bigValue = new BigNumber("3.14");
+const bigLength: Length<BigNumber> = BigNumberMeasure.of(bigValue, meters);
+// END
+
+console.log(bigLength, meters, kilograms, seconds, rest);

docs/examples/builtinBaseUnits.ts

@@ -0,0 +1,14 @@
+// START
+class WrappedNumber {
+    constructor(public readonly value: number) {}
+
+    declare foo: () => WrappedNumber;
+    // ...
+}
+
+function wrap(value: number) {
+    return new WrappedNumber(value);
+}
+// END
+
+export { WrappedNumber, wrap };

docs/examples/genericMeasureIntro.ts

@@ -0,0 +1,20 @@
+import { WrappedNumber, wrap } from "./genericMeasureIntro";
+
+// START
+import { createMeasureType, GenericMeasure, Unit } from "safe-units";
+
+type WrappedMeasure<B, U extends Unit<B>> = GenericMeasure<WrappedNumber, B, U>;
+const WrappedMeasure = createMeasureType<WrappedNumber>({
+    one: () => wrap(1),
+    neg: x => wrap(-x.value),
+    add: (x, y) => wrap(x.value + y.value),
+    sub: (x, y) => wrap(x.value - y.value),
+    mult: (x, y) => wrap(x.value * y.value),
+    div: (x, y) => wrap(x.value / y.value),
+    reciprocal: x => wrap(1 / x.value),
+    compare: (x, y) => x.value - y.value,
+    format: x => `${x}`,
+});
+// END
+
+console.log(WrappedMeasure);

docs/examples/genericMeasureWrapped.ts

@@ -0,0 +1,16 @@
+import { GenericMeasure, Mass, NumericOperations, Unit, createMeasureType, wrapUnaryFn } from "safe-units";
+
+class WrappedNumber {}
+type WrappedMeasure<B, U extends Unit<B>> = GenericMeasure<WrappedNumber, B, U>;
+declare const numericOperations: NumericOperations<WrappedNumber>;
+
+// START
+declare function foo(value: WrappedNumber): WrappedNumber;
+declare const mass: Mass<WrappedNumber>;
+
+const WrappedMeasure = createMeasureType(numericOperations, {
+    foo: wrapUnaryFn(foo),
+});
+
+WrappedMeasure.foo(mass);
+// END

docs/examples/genericMeasuresStaticMethods.ts

@@ -13,5 +13,5 @@ console.log(velocity.toString()); // 2 m * s^-1
 const error: Velocity = length.times(time);
 // END
 
-// Ensure that error is used
+// Ensure that variables are used
 console.log(error);

docs/examples/intro.ts

@@ -0,0 +1,11 @@
+import { kilograms, liters, Mass, Measure, Volume } from "safe-units";
+
+const VolumeDensity = Mass.over(Volume);
+type VolumeDensity = typeof VolumeDensity;
+
+const mass = Measure.of(30, kilograms);
+const volume = Measure.of(3, liters);
+
+const density: VolumeDensity = mass.over(volume);
+
+console.log(density.toString()); // 10 kg * m^-3

docs/examples/introDerivingQuantities.ts

@@ -0,0 +1,13 @@
+import { days, Measure, mega, micro, miles, speedOfLight, yards } from "safe-units";
+
+const furlongs = Measure.of(220, yards, "fur");
+
+Measure.of(8, furlongs).in(miles); // "1 mi"
+Measure.of(1, miles).in(furlongs); // "8 fur"
+
+const fortnights = Measure.of(14, days, "ftn");
+const megafurlong = mega(furlongs);
+const microfortnight = micro(fortnights);
+const mfPerUFtn = megafurlong.per(microfortnight).withSymbol("Mfur/µftn");
+
+speedOfLight.in(mfPerUFtn); // "1.8026174997852542 Mfur/µftn"

docs/examples/introNamingUnits.ts

@@ -0,0 +1,16 @@
+import { Force, hours, Length, Measure, meters, seconds, Time } from "safe-units";
+
+const length: Length = Measure.of(10, meters);
+const time: Time = Measure.of(10, seconds);
+
+// @ts-expect-error - Measures of different units cannot be added
+length.plus(time);
+
+// @ts-expect-error - Measures of different units cannot be compared
+length.eq(time);
+
+// @ts-expect-error - Measure of m/s is not assigneable to measure of kg*m/s^2
+const force: Force = length.over(time);
+
+// @ts-expect-error - Cannot convert length measure to time measure
+length.in(hours);