Implement xor and add tests

[ifreund]

Purpose:

I was using this crate and wanted to take the symmetric difference between two vectors. To my dismay there was no function for this.

Describe the solution:

Implement symmetric_difference() to calculate the symmetric difference of two bitvectors, setting self to the result. The implementation is quite simple, it's just an xor.

Add two tests, test_small_symmetric_difference() and test_big_symmetric_difference() for the new function.

[pczarn]

cc #33

[pczarn]

@tbu- could you please elaborate on

// FIXME(tbu-): `BitVec`'s methods shouldn't be `union`, `intersection`, but
// rather `or` and `and`.

Should we rename to xor from symmetric_difference?

[tbu-]

I don't remember. The blame of the file seems to be wrong due to a repository import.

[tbu-]

Ah right. Since BitVec fundamentally is a sequence of bits, it doesn't really make sense to talk about union or intersection, the former sounds more like appending both of the bit vectors.

I don't care about this anymore, feel free to disregard this and remove the FIXME.

[pczarn]

By saying you don't care about this, do you mean you do not have an opinion, or do you think we shouldn't change this? I mean, the motivation is good.

[tbu-]

By saying you don't care about this, do you mean you do not have an opinion, or do you think we shouldn't change this?

By that I mean that I don't have a skin in the game anymore. I still think the reason is good, but I won't spend time defending that opinion.

[ifreund]

I agree that union/intersection/symmetric difference are terminology for sets and not technically accurate when talking about a BitVec, but I'm not sure if it's worth changing the established API to correct this.

Will defer to whatever the maintainers of this repository decide.

[pczarn]

I put to together a script to download crates and search for uses of these methods.

In case there are very few uses of these methods, we go through with this. Then, we send PRs to patch for the change.

Requirements

cargo install cargo-download

Script

let deps = [];
function handleDeps(res) {
  res.on('data', data => { deps.push(JSON.parse(data.toString())) })
}
function grab(page) {
  const httpsOpts = { headers: { "User-Agent": "bit-vec crawl by @pczarn" } };
  const url = `https://crates.io/api/v1/crates/bit-vec/reverse_dependencies?page=${page}`;
  https.get(url, httpsOpts, handleDeps);
}

Array(8).fill().map((_, i) => grab(i + 1));
// ... wait
deps.flatMap(pageD => pageD.versions)
  .map(v => v.crate)
  .forEach(name =>
    exec(`cargo download ${name} > ${name}.tar.gz && tar -xvf ${name}.tar.gz`)
  );

Search

rg "\b(union|intersect|negate)\b"

=> https://gist.github.com/pczarn/1dcf41ee516aea185c71f496930eb06a

Turns out we have bloom using the methods and bit-array reimplementing the same methods.
False positives are bellperson, bellman and bit-set.

[pczarn]

Of course we have no idea about private code.

Anyhow, we will rename the methods for v 0.7. Futher possibilities that I can think of are

• adding nand, nor and xnor methods for completeness
• renaming negate to not for consistency, although that borders on pointless
• renaming difference to something else, but I do not see a motivation for that
• deprecating the current methods

So, @ifreund please rename and I'll then merge

[ifreund]

Renamed.

Anyhow, we will rename the methods for v 0.7. Futher possibilities that I can think of are:
adding nand, nor and xnor methods for completeness

I could probably crank those out this weekend.

[pczarn]

Great, feel free to leave the task to me, in case you'd wish to spend time elsewhere.

Thank you

[ifreund]

Great, feel free to leave the task to me, in case you'd wish to spend time elsewhere.

Probably wont get to it till Sunday, if you get to it before then no worries.