jQuery Combine
Combine regular JS objects using some basic operations: union, intersection, difference, and symmetric difference.
Only 238 bytes (gzipped)!
Getting Started
Download the production version or the development version.
In your web page:
<script src="libs/jquery/jquery.js"></script>
<script src="dist/jquery.combine.min.js"></script>
In your script:
var a = { foo: 1, bar: 1 };
var b = { foo: 2, buz: 1 };
var w = $.union(a, b); // { foo: 2, bar: 1, buz: 1 }
var x = $.intersection(a, b); // { foo: 2 }
var y = $.difference(a, b); // { bar: 1 }
var z = $.symmetric(a, b); // { bar: 1, buz: 1 }
Documentation
jQuery.extend()
is useful in a lot of situations to join objects. In a project I needed to do something different. I needed to find unique values amongst various attributes to form one unique combination. Basically I needed several differences
and then an union
, or more commonly done through a symmetric difference
.
This library supports four combinations common in set theory
:
- Union
- Intersection
- Difference
- Symmetric difference
The methods take two or more arguments. It currently does not support deep comparisons, or "recursive call", like jQuery.extend()
does.
Note: When there's attributes with different values, the last one in the arguments list is used.
Union
Union of the sets A and B, denoted A ∪ B, is the set of all objects that are a member of A, or B, or both. The union of {1, 2, 3} and {2, 3, 4} is the set {1, 2, 3, 4} .
Intersection
Intersection of the sets A and B, denoted A ∩ B, is the set of all objects that are members of both A and B. The intersection of {1, 2, 3} and {2, 3, 4} is the set {2, 3} .
Difference
Set difference of U and A, denoted U \ A, is the set of all members of U that are not members of A. The set difference {1,2,3} \ {2,3,4} is {1} , while, conversely, the set difference {2,3,4} \ {1,2,3} is {4}. When A is a subset of U, the set difference U \ A is also called the complement of A in U. In this case, if the choice of U is clear from the context, the notation Ac is sometimes used instead of U \ A, particularly if U is a universal set as in the study of Venn diagrams.
Symmetric difference
Symmetric difference of sets A and B is the set of all objects that are a member of exactly one of A and B (elements which are in one of the sets, but not in both). For instance, for the sets {1,2,3} and {2,3,4} , the symmetric difference set is {1,4} . It is the set difference of the union and the intersection, (A ∪ B) \ (A ∩ B) or (A \ B) ∪ (B \ A).
Examples
Union
Union is pretty much the same as $.extend() in regular jQuery. Supports more than two arguments.
var a = { foo: 1, bar: 1 };
var b = { foo: 2, buz: 1 };
var result = $.union(a, b); // { foo: 2, bar: 1, buz: 1 }
Intersection
Copies the common properties between given objects, into a new object. Supports more than two arguments.
var a = { foo: 1, bar: 1 };
var b = { foo: 2, buz: 1 };
var result = $.intersection(a, b); // { foo: 2 }
Difference
The first argument is compared to the others and the the unique properties are copied to a new object. Supports more than two arguments.
var a = { foo: 1, bar: 1 };
var b = { foo: 2, buz: 1 };
var result = $.difference(a, b); // { bar: 1 }
Symmetric difference
Similar to difference
but it doesn't treat any arguments different, instead it makes a union
between the difference
of all arguments. Supports more than two arguments.
var a = { foo: 1, bar: 1 };
var b = { foo: 2, buz: 1 };
var result = $.symmetric(a, b); // { bar: 1, buz: 1 }
Developers
This project can be developed and tested simply by using your standard editor and opening /test/index.html in a browser. But it also supports Grunt to set up a nice environment and work with Travis-CI. grunt dist
creates a distribution package. It uses Bower to keep the libraries updated, but for convenience the libraries are checked in. If you use WebStorm IDE or otherwise prefer the jsTestDriver there's support for that as well. JSHint is used and encouraged, so use the included config files. Dependencies are solved with RequireJS, but does not rely on any other functionality from it.
Release History
v0.1.0 - 17 April 2013 - Updated library based on feedback. Also added support for hipster-coding and increased buzzword-compliance. v0.0.1 - 25 March 2013 - Completed library code and basic documentation.