SwiftRoaring

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

Roaring bitmaps are used by several important systems:

• Apache Lucene and derivative systems such as Solr and Elastic,
• Metamarkets' Druid,
• Apache Spark,
• Netflix Atlas,
• LinkedIn Pinot,
• OpenSearchServer,
• Cloud Torrent,
• Whoosh,
• Pilosa,
• Microsoft Visual Studio Team Services (VSTS),
• eBay's Apache Kylin.

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)

Dependencies

Swift 4.0 or higher

Usage using Swift Package Manager

Create a directory where you will create your application:

mkdir foo
cd foo
swift package init --type executable

Then edit Package.swift so that it reads something like this:

import PackageDescription

let package = Package(
    name: "foo",
    dependencies: [
   .package(url: "https://github.com/RoaringBitmap/SwiftRoaring",  from: "0.0.1")
    ],
    targets: [
        .target(
            name: "foo",
            dependencies: ["SwiftRoaring"]),
    ]
)

Edit main.swift (in Sources) so that it looks something like this :

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!

64-bit bitmaps

RoaringBitmap stores UInt32 values. To store UInt64 values, use Roaring64Bitmap, which offers the same API:

import SwiftRoaring

let bitmap: Roaring64Bitmap = [1, 1 << 32, UInt64.max]

bitmap.add(1_000...2_000)
print(bitmap.count)                 // 1004
print(bitmap.contains(1 << 32))     // true

//Set operations, ranges, rank/select, iterators and
//serialization all work as they do in 32 bits.
let other = Roaring64Bitmap(range: 0..<1_000_000, step: 7)
let common = bitmap & other

//Convert a 32-bit bitmap to a 64-bit one
let widened = Roaring64Bitmap(RoaringBitmap([1, 2, 3]))

Development

You can build using Swift Package Manager as follows:

swift build  --configuration release

To find where the library is built, type the following in your shell:

 echo $(swift build   --configuration release  --show-bin-path)

You can run tests using Swift Package Manager as follows:

swift test

Interactive use

$ swift build  --configuration release
$ swift repl -I .build/release -L .build/release -lSwiftRoaringDynamic
  1> import SwiftRoaring
  2> let bitmap = RoaringBitmap()
  3> bitmap.add(1)
  4> for i in bitmap {
       print(i)
     }

Mailing list/discussion group

https://groups.google.com/g/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