/docs/jshashset.html
HTML | 325 lines | 323 code | 2 blank | 0 comment | 0 complexity | 43258e1d3ea3668e5e5ec1ce27ad6c60 MD5 | raw file
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3 <head> 4 <title>jshashset, a JavaScript implementation of HashSet</title> 5 <meta name="author" content="Tim Down - tim@timdown.co.uk"> 6 <meta name="keywords" content="hash, set, JavaScript, hashmap, hashset, hashtable, DHTML"> 7 <meta name="description" content="jshashtable, a JavaScript hash table implementation"> 8 <meta name="robots" content="all"> 9 <link rel="stylesheet" type="text/css" href="main.css" title="Default"> 10 </head> 11 <body> 12 <div id="container" class="nonav"> 13 <div id="header"> 14 <h1>jshashset 3.0</h1> 15 <div id="nav"> 16 <span class="navitem">home</span> 17 | <a class="navitem" href="http://code.google.com/p/jshashtable/downloads/list" 18 title="Download">download</a> 19 | <a class="navitem" href="http://www.timdown.co.uk/jshashtable">website</a> 20 | <a class="navitem" href="http://www.timdown.co.uk">timdown.co.uk</a> 21 </div> 22 </div> 23 <div id="content"> 24 <h1>jshashset 3.0</h1> 25 <div id="toc"> 26 <h2>Contents</h2> 27 <ul> 28 <li><a href="#intro">Introduction</a></li> 29 <li><a href="#setup">Set-up</a></li> 30 <li><a href="#usage">Usage</a></li> 31 <li><a href="#api">Public API</a></li> 32 </ul> 33 </div> 34 <div id="intro"> 35 <h2>Introduction</h2> 36 <p> 37 <span class="jsh">jshashset</span> is a JavaScript implementation of HashSet, as found in Java 38 or C#'s standard libraries. It depends on <a href="index.html">jshashtable</a> and uses the keys 39 of a <span class="jsh">jshashtable</span> hash table as the underlying set. 40 </p> 41 <p> 42 <span class="jsh">jshashset</span> was first included as a separate download for version 2.1 of 43 <span class="jsh">jshashtable</span> and is included with jshashtable from version 3.0. 44 </p> 45 <p class="linktotop"> 46 <a href="#container">Top</a> 47 </p> 48 </div> 49 <div id="setup"> 50 <h2>Set-up</h2> 51 <ol> 52 <li> 53 <h3>Download the code</h3> 54 <p> 55 <strong><a href="http://code.google.com/p/jshashtable/downloads/list" 56 title="Download">Download jshashset</a></strong>. 57 You can download a compressed or uncompressed version of <code>jshashset.js</code> 58 which are functionally identical or a zip containing compressed and uncompressed code 59 for both <span class="jsh">jshashtable</span> and <span class="jsh">jshashset</span> 60 plus documentation. 61 </p> 62 </li> 63 <li> 64 <h3>Include jshashtable and jshashset in your page</h3> 65 <p> 66 Include <code>jshashtable.js</code> and <code>jshashset.js</code> in that order in 67 script tags in your page. These files create two objects in the global scope, which are 68 <code>Hashtable</code> and <code>HashSet</code>. 69 </p> 70 </li> 71 <li> 72 <h3>Create your hash set</h3> 73 <p> 74 Create your hash set, as in the example below. Any non-null, non-undefined JavaScript 75 object can be used as member of the set. 76 </p> 77 <pre class="code"> 78<script type="text/javascript" src="jshashtable.js"></script> 79<script type="text/javascript" src="jshashset.js"></script> 80<script type="text/javascript"> 81 var dinosaurs = new HashSet(); 82 83 dinosaurs.add("Triceratops"); 84 dinosaurs.add("Diplodocus"); 85 dinosaurs.add("Stegosaurus"); 86 87 alert( dinosaurs.values.join(",") ); 88 /* Triceratops,Diplodocus,Stegosaurus */ 89</script> 90</pre> 91 </li> 92 </ol> 93 <p class="linktotop"> 94 <a href="#container">Top</a> 95 </p> 96 </div> 97 <div id="api"> 98 <h2>Public API</h2> 99 <h4>Constructors</h4> 100 <ul class="propertieslist"> 101 <li class="method"> 102 <div class="methodsignature"> 103 <code><strong>HashSet</strong>()</code> 104 </div> 105 <p> 106 Creates a new, empty hash set. 107 </p> 108 </li> 109 <li class="method"> 110 <div class="methodsignature"> 111 <code><strong>HashSet</strong>(Object <em>options</em>)</code> 112 </div> 113 <div class="summary"> 114 <p class="new">New in version 3.0</p> 115 <p> 116 Creates a new, empty hash set with the supplied options. 117 </p> 118 </div> 119 <div class="paramsheading">Option properties:</div> 120 <ul class="params"> 121 <li class="param"> 122 <code class="paramname">hashCode</code> 123 <div> 124 A function that provides hash codes for objects placed in the set. It is passed 125 the object to be hashed as its only parameter. If not provided, the set checks 126 whether the object has a <code>hashCode()</code> method, and if not, calls 127 <code>toString()</code> on the object. 128 </div> 129 </li> 130 <li class="param"> 131 <code class="paramname">equals</code> 132 <div> 133 <p> 134 A function that checks for equality between two objects with the same hash 135 code. If two objects that are considered equal then only one can be in the 136 set at any one time. 137 </p> 138 <p> 139 This function is passed the two objects to be compared as its parameters. If 140 not provided, the set checks whether either object being compared has an 141 <code>equals()</code> method, and if not, compares the objects using the 142 <code>===</code> operator. 143 </p> 144 </div> 145 </li> 146 <li class="param"> 147 <code class="paramname">replaceDuplicateKey</code> 148 <p class="new">New in version 3.0</p> 149 <p> 150 Controls what happens when <code>add()</code> is called with an object that is 151 equal to an existing object in the set. If <code>replaceDuplicateKey</code> is 152 <code>true</code>, the existing key is always replaced by the new key. 153 Otherwise, the existing key is left in place (which is what always happened 154 prior to version 3.0). The default is <code>true</code>; prior to version 3.0. 155 </p> 156 </li> 157 </ul> 158 </li> 159 <li class="method"> 160 <div class="methodsignature"> 161 <code><strong>HashSet</strong>(Function <em>hashingFunction</em>, Function 162 <em>equalityFunction</em>)</code> 163 </div> 164 <p class="summary"> 165 Creates a new, empty hash set with the supplied hashing function and equality 166 function. This form maintains backwards compatibility with versions prior to 3.0. 167 The following line 168 </p> 169 <pre class="code"> 170var set = new HashSet(hashingFunction, equalityFunction); 171</pre> 172 <p>... is equivalent to</p> 173 <pre class="code"> 174var set = new HashSet( { hashCode: hashingFunction, equals: equalityFunction } ); 175</pre> 176 <div class="paramsheading">Parameters:</div> 177 <ul class="params"> 178 <li class="param"> 179 <code class="paramname">hashingFunction</code> 180 <p>See above.</p> 181 </li> 182 <li class="param"> 183 <code class="paramname">equalityFunction</code> 184 <p>See above.</p> 185 </li> 186 </ul> 187 </li> 188 </ul> 189 <h4>Methods</h4> 190 <ul class="propertieslist"> 191 <li class="method" id="put"> 192 <div class="methodsignature"><code>void <strong>add</strong>(mixed 193 <em>value</em>)</code></div> 194 <div class="summary"> 195 Adds the specified object or primitive to the set. <code>value</code> replaces any 196 member of the set equal to it, unless <code>replaceDuplicateKey</code> was set to 197 <code>false</code> in the constructor. 198 </div> 199 </li> 200 <li class="method"> 201 <div class="methodsignature"><code>void <strong>addAll</strong>(Array 202 <em>arr</em>)</code></div> 203 <div class="summary"> 204 Adds all members of an array <code>arr</code> to the set in order. Each member of 205 <code>arr</code> replaces any member of the set equal to it, unless 206 <code>replaceDuplicateKey</code> was set to <code>false</code> in the constructor, in 207 which case the original value is left in place. 208 </div> 209 </li> 210 <li class="method"> 211 <div class="methodsignature"><code>Array <strong>values</strong>()</code></div> 212 <div class="summary"> 213 <p> 214 Returns an array containing all the members of the set in unspecified order. 215 </p> 216 </div> 217 </li> 218 <li class="method"> 219 <div class="methodsignature"><code>void <strong>remove</strong>(mixed 220 <em>key</em>)</code></div> 221 <div class="summary"> 222 <p> 223 Removes the specified value from the set. 224 </p> 225 </div> 226 </li> 227 <li class="method"> 228 <div class="methodsignature"><code>Boolean <strong>contains</strong>(mixed 229 <em>value</em>)</code></div> 230 <div class="summary"> 231 <p> 232 Returns whether the set contains the specified value. 233 </p> 234 </div> 235 </li> 236 <li class="method"> 237 <div class="methodsignature"><code>void <strong>clear</strong>()</code></div> 238 <div class="summary"> 239 <p> 240 Removes all members from the set. 241 </p> 242 </div> 243 </li> 244 <li class="method"> 245 <div class="methodsignature"><code>Number <strong>size</strong>()</code></div> 246 <div class="summary"> 247 <p> 248 Returns the number of members contained in the set. 249 </p> 250 </div> 251 </li> 252 <li class="method"> 253 <div class="methodsignature"><code>Boolean <strong>isEmpty</strong>()</code></div> 254 <div class="summary"> 255 <p> 256 Returns <code>true</code> if the set contains no members, <code>false</code> 257 otherwise. 258 </p> 259 </div> 260 </li> 261 <li class="method"> 262 <div class="methodsignature"><code>Boolean <strong>isSubsetOf</strong>(HashSet 263 <em>set</em>)</code></div> 264 <div class="summary"> 265 <p> 266 Returns <code>true</code> if every member this set is also a member of 267 <code>set</code>, <code>false</code> otherwise. 268 </p> 269 </div> 270 </li> 271 <li class="method"> 272 <div class="methodsignature"><code>HashSet <strong>clone</strong>()</code></div> 273 <div class="summary"> 274 <p> 275 Creates and returns a shallow copy of the set, using the same options provided to 276 the set when it was constructed. 277 </p> 278 </div> 279 </li> 280 <li class="method"> 281 <div class="methodsignature"><code>HashSet <strong>intersection</strong>(HashSet 282 <em>set</em>)</code></div> 283 <div class="summary"> 284 <p> 285 Creates and returns a new <code>HashSet</code> containing only those elements that 286 are contained in both this set and <code>set</code>. 287 </p> 288 </div> 289 </li> 290 <li class="method"> 291 <div class="methodsignature"><code>HashSet <strong>union</strong>(HashSet 292 <em>set</em>)</code></div> 293 <div class="summary"> 294 <p> 295 Creates and returns a new <code>HashSet</code> containing those elements that are 296 contained either of or both this set and <code>set</code>. 297 </p> 298 </div> 299 </li> 300 <li class="method"> 301 <div class="methodsignature"><code>HashSet <strong>complement</strong>(HashSet 302 <em>set</em>)</code></div> 303 <div class="summary"> 304 <p> 305 Creates and returns a new <code>HashSet</code> containing those elements that are 306 contained in this set but not <code>set</code>. 307 </p> 308 </div> 309 </li> 310 </ul> 311 <p class="linktotop"> 312 <a href="#container">Top</a> 313 </p> 314 </div> 315 </div> 316 <div id="footer"> 317 Written by Tim Down. <a href="mailto:tim@timdown.co.uk">tim@timdown.co.uk</a> 318 <br> 319 <span class="jsh">jshashtable</span> is distributed under the 320 <a href="http://www.apache.org/licenses/LICENSE-2.0.html" title="Apache License, Version 2.0">Apache 321 License, Version 2.0</a> 322 </div> 323 </div> 324 </body> 325</html>