├── .gitignore
├── Cargo.toml
├── src
    ├── hashing.rs
    ├── lib.rs
    ├── valuevec.rs
    ├── counting.rs
    └── bloom.rs
├── README.md
└── LICENSE


/.gitignore:
--------------------------------------------------------------------------------
1 | /target/
2 | /Cargo.lock
3 | 


--------------------------------------------------------------------------------
/Cargo.toml:
--------------------------------------------------------------------------------
 1 | [package]
 2 | name = "bloom"
 3 | description = "Bloom filter implementation in rust"
 4 | version = "0.3.1"
 5 | authors = ["Nick Lanham <nick@afternight.org>"]
 6 | homepage = "https://github.com/nicklan/bloom-rs"
 7 | documentation = "https://docs.rs/bloom/"
 8 | readme = "README.md"
 9 | keywords = ["bloom", "filter", "bloomfilter"]
10 | license = "GPL-2.0"
11 | 
12 | [lib]
13 | name = "bloom"
14 | 
15 | [dependencies]
16 | bit-vec = "0.4.3"
17 | 
18 | [dev-dependencies]
19 | rand = "0.3.14"
20 | 
21 | [features]
22 | do-bench=[]
23 | 
24 | 


--------------------------------------------------------------------------------
/src/hashing.rs:
--------------------------------------------------------------------------------
 1 | 
 2 | use std::hash::{BuildHasher,Hash,Hasher};
 3 | // utilities for hashing
 4 | 
 5 | pub struct HashIter {
 6 |     h1: u64,
 7 |     h2: u64,
 8 |     i: u32,
 9 |     count: u32,
10 | }
11 | 
12 | impl Iterator for HashIter {
13 |     type Item = u64;
14 | 
15 |     fn next(&mut self) -> Option<u64> {
16 |         if self.i == self.count {
17 |             return None;
18 |         }
19 |         let r = match self.i {
20 |             0 => { self.h1 }
21 |             1 => { self.h2 }
22 |             _ => {
23 |                 let p1 = self.h1.wrapping_add(self.i as u64);
24 |                 p1.wrapping_mul(self.h2)
25 |             }
26 |         };
27 |         self.i+=1;
28 |         Some(r)
29 |     }
30 | }
31 | 
32 | impl HashIter {
33 |     pub fn from<T: Hash, R: BuildHasher, S: BuildHasher>(item: T, count: u32, build_hasher_one:&R, build_hasher_two:&S) -> HashIter {
34 |         let mut hasher_one = build_hasher_one.build_hasher();
35 |         let mut hasher_two = build_hasher_two.build_hasher();
36 |         item.hash(&mut hasher_one);
37 |         item.hash(&mut hasher_two);
38 |         let h1 = hasher_one.finish();
39 |         let h2 = hasher_two.finish();
40 |         HashIter {
41 |             h1: h1,
42 |             h2: h2,
43 |             i: 0,
44 |             count: count,
45 |         }
46 |     }
47 | }
48 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # bloom
 2 | 
 3 | An implementation of various Approximate Set Membership structures in
 4 | Rust.  Currently included are a standard Bloom Filter, and the
 5 | simplest kind of Counting Bloom Filter.
 6 | 
 7 | At some point more advanced types of ASMSes will be added.
 8 | 
 9 | # Basic Usage
