/docs/jshashset.html

http://jshashtable.googlecode.com/ · 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. &lt;script type="text/javascript" src="jshashtable.js"&gt;&lt;/script&gt;
  79. &lt;script type="text/javascript" src="jshashset.js"&gt;&lt;/script&gt;
  80. &lt;script type="text/javascript"&gt;
  81. var dinosaurs = new HashSet();
  82. dinosaurs.add("Triceratops");
  83. dinosaurs.add("Diplodocus");
  84. dinosaurs.add("Stegosaurus");
  85. alert( dinosaurs.values.join(",") );
  86. /* Triceratops,Diplodocus,Stegosaurus */
  87. &lt;/script&gt;
  88. </pre>
  89. </li>
  90. </ol>
  91. <p class="linktotop">
  92. <a href="#container">Top</a>
  93. </p>
  94. </div>
  95. <div id="api">
  96. <h2>Public API</h2>
  97. <h4>Constructors</h4>
  98. <ul class="propertieslist">
  99. <li class="method">
  100. <div class="methodsignature">
  101. <code><strong>HashSet</strong>()</code>
  102. </div>
  103. <p>
  104. Creates a new, empty hash set.
  105. </p>
  106. </li>
  107. <li class="method">
  108. <div class="methodsignature">
  109. <code><strong>HashSet</strong>(Object <em>options</em>)</code>
  110. </div>
  111. <div class="summary">
  112. <p class="new">New in version 3.0</p>
  113. <p>
  114. Creates a new, empty hash set with the supplied options.
  115. </p>
  116. </div>
  117. <div class="paramsheading">Option properties:</div>
  118. <ul class="params">
  119. <li class="param">
  120. <code class="paramname">hashCode</code>
  121. <div>
  122. A function that provides hash codes for objects placed in the set. It is passed
  123. the object to be hashed as its only parameter. If not provided, the set checks
  124. whether the object has a <code>hashCode()</code> method, and if not, calls
  125. <code>toString()</code> on the object.
  126. </div>
  127. </li>
  128. <li class="param">
  129. <code class="paramname">equals</code>
  130. <div>
  131. <p>
  132. A function that checks for equality between two objects with the same hash
  133. code. If two objects that are considered equal then only one can be in the
  134. set at any one time.
  135. </p>
  136. <p>
  137. This function is passed the two objects to be compared as its parameters. If
  138. not provided, the set checks whether either object being compared has an
  139. <code>equals()</code> method, and if not, compares the objects using the
  140. <code>===</code> operator.
  141. </p>
  142. </div>
  143. </li>
  144. <li class="param">
  145. <code class="paramname">replaceDuplicateKey</code>
  146. <p class="new">New in version 3.0</p>
  147. <p>
  148. Controls what happens when <code>add()</code> is called with an object that is
  149. equal to an existing object in the set. If <code>replaceDuplicateKey</code> is
  150. <code>true</code>, the existing key is always replaced by the new key.
  151. Otherwise, the existing key is left in place (which is what always happened
  152. prior to version 3.0). The default is <code>true</code>; prior to version 3.0.
  153. </p>
  154. </li>
  155. </ul>
  156. </li>
  157. <li class="method">
  158. <div class="methodsignature">
  159. <code><strong>HashSet</strong>(Function <em>hashingFunction</em>, Function
  160. <em>equalityFunction</em>)</code>
  161. </div>
  162. <p class="summary">
  163. Creates a new, empty hash set with the supplied hashing function and equality
  164. function. This form maintains backwards compatibility with versions prior to 3.0.
  165. The following line
  166. </p>
  167. <pre class="code">
  168. var set = new HashSet(hashingFunction, equalityFunction);
  169. </pre>
  170. <p>... is equivalent to</p>
  171. <pre class="code">
  172. var set = new HashSet( { hashCode: hashingFunction, equals: equalityFunction } );
  173. </pre>
  174. <div class="paramsheading">Parameters:</div>
  175. <ul class="params">
  176. <li class="param">
  177. <code class="paramname">hashingFunction</code>
  178. <p>See above.</p>
  179. </li>
  180. <li class="param">
  181. <code class="paramname">equalityFunction</code>
  182. <p>See above.</p>
  183. </li>
  184. </ul>
  185. </li>
  186. </ul>
  187. <h4>Methods</h4>
  188. <ul class="propertieslist">
  189. <li class="method" id="put">
  190. <div class="methodsignature"><code>void <strong>add</strong>(mixed
  191. <em>value</em>)</code></div>
  192. <div class="summary">
  193. Adds the specified object or primitive to the set. <code>value</code> replaces any
  194. member of the set equal to it, unless <code>replaceDuplicateKey</code> was set to
  195. <code>false</code> in the constructor.
  196. </div>
  197. </li>
  198. <li class="method">
  199. <div class="methodsignature"><code>void <strong>addAll</strong>(Array
  200. <em>arr</em>)</code></div>
  201. <div class="summary">
  202. Adds all members of an array <code>arr</code> to the set in order. Each member of
  203. <code>arr</code> replaces any member of the set equal to it, unless
  204. <code>replaceDuplicateKey</code> was set to <code>false</code> in the constructor, in
  205. which case the original value is left in place.
  206. </div>
  207. </li>
  208. <li class="method">
  209. <div class="methodsignature"><code>Array <strong>values</strong>()</code></div>
  210. <div class="summary">
  211. <p>
  212. Returns an array containing all the members of the set in unspecified order.
  213. </p>
  214. </div>
  215. </li>
  216. <li class="method">
  217. <div class="methodsignature"><code>void <strong>remove</strong>(mixed
  218. <em>key</em>)</code></div>
  219. <div class="summary">
  220. <p>
  221. Removes the specified value from the set.
  222. </p>
  223. </div>
  224. </li>
  225. <li class="method">
  226. <div class="methodsignature"><code>Boolean <strong>contains</strong>(mixed
  227. <em>value</em>)</code></div>
  228. <div class="summary">
  229. <p>
  230. Returns whether the set contains the specified value.
  231. </p>
  232. </div>
  233. </li>
  234. <li class="method">
  235. <div class="methodsignature"><code>void <strong>clear</strong>()</code></div>
  236. <div class="summary">
  237. <p>
  238. Removes all members from the set.
  239. </p>
  240. </div>
  241. </li>
  242. <li class="method">
  243. <div class="methodsignature"><code>Number <strong>size</strong>()</code></div>
  244. <div class="summary">
  245. <p>
  246. Returns the number of members contained in the set.
  247. </p>
  248. </div>
  249. </li>
  250. <li class="method">
  251. <div class="methodsignature"><code>Boolean <strong>isEmpty</strong>()</code></div>
  252. <div class="summary">
  253. <p>
  254. Returns <code>true</code> if the set contains no members, <code>false</code>
  255. otherwise.
  256. </p>
  257. </div>
  258. </li>
  259. <li class="method">
  260. <div class="methodsignature"><code>Boolean <strong>isSubsetOf</strong>(HashSet
  261. <em>set</em>)</code></div>
  262. <div class="summary">
  263. <p>
  264. Returns <code>true</code> if every member this set is also a member of
  265. <code>set</code>, <code>false</code> otherwise.
  266. </p>
  267. </div>
  268. </li>
  269. <li class="method">
  270. <div class="methodsignature"><code>HashSet <strong>clone</strong>()</code></div>
  271. <div class="summary">
  272. <p>
  273. Creates and returns a shallow copy of the set, using the same options provided to
  274. the set when it was constructed.
  275. </p>
  276. </div>
  277. </li>
  278. <li class="method">
  279. <div class="methodsignature"><code>HashSet <strong>intersection</strong>(HashSet
  280. <em>set</em>)</code></div>
  281. <div class="summary">
  282. <p>
  283. Creates and returns a new <code>HashSet</code> containing only those elements that
  284. are contained in both this set and <code>set</code>.
  285. </p>
  286. </div>
  287. </li>
  288. <li class="method">
  289. <div class="methodsignature"><code>HashSet <strong>union</strong>(HashSet
  290. <em>set</em>)</code></div>
  291. <div class="summary">
  292. <p>
  293. Creates and returns a new <code>HashSet</code> containing those elements that are
  294. contained either of or both this set and <code>set</code>.
  295. </p>
  296. </div>
  297. </li>
  298. <li class="method">
  299. <div class="methodsignature"><code>HashSet <strong>complement</strong>(HashSet
  300. <em>set</em>)</code></div>
  301. <div class="summary">
  302. <p>
  303. Creates and returns a new <code>HashSet</code> containing those elements that are
  304. contained in this set but not <code>set</code>.
  305. </p>
  306. </div>
  307. </li>
  308. </ul>
  309. <p class="linktotop">
  310. <a href="#container">Top</a>
  311. </p>
  312. </div>
  313. </div>
  314. <div id="footer">
  315. Written by Tim Down. <a href="mailto:tim@timdown.co.uk">tim@timdown.co.uk</a>
  316. <br>
  317. <span class="jsh">jshashtable</span> is distributed under the
  318. <a href="http://www.apache.org/licenses/LICENSE-2.0.html" title="Apache License, Version 2.0">Apache
  319. License, Version 2.0</a>
  320. </div>
  321. </div>
  322. </body>
  323. </html>