11"use strict" ;
2+ /**
3+ * @author Jacoby Johnson
4+ * @file src/common/Set2D.ts
5+ * @package jsutil
6+ * @github https://www.github.com/cobyj33/jsutil
7+ * @description A Set implementation to hold a unique set of 2D vector
8+ * values that can easily be queried for existence and iterated over
9+ * @version 0.1.0
10+ * @date 2023-4-09
11+ */
212Object . defineProperty ( exports , "__esModule" , { value : true } ) ;
313exports . Set2D = void 0 ;
14+ /**
15+ * A Set implementation to quickly and reliably hold a unique set of 2D vector
16+ * values that can easily be queried for existence and iterated over
17+ */
418class Set2D {
519 constructor ( values = [ ] ) {
20+ /**
21+ * @brief This map internally holds all of the data to query into the Set2D.
22+ *
23+ * @summary It consists of a key which represents the first component of a 2-dimensional vector,
24+ * with a set of number values which represent any second component values associated with the given first component
25+ */
626 this . map = new Map ( ) ;
727 this . _length = 0 ;
8- if ( Array . isArray ( values ) ) {
9- values . forEach ( value => this . add ( value [ 0 ] , value [ 1 ] ) ) ;
28+ values . forEach ( value => this . add ( value [ 0 ] , value [ 1 ] ) ) ;
29+ }
30+ /**
31+ * Clear all data within this Set2D instance.
32+ *
33+ * @param total An optional parameter on whether to totally clear the allocated internal data
34+ * structures used in the Set2D or not. Defaults to false. Note that whether this "total" parameter
35+ * is false or true does not affect this function's purpose: This function will always remove all 2D
36+ * vectors present in this Set2D instance. However, users can choose whether to reallocate storage containers
37+ * within the Set2D instance with the "total" parameter
38+ */
39+ clear ( total = false ) {
40+ if ( total ) {
41+ this . map = new Map ( ) ;
1042 }
1143 else {
12- values . forEach ( ( [ first , second ] ) => this . add ( first , second ) ) ;
44+ [ ... this . map . values ( ) ] . forEach ( set => set . clear ( ) ) ;
1345 }
14- }
15- fullClear ( ) {
16- this . map = new Map ( ) ;
17- this . _length = 0 ;
18- }
19- clear ( ) {
20- [ ...this . map . values ( ) ] . forEach ( set => set . clear ( ) ) ;
2146 this . _length = 0 ;
2247 }
48+ /**
49+ * @brief The number of unique 2D vectors stored in this Set2D instance
50+ * This number cannot be set by the user. It is instead changed by the
51+ * Set2D class internally among additions and removals.
52+ */
2353 get length ( ) { return this . _length ; }
24- static fromNumberMatrix ( values ) {
25- const set = new Set2D ( ) ;
26- for ( let row = 0 ; row < values . length ; row ++ ) {
27- for ( let col = 0 ; col < values [ row ] . length ; col ++ ) {
28- if ( values [ row ] [ col ] === 1 ) {
29- set . add ( row , col ) ;
30- }
31- }
32- }
33- return set ;
34- }
54+ /**
55+ * @returns An array of 2D tuples in the form {[number, number]} of the unique
56+ * 2D vectors present in this Set2D instance
57+ */
3558 getTuples ( ) {
3659 const arr = new Array ( this . length ) ;
3760 let i = 0 ;
@@ -41,9 +64,27 @@ class Set2D {
4164 } ) ;
4265 return arr ;
4366 }
67+ /**
68+ * Perform a callback function for every vector present in t
69+ *
70+ * @note The ordering of the calls to the forEach function should not be assumed and is not
71+ * guaranteed to stay the same between different versions of jsutil.
72+ *
73+ * @param callbackfn The callback function to be performed on each 2D vector in this Set2D instance. The
74+ * callback function will be passed a 2D vector in the form of {[number, number]}.
75+ */
4476 forEach ( callbackfn ) {
4577 this . map . forEach ( ( set , first ) => set . forEach ( second => callbackfn ( [ first , second ] ) ) ) ;
4678 }
79+ /**
80+ * Add a 2D vector to this Set2D instance
81+ *
82+ * If the given 2D vector is already present in this Set2D instance
83+ * the vector will NOT be added to the Set2D and the Set2D instance will not change
84+ *
85+ * @param first The first component of the 2D vector to add
86+ * @param second The second component of the 2D vector to add
87+ */
4788 add ( first , second ) {
4889 var _a , _b ;
4990 if ( ( ( _a = this . map . get ( first ) ) === null || _a === void 0 ? void 0 : _a . has ( second ) ) === false ) {
@@ -55,43 +96,105 @@ class Set2D {
5596 this . _length += 1 ;
5697 }
5798 }
99+ /**
100+ * Remove a 2D vector to this Set2D instance
101+ *
102+ * If the given 2D vector is not present in this Set2D instance, then
103+ * the Set2D instance will not change and this function will do nothing
104+ *
105+ * @param first The first component of the 2D vector to remove
106+ * @param second The second component of the 2D vector to remove
107+ */
58108 remove ( first , second ) {
59109 let set ;
60110 if ( set = this . map . get ( first ) ) {
61111 if ( set . has ( second ) ) {
62112 set . delete ( second ) ;
63113 this . _length -= 1 ;
64- // if (set.size === 0) {
65- // this.map.delete(first)
66- // }
114+ if ( set . size === 0 ) {
115+ this . map . delete ( first ) ;
116+ }
67117 }
68118 }
69119 }
120+ /**
121+ * Check whether this Set2D instance contains a given 2D vector.
122+ *
123+ * @param first The first component of the 2D Vector to check
124+ * @param second The second component of the 2D Vector to check
125+ * @returns Whether the given 2D vector is present in this Set2D instance
126+ */
70127 has ( first , second ) {
71128 var _a ;
72129 return ( ( _a = this . map . get ( first ) ) === null || _a === void 0 ? void 0 : _a . has ( second ) ) || false ;
73130 }
131+ /**
132+ * Check whether this Set2D instance contains all of the given 2D vectors in a list.
133+ *
134+ * @param tuples The 2D vectors to check for existence in this Set2D instance
135+ * @returns Whether all given 2D vectos are present in this Set2D instance
136+ */
74137 hasAll ( tuples ) {
75138 return tuples . every ( tuple => this . has ( tuple [ 0 ] , tuple [ 1 ] ) ) ;
76139 }
140+ /**
141+ * Check whether this Set2D instance contains all and ONLY all of the given 2D vectors in a list.
142+ *
143+ * @param tuples The 2D vectors to check for existence in this Set2D instance
144+ * @returns Whether all given 2D vectos are present in this Set2D instance,
145+ */
77146 hasAllExact ( tuples ) {
78147 return tuples . length === this . length && this . hasAll ( tuples ) ;
79148 }
149+ /**
150+ * Combine this Set2D with other Set2D's and/or 2D vector arrays
151+ *
152+ * Similar to the concat function in Javascript Arrays
153+ *
154+ * Note that this Set2D instance will NOT be modified by the "combine" function. In order to push 2D vector data and
155+ * modify this Set2D instance in-place, use the "push" function.
156+ *
157+ * @param others Variable arguments. Other Set2D's or 2D vector arrays
158+ * @returns A new Set2D instance created by combining 2D vectors present in this Set2D instance,
159+ * given Set2D instances, and given 2D vector arrays
160+ */
80161 combine ( ...others ) {
81162 const set = new Set2D ( ) ;
82163 set . push ( this , ...others ) ;
83164 return set ;
84165 }
166+ /**
167+ * Push 2D vector values into this Set2D instance
168+ *
169+ * Similar to the push function in Javascript Arrays
170+ *
171+ * Note that this Set2D instance will be modified by pushing data. In order to create a new Set2D instance
172+ * with combined data without modifying this Set2D instance in-place, use the "combine" function.
173+ *
174+ * @param others Variable argument parameter, where other Set2D's or arrays of 2D vectors can be pushed into this Set2D instance.
175+ * Each given vector is added to this Set2D instance.
176+ */
85177 push ( ...others ) {
86- others . forEach ( other => other . forEach ( tuple => this . add ( tuple [ 0 ] , tuple [ 1 ] ) ) ) ;
178+ others . forEach ( other => Array . isArray ( other ) ? this . add ( other [ 0 ] , other [ 1 ] ) : other . forEach ( tuple => this . add ( tuple [ 0 ] , tuple [ 1 ] ) ) ) ;
87179 }
180+ /**
181+ * Iterator integration for "for ... of " syntax
182+ */
88183 * [ Symbol . iterator ] ( ) {
89184 for ( const pair of this . map ) {
90185 for ( const second of pair [ 1 ] ) {
91186 yield [ pair [ 0 ] , second ] ;
92187 }
93188 }
94189 }
190+ /**
191+ * Check whether 2 Set2D instances are equal
192+ *
193+ * 2 Set2D instances are considered "equal" if they have the same stored vectors present within
194+ *
195+ * @param other The other Set2D instance to check equality with
196+ * @returns Whether the two Set2D instances are equal according to the stated conditions.
197+ */
95198 equals ( other ) {
96199 if ( this . length !== other . length ) {
97200 return false ;
0 commit comments