10 | 
11 | ```rust
12 | extern crate bloom;
13 | use bloom::BloomFilter;
14 | let expected_num_items = 1000;
15 | let false_positive_rate = 0.01;
16 | let mut filter:BloomFilter = BloomFilter::with_rate(false_positive_rate,expected_num_items);
17 | filter.insert(&1i);
18 | filter.contains(&1i); /* true */
19 | filter.contains(&2i); /* false */
20 | ```
21 | 
22 | # Installation
23 | Use [Cargo](http://doc.crates.io/) and add the following to your Cargo.toml
24 | 
25 | ```
26 | [dependencies]
27 | bloom="0.2.0"
28 | ```
29 | 
30 | # Documentation
31 | See [here](https://docs.rs/bloom/)
32 | 
33 | # False Positive Rate
34 | The false positive rate is specified as a float in the range
35 | (0,1).  If indicates that out of `X` probes, `X * rate` should
36 | return a false positive.  Higher values will lead to smaller (but
37 | more inaccurate) filters.
38 | 
39 | # Benchmarks
40 | This crate includes some benchmarks to test the performance of the
41 | bloom filter.  To run them you'll need to use rust nightly (the
42 | benchmark feature isn't stable yet), and then run:
43 | 
44 | ```
45 | cargo bench --features "do-bench"
46 | ```
47 | 


--------------------------------------------------------------------------------
/src/lib.rs:
--------------------------------------------------------------------------------
  1 | // A Rust BloomFilter implementation.
  2 | // Copywrite (c) 2016 Nick Lanham
  3 | 
  4 | // This program is free software; you can redistribute it and/or
  5 | // modify it under the terms of the GNU General Public License as
  6 | // published by the Free Software Foundation; either version 2 of the
  7 | // License, or (at your option) any later version.
  8 | 
  9 | // This program is distributed in the hope that it will be useful, but
 10 | // WITHOUT ANY WARRANTY; without even the implied warranty of
 11 | // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 12 | // General Public License for more details.
 13 | 
 14 | // You should have received a copy of the GNU General Public License
 15 | // along with this program; if not, write to the Free Software
 16 | // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 17 | // 02110-1301, USA.
 18 | 
 19 | 
 20 | //! An implementation of various Approximate Set Membership structures
 21 | //! in Rust.  Currently included are a standard Bloom Filter, and the
 22 | //! simplest kind of Counting Bloom Filter.
 23 | //!
 24 | //! # Usage
 25 | //!
 26 | //! This crate is [on crates.io](https://crates.io/crates/rand) and
 27 | //! can be used by adding `bloom` to the dependencies in your
 28 | //! project's `Cargo.toml`.
 29 | //!
 30 | //! ```toml
 31 | //! [dependencies]
 32 | //! bloom = "0.2.0"
 33 | //! ```
 34 | //!
 35 | //! add this to your crate root:
 36 | //!
 37 | //! ```rust
 38 | //! extern crate bloom;
 39 | //! ```
 40 | //!
 41 | //! # Bloom Filters
 42 | //!
 43 | //! A Bloom Filter is an Approximate Set Membership structure, which
 44 | //! means it can track a set of items and check if an item is a member
 45 | //! of the set it is tracking.  It is able to do this using a much
 46 | //! smaller amount of memory than storing the actual items, at the
 47 | //! cost of an occasionally indicating that an item is in the set even
 48 | //! though it is not.  This occurence is called a "False Positive".  A
 49 | //! traditional Bloom Filter will never have a "False Negative"
 50 | //! however, which would be indicating that an item is *not* in the
 51 | //! set, when in fact it is.  The frequency of false positives can be
 52 | //! preciecly bounded by setting the size of the filter, and is called
 53 | //! the False Positive Rate.  Their small memory footprint and absence
 54 | //! of false negatives makes BloomFilters suitable for many
 55 | //! applications.
 56 | //!
 57 | //! # Example Usage
 58 | //!
 59 | //! ```rust
 60 | //! use bloom::{ASMS,BloomFilter};
 61 | //!
 62 | //! let expected_num_items = 1000;
 63 | //!
 64 | //! // out of 100 items that are not inserted, expect 1 to return true for contain
 65 | //! let false_positive_rate = 0.01;
 66 | //!
 67 | //! let mut filter = BloomFilter::with_rate(false_positive_rate,expected_num_items);
 68 | //! filter.insert(&1);
 69 | //! filter.contains(&1); /* true */
 70 | //! filter.contains(&2); /* probably false */
 71 | //! ```
 72 | //!
 73 | //! # Counting Bloom Filters
 74 | //!
 75 | //! Counting filters allow removal from a Bloom filter without
 76 | //! recreating the filter afresh. A counting filter uses an n-bit
 77 | //! counter where a standard Bloom Filter uses a single bit.  Counting
 78 | //! filters can also provide an upper bound on the number of times a
 79 | //! particular element has been inserted into the filter.  In general
 80 | //! 4 bits per element is considered a good size.  This will cause the
 81 | //! filter to use 4 times as much memory as compared to standard Bloom
 82 | //! Filter.
 83 | //!
 84 | //! # Example Usage
 85 | //!
 86 | //! ```rust
 87 | //! use bloom::{ASMS,CountingBloomFilter};
 88 | //! // Create a counting filter that uses 4 bits per element and has a false positive rate
 89 | //! // of 0.01 when 100 items have been inserted
 90 | //! let mut cbf:CountingBloomFilter = CountingBloomFilter::with_rate(4,0.01,100);
 91 | //! cbf.insert(&1);
 92 | //! cbf.insert(&2);
 93 | //! assert_eq!(cbf.estimate_count(&1),1);
 94 | //! assert_eq!(cbf.estimate_count(&2),1);
 95 | //! assert_eq!(cbf.insert_get_count(&1),1);
 96 | //! assert_eq!(cbf.estimate_count(&1),2);
 97 | //! assert_eq!(cbf.remove(&1),2);
 98 | //! assert_eq!(cbf.estimate_count(&1),1);
 99 | //! ```
100 | 
101 | 
102 | #![crate_name="bloom"]
103 | #![crate_type = "rlib"]
104 | 
105 | #![cfg_attr(feature = "do-bench", feature(test))]
106 | 
107 | extern crate core;
108 | extern crate bit_vec;
109 | use std::hash::Hash;
110 | 
111 | mod hashing;
112 | 
113 | pub mod bloom;
114 | pub use bloom::{BloomFilter,optimal_num_hashes,needed_bits};
115 | 
116 | pub mod counting;
117 | pub use counting::CountingBloomFilter;
118 | 
119 | pub mod valuevec;
120 | pub use valuevec::ValueVec;
121 | 
122 | /// Stanard filter functions
123 | pub trait ASMS {
124 |     fn insert<T: Hash>(& mut self,item: &T) -> bool;
125 |     fn contains<T: Hash>(&self, item: &T) -> bool;
126 |     fn clear(&mut self);
127 | }
128 | 
129 | /// Filters that implement this trait can be intersected with filters
130 | /// of the same type to produce a filter that contains the
131 | /// items that have been inserted into *both* filters.
132 | ///
133 | /// Both filters MUST be the same size and be using the same hash
134 | /// functions for this to work.  Will panic if the filters are not the
135 | /// same size, but will simply produce incorrect (meaningless) results
136 | /// if the filters are using different hash functions.
137 | pub trait Intersectable {
138 |     fn intersect(&mut self, other: &Self) -> bool;
139 | }
140 | 
141 | /// Filters that implement this trait can be unioned with filters
142 | /// of the same type to produce a filter that contains the
143 | /// items that have been inserted into *either* filter.
144 | ///
145 | /// Both filters MUST be the same size and be using the same hash
146 | /// functions for this to work.  Will panic if the filters are not the
147 | /// same size, but will simply produce incorrect (meaningless) results
148 | /// if the filters are using different hash functions.
149 | pub trait Unionable {
150 |     fn union(&mut self, other: &Self) -> bool;
151 | }
152 | 
153 | /// Filters than are Combineable can be unioned and intersected
154 | pub trait Combineable: Intersectable + Unionable {}
155 | impl<T> Combineable for T where T: Intersectable + Unionable {}
156 | 


--------------------------------------------------------------------------------
/src/valuevec.rs:
--------------------------------------------------------------------------------
  1 | // This program is free software; you can redistribute it and/or
  2 | // modify it under the terms of the GNU General Public License as
  3 | // published by the Free Software Foundation; either version 2 of the
  4 | // License, or (at your option) any later version.
  5 | 
  6 | // This program is distributed in the hope that it will be useful, but
  7 | // WITHOUT ANY WARRANTY; without even the implied warranty of
  8 | // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  9 | // General Public License for more details.
 10 | 
 11 | // You should have received a copy of the GNU General Public License
 12 | // along with this program; if not, write to the Free Software
 13 | // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 14 | // 02110-1301, USA.
 15 | 
 16 | extern crate core;
 17 | extern crate bit_vec;
 18 | 
 19 | use bit_vec::BitVec;
 20 | 
 21 | /// A ValueVec is a bit vector that holds fixed sized unsigned integer
 22 | /// values.
 23 | pub struct ValueVec {
 24 |     bits_per_val: usize,
 25 |     mask: u32,
 26 |     bits: BitVec,
 27 | }
 28 | 
 29 | impl ValueVec {
 30 | 
 31 |     /// Create a ValueVec that holds values with `bits_per_val` bits and
 32 |     /// space to hold `count` values.
 33 |     pub fn new(bits_per_val: usize, count: usize) -> ValueVec {
 34 |         let bits = bits_per_val*count;
 35 |         ValueVec {
 36 |             bits_per_val: bits_per_val,
 37 |             mask: 2u32.pow(bits_per_val as u32)-1,
 38 |             bits: BitVec::from_elem(bits,false),
 39 |         }
 40 |     }
 41 | 
 42 |     /// Create a ValueVec that can hold `count` values where the
 43 |     /// maximam value of each entry is at least `max_val` (inclusive)
 44 |     ///
 45 |     /// # Example
 46 |     ///
 47 |     /// ```rust,should_panic
 48 |     /// use bloom::ValueVec;
 49 |     /// let mut vv = ValueVec::with_max(7,3);
 50 |     /// vv.set(0,7); // okay
 51 |     /// vv.set(0,8); // will panic
 52 |     /// ```
 53 |     pub fn with_max(max_val: u32, count: usize) -> ValueVec {
 54 |         let mut bits_per_val = 0;
 55 |         let mut cur = max_val;
 56 |         // there are fancy faster versions of this, but this is only
 57 |         // run in a constructor, so no need to complicate things
 58 |         while cur > 0 {
 59 |             bits_per_val+=1;
 60 |             cur>>=1;
 61 |         }
 62 |         ValueVec::new(bits_per_val,count)
 63 |     }
 64 | 
 65 |     /// How many bits this ValueVec is using to store each value
 66 |     pub fn bits_per_val(&self) -> usize {
 67 |         self.bits_per_val
 68 |     }
 69 | 
 70 |     /// The maximum value this ValueVec can hold per entry
 71 |     pub fn max_value(&self) -> u32 {
 72 |         self.mask
 73 |     }
 74 | 
 75 |     /// Resets all values to 0 in this ValueVec
 76 |     pub fn clear(&mut self) {
 77 |         self.bits.clear();
 78 |     }
 79 | 
 80 |     fn set_bits(&mut self, idx: usize,  val: u32, num_bits: usize) {
 81 |         let mut blocks = unsafe {self.bits.storage_mut()};
 82 |         let blockidx = idx/32;
 83 |         let shift = 32-(idx%32)-num_bits;
 84 |         let mask =
 85 |             if num_bits==self.bits_per_val {
 86 |                 self.mask
 87 |             } else {
 88 |                 2u32.pow(num_bits as u32)-1
 89 |             } << shift;
 90 |         let block = blocks[blockidx];
 91 | 
 92 |         // this will be the value with all bits in our value set to zero
 93 |         let zeroed = (block ^ mask) & block;
 94 |         // or in the new val
 95 |         blocks[blockidx] = zeroed | (val<<shift);
 96 |     }
 97 | 
 98 |     fn get_bits(&self, idx: usize, num_bits: usize) -> u32 {
 99 |         let blocks = self.bits.storage();
100 |         let shift = 32-(idx%32)-num_bits;
101 |         let mask =
102 |             if num_bits==self.bits_per_val {
103 |                 self.mask
104 |             } else {
105 |                 2u32.pow(num_bits as u32)-1
106 |             } << shift;
107 |         let val = blocks[idx/32] & mask;
108 |         val >> shift
109 |     }
110 | 
111 |     /// Get the total number of bits this valuevec is using
112 |     pub fn len(&self) -> usize {
113 |         self.bits.len()
114 |     }
115 | 
116 |     /// Set value at index `i` to value `val`.
117 |     ///
118 |     /// # Panics
119 |     ///
120 |     /// Panics if `val` needs more bits to store than the number of
121 |     /// bits this vec is using per value
122 |     pub fn set(&mut self, i: usize, val: u32) {
123 |         if val > self.mask {
124 |             panic!("set with val {}, max value this ValueVec can hold is {}",
125 |                    val,self.mask);
126 |         }
127 |         let idx = i*self.bits_per_val;
128 |         //println!("idx is: {}",idx);
129 |         let rem = 32-(idx%32);
130 |         if rem < self.bits_per_val {
131 |             // rem is how many bits needed in the lower part
132 |             let left = self.bits_per_val-rem;
133 |             let lowerval = val>>left;
134 |             self.set_bits(idx,lowerval,rem);
135 | 
136 |             // now put the rest of the bits in
137 |             let upval = val&(2u32.pow(left as u32)-1);
138 |             self.set_bits(idx+rem,upval,left);
139 |         } else {
140 |             let vs = self.bits_per_val;
141 |             self.set_bits(idx,val,vs);
142 |         }
143 |     }
144 | 
145 |     /// Get the value in this ValueVec stored at index `i`
146 |     pub fn get(&self, i: usize) -> u32 {
147 |         let idx = i*self.bits_per_val;
148 |         let rem = 32-(idx%32);
149 |         if rem < self.bits_per_val {
150 |             let lower = self.get_bits(idx,rem);
151 |             let left = self.bits_per_val-rem;
152 |             let upper = self.get_bits(idx+rem,left);
153 |             (lower<<left)|upper
154 |         } else {
155 |             self.get_bits(idx,self.bits_per_val)
156 |         }
157 |     }
158 | }
159 | 
160 | #[cfg(test)]
161 | mod tests {
162 |     use valuevec::ValueVec;
163 | 
164 |     #[test]
165 |     fn set_get_no_overlap() {
166 |         let mut vv = ValueVec::new(4,12);
167 | 
168 |         vv.set(1,3);
169 |         assert_eq!(vv.get(1),3);
170 | 
171 |         vv.set(2,4);
172 |         assert_eq!(vv.get(1),3);
173 |         assert_eq!(vv.get(2),4);
174 | 
175 |         vv.set(11,2);
176 |         assert_eq!(vv.get(1),3);
177 |         assert_eq!(vv.get(2),4);
178 |         assert_eq!(vv.get(11),2);
179 |     }
180 | 
181 |     #[test]
182 |     fn set_get_overlap() {
183 |         let mut vv = ValueVec::new(3,12);
184 | 
185 |         vv.set(1,3);
186 |         assert_eq!(vv.get(1),3);
187 | 
188 |         vv.set(2,4);
189 |         assert_eq!(vv.get(1),3);
190 |         assert_eq!(vv.get(2),4);
191 | 
192 |         vv.set(10,7);
193 |         assert_eq!(vv.get(1),3);
194 |         assert_eq!(vv.get(2),4);
195 |         assert_eq!(vv.get(10),7);
196 | 
197 |         vv.set(11,2);
198 |         assert_eq!(vv.get(1),3);
199 |         assert_eq!(vv.get(2),4);
200 |         assert_eq!(vv.get(10),7);
201 |         assert_eq!(vv.get(11),2);
202 |     }
203 | 
204 |     #[test]
205 |     #[should_panic]
206 |     fn set_over_max() {
207 |         let mut vv = ValueVec::new(2,2);
208 |         vv.set(0,100);
209 |     }
210 | 
211 |     #[test]
212 |     fn with_max() {
213 |         let mut vv = ValueVec::with_max(35,3);
214 |         vv.set(0,35);
215 |         assert_eq!(vv.get(0),35);
216 |         vv.set(2,14);
217 |         assert_eq!(vv.get(0),35);
218 |         assert_eq!(vv.get(2),14);
219 |         assert_eq!(vv.get(1),0);
220 |     }
221 | 
222 |     #[test]
223 |     #[should_panic]
224 |     fn over_with_max() {
225 |         let mut vv = ValueVec::with_max(7,2);
226 |         vv.set(0,7);
227 |         vv.set(1,8);
228 |     }
229 | }
230 | 


--------------------------------------------------------------------------------
/src/counting.rs:
--------------------------------------------------------------------------------
  1 | 
  2 | use std::hash::{BuildHasher,Hash};
  3 | use std::collections::hash_map::RandomState;
  4 | use super::ValueVec;
  5 | use super::ASMS;
  6 | use super::hashing::HashIter;
  7 | 
  8 | /// A standard counting bloom filter that uses a fixed number of bits
  9 | /// per counter, supports remove, and estimating the count of the
 10 | /// number of items inserted.
 11 | pub struct CountingBloomFilter<R = RandomState, S = RandomState> {
 12 |     counters: ValueVec,
 13 |     num_entries: u64,
 14 |     num_hashes: u32,
 15 |     hash_builder_one: R,
 16 |     hash_builder_two: S,
 17 | }
 18 | 
 19 | 
 20 | impl CountingBloomFilter<RandomState,RandomState> {
 21 |     /// Create a new CountingBloomFilter that will hold `num_entries`
 22 |     /// items, uses `bits_per_entry` per item, and `num_hashes` hashes
 23 |     pub fn with_size(num_entries: usize,
 24 |                      bits_per_entry: usize,
 25 |                      num_hashes: u32) -> CountingBloomFilter<RandomState,RandomState> {
 26 |         CountingBloomFilter {
 27 |             counters: ValueVec::new(bits_per_entry, num_entries),
 28 |             num_entries: num_entries as u64,
 29 |             num_hashes: num_hashes,
 30 |             hash_builder_one: RandomState::new(),
 31 |             hash_builder_two: RandomState::new(),
 32 |         }
 33 |     }
 34 | 
 35 |     /// create a CountingBloomFilter that uses `bits_per_entry`
 36 |     /// entries and expects to hold `expected_num_items`.  The filter
 37 |     /// will be sized to have a false positive rate of the value
 38 |     /// specified in `rate`.
 39 |     pub fn with_rate(bits_per_entry: usize, rate: f32, expected_num_items: u32) -> CountingBloomFilter<RandomState, RandomState> {
 40 |         let entries = super::bloom::needed_bits(rate,expected_num_items);
 41 |         CountingBloomFilter::with_size(entries,
 42 |                                        bits_per_entry,
 43 |                                        super::bloom::optimal_num_hashes(entries,expected_num_items))
 44 |     }
 45 | 
 46 |     /// Return the number of bits needed to hold values up to and
 47 |     /// including `max`
 48 |     ///
 49 |     /// # Example
 50 |     ///
 51 |     /// ```rust
 52 |     /// use bloom::CountingBloomFilter;
 53 |     /// // Create a CountingBloomFilter that can count up to 10 on each entry, and with 1000
 54 |     /// // items will have a false positive rate of 0.01
 55 |     /// let cfb = CountingBloomFilter::with_rate(CountingBloomFilter::bits_for_max(10),
 56 |     ///                                          0.01,
 57 |     ///                                          1000);
 58 |     /// ```
 59 |     pub fn bits_for_max(max: u32) -> usize {
 60 |         let mut bits_per_val = 0;
 61 |         let mut cur = max;
 62 |         while cur > 0 {
 63 |             bits_per_val+=1;
 64 |             cur>>=1;
 65 |         }
 66 |         bits_per_val
 67 |     }
 68 | }
 69 | 
 70 | impl<R,S> CountingBloomFilter<R,S>
 71 |     where R: BuildHasher, S: BuildHasher
 72 | {
 73 |     /// Create a new CountingBloomFilter with the specified number of
 74 |     /// bits, hashes, and the two specified HashBuilders.  Note the
 75 |     /// the HashBuilders MUST provide independent hash values.
 76 |     /// Passing two HashBuilders that produce the same or correlated
 77 |     /// hash values will break the false positive guarantees of the
 78 |     /// CountingBloomFilter.
 79 |     pub fn with_size_and_hashers(num_entries: usize,
 80 |                                  bits_per_entry: usize,
 81 |                                  num_hashes: u32,
 82 |                                  hash_builder_one: R, hash_builder_two: S) -> CountingBloomFilter<R,S> {
 83 |         CountingBloomFilter {
 84 |             counters: ValueVec::new(bits_per_entry, num_entries),
 85 |             num_entries: num_entries as u64,
 86 |             num_hashes: num_hashes,
 87 |             hash_builder_one: hash_builder_one,
 88 |             hash_builder_two: hash_builder_two,
 89 |         }
 90 |     }
 91 | 
 92 |     /// Create a CountingBloomFilter that expects to hold
 93 |     /// `expected_num_items`.  The filter will be sized to have a
 94 |     /// false positive rate of the value specified in `rate`.  Items
 95 |     /// will be hashed using the Hashers produced by
 96 |     /// `hash_builder_one` and `hash_builder_two`.  Note the the
 97 |     /// HashBuilders MUST provide independent hash values.  Passing
 98 |     /// two HashBuilders that produce the same or correlated hash
 99 |     /// values will break the false positive guarantees of the
100 |     /// CountingBloomFilter.
101 |     pub fn with_rate_and_hashers(bits_per_entry: usize, rate: f32, expected_num_items: u32,
102 |                                  hash_builder_one: R, hash_builder_two: S) -> CountingBloomFilter<R, S> {
103 |         let entries = super::bloom::needed_bits(rate,expected_num_items);
104 |         CountingBloomFilter::with_size_and_hashers(entries,bits_per_entry,
105 |                                                    super::bloom::optimal_num_hashes(entries,expected_num_items),
106 |                                                    hash_builder_one,hash_builder_two)
107 |     }
108 | 
109 |     /// Remove an item.  Returns an upper bound of the number of times
110 |     /// this item had been inserted previously (i.e. the count before
111 |     /// this remove).  Returns 0 if item was never inserted.
112 |     pub fn remove<T: Hash>(&mut self, item: &T) ->  u32 {
113 |         if !(self as &CountingBloomFilter<R,S>).contains(item) {
114 |             return 0;
115 |         }
116 |         let mut min = u32::max_value();
117 |         for h in HashIter::from(item,
118 |                                 self.num_hashes,
119 |                                 &self.hash_builder_one,
120 |                                 &self.hash_builder_two) {
121 |             let idx = (h % self.num_entries) as usize;
122 |             let cur = self.counters.get(idx);
123 |             if cur < min {
124 |                 min = cur;
125 |             }
126 |             if cur > 0 {
127 |                 self.counters.set(idx,cur-1);
128 |             } else {
129 |                 panic!("Contains returned true but a counter is 0");
130 |             }
131 |         }
132 |         min
133 |     }
134 | 
135 |     /// Return an estimate of the number of times `item` has been
136 |     /// inserted into the filter.  Esitimate is a upper bound on the
137 |     /// count, meaning the item has been inserted *at most* this many
138 |     /// times, but possibly fewer.
139 |     pub fn estimate_count<T: Hash>(&self, item: &T) -> u32 {
140 |         let mut min = u32::max_value();
141 |         for h in HashIter::from(item,
142 |                                 self.num_hashes,
143 |                                 &self.hash_builder_one,
144 |                                 &self.hash_builder_two) {
145 |             let idx = (h % self.num_entries) as usize;
146 |             let cur = self.counters.get(idx);
147 |             if cur < min {
148 |                 min = cur;
149 |             }
150 |         }
151 |         min
152 |     }
153 | 
154 |     /// Inserts an item, returns the estimated count of the number of
155 |     /// times this item had previously been inserted (not counting
156 |     /// this insertion)
157 |     pub fn insert_get_count<T: Hash>(&mut self, item: &T) -> u32 {
158 |         let mut min = u32::max_value();
159 |         for h in HashIter::from(item,
160 |                                 self.num_hashes,
161 |                                 &self.hash_builder_one,
162 |                                 &self.hash_builder_two) {
163 |             let idx = (h % self.num_entries) as usize;
164 |             let cur = self.counters.get(idx);
165 |             if cur < min {
166 |                 min = cur;
167 |             }
168 |             if cur < self.counters.max_value() {
169 |                 self.counters.set(idx,cur+1);
170 |             }
171 |         }
172 |         min
173 |     }
174 | }
175 | 
176 | impl<R,S> ASMS for CountingBloomFilter<R,S>
177 |     where R: BuildHasher, S: BuildHasher {
178 |     /// Inserts an item, returns true if this item was already in the
179 |     /// filter any number of times
180 |     fn insert<T: Hash>(&mut self, item: &T) -> bool {
181 |         let mut min = u32::max_value();
182 |         for h in HashIter::from(item,
183 |                                 self.num_hashes,
184 |                                 &self.hash_builder_one,
185 |                                 &self.hash_builder_two) {
186 |             let idx = (h % self.num_entries) as usize;
187 |             let cur = self.counters.get(idx);
188 |             if cur < min {
189 |                 min = cur;
190 |             }
191 |             if cur < self.counters.max_value() {
192 |                 self.counters.set(idx,cur+1);
193 |             }
194 |         }
195 |         min > 0
196 |     }
197 | 
198 | 
199 |     /// Check if the item has been inserted into this
200 |     /// CountingBloomFilter.  This function can return false
201 |     /// positives, but not false negatives.
202 |     fn contains<T: Hash>(&self, item: &T) -> bool {
203 |         for h in HashIter::from(item,
204 |                                 self.num_hashes,
205 |                                 &self.hash_builder_one,
206 |                                 &self.hash_builder_two) {
207 |             let idx = (h % self.num_entries) as usize;
208 |             let cur = self.counters.get(idx);
209 |             if cur == 0 {
210 |                 return false;
211 |             }
212 |         }
213 |         true
214 |     }
215 | 
216 |     /// Remove all values from this CountingBloomFilter
217 |     fn clear(&mut self) {
218 |         self.counters.clear();
219 |     }
220 | }
221 | 
222 | 
223 | #[cfg(test)]
224 | mod tests {
225 |     use super::CountingBloomFilter;
226 |     use ASMS;
227 | 
228 |     #[test]
229 |     fn simple() {
230 |         let mut cbf:CountingBloomFilter = CountingBloomFilter::with_rate(4,0.01,100);
231 |         assert_eq!(cbf.insert(&1),false);
232 |         assert!(cbf.contains(&1));
233 |         assert!(!cbf.contains(&2));
234 |     }
235 | 
236 |     #[test]
237 |     fn remove() {
238 |         let mut cbf:CountingBloomFilter = CountingBloomFilter::with_rate(CountingBloomFilter::bits_for_max(10)
239 |                                                                          ,0.01,100);
240 |         assert_eq!(cbf.insert_get_count(&1),0);
241 |         cbf.insert(&2);
242 |         assert!(cbf.contains(&1));
243 |         assert!(cbf.contains(&2));
244 |         assert_eq!(cbf.remove(&2),1);
245 |         assert_eq!(cbf.remove(&3),0);
246 |         assert!(cbf.contains(&1));
247 |         assert!(!cbf.contains(&2));
248 |     }
249 | 
250 |     #[test]
251 |     fn estimate_count() {
252 |         let mut cbf:CountingBloomFilter = CountingBloomFilter::with_rate(4,0.01,100);
253 |         cbf.insert(&1);
254 |         cbf.insert(&2);
255 |         assert_eq!(cbf.estimate_count(&1),1);
256 |         assert_eq!(cbf.estimate_count(&2),1);
257 |         assert_eq!(cbf.insert_get_count(&1),1);
258 |         assert_eq!(cbf.estimate_count(&1),2);
259 |     }
260 | }
261 | 
262 | 


--------------------------------------------------------------------------------
/src/bloom.rs:
--------------------------------------------------------------------------------
  1 | // This program is free software; you can redistribute it and/or
  2 | // modify it under the terms of the GNU General Public License as
  3 | // published by the Free Software Foundation; either version 2 of the
  4 | // License, or (at your option) any later version.
  5 | 
  6 | // This program is distributed in the hope that it will be useful, but
  7 | // WITHOUT ANY WARRANTY; without even the implied warranty of
  8 | // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  9 | // General Public License for more details.
 10 | 
 11 | // You should have received a copy of the GNU General Public License
 12 | // along with this program; if not, write to the Free Software
 13 | // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 14 | // 02110-1301, USA.
 15 | 
 16 | extern crate core;
 17 | extern crate bit_vec;
 18 | 
 19 | use bit_vec::BitVec;
 20 | use std::cmp::{min,max};
 21 | use std::collections::hash_map::RandomState;
 22 | use std::hash::{BuildHasher,Hash};
 23 | 
 24 | use super::{ASMS,Intersectable,Unionable};
 25 | use super::hashing::HashIter;
 26 | 
 27 | /// A standard BloomFilter.  If an item is instered then `contains`
 28 | /// is guaranteed to return `true` for that item.  For items not
 29 | /// inserted `contains` will probably return false.  The probability
 30 | /// that `contains` returns `true` for an item that was not inserted
 31 | /// is called the False Positive Rate.
 32 | ///
 33 | /// # False Positive Rate
 34 | /// The false positive rate is specified as a float in the range
 35 | /// (0,1).  If indicates that out of `X` probes, `X * rate` should
 36 | /// return a false positive.  Higher values will lead to smaller (but
 37 | /// more inaccurate) filters.
 38 | ///
 39 | /// # Example Usage
 40 | ///
 41 | /// ```rust
 42 | /// use bloom::{ASMS,BloomFilter};
 43 | ///
 44 | /// let expected_num_items = 1000;
 45 | ///
 46 | /// // out of 100 items that are not inserted, expect 1 to return true for contain
 47 | /// let false_positive_rate = 0.01;
 48 | ///
 49 | /// let mut filter = BloomFilter::with_rate(false_positive_rate,expected_num_items);
 50 | /// filter.insert(&1);
 51 | /// filter.contains(&1); /* true */
 52 | /// filter.contains(&2); /* false */
 53 | /// ```
 54 | pub struct BloomFilter<R = RandomState, S = RandomState> {
 55 |     bits: BitVec,
 56 |     num_hashes: u32,
 57 |     hash_builder_one: R,
 58 |     hash_builder_two: S,
 59 | }
 60 | 
 61 | 
 62 | impl BloomFilter<RandomState, RandomState> {
 63 |     /// Create a new BloomFilter with the specified number of bits,
 64 |     /// and hashes
 65 |     pub fn with_size(num_bits: usize, num_hashes: u32) -> BloomFilter<RandomState, RandomState> {
 66 |         BloomFilter {
 67 |             bits: BitVec::from_elem(num_bits,false),
 68 |             num_hashes: num_hashes,
 69 |             hash_builder_one: RandomState::new(),
 70 |             hash_builder_two: RandomState::new(),
 71 |         }
 72 |     }
 73 | 
 74 |     /// create a BloomFilter that expects to hold
 75 |     /// `expected_num_items`.  The filter will be sized to have a
 76 |     /// false positive rate of the value specified in `rate`.
 77 |     pub fn with_rate(rate: f32, expected_num_items: u32) -> BloomFilter<RandomState, RandomState> {
 78 |         let bits = needed_bits(rate,expected_num_items);
 79 |         BloomFilter::with_size(bits,optimal_num_hashes(bits,expected_num_items))
 80 |     }
 81 | }
 82 | 
 83 | impl<R,S> BloomFilter<R,S>
 84 |     where R: BuildHasher, S: BuildHasher
 85 | {
 86 | 
 87 |     /// Create a new BloomFilter with the specified number of bits,
 88 |     /// hashes, and the two specified HashBuilders.  Note the the
 89 |     /// HashBuilders MUST provide independent hash values.  Passing
 90 |     /// two HashBuilders that produce the same or correlated hash
 91 |     /// values will break the false positive guarantees of the
 92 |     /// BloomFilter.
 93 |     pub fn with_size_and_hashers(num_bits: usize, num_hashes: u32,
 94 |                                  hash_builder_one: R, hash_builder_two: S) -> BloomFilter<R,S> {
 95 |         BloomFilter {
 96 |             bits: BitVec::from_elem(num_bits,false),
 97 |             num_hashes: num_hashes,
 98 |             hash_builder_one: hash_builder_one,
 99 |             hash_builder_two: hash_builder_two,
100 |         }
101 |     }
102 | 
103 |     /// Create a BloomFilter that expects to hold
104 |     /// `expected_num_items`.  The filter will be sized to have a
105 |     /// false positive rate of the value specified in `rate`.  Items
106 |     /// will be hashed using the Hashers produced by
107 |     /// `hash_builder_one` and `hash_builder_two`.  Note the the
108 |     /// HashBuilders MUST provide independent hash values.  Passing
109 |     /// two HashBuilders that produce the same or correlated hash
110 |     /// values will break the false positive guarantees of the
111 |     /// BloomFilter.
112 |     pub fn with_rate_and_hashers(rate: f32, expected_num_items: u32,
113 |                                  hash_builder_one: R, hash_builder_two: S) -> BloomFilter<R, S> {
114 |         let bits = needed_bits(rate,expected_num_items);
115 |         BloomFilter::with_size_and_hashers(bits,optimal_num_hashes(bits,expected_num_items),
116 |                                            hash_builder_one,hash_builder_two)
117 |     }
118 | 
119 |     /// Get the number of bits this BloomFilter is using
120 |     pub fn num_bits(&self) -> usize {
121 |         self.bits.len()
122 |     }
123 | 
124 |     /// Get the number of hash functions this BloomFilter is using
125 |     pub fn num_hashes(&self) -> u32 {
126 |         self.num_hashes
127 |     }
128 | }
129 | 
130 | impl<R,S> ASMS for BloomFilter<R,S>
131 |     where R: BuildHasher, S: BuildHasher {
132 |     /// Insert item into this BloomFilter.
133 |     ///
134 |     /// If the BloomFilter did not have this value present, `true` is returned.
135 |     ///
136 |     /// If the BloomFilter did have this value present, `false` is returned.
137 |     fn insert<T: Hash>(& mut self,item: &T) -> bool {
138 |         let mut contained = true;
139 |         for h in HashIter::from(item,
140 |                                 self.num_hashes,
141 |                                 &self.hash_builder_one,
142 |                                 &self.hash_builder_two) {
143 |             let idx = (h % self.bits.len() as u64) as usize;
144 |             match self.bits.get(idx) {
145 |                 Some(b) => {
146 |                     if !b {
147 |                         contained = false;
148 |                     }
149 |                 }
150 |                 None => { panic!("Hash mod failed in insert"); }
151 |             }
152 |             self.bits.set(idx,true)
153 |         }
154 |         !contained
155 |     }
156 | 
157 |     /// Check if the item has been inserted into this bloom filter.
158 |     /// This function can return false positives, but not false
159 |     /// negatives.
160 |     fn contains<T: Hash>(&self, item: &T) -> bool {
161 |         for h in HashIter::from(item,
162 |                                 self.num_hashes,
163 |                                 &self.hash_builder_one,
164 |                                 &self.hash_builder_two) {
165 |             let idx = (h % self.bits.len() as u64) as usize;
166 |             match self.bits.get(idx) {
167 |                 Some(b) => {
168 |                     if !b {
169 |                         return false;
170 |                     }
171 |                 }
172 |                 None => { panic!("Hash mod failed"); }
173 |             }
174 |         }
175 |         true
176 |     }
177 | 
178 |     /// Remove all values from this BloomFilter
179 |     fn clear(&mut self) {
180 |         self.bits.clear();
181 |     }
182 | }
183 | 
184 | impl Intersectable for BloomFilter {
185 |     /// Calculates the intersection of two BloomFilters.  Only items inserted into both filters will still be present in `self`.
186 |     ///
187 |     /// Both BloomFilters must be using the same number of
188 |     /// bits. Returns true if self changed.
189 |     ///
190 |     /// # Panics
191 |     /// Panics if the BloomFilters are not using the same number of bits
192 |     fn intersect(&mut self, other: &BloomFilter) -> bool {
193 |         self.bits.intersect(&other.bits)
194 |     }
195 | }
196 | 
197 | 
198 | impl Unionable for BloomFilter {
199 |     /// Calculates the union of two BloomFilters.  Items inserted into
200 |     /// either filters will be present in `self`.
201 |     ///
202 |     /// Both BloomFilters must be using the same number of
203 |     /// bits. Returns true if self changed.
204 |     ///
205 |     /// # Panics
206 |     /// Panics if the BloomFilters are not using the same number of bits
207 |     fn union(&mut self, other: &BloomFilter) -> bool {
208 |         self.bits.union(&other.bits)
209 |     }
210 | }
211 | 
212 | 
213 | /// Return the optimal number of hashes to use for the given number of
214 | /// bits and items in a filter
215 | pub fn optimal_num_hashes(num_bits: usize, num_items: u32) -> u32 {
216 |     min(
217 |         max(
218 |             (num_bits as f32 / num_items as f32 * core::f32::consts::LN_2).round() as u32,
219 |              2
220 |            ),
221 |         200
222 |       )
223 | }
224 | 
225 | /// Return the number of bits needed to satisfy the specified false
226 | /// positive rate, if the filter will hold `num_items` items.
227 | pub fn needed_bits(false_pos_rate:f32, num_items: u32) -> usize {
228 |     let ln22 = core::f32::consts::LN_2 * core::f32::consts::LN_2;
229 |     (num_items as f32 * ((1.0/false_pos_rate).ln() / ln22)).round() as usize
230 | }
231 | 
232 | #[cfg(test)]
233 | extern crate rand;
234 | 
235 | #[cfg(feature = "do-bench")]
236 | #[cfg(test)]
237 | mod bench {
238 |     extern crate test;
239 |     use self::test::Bencher;
240 |     use bloom::rand::{self,Rng};
241 | 
242 |     use super::BloomFilter;
243 |     use ASMS;
244 | 
245 |     #[bench]
246 |     fn insert_benchmark(b: &mut Bencher) {
247 |         let cnt = 500000;
248 |         let rate = 0.01 as f32;
249 | 
250 |         let mut bf:BloomFilter = BloomFilter::with_rate(rate,cnt);
251 |         let mut rng = rand::thread_rng();
252 | 
253 |         b.iter(|| {
254 |             let v = rng.gen::<i32>();
255 |             bf.insert(&v);
256 |         })
257 |     }
258 | 
259 |     #[bench]
260 |     fn contains_benchmark(b: &mut Bencher) {
261 |         let cnt = 500000;
262 |         let rate = 0.01 as f32;
263 | 
264 |         let mut bf:BloomFilter = BloomFilter::with_rate(rate,cnt);
265 |         let mut rng = rand::thread_rng();
266 | 
267 |         let mut i = 0;
268 |         while i < cnt {
269 |             let v = rng.gen::<i32>();
270 |             bf.insert(&v);
271 |             i+=1;
272 |         }
273 | 
274 |         b.iter(|| {
275 |             let v = rng.gen::<i32>();
276 |             bf.contains(&v);
277 |         })
278 |     }
279 | }
280 | 
281 | #[cfg(test)]
282 | mod tests {
283 |     use std::collections::HashSet;
284 |     use bloom::rand::{self,Rng};
285 |     use super::{BloomFilter,needed_bits,optimal_num_hashes};
286 |     use {ASMS,Intersectable,Unionable};
287 | 
288 |     #[test]
289 |     fn simple() {
290 |         let mut b:BloomFilter = BloomFilter::with_rate(0.01,100);
291 |         b.insert(&1);
292 |         assert!(b.contains(&1));
293 |         assert!(!b.contains(&2));
294 |         b.clear();
295 |         assert!(!b.contains(&1));
296 |     }
297 | 
298 |     #[test]
299 |     fn intersect() {
300 |         let mut b1:BloomFilter = BloomFilter::with_rate(0.01,20);
301 |         b1.insert(&1);
302 |         b1.insert(&2);
303 |         let mut b2:BloomFilter = BloomFilter::with_rate(0.01,20);
304 |         b2.insert(&1);
305 | 
306 |         b1.intersect(&b2);
307 | 
308 |         assert!(b1.contains(&1));
309 |         assert!(!b1.contains(&2));
310 |     }
311 | 
312 |     #[test]
313 |     fn union() {
314 |         let mut b1:BloomFilter = BloomFilter::with_rate(0.01,20);
315 |         b1.insert(&1);
316 |         let mut b2:BloomFilter = BloomFilter::with_rate(0.01,20);
317 |         b2.insert(&2);
318 | 
319 |         b1.union(&b2);
320 | 
321 |         assert!(b1.contains(&1));
322 |         assert!(b1.contains(&2));
323 |     }
324 | 
325 |     #[test]
326 |     fn fpr_test() {
327 |         let cnt = 500000;
328 |         let rate = 0.01 as f32;
329 | 
330 |         let bits = needed_bits(rate,cnt);
331 |         assert_eq!(bits, 4792529);
332 |         let hashes = optimal_num_hashes(bits,cnt);
333 |         assert_eq!(hashes, 7);
334 | 
335 |         let mut b:BloomFilter = BloomFilter::with_rate(rate,cnt);
336 |         let mut set:HashSet<i32> = HashSet::new();
337 |         let mut rng = rand::thread_rng();
338 | 
339 |         let mut i = 0;
340 | 
341 |         while i < cnt {
342 |             let v = rng.gen::<i32>();
343 |             set.insert(v);
344 |             b.insert(&v);
345 |             i+=1;
346 |         }
347 | 
348 |         i = 0;
349 |         let mut false_positives = 0;
350 |         while i < cnt {
351 |             let v = rng.gen::<i32>();
352 |             match (b.contains(&v),set.contains(&v)) {
353 |                 (true, false) => { false_positives += 1; }
354 |                 (false, true) => { assert!(false); } // should never happen
355 |                 _ => {}
356 |             }
357 |             i+=1;
358 |         }
359 | 
360 |         // make sure we're not too far off
361 |         let actual_rate = false_positives as f32 / cnt as f32;
362 |         assert!(actual_rate > (rate-0.001));
363 |         assert!(actual_rate < (rate+0.001));
364 |     }
365 | }
366 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
  1 |                     GNU GENERAL PUBLIC LICENSE
  2 |                        Version 2, June 1991
  3 | 
  4 |  Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
  5 |  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  6 |  Everyone is permitted to copy and distribute verbatim copies
  7 |  of this license document, but changing it is not allowed.
  8 | 
  9 |                             Preamble
 10 | 
 11 |   The licenses for most software are designed to take away your
 12 | freedom to share and change it.  By contrast, the GNU General Public
 13 | License is intended to guarantee your freedom to share and change free
 14 | software--to make sure the software is free for all its users.  This
 15 | General Public License applies to most of the Free Software
 16 | Foundation's software and to any other program whose authors commit to
 17 | using it.  (Some other Free Software Foundation software is covered by
 18 | the GNU Lesser General Public License instead.)  You can apply it to
 19 | your programs, too.
 20 | 
 21 |   When we speak of free software, we are referring to freedom, not
 22 | price.  Our General Public Licenses are designed to make sure that you
 23 | have the freedom to distribute copies of free software (and charge for
 24 | this service if you wish), that you receive source code or can get it
 25 | if you want it, that you can change the software or use pieces of it
 26 | in new free programs; and that you know you can do these things.
 27 | 
 28 |   To protect your rights, we need to make restrictions that forbid
 29 | anyone to deny you these rights or to ask you to surrender the rights.
 30 | These restrictions translate to certain responsibilities for you if you
 31 | distribute copies of the software, or if you modify it.
 32 | 
 33 |   For example, if you distribute copies of such a program, whether
 34 | gratis or for a fee, you must give the recipients all the rights that
 35 | you have.  You must make sure that they, too, receive or can get the
 36 | source code.  And you must show them these terms so they know their
 37 | rights.
 38 | 
 39 |   We protect your rights with two steps: (1) copyright the software, and
 40 | (2) offer you this license which gives you legal permission to copy,
 41 | distribute and/or modify the software.
 42 | 
 43 |   Also, for each author's protection and ours, we want to make certain
 44 | that everyone understands that there is no warranty for this free
 45 | software.  If the software is modified by someone else and passed on, we
 46 | want its recipients to know that what they have is not the original, so
 47 | that any problems introduced by others will not reflect on the original
 48 | authors' reputations.
 49 | 
 50 |   Finally, any free program is threatened constantly by software
 51 | patents.  We wish to avoid the danger that redistributors of a free
 52 | program will individually obtain patent licenses, in effect making the
 53 | program proprietary.  To prevent this, we have made it clear that any
 54 | patent must be licensed for everyone's free use or not licensed at all.
 55 | 
 56 |   The precise terms and conditions for copying, distribution and
 57 | modification follow.
 58 | 
 59 |                     GNU GENERAL PUBLIC LICENSE
 60 |    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
 61 | 
 62 |   0. This License applies to any program or other work which contains
 63 | a notice placed by the copyright holder saying it may be distributed
 64 | under the terms of this General Public License.  The "Program", below,
 65 | refers to any such program or work, and a "work based on the Program"
 66 | means either the Program or any derivative work under copyright law:
 67 | that is to say, a work containing the Program or a portion of it,
 68 | either verbatim or with modifications and/or translated into another
 69 | language.  (Hereinafter, translation is included without limitation in
 70 | the term "modification".)  Each licensee is addressed as "you".
 71 | 
 72 | Activities other than copying, distribution and modification are not
 73 | covered by this License; they are outside its scope.  The act of
 74 | running the Program is not restricted, and the output from the Program
 75 | is covered only if its contents constitute a work based on the
 76 | Program (independent of having been made by running the Program).
 77 | Whether that is true depends on what the Program does.
 78 | 
 79 |   1. You may copy and distribute verbatim copies of the Program's
 80 | source code as you receive it, in any medium, provided that you
 81 | conspicuously and appropriately publish on each copy an appropriate
 82 | copyright notice and disclaimer of warranty; keep intact all the
 83 | notices that refer to this License and to the absence of any warranty;
 84 | and give any other recipients of the Program a copy of this License
 85 | along with the Program.
 86 | 
 87 | You may charge a fee for the physical act of transferring a copy, and
 88 | you may at your option offer warranty protection in exchange for a fee.
 89 | 
 90 |   2. You may modify your copy or copies of the Program or any portion
 91 | of it, thus forming a work based on the Program, and copy and
 92 | distribute such modifications or work under the terms of Section 1
 93 | above, provided that you also meet all of these conditions:
 94 | 
 95 |     a) You must cause the modified files to carry prominent notices
 96 |     stating that you changed the files and the date of any change.
 97 | 
 98 |     b) You must cause any work that you distribute or publish, that in
 99 |     whole or in part contains or is derived from the Program or any
100 |     part thereof, to be licensed as a whole at no charge to all third
101 |     parties under the terms of this License.
102 | 
103 |     c) If the modified program normally reads commands interactively
104 |     when run, you must cause it, when started running for such
105 |     interactive use in the most ordinary way, to print or display an
106 |     announcement including an appropriate copyright notice and a
107 |     notice that there is no warranty (or else, saying that you provide
108 |     a warranty) and that users may redistribute the program under
109 |     these conditions, and telling the user how to view a copy of this
110 |     License.  (Exception: if the Program itself is interactive but
111 |     does not normally print such an announcement, your work based on
112 |     the Program is not required to print an announcement.)
113 | 
114 | These requirements apply to the modified work as a whole.  If
115 | identifiable sections of that work are not derived from the Program,
116 | and can be reasonably considered independent and separate works in
117 | themselves, then this License, and its terms, do not apply to those
118 | sections when you distribute them as separate works.  But when you
119 | distribute the same sections as part of a whole which is a work based
120 | on the Program, the distribution of the whole must be on the terms of
121 | this License, whose permissions for other licensees extend to the
122 | entire whole, and thus to each and every part regardless of who wrote it.
123 | 
124 | Thus, it is not the intent of this section to claim rights or contest
125 | your rights to work written entirely by you; rather, the intent is to
126 | exercise the right to control the distribution of derivative or
127 | collective works based on the Program.
128 | 
129 | In addition, mere aggregation of another work not based on the Program
130 | with the Program (or with a work based on the Program) on a volume of
131 | a storage or distribution medium does not bring the other work under
132 | the scope of this License.
133 | 
134 |   3. You may copy and distribute the Program (or a work based on it,
135 | under Section 2) in object code or executable form under the terms of
136 | Sections 1 and 2 above provided that you also do one of the following:
137 | 
138 |     a) Accompany it with the complete corresponding machine-readable
139 |     source code, which must be distributed under the terms of Sections
140 |     1 and 2 above on a medium customarily used for software interchange; or,
141 | 
142 |     b) Accompany it with a written offer, valid for at least three
143 |     years, to give any third party, for a charge no more than your
144 |     cost of physically performing source distribution, a complete
145 |     machine-readable copy of the corresponding source code, to be
146 |     distributed under the terms of Sections 1 and 2 above on a medium
147 |     customarily used for software interchange; or,
148 | 
149 |     c) Accompany it with the information you received as to the offer
150 |     to distribute corresponding source code.  (This alternative is
151 |     allowed only for noncommercial distribution and only if you
152 |     received the program in object code or executable form with such
153 |     an offer, in accord with Subsection b above.)
154 | 
155 | The source code for a work means the preferred form of the work for
156 | making modifications to it.  For an executable work, complete source
157 | code means all the source code for all modules it contains, plus any
158 | associated interface definition files, plus the scripts used to
159 | control compilation and installation of the executable.  However, as a
160 | special exception, the source code distributed need not include
161 | anything that is normally distributed (in either source or binary
162 | form) with the major components (compiler, kernel, and so on) of the
163 | operating system on which the executable runs, unless that component
164 | itself accompanies the executable.
165 | 
166 | If distribution of executable or object code is made by offering
167 | access to copy from a designated place, then offering equivalent
168 | access to copy the source code from the same place counts as
169 | distribution of the source code, even though third parties are not
170 | compelled to copy the source along with the object code.
171 | 
172 |   4. You may not copy, modify, sublicense, or distribute the Program
173 | except as expressly provided under this License.  Any attempt
174 | otherwise to copy, modify, sublicense or distribute the Program is
175 | void, and will automatically terminate your rights under this License.
176 | However, parties who have received copies, or rights, from you under
177 | this License will not have their licenses terminated so long as such
178 | parties remain in full compliance.
179 | 
180 |   5. You are not required to accept this License, since you have not
181 | signed it.  However, nothing else grants you permission to modify or
182 | distribute the Program or its derivative works.  These actions are
183 | prohibited by law if you do not accept this License.  Therefore, by
184 | modifying or distributing the Program (or any work based on the
185 | Program), you indicate your acceptance of this License to do so, and
186 | all its terms and conditions for copying, distributing or modifying
187 | the Program or works based on it.
188 | 
189 |   6. Each time you redistribute the Program (or any work based on the
190 | Program), the recipient automatically receives a license from the
191 | original licensor to copy, distribute or modify the Program subject to
192 | these terms and conditions.  You may not impose any further
193 | restrictions on the recipients' exercise of the rights granted herein.
194 | You are not responsible for enforcing compliance by third parties to
195 | this License.
196 | 
197 |   7. If, as a consequence of a court judgment or allegation of patent
198 | infringement or for any other reason (not limited to patent issues),
199 | conditions are imposed on you (whether by court order, agreement or
200 | otherwise) that contradict the conditions of this License, they do not
201 | excuse you from the conditions of this License.  If you cannot
202 | distribute so as to satisfy simultaneously your obligations under this
203 | License and any other pertinent obligations, then as a consequence you
204 | may not distribute the Program at all.  For example, if a patent
205 | license would not permit royalty-free redistribution of the Program by
206 | all those who receive copies directly or indirectly through you, then
207 | the only way you could satisfy both it and this License would be to
208 | refrain entirely from distribution of the Program.
209 | 
210 | If any portion of this section is held invalid or unenforceable under
211 | any particular circumstance, the balance of the section is intended to
212 | apply and the section as a whole is intended to apply in other
213 | circumstances.
214 | 
215 | It is not the purpose of this section to induce you to infringe any
216 | patents or other property right claims or to contest validity of any
217 | such claims; this section has the sole purpose of protecting the
218 | integrity of the free software distribution system, which is
219 | implemented by public license practices.  Many people have made
220 | generous contributions to the wide range of software distributed
221 | through that system in reliance on consistent application of that
222 | system; it is up to the author/donor to decide if he or she is willing
223 | to distribute software through any other system and a licensee cannot
224 | impose that choice.
225 | 
226 | This section is intended to make thoroughly clear what is believed to
227 | be a consequence of the rest of this License.
228 | 
229 |   8. If the distribution and/or use of the Program is restricted in
230 | certain countries either by patents or by copyrighted interfaces, the
231 | original copyright holder who places the Program under this License
232 | may add an explicit geographical distribution limitation excluding
233 | those countries, so that distribution is permitted only in or among
234 | countries not thus excluded.  In such case, this License incorporates
235 | the limitation as if written in the body of this License.
236 | 
237 |   9. The Free Software Foundation may publish revised and/or new versions
238 | of the General Public License from time to time.  Such new versions will
239 | be similar in spirit to the present version, but may differ in detail to
240 | address new problems or concerns.
241 | 
242 | Each version is given a distinguishing version number.  If the Program
243 | specifies a version number of this License which applies to it and "any
244 | later version", you have the option of following the terms and conditions
245 | either of that version or of any later version published by the Free
246 | Software Foundation.  If the Program does not specify a version number of
247 | this License, you may choose any version ever published by the Free Software
248 | Foundation.
249 | 
250 |   10. If you wish to incorporate parts of the Program into other free
251 | programs whose distribution conditions are different, write to the author
252 | to ask for permission.  For software which is copyrighted by the Free
253 | Software Foundation, write to the Free Software Foundation; we sometimes
254 | make exceptions for this.  Our decision will be guided by the two goals
255 | of preserving the free status of all derivatives of our free software and
256 | of promoting the sharing and reuse of software generally.
257 | 
258 |                             NO WARRANTY
259 | 
260 |   11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
261 | FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
262 | OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
263 | PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
264 | OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
265 | MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
266 | TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
267 | PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
268 | REPAIR OR CORRECTION.
269 | 
270 |   12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
271 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
272 | REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
273 | INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
274 | OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
275 | TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
276 | YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
277 | PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
278 | POSSIBILITY OF SUCH DAMAGES.
279 | 
280 |                      END OF TERMS AND CONDITIONS
281 | 
282 |             How to Apply These Terms to Your New Programs
283 | 
284 |   If you develop a new program, and you want it to be of the greatest
285 | possible use to the public, the best way to achieve this is to make it
286 | free software which everyone can redistribute and change under these terms.
287 | 
288 |   To do so, attach the following notices to the program.  It is safest
289 | to attach them to the start of each source file to most effectively
290 | convey the exclusion of warranty; and each file should have at least
291 | the "copyright" line and a pointer to where the full notice is found.
292 | 
293 |     <one line to give the program's name and a brief idea of what it does.>
294 |     Copyright (C) <year>  <name of author>
295 | 
296 |     This program is free software; you can redistribute it and/or modify
297 |     it under the terms of the GNU General Public License as published by
298 |     the Free Software Foundation; either version 2 of the License, or
299 |     (at your option) any later version.
300 | 
301 |     This program is distributed in the hope that it will be useful,
302 |     but WITHOUT ANY WARRANTY; without even the implied warranty of
303 |     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
304 |     GNU General Public License for more details.
305 | 
306 |     You should have received a copy of the GNU General Public License along
307 |     with this program; if not, write to the Free Software Foundation, Inc.,
308 |     51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
309 | 
310 | Also add information on how to contact you by electronic and paper mail.
311 | 
312 | If the program is interactive, make it output a short notice like this
313 | when it starts in an interactive mode:
314 | 
315 |     Gnomovision version 69, Copyright (C) year name of author
316 |     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
317 |     This is free software, and you are welcome to redistribute it
318 |     under certain conditions; type `show c' for details.
319 | 
320 | The hypothetical commands `show w' and `show c' should show the appropriate
321 | parts of the General Public License.  Of course, the commands you use may
322 | be called something other than `show w' and `show c'; they could even be
323 | mouse-clicks or menu items--whatever suits your program.
324 | 
325 | You should also get your employer (if you work as a programmer) or your
326 | school, if any, to sign a "copyright disclaimer" for the program, if
327 | necessary.  Here is a sample; alter the names:
328 | 
329 |   Yoyodyne, Inc., hereby disclaims all copyright interest in the program
330 |   `Gnomovision' (which makes passes at compilers) written by James Hacker.
331 | 
332 |   <signature of Ty Coon>, 1 April 1989
333 |   Ty Coon, President of Vice
334 | 
335 | This General Public License does not permit incorporating your program into
336 | proprietary programs.  If your program is a subroutine library, you may
337 | consider it more useful to permit linking proprietary applications with the
338 | library.  If this is what you want to do, use the GNU Lesser General
339 | Public License instead of this License.
340 | 


--------------------------------------------------------------------------------