A better compressed bitset in Swift
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
Scripts
Sources
Tests
.gitignore
.travis.yml
AUTHORS
Cartfile
Cartfile.resolved
LICENSE
Package.swift
README.md
codecov.yml

README.md

SwiftRoaring

Swift 4 compatible Carthage compatible Build Status codecov

Swift wrapper for CRoaring (a C/C++ implementation at https://github.com/RoaringBitmap/CRoaring)

Roaring bitmaps are used by several important systems:

Roaring bitmaps are found to work well in many important applications:

Use Roaring for bitmap compression whenever possible. Do not use other bitmap compression methods (Wang et al., SIGMOD 2017)

Benchmarking

There is an entire repository dedicated to benchmarking. You can find it here.

The following benchmarks were produced using this CPU model: Intel(R) Core(TM) i7-4770 CPU @ 3.40GHz

The following benchmarks were produced using this CPU model: Intel(R) Core(TM) i7-8700 CPU @ 3.20GHz

Dependencies

Swift 4.0 or higher

Usage

1. Intall SwiftRoaring

  • With Swift Package Manager:

    Edit Package.swift so that it reads something like this:

    import PackageDescription
    
    let package = Package(
        name: "foo",
        dependencies: [
            .package(url: "https://github.com/piotte13/SwiftRoaring",  from: "1.0.4")
        ],
        targets: [
            .target(
                name: "foo",
                dependencies: ["SwiftRoaring"]),
        ]
    )
  • With Carthage:
    github "piotte13/SwiftRoaring"

2. Import SwiftRoaring in your project

import SwiftRoaring;

....

Example

Here is a simplified but complete example:

import SwiftRoaring

//Create a new Roaring Bitmap
let bitmap = RoaringBitmap()

//Example: Add Range
bitmap.addRange(min: 0, max: 500)

//Example: copy
let cpy = bitmap.copy()

//Example: Operators
let and = bitmap && cpy

//Example: Iterate
for i in bitmap {
    print(i)
}

//See documentation for more functionalities!

Documentation

https://piotte13.github.io/SwiftRoaring/

Development

You can build using Swift Package Manager as follows:

swift build  -Xcc -march=native  --configuration release
$(swift build   --configuration release  --show-bin-path)/fun

You can run tests using Swift Package Manager as follows:

swift test

Interactive use

$ swift build  -Xcc -march=native  --configuration release
$ swift -I .build/release -L .build/release -lSwiftRoaringDynamic
  1> import SwiftRoaring
  2> let bitmap = RoaringBitmap()
  3> bitmap.add(1)

Mailing list/discussion group

https://groups.google.com/forum/#!forum/roaring-bitmaps

Compatibility with Java RoaringBitmap library

You can read bitmaps in Go, Java, C, C++ that have been serialized in Java, C, C++.

References

  • Daniel Lemire, Owen Kaser, Nathan Kurz, Luca Deri, Chris O'Hara, François Saint-Jacques, Gregory Ssi-Yan-Kai, Software: Practice and Experience Volume 48, Issue 4 April 2018 Pages 867-895 arXiv:1709.07821
  • Samy Chambi, Daniel Lemire, Owen Kaser, Robert Godin, Better bitmap performance with Roaring bitmaps, Software: Practice and Experience Volume 46, Issue 5, pages 709–719, May 2016 http://arxiv.org/abs/1402.6407 This paper used data from http://lemire.me/data/realroaring2014.html
  • Daniel Lemire, Gregory Ssi-Yan-Kai, Owen Kaser, Consistently faster and smaller compressed bitmaps with Roaring, Software: Practice and Experience Volume 46, Issue 11, pages 1547-1569, November 2016 http://arxiv.org/abs/1603.06549