readme updates for 1.0.0 including examples

README.md

@@ -11,9 +11,15 @@ A javascript library for easing working with numeric values that have units asso
 
 ## Use in node (or with browserify / webpack etc)
 
-* `npm install unit-value`
-* `import UnitValue from 'unit-value';`
-* `const uv = new UnitValue(10, "px");`
+`npm install unit-value`
+
+```js
+const UnitValue = require("unit-value");
+const uv = new UnitValue(10, "px");
+console.log(uv.add(25).toString()); // prints "35px"
+```
+
+There is a small sample node script that can be run with `npm run sample`.
 
 ## Use in the browser
 
@@ -22,10 +28,49 @@ Currently there's no standalone build for browser use.
 This will probably be added in future, but there may be some namespacing changes to make for that.
 Also I feel the library is significantly more useful inside modules than in the browser.
 
+## Examples
+
+The API Reference Docs give a good sense of what is possible with the library, but here are some examples
+
+### Perform math on CSS values without separating the units and adding them back after
+
+```js
+element1.style.width = "100px";
+element2.style.width = UnitValue.parse(element1.style.width) // turn the existing css value string into a UnitValue
+  .subtract(30) // make it slightly smaller
+  .toString(); // returns "70px"
+```
+
+### Perform math using regular javascript operators, while using the friendly string for UI display
+
+```js
+const period = new UnitValue(10, "s"); // amount of time in seconds
+myUI.timePeriod = period.toString(); // "10s"
+
+// convert to milliseconds to have a repeating action every 10s
+const periodMs = period * 1000; // the js * operator uses `valueOf()` for the UnitValue object, and works normally
+setInterval(() => console.log("hello"), periodMs);
+```
+
+### Perform unit conversions, changing the units string at the same time as doing the calculation
+
+```js
+const length_us = "5 inches";
+const length_international = UnitValue.parse(length_us) // create a UnitValue from the original value
+  .multiply(2.54, "cm") // apply the conversion math and change the resulting units
+  .toString(); // return a string again - "2.54cm"
+```
+
 # Build
 
 `npm run lib` will run the source through Babel, producing a lib directory which can be consumed in a node.js environment (this is what the npm package is).
 
+# Test
+
+The library is fully test covered by `mocha`, with `chai` expect assertions. `nyc` assesses and reports on code coverage.
+
+Tests can be run with `npm test` but the library will need to be built first.
+
 # Documentation
 
 The code is documented with jsdoc comments.
@@ -44,6 +89,10 @@ Contributions are welcome. Just raise a PR.
 
 PR's are more likely to be considered in response to issues.
 
-The repo (and npm scripts) uses `eslint` and `prettier`, as well as providing a basic `editorconfig`, so it's pretty hard to not follow a consistent style (since prettier formats on commit).
+The repo (and npm scripts) uses `eslint` and `prettier`, as well as providing a basic `editorconfig`, so it's pretty hard to _not_ follow a consistent style (since prettier formats on commit).
+
+`npm lint` will run the linter, but it's recommended to use an editor that supports eslint, and prefereably prettier too. I use [Visual Studio Code](https://code.visualstudio.com).
+
+PRs should contain unit tests. Refer to the existing tests for style expectations. Preferably code coverage will be at 100% before a PR is accepted, unless there is a good reason for reduced coverage.
 
-Travis builds must pass on PR's, and these run eslint, so the linter will also keep code to the intended quality.
+Travis builds must pass on PR's, and these run eslint and unit tests, so the linter will also keep code to the intended quality, and tests must pass.

docs/UnitValue.html

@@ -3090,7 +3090,7 @@ <h5>Example</h5>
 <br class="clear">
 
 <footer>
-    Documentation generated at Fri Mar 30 2018 21:54:07 GMT+0100 (GMT Summer Time)
+    Documentation generated at Fri Mar 30 2018 22:41:43 GMT+0100 (GMT Summer Time)
 </footer>
 
 <script>prettyPrint();</script>

docs/external-parse-unit.html

@@ -140,7 +140,7 @@ <h2>
 <br class="clear">
 
 <footer>
-    Documentation generated at Fri Mar 30 2018 21:54:07 GMT+0100 (GMT Summer Time)
+    Documentation generated at Fri Mar 30 2018 22:41:43 GMT+0100 (GMT Summer Time)
 </footer>
 
 <script>prettyPrint();</script>

docs/externals.js.html

@@ -59,7 +59,7 @@ <h1 class="page-title">externals.js</h1>
 <br class="clear">
 
 <footer>
-    Documentation generated at Fri Mar 30 2018 21:54:07 GMT+0100 (GMT Summer Time)
+    Documentation generated at Fri Mar 30 2018 22:41:43 GMT+0100 (GMT Summer Time)
 </footer>
 
 <script>prettyPrint();</script>

docs/index.html

@@ -51,23 +51,40 @@ <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="UnitValue
 <p><a href="https://travis-ci.org/beforan/unit-value"><img src="https://travis-ci.org/beforan/unit-value.svg?branch=master" alt="Build Status"></a>
 <a href="https://coveralls.io/github/beforan/unit-value?branch=master"><img src="https://coveralls.io/repos/github/beforan/unit-value/badge.svg?branch=master" alt="Coverage Status"></a></p>
 <p>A javascript library for easing working with numeric values that have units associated with them.</p>
-<h1>Getting Started</h1><h2>Use in node (or with browserify / webpack etc)</h2><ul>
-<li><code>npm install unit-value</code></li>
-<li><code>import UnitValue from 'unit-value';</code></li>
-<li><code>const uv = new UnitValue(10, &quot;px&quot;);</code></li>
-</ul>
+<h1>Getting Started</h1><h2>Use in node (or with browserify / webpack etc)</h2><p><code>npm install unit-value</code></p>
+<pre class="prettyprint source lang-js"><code>const UnitValue = require(&quot;unit-value&quot;);
+const uv = new UnitValue(10, &quot;px&quot;);
+console.log(uv.add(25).toString()); // prints &quot;35px&quot;</code></pre><p>There is a small sample node script that can be run with <code>npm run sample</code>.</p>
 <h2>Use in the browser</h2><p>Currently there's no standalone build for browser use.</p>
 <p>This will probably be added in future, but there may be some namespacing changes to make for that.
 Also I feel the library is significantly more useful inside modules than in the browser.</p>
-<h1>Build</h1><p><code>npm run lib</code> will run the source through Babel, producing a lib directory which can be consumed in a node.js environment (this is what the npm package is).</p>
+<h2>Examples</h2><p>The API Reference Docs give a good sense of what is possible with the library, but here are some examples</p>
+<h3>Perform math on CSS values without separating the units and adding them back after</h3><pre class="prettyprint source lang-js"><code>element1.style.width = &quot;100px&quot;;
+element2.style.width = UnitValue
+    .parse(element1.style.width) // turn the existing css value string into a UnitValue
+    .subtract(30) // make it slightly smaller
+    .toString(); // returns &quot;70px&quot;</code></pre><h3>Perform math using regular javascript operators, while using the friendly string for UI display</h3><pre class="prettyprint source lang-js"><code>const period = new UnitValue(10, &quot;s&quot;); // amount of time in seconds
+myUI.timePeriod = period.toString() // &quot;10s&quot;
+
+// convert to milliseconds to have a repeating action every 10s
+const periodMs = period * 1000; // the js * operator uses `valueOf()` for the UnitValue object, and works normally
+setInterval(() => console.log(&quot;hello&quot;), periodMs);</code></pre><h3>Perform unit conversions, changing the units string at the same time as doing the calculation</h3><pre class="prettyprint source lang-js"><code>const length_us = &quot;5 inches&quot;;
+const length_international = UnitValue
+    .parse(length_us) // create a UnitValue from the original value
+    .multiply(2.54, &quot;cm&quot;) // apply the conversion math and change the resulting units
+    .toString(); // return a string again - &quot;2.54cm&quot;</code></pre><h1>Build</h1><p><code>npm run lib</code> will run the source through Babel, producing a lib directory which can be consumed in a node.js environment (this is what the npm package is).</p>
+<h1>Test</h1><p>The library is fully test covered by <code>mocha</code>, with <code>chai</code> expect assertions. <code>nyc</code> assesses and reports on code coverage.</p>
+<p>Tests can be run with <code>npm test</code> but the library will need to be built first.</p>
 <h1>Documentation</h1><p>The code is documented with jsdoc comments.</p>
 <p>The documentation for the latest stable code (<code>master</code> branch) is available online at <a href="https://beforan.github.io/unit-value/">https://beforan.github.io/unit-value/</a>.</p>
 <p>The documentation relevant to the commit you are looking at should always be present inside <code>/docs</code>, but you can always build the current docs for the code you're looking at by running <code>npm run docs</code>.</p>
 <h3>A note on pre-commit hooks</h3><p>Documentation is kept accurate and up-to-date through the use of a precommit hook. When you commit to git, the docs are automagically built and staged. Bear this in mind if commits appear to be taking longer than usual. If you encounter issues committing, ensure that all npm dev dependencies have been installed with <code>npm install</code>, and that you have <code>git</code> available in your <code>PATH</code>.</p>
 <h1>Contributing</h1><p>Contributions are welcome. Just raise a PR.</p>
 <p>PR's are more likely to be considered in response to issues.</p>
-<p>The repo (and npm scripts) uses <code>eslint</code> and <code>prettier</code>, as well as providing a basic <code>editorconfig</code>, so it's pretty hard to not follow a consistent style (since prettier formats on commit).</p>
-<p>Travis builds must pass on PR's, and these run eslint, so the linter will also keep code to the intended quality.</p></article>
+<p>The repo (and npm scripts) uses <code>eslint</code> and <code>prettier</code>, as well as providing a basic <code>editorconfig</code>, so it's pretty hard to <em>not</em> follow a consistent style (since prettier formats on commit).</p>
+<p><code>npm lint</code> will run the linter, but it's recommended to use an editor that supports eslint, and prefereably prettier too. I use <a href="https://code.visualstudio.com">Visual Studio Code</a>.</p>
+<p>PRs should contain unit tests. Refer to the existing tests for style expectations. Preferably code coverage will be at 100% before a PR is accepted, unless there is a good reason for reduced coverage.</p>
+<p>Travis builds must pass on PR's, and these run eslint and unit tests, so the linter will also keep code to the intended quality, and tests must pass.</p></article>
     </section>
 
 
@@ -80,7 +97,7 @@ <h1>Contributing</h1><p>Contributions are welcome. Just raise a PR.</p>
 <br class="clear">
 
 <footer>
-    Documentation generated at Fri Mar 30 2018 21:54:07 GMT+0100 (GMT Summer Time)
+    Documentation generated at Fri Mar 30 2018 22:41:43 GMT+0100 (GMT Summer Time)
 </footer>
 
 <script>prettyPrint();</script>

docs/unit-value.js.html

@@ -489,7 +489,7 @@ <h1 class="page-title">unit-value.js</h1>
 <br class="clear">
 
 <footer>
-    Documentation generated at Fri Mar 30 2018 21:54:07 GMT+0100 (GMT Summer Time)
+    Documentation generated at Fri Mar 30 2018 22:41:43 GMT+0100 (GMT Summer Time)
 </footer>
 
 <script>prettyPrint();</script>