Fixed Documentation

mootable · May 17, 2021 · fed347f · fed347f
1 parent 9a4d9ba
commit fed347f
Show file tree

Hide file tree

Showing 21 changed files with 650 additions and 558 deletions.
diff --git a/.gradle/6.8/executionHistory/executionHistory.lock b/.gradle/6.8/executionHistory/executionHistory.lock
diff --git a/.gradle/6.8/fileChanges/last-build.bin b/.gradle/6.8/fileChanges/last-build.bin
diff --git a/.gradle/6.8/fileHashes/fileHashes.lock b/.gradle/6.8/fileHashes/fileHashes.lock
diff --git a/.gradle/6.8/gc.properties b/.gradle/6.8/gc.properties
diff --git a/.gradle/buildOutputCleanup/buildOutputCleanup.lock b/.gradle/buildOutputCleanup/buildOutputCleanup.lock
diff --git a/.gradle/buildOutputCleanup/cache.properties b/.gradle/buildOutputCleanup/cache.properties
@@ -0,0 +1,2 @@
+#Mon May 17 23:00:44 BST 2021
+gradle.version=6.8
diff --git a/.gradle/checksums/checksums.lock b/.gradle/checksums/checksums.lock
diff --git a/.gradle/configuration-cache/gc.properties b/.gradle/configuration-cache/gc.properties
diff --git a/.gradle/vcs-1/gc.properties b/.gradle/vcs-1/gc.properties
diff --git a/API.md b/API.md
@@ -692,8 +692,8 @@ Find a value
 
 ```javascript
 const hashmap = new HashMap([[1,'value1'],[2,'value2'],[3,'value3']]);
-const findResult = hashmap.find((value) => value.endsWith('ue2'));
-// findResult === 'value2'
+const findResult = hashmap.find((value) => value.startsWith('val'));
+// findResult === 'value1'
 ```
 
 Can't find a value
@@ -710,11 +710,13 @@ Returns **any** the value of the element that matches.
 
 *   **See**: [Array.find](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find)
 
-Find the first value in the map which passes the provided <code>MatchesPredicate</code>.
+Find the last value in the map which passes the provided <code>MatchesPredicate</code>.
 
-*   return the first <code>value</code> from the <code>\[key,value]</code> pair that matches
+*   return the last <code>value</code> from the <code>\[key,value]</code> pair that matches
 *   if no elements match, it returns undefined.
-*   if no predicate is defined, will return the first value it finds.
+*   if no predicate is defined, will return the last value it finds. (It does this by iterating over the hashmap in reverse, and returning the first
+
+item that matches)
 
 ##### Parameters
 
@@ -723,20 +725,20 @@ Find the first value in the map which passes the provided <code>MatchesPredicate
 
 ##### Examples
 
-Find a value
+Find the last value
 
 ```javascript
 const hashmap = new HashMap([[1,'value1'],[2,'value2'],[3,'value3']]);
-const findResult = hashmap.find((value) => value.endsWith('ue2'));
-// findResult === 'value2'
+const findLastResult = hashmap.findLast((value) => value.startsWith('val'));
+// findLastResult === 'value3'
 ```
 
 Can't find a value
 
 ```javascript
 const hashmap = new HashMap([[1,'value1'],[2,'value2'],[3,'value3']]);
-const findResult = hashmap.find((value) => value.startsWith('something'));
-// findResult === undefined
+const findLastResult = hashmap.findLast((value) => value.startsWith('something'));
+// findLastResult === undefined
 ```
 
 Returns **any** the value of the element that matches.
@@ -749,8 +751,8 @@ Returns **any** the value of the element that matches.
 
 Find the first value in the map which passes the provided <code>MatchesPredicate</code>.
 
-*   return the first <code>value</code> from the <code>\[key,value]</code> pair that matches
-*   if no elements match, it returns undefined.
+*   return the first <code>value</code> from the <code>\[key,value]</code> pair that matches, wrapped in an Option
+*   if no elements match, it returns none.
 *   if no predicate is defined, will return the first value it finds.
 
 ##### Parameters
@@ -764,31 +766,34 @@ Find a value
 
 ```javascript
 const hashmap = new HashMap([[1,'value1'],[2,'value2'],[3,'value3']]);
-const findResult = hashmap.find((value) => value.endsWith('ue2'));
-// findResult === 'value2'
+const optionalFindResult = hashmap.optionalFind((value) => value.startsWith('val'));
+// optionalFindResult.value === 'value1'
+// optionalFindResult.has === true
 ```
 
 Can't find a value
 
 ```javascript
 const hashmap = new HashMap([[1,'value1'],[2,'value2'],[3,'value3']]);
-const findResult = hashmap.find((value) => value.startsWith('something'));
-// findResult === undefined
+const optionalFindResult = hashmap.optionalFind((value) => value.startsWith('something'));
+// optionalFindResult.has === false
 ```
 
-Returns **any** the value of the element that matches.
+Returns **([Option](#option)\<any> | [Option.none](#optionnone))** the value of the element that matches.
 
 #### optionalFindLast
 
 *   **See**: [Option.some](#optionsome)
 *   **See**: [Option.none](#optionnone)
 *   **See**: [Array.find](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find)
 
-Find the first value in the map which passes the provided <code>MatchesPredicate</code>.
+Find the last value in the map which passes the provided <code>MatchesPredicate</code>.
 
-*   return the first <code>value</code> from the <code>\[key,value]</code> pair that matches
-*   if no elements match, it returns undefined.
-*   if no predicate is defined, will return the first value it finds.
+*   return the last <code>value</code> from the <code>\[key,value]</code> pair that matches, wrapped in an Option
+*   if no elements match, it returns none.
+*   if no predicate is defined, will return the last value it finds. (It does this by iterating over the hashmap in reverse, and returning the first
+
+item that matches)
 
 ##### Parameters
 
@@ -801,25 +806,26 @@ Find a value
 
 ```javascript
 const hashmap = new HashMap([[1,'value1'],[2,'value2'],[3,'value3']]);
-const findResult = hashmap.find((value) => value.endsWith('ue2'));
-// findResult === 'value2'
+const optionalFindLastResult = hashmap.optionalFindLast((value) => value.startsWith('val'));
+// optionalFindLastResult.value === 'value3'
+// optionalFindLastResult.has === true
 ```
 
 Can't find a value
 
 ```javascript
 const hashmap = new HashMap([[1,'value1'],[2,'value2'],[3,'value3']]);
-const findResult = hashmap.find((value) => value.startsWith('something'));
-// findResult === undefined
+const optionalFindLastResult = hashmap.optionalFindLast((value) => value.startsWith('something'));
+// optionalFindLastResult.has === false
 ```
 
-Returns **any** the value of the element that matches.
+Returns **([Option](#option)\<any> | [Option.none](#optionnone))** the value of the element that matches.
 
 #### findKey
 
 *   **See**: [Array.findIndex](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex)
 
-Find the first value in the key which passes the provided  <code>MatchesPredicate</code>.
+Find the first key in the map which passes the provided  <code>MatchesPredicate</code>.
 
 *   return the first <code>key</code> from the <code>\[key,value]</code> pair that matches
 *   if no elements match, it returns undefined.
@@ -836,16 +842,16 @@ Find a key
 
 ```javascript
 const hashmap = new HashMap([[1,'value1'],[2,'value2'],[3,'value3']]);
-const findIndexResult = hashmap.findIndex((value) => value.endsWith('ue2'));
-// findIndexResult === 2
+const findKeyResult = hashmap.findKey((value) => value.startsWith('val'));
+// findKeyResult === 1
 ```
 
 Can't find a key
 
 ```javascript
 const hashmap = new HashMap([[1,'value1'],[2,'value2'],[3,'value3']]);
-const findIndexResult = hashmap.findIndex((value) => value.startsWith('something'));
-// findIndexResult === undefined
+const findKeyResult = hashmap.findKey((value) => value.startsWith('something'));
+// findKeyResult === undefined
 ```
 
 Returns **any** the key of the element that matches..
@@ -854,11 +860,13 @@ Returns **any** the key of the element that matches..
 
 *   **See**: [Array.prototype.findIndex](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex)
 
-Find the first value in the key which passes the provided  <code>MatchesPredicate</code>.
+Find the last key in the map which passes the provided <code>MatchesPredicate</code>.
 
-*   return the first <code>key</code> from the <code>\[key,value]</code> pair that matches
+*   return the last <code>key</code> from the <code>\[key,value]</code> pair that matches
 *   if no elements match, it returns undefined.
-*   if no predicate is defined, will return the first key it finds.
+*   if no predicate is defined, will return the last key it finds. (It does this by iterating over the hashmap in reverse, and returning the first
+
+item that matches)
 
 ##### Parameters
 
@@ -871,16 +879,16 @@ Find a key
 
 ```javascript
 const hashmap = new HashMap([[1,'value1'],[2,'value2'],[3,'value3']]);
-const findIndexResult = hashmap.findIndex((value) => value.endsWith('ue2'));
-// findIndexResult === 2
+const findLastKeyResult = hashmap.findLastKey((value) => value.startsWith('val'));
+// findLastKeyResult === 3
 ```
 
 Can't find a key
 
 ```javascript
 const hashmap = new HashMap([[1,'value1'],[2,'value2'],[3,'value3']]);
-const findIndexResult = hashmap.findIndex((value) => value.startsWith('something'));
-// findIndexResult === undefined
+const findLastKeyResult = hashmap.findLastKey((value) => value.startsWith('something'));
+// findLastKeyResult === undefined
 ```
 
 Returns **any** the key of the element that matches..
@@ -891,10 +899,10 @@ Returns **any** the key of the element that matches..
 *   **See**: [Option.none](#optionnone)
 *   **See**: [Array.prototype.findIndex](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex)
 
-Find the first value in the key which passes the provided  <code>MatchesPredicate</code>.
+Find the first key in the map which passes the provided <code>MatchesPredicate</code>.
 
-*   return the first <code>key</code> from the <code>\[key,value]</code> pair that matches
-*   if no elements match, it returns undefined.
+*   return the first <code>key</code> from the <code>\[key,value]</code> pair that matches, wrapped in an Option
+*   if no elements match, it returns none.
 *   if no predicate is defined, will return the first key it finds.
 
 ##### Parameters
@@ -908,31 +916,34 @@ Find a key
 
 ```javascript
 const hashmap = new HashMap([[1,'value1'],[2,'value2'],[3,'value3']]);
-const findIndexResult = hashmap.findIndex((value) => value.endsWith('ue2'));
-// findIndexResult === 2
+const optionalFindKeyResult = hashmap.optionalFindKey((value) => value.startsWith('val'));
+// optionalFindKeyResult.value === 1
+// optionalFindKeyResult.has === true
 ```
 
 Can't find a key
 
 ```javascript
 const hashmap = new HashMap([[1,'value1'],[2,'value2'],[3,'value3']]);
-const findIndexResult = hashmap.findIndex((value) => value.startsWith('something'));
-// findIndexResult === undefined
+const optionalFindKeyResult = hashmap.optionalFindKey((value) => value.startsWith('something'));
+// optionalFindKeyResult.has === false
 ```
 
-Returns **any** the key of the element that matches..
+Returns **([Option](#option)\<any> | [Option.none](#optionnone))** the key of the element that matches.
 
 #### optionalFindLastKey
 
 *   **See**: [Option.some](#optionsome)
 *   **See**: [Option.none](#optionnone)
 *   **See**: [Array.prototype.findIndex](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex)
 
-Find the first value in the key which passes the provided  <code>MatchesPredicate</code>.
+Find the last key in the map which passes the provided <code>MatchesPredicate</code>.
 
-*   return the first <code>key</code> from the <code>\[key,value]</code> pair that matches
-*   if no elements match, it returns undefined.
-*   if no predicate is defined, will return the first key it finds.
+*   return the last <code>key</code> from the <code>\[key,value]</code> pair that matches, wrapped in an Option
+*   if no elements match, it returns none.
+*   if no predicate is defined, will return the last key it finds. (It does this by iterating over the hashmap in reverse, and returning the first
+
+item that matches)
 
 ##### Parameters
 
@@ -945,26 +956,31 @@ Find a key
 
 ```javascript
 const hashmap = new HashMap([[1,'value1'],[2,'value2'],[3,'value3']]);
-const findIndexResult = hashmap.findIndex((value) => value.endsWith('ue2'));
-// findIndexResult === 2
+const optionalFindLastKeyResult = hashmap.optionalFindLastKey(value) => value.startsWith('val'));
+// optionalFindLastKeyResult.value === 3
+// optionalFindLastKeyResult.has === true
 ```
 
 Can't find a key
 
 ```javascript
 const hashmap = new HashMap([[1,'value1'],[2,'value2'],[3,'value3']]);
-const findIndexResult = hashmap.findIndex((value) => value.startsWith('something'));
-// findIndexResult === undefined
+const optionalFindLastKeyResult = hashmap.optionalFindLastKey((value) => value.startsWith('something'));
+// optionalFindLastKeyResult.has === false
 ```
 
-Returns **any** the key of the element that matches..
+Returns **([Option](#option)\<any> | [Option.none](#optionnone))** the key of the element that matches.
 
 #### set
 
 *   **See**: [Map.prototype.set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/set)
 
 Sets a value onto this map, using the key as its reference.
 
+*   If the key already exists, this will overwrite the value with the new value.
+*   If it doesn't exist it adds the new key value pair to the map.
+*   NB: Ordering in a HashMap is not defined by insertion order (much), but by hash value (mostly).
+
 ##### Parameters
 
 *   `key` **any** the key we want to key our value to
@@ -1335,7 +1351,7 @@ Test to see if ALL elements pass the test implemented by the passed <code>Matche
 
 ##### Examples
 
-Do all values start with value. (yes)
+Do all values start with 'value'. (yes)
 
 ```javascript
 const hashmap = new HashMap([[1,'value1'],[2,'value2'],[3,'value3']]);

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,9 +1,12 @@
 # Changelog
 ## Current
+## 1.0.5
+- Updated Dev Dependencies.
+- Added more documentation.
 ## 1.0.4
 Added badges
 ## 1.0.3
-- Removed JSDoc which had an underlying dependancy (underscore) which had a security vulnerability, as it is a dev dependancy, there is no additional risk to projects that depend on @mootable/hashmap.
+- Removed JSDoc which had an underlying dependency (underscore) which had a security vulnerability, as it is a dev dependency, there is no additional risk to projects that depend on @mootable/hashmap.
 - Replaced with Documentation.js
   - Built a Mootable theme.
 - Fixed up a load of the ReadMe and Documentation pages.