/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. 

  2. <html>

    3. 

  3.     <head>

    4. 

  4.         <title>jshashset, a JavaScript implementation of HashSet</title>

    5. 

  5.         <meta name="author" content="Tim Down - tim@timdown.co.uk">

    6. 

  6.         <meta name="keywords" content="hash, set, JavaScript, hashmap, hashset, hashtable, DHTML">

    7. 

  7.         <meta name="description" content="jshashtable, a JavaScript hash table implementation">

    8. 

  8.         <meta name="robots" content="all">

    9. 

  9.         <link rel="stylesheet" type="text/css" href="main.css" title="Default">

    10. 

  10.     </head>

    11. 

  11.     <body>

    12. 

  12.         <div id="container" class="nonav">

    13. 

  13.             <div id="header">

    14. 

  14.                 <h1>jshashset 3.0</h1>

    15. 

  15.                 <div id="nav">

    16. 

  16.                     <span class="navitem">home</span>

    17. 

  17.                     | <a class="navitem" href="http://code.google.com/p/jshashtable/downloads/list"

    18. 

  18.                          title="Download">download</a>

    19. 

  19.                     | <a class="navitem" href="http://www.timdown.co.uk/jshashtable">website</a>

    20. 

  20.                     | <a class="navitem" href="http://www.timdown.co.uk">timdown.co.uk</a>

    21. 

  21.                 </div>

    22. 

  22.             </div>

    23. 

  23.             <div id="content">

    24. 

  24.                 <h1>jshashset 3.0</h1>

    25. 

  25.                 <div id="toc">

    26. 

  26.                     <h2>Contents</h2>

    27. 

  27.                     <ul>

    28. 

  28.                         <li><a href="#intro">Introduction</a></li>

    29. 

  29.                         <li><a href="#setup">Set-up</a></li>

    30. 

  30.                         <li><a href="#usage">Usage</a></li>

    31. 

  31.                         <li><a href="#api">Public API</a></li>

    32. 

  32.                     </ul>

    33. 

  33.                 </div>

    34. 

  34.                 <div id="intro">

    35. 

  35.                     <h2>Introduction</h2>

    36. 

  36.                     <p>

    37. 

  37.                         <span class="jsh">jshashset</span> is a JavaScript implementation of HashSet, as found in Java

    38. 

  38.                         or C#'s standard libraries. It depends on <a href="index.html">jshashtable</a> and uses the keys

    39. 

  39.                         of a <span class="jsh">jshashtable</span> hash table as the underlying set.

    40. 

  40.                     </p>

    41. 

  41.                     <p>

    42. 

  42.                         <span class="jsh">jshashset</span> was first included as a separate download for version 2.1 of

    43. 

  43.                         <span class="jsh">jshashtable</span> and is included with jshashtable from version 3.0.

    44. 

  44.                     </p>

    45. 

  45.                     <p class="linktotop">

    46. 

  46.                         <a href="#container">Top</a>

    47. 

  47.                     </p>

    48. 

  48.                 </div>

    49. 

  49.                 <div id="setup">

    50. 

  50.                     <h2>Set-up</h2>

    51. 

  51.                     <ol>

    52. 

  52.                         <li>

    53. 

  53.                             <h3>Download the code</h3>

    54. 

  54.                             <p>

    55. 

  55.                                 <strong><a href="http://code.google.com/p/jshashtable/downloads/list"

    56. 

  56.                                            title="Download">Download jshashset</a></strong>.

    57. 

  57.                                 You can download a compressed or uncompressed version of <code>jshashset.js</code>

    58. 

  58.                                 which are functionally identical or a zip containing compressed and uncompressed code

    59. 

  59.                                 for both <span class="jsh">jshashtable</span> and <span class="jsh">jshashset</span>

    60. 

  60.                                 plus documentation.

    61. 

  61.                             </p>

    62. 

  62.                         </li>

    63. 

  63.                         <li>

    64. 

  64.                             <h3>Include jshashtable and jshashset in your page</h3>

    65. 

  65.                             <p>

    66. 

  66.                                 Include <code>jshashtable.js</code> and <code>jshashset.js</code> in that order in

    67. 

  67.                                 script tags in your page. These files create two objects in the global scope, which are

    68. 

  68.                                 <code>Hashtable</code> and <code>HashSet</code>.

    69. 

  69.                             </p>

    70. 

  70.                         </li>

    71. 

  71.                         <li>

    72. 

  72.                             <h3>Create your hash set</h3>

    73. 

  73.                             <p>

    74. 

  74.                                 Create your hash set, as in the example below. Any non-null, non-undefined JavaScript

    75. 

  75.                                 object can be used as member of the set.

    76. 

  76.                             </p>

    77. 

  77.                     <pre class="code">

    78. 

  78. &lt;script type="text/javascript" src="jshashtable.js"&gt;&lt;/script&gt;

    79. 

  79. &lt;script type="text/javascript" src="jshashset.js"&gt;&lt;/script&gt;

    80. 

  80. &lt;script type="text/javascript"&gt;

    81. 

  81.     var dinosaurs = new HashSet();

    82. 

  82. 

    83. 

  83.     dinosaurs.add("Triceratops");

    84. 

  84.     dinosaurs.add("Diplodocus");

    85. 

  85.     dinosaurs.add("Stegosaurus");

    86. 

  86. 

    87. 

  87.     alert( dinosaurs.values.join(",") );

    88. 

  88.     /* Triceratops,Diplodocus,Stegosaurus */

    89. 

  89. &lt;/script&gt;

    90. 

  90. </pre>

    91. 

  91.                         </li>

    92. 

  92.                     </ol>

    93. 

  93.                     <p class="linktotop">

    94. 

  94.                         <a href="#container">Top</a>

    95. 

  95.                     </p>

    96. 

  96.                 </div>

    97. 

  97.                 <div id="api">

    98. 

  98.                     <h2>Public API</h2>

    99. 

  99.                     <h4>Constructors</h4>

    100. 

  100.                     <ul class="propertieslist">

    101. 

  101.                         <li class="method">

    102. 

  102.                             <div class="methodsignature">

    103. 

  103.                                 <code><strong>HashSet</strong>()</code>

    104. 

  104.                             </div>

    105. 

  105.                             <p>

    106. 

  106.                                 Creates a new, empty hash set.

    107. 

  107.                             </p>

    108. 

  108.                         </li>

    109. 

  109.                         <li class="method">

    110. 

  110.                             <div class="methodsignature">

    111. 

  111.                                 <code><strong>HashSet</strong>(Object <em>options</em>)</code>

    112. 

  112.                             </div>

    113. 

  113.                             <div class="summary">

    114. 

  114.                                 <p class="new">New in version 3.0</p>

    115. 

  115.                                 <p>

    116. 

  116.                                     Creates a new, empty hash set with the supplied options.

    117. 

  117.                                 </p>

    118. 

  118.                             </div>

    119. 

  119.                             <div class="paramsheading">Option properties:</div>

    120. 

  120.                             <ul class="params">

    121. 

  121.                                 <li class="param">

    122. 

  122.                                     <code class="paramname">hashCode</code>

    123. 

  123.                                     <div>

    124. 

  124.                                         A function that provides hash codes for objects placed in the set. It is passed

    125. 

  125.                                         the object to be hashed as its only parameter. If not provided, the set checks

    126. 

  126.                                         whether the object has a <code>hashCode()</code> method, and if not, calls

    127. 

  127.                                         <code>toString()</code> on the object.

    128. 

  128.                                     </div>

    129. 

  129.                                 </li>

    130. 

  130.                                 <li class="param">

    131. 

  131.                                     <code class="paramname">equals</code>

    132. 

  132.                                     <div>

    133. 

  133.                                         <p>

    134. 

  134.                                             A function that checks for equality between two objects with the same hash

    135. 

  135.                                             code. If two objects that are considered equal then only one can be in the

    136. 

  136.                                             set at any one time.

    137. 

  137.                                         </p>

    138. 

  138.                                         <p>

    139. 

  139.                                             This function is passed the two objects to be compared as its parameters. If

    140. 

  140.                                             not provided, the set checks whether either object being compared has an

    141. 

  141.                                             <code>equals()</code> method, and if not, compares the objects using the

    142. 

  142.                                             <code>===</code> operator.

    143. 

  143.                                         </p>

    144. 

  144.                                     </div>

    145. 

  145.                                 </li>

    146. 

  146.                                 <li class="param">

    147. 

  147.                                     <code class="paramname">replaceDuplicateKey</code>

    148. 

  148.                                     <p class="new">New in version 3.0</p>

    149. 

  149.                                     <p>

    150. 

  150.                                         Controls what happens when <code>add()</code> is called with an object that is

    151. 

  151.                                         equal to an existing object in the set. If <code>replaceDuplicateKey</code> is

    152. 

  152.                                         <code>true</code>, the existing key is always replaced by the new key.

    153. 

  153.                                         Otherwise, the existing key is left in place (which is what always happened

    154. 

  154.                                         prior to version 3.0). The default is <code>true</code>; prior to version 3.0.

    155. 

  155.                                     </p>

    156. 

  156.                                 </li>

    157. 

  157.                             </ul>

    158. 

  158.                         </li>

    159. 

  159.                         <li class="method">

    160. 

  160.                             <div class="methodsignature">

    161. 

  161.                                 <code><strong>HashSet</strong>(Function <em>hashingFunction</em>, Function

    162. 

  162.                                     <em>equalityFunction</em>)</code>

    163. 

  163.                             </div>

    164. 

  164.                             <p class="summary">

    165. 

  165.                                 Creates a new, empty hash set with the supplied hashing function and equality

    166. 

  166.                                 function. This form maintains backwards compatibility with versions prior to 3.0.

    167. 

  167.                                 The following line

    168. 

  168.                             </p>

    169. 

  169.                             <pre class="code">

    170. 

  170. var set = new HashSet(hashingFunction, equalityFunction);

    171. 

  171. </pre>

    172. 

  172.                             <p>... is equivalent to</p>

    173. 

  173.                             <pre class="code">

    174. 

  174. var set = new HashSet( { hashCode: hashingFunction, equals: equalityFunction } );

    175. 

  175. </pre>

    176. 

  176.                             <div class="paramsheading">Parameters:</div>

    177. 

  177.                             <ul class="params">

    178. 

  178.                                 <li class="param">

    179. 

  179.                                     <code class="paramname">hashingFunction</code>

    180. 

  180.                                     <p>See above.</p>

    181. 

  181.                                 </li>

    182. 

  182.                                 <li class="param">

    183. 

  183.                                     <code class="paramname">equalityFunction</code>

    184. 

  184.                                     <p>See above.</p>

    185. 

  185.                                 </li>

    186. 

  186.                             </ul>

    187. 

  187.                         </li>

    188. 

  188.                     </ul>

    189. 

  189.                     <h4>Methods</h4>

    190. 

  190.                     <ul class="propertieslist">

    191. 

  191.                         <li class="method" id="put">

    192. 

  192.                             <div class="methodsignature"><code>void <strong>add</strong>(mixed

    193. 

  193.                                 <em>value</em>)</code></div>

    194. 

  194.                             <div class="summary">

    195. 

  195.                                 Adds the specified object or primitive to the set. <code>value</code> replaces any

    196. 

  196.                                 member of the set equal to it, unless <code>replaceDuplicateKey</code> was set to

    197. 

  197.                                 <code>false</code> in the constructor.

    198. 

  198.                             </div>

    199. 

  199.                         </li>

    200. 

  200.                         <li class="method">

    201. 

  201.                             <div class="methodsignature"><code>void <strong>addAll</strong>(Array

    202. 

  202.                                 <em>arr</em>)</code></div>

    203. 

  203.                             <div class="summary">

    204. 

  204.                                 Adds all members of an array <code>arr</code> to the set in order. Each member of

    205. 

  205.                                 <code>arr</code> replaces any member of the set equal to it, unless

    206. 

  206.                                 <code>replaceDuplicateKey</code> was set to <code>false</code> in the constructor, in

    207. 

  207.                                 which case the original value is left in place.

    208. 

  208.                             </div>

    209. 

  209.                         </li>

    210. 

  210.                         <li class="method">

    211. 

  211.                             <div class="methodsignature"><code>Array <strong>values</strong>()</code></div>

    212. 

  212.                             <div class="summary">

    213. 

  213.                                 <p>

    214. 

  214.                                     Returns an array containing all the members of the set in unspecified order.

    215. 

  215.                                 </p>

    216. 

  216.                             </div>

    217. 

  217.                         </li>

    218. 

  218.                         <li class="method">

    219. 

  219.                             <div class="methodsignature"><code>void <strong>remove</strong>(mixed

    220. 

  220.                                 <em>key</em>)</code></div>

    221. 

  221.                             <div class="summary">

    222. 

  222.                                 <p>

    223. 

  223.                                     Removes the specified value from the set.

    224. 

  224.                                 </p>

    225. 

  225.                             </div>

    226. 

  226.                         </li>

    227. 

  227.                         <li class="method">

    228. 

  228.                             <div class="methodsignature"><code>Boolean <strong>contains</strong>(mixed

    229. 

  229.                                 <em>value</em>)</code></div>

    230. 

  230.                             <div class="summary">

    231. 

  231.                                 <p>

    232. 

  232.                                     Returns whether the set contains the specified value.

    233. 

  233.                                 </p>

    234. 

  234.                             </div>

    235. 

  235.                         </li>

    236. 

  236.                         <li class="method">

    237. 

  237.                             <div class="methodsignature"><code>void <strong>clear</strong>()</code></div>

    238. 

  238.                             <div class="summary">

    239. 

  239.                                 <p>

    240. 

  240.                                     Removes all members from the set.

    241. 

  241.                                 </p>

    242. 

  242.                             </div>

    243. 

  243.                         </li>

    244. 

  244.                         <li class="method">

    245. 

  245.                             <div class="methodsignature"><code>Number <strong>size</strong>()</code></div>

    246. 

  246.                             <div class="summary">

    247. 

  247.                                 <p>

    248. 

  248.                                     Returns the number of members contained in the set.

    249. 

  249.                                 </p>

    250. 

  250.                             </div>

    251. 

  251.                         </li>

    252. 

  252.                         <li class="method">

    253. 

  253.                             <div class="methodsignature"><code>Boolean <strong>isEmpty</strong>()</code></div>

    254. 

  254.                             <div class="summary">

    255. 

  255.                                 <p>

    256. 

  256.                                     Returns <code>true</code> if the set contains no members, <code>false</code>

    257. 

  257.                                     otherwise.

    258. 

  258.                                 </p>

    259. 

  259.                             </div>

    260. 

  260.                         </li>

    261. 

  261.                         <li class="method">

    262. 

  262.                             <div class="methodsignature"><code>Boolean <strong>isSubsetOf</strong>(HashSet

    263. 

  263.                                 <em>set</em>)</code></div>

    264. 

  264.                             <div class="summary">

    265. 

  265.                                 <p>

    266. 

  266.                                     Returns <code>true</code> if every member this set is also a member of

    267. 

  267.                                     <code>set</code>, <code>false</code> otherwise.

    268. 

  268.                                 </p>

    269. 

  269.                             </div>

    270. 

  270.                         </li>

    271. 

  271.                         <li class="method">

    272. 

  272.                             <div class="methodsignature"><code>HashSet <strong>clone</strong>()</code></div>

    273. 

  273.                             <div class="summary">

    274. 

  274.                                 <p>

    275. 

  275.                                     Creates and returns a shallow copy of the set, using the same options provided to

    276. 

  276.                                     the set when it was constructed.

    277. 

  277.                                 </p>

    278. 

  278.                             </div>

    279. 

  279.                         </li>

    280. 

  280.                         <li class="method">

    281. 

  281.                             <div class="methodsignature"><code>HashSet <strong>intersection</strong>(HashSet

    282. 

  282.                                 <em>set</em>)</code></div>

    283. 

  283.                             <div class="summary">

    284. 

  284.                                 <p>

    285. 

  285.                                     Creates and returns a new <code>HashSet</code> containing only those elements that

    286. 

  286.                                     are contained in both this set and <code>set</code>.

    287. 

  287.                                 </p>

    288. 

  288.                             </div>

    289. 

  289.                         </li>

    290. 

  290.                         <li class="method">

    291. 

  291.                             <div class="methodsignature"><code>HashSet <strong>union</strong>(HashSet

    292. 

  292.                                 <em>set</em>)</code></div>

    293. 

  293.                             <div class="summary">

    294. 

  294.                                 <p>

    295. 

  295.                                     Creates and returns a new <code>HashSet</code> containing those elements that are

    296. 

  296.                                     contained either of or both this set and <code>set</code>.

    297. 

  297.                                 </p>

    298. 

  298.                             </div>

    299. 

  299.                         </li>

    300. 

  300.                         <li class="method">

    301. 

  301.                             <div class="methodsignature"><code>HashSet <strong>complement</strong>(HashSet

    302. 

  302.                                 <em>set</em>)</code></div>

    303. 

  303.                             <div class="summary">

    304. 

  304.                                 <p>

    305. 

  305.                                     Creates and returns a new <code>HashSet</code> containing those elements that are

    306. 

  306.                                     contained in this set but not <code>set</code>.

    307. 

  307.                                 </p>

    308. 

  308.                             </div>

    309. 

  309.                         </li>

    310. 

  310.                     </ul>

    311. 

  311.                     <p class="linktotop">

    312. 

  312.                         <a href="#container">Top</a>

    313. 

  313.                     </p>

    314. 

  314.                 </div>

    315. 

  315.             </div>

    316. 

  316.             <div id="footer">

    317. 

  317.                 Written by Tim Down. <a href="mailto:tim@timdown.co.uk">tim@timdown.co.uk</a>

    318. 

  318.                 <br>

    319. 

  319.                 <span class="jsh">jshashtable</span> is distributed under the

    320. 

  320.                 <a href="http://www.apache.org/licenses/LICENSE-2.0.html" title="Apache License, Version 2.0">Apache

    321. 

  321.                     License, Version 2.0</a>

    322. 

  322.             </div>

    323. 

  323.         </div>

    324. 

  324.     </body>

    325. 

  325. </html>
    326.