Skip to content
Browse files

Write docs.

  • Loading branch information...
1 parent 0a2128a commit 9919f7877ce69d2eb097b49b9e0fde291f3b8405 @Gozala committed Jan 2, 2013
Showing with 146 additions and 17 deletions.
  1. +76 −1 Readme.md
  2. +22 −5 difference.js
  3. +28 −8 intersection.js
  4. +20 −3 union.js
View
77 Readme.md
@@ -4,8 +4,83 @@
[![browser support](http://ci.testling.com/Gozala/interset.png)](http://ci.testling.com/Gozala/interset)
-Binary operations for logical sets
+Binary operations for logical sets in our case arrays, although in a future
+support for upcoming sets maybe added.
+
+## API
+
+#### union
+
+Return a set that is the [union][] of the input sets.
+
+[!union](http://upload.wikimedia.org/wikipedia/commons/thumb/3/30/Venn0111.svg/200px-Venn0111.svg.png)
+
+
+```js
+var union = require("interset/union")
+
+union()
+// => []
+
+union([1, 2])
+// => [1, 2]
+
+union([1, 2], [2, 3])
+// => [1, 2, 3]
+
+union([1, 2], [2, 3], [3, 4])
+// => [1, 2, 3, 4]
+```
+
+#### intersection
+
+Return a set that is the [intersection][] of the input sets.
+
+[!intersection](http://upload.wikimedia.org/wikipedia/commons/thumb/9/99/Venn0001.svg/200px-Venn0001.svg.png)
+
+```js
+intersection()
+// => TypeError: intersection requires at least one argument
+
+intersection([1])
+// => [1]
+
+intersection([1, 2], [2, 3])
+// => [2]
+
+intersection([1, 2], [2, 3], [3, 4])
+// => []
+
+intersection([1, "a"], ["a", 3], ["a"])
+// => ["a"]
+```
+
+#### difference
+
+Return a set that is the first set without elements of the remaining sets
+
+[!difference](http://upload.wikimedia.org/wikipedia/commons/thumb/5/5a/Venn0010.svg/200px-Venn0010.svg.png)
+
+```js
+var difference = require("interset/difference")
+
+difference()
+// => TypeError: difference requires at least one arguments
+
+difference([1, 2, 3])
+// => [1, 2, 3]
+
+difference([1, 2], [2, 3])
+// => [1]
+
+difference([1, 2, 3], [1], [1, 4], [3])
+// => [2]
+```
## Install
npm install interset
+
+[union]:http://en.wikipedia.org/wiki/Union_%28set_theory%29
+[intersection]:http://en.wikipedia.org/wiki/Intersection_%28set_theory%29
+[difference]:http://en.wikipedia.org/wiki/Set_difference#Relative_complement
View
27 difference.js
@@ -4,9 +4,26 @@ var slicer = Array.prototype.slice
var concater = Array.prototype.concat
var excludes = function excludes(item) { return this.indexOf(item) < 0 }
-module.exports = function difference(source, exclude, rest) {
- if (!source) throw TypeError("difference requires at least one arguments")
- if (!exclude) return source
- exclude = concater.apply([], slicer.call(arguments, 1))
- return source.filter(excludes, exclude)
+module.exports = function difference(first, second) {
+ /**
+ Return a set that is the `first` set without elements of the remaining sets
+
+ var difference = require("interset/difference")
+
+ difference()
+ // => TypeError: difference requires at least one arguments
+
+ difference([1, 2, 3])
+ // => [1, 2, 3]
+
+ difference([1, 2], [2, 3])
+ // => [1]
+
+ difference([1, 2, 3], [1], [1, 4], [3])
+ // => [2]
+ **/
+ if (!first) throw TypeError("difference requires at least one argument")
+ if (!second) return first
+ var remaining = concater.apply([], slicer.call(arguments, 1))
+ return first.filter(excludes, remaining)
}
View
36 intersection.js
@@ -3,14 +3,34 @@
var slicer = Array.prototype.slice
var contains = function(item) { return this.indexOf(item) >= 0 }
-function intersection2(first, second) {
- return first.length > second.length ? first.filter(contains, second) :
- second.filter(contains, first)
+function intersection2(a, b) {
+ return a.length > b.length ? a.filter(contains, b) :
+ b.filter(contains, a)
}
-module.exports = function intersection(first, second, rest) {
- if (!first) throw TypeError("intersection requires at least one arguments")
- if (!second) return first
- if (!rest) return intersection2(first, second)
- return slicer.call(arguments, 1).reduce(intersection2, first)
+module.exports = function intersection(a, b, rest) {
+ /**
+ Return a set that is the [intersection][] of the input sets.
+
+ var intersection = require("interset/intersection")
+
+ intersection()
+ // => TypeError: intersection requires at least one arguments
+
+ intersection([1])
+ // => [1]
+
+ intersection([1, 2], [2, 3])
+ // => [2]
+
+ intersection([1, 2], [2, 3], [3, 4])
+ // => []
+
+ intersection([1, "a"], ["a", 3], ["a"])
+ // => ["a"]
+ **/
+ if (!a) throw TypeError("intersection requires at least one argument")
+ if (!b) return a
+ if (!rest) return intersection2(a, b)
+ return slicer.call(arguments, 1).reduce(intersection2, a)
}
View
23 union.js
@@ -10,8 +10,25 @@ function include(union, set) {
return set.reduce(add, union)
}
-module.exports = function union(first, second, rest) {
- if (!first) return []
- if (!second) return first
+module.exports = function union(a, b) {
+ /**
+ Return a set that is the [union][] of the input sets.
+
+ var union = require("interset/union")
+
+ union()
+ // => []
+
+ union([1, 2])
+ // => [1, 2]
+
+ union([1, 2], [2, 3])
+ // => [1, 2, 3]
+
+ union([1, 2], [2, 3], [3, 4])
+ // => [1, 2, 3, 4]
+ **/
+ if (!a) return []
+ if (!b) return a
return slicer.call(arguments).reduce(include, [])
}

0 comments on commit 9919f78

Please sign in to comment.
Something went wrong with that request. Please try again.