croaring 0.0.2
Compressed integer sets based on Roaring bitmaps.
License: UNLICENSE

CRoaring.py: Fast, compact integer bitmap sets, based on CRoaring
=================================================================

`Roaring bitmaps <http://roaringbitmap.org/>`__ are fast, compressed,
and portable bitmaps, used to store unique sorted integer sets. These
bitmaps offer better real-world space complexity and performance than
typical hash sets (such as Python's built-in ``set``), and can be
serialized into a portable format for storage and interop with the
C/C++, Java and Go libraries.

This library makes the
`CRoaring <https://github.com/RoaringBitmap/CRoaring>`__ implementation
available in Python 2.7 and 3.5+. It uses
`CFFI <http://cffi.readthedocs.io/en/latest/>`__, so it works on both
CPython and PyPy. The full Python ``set`` interface is implemented.
Comprehensive tests are included.

Installation
------------

::

    pip install croaring

The CRoaring source is included with the Python library, so you don't
need to install it from elsewhere (though you may need a C compiler
available if a binary package is unavailable for your architecture).

Usage
-----

Instantiate a ``croaring.RoaringBitmap()``, and use it just like a
normal ``set``:

::

    >>> import croaring
    >>> bitmap = croaring.RoaringBitmap()
    >>> bitmap
    RoaringBitmap([])
    >>> bitmap.add(1)
    >>> bitmap.add(4572)
    >>> bitmap.add(326)
    >>> bitmap
    RoaringBitmap([1, 326, 4572])

You can use either binary operators (``|``, ``&``, ``^`` and ``-``) or
their English names (``union``, ``intersection``,
``symmetric_difference`` and ``difference``):

::

    >>> bitmap | RoaringBitmap([50, 95])
    RoaringBitmap([1, 50, 95, 326, 4572])
    >>> bitmap & RoaringBitmap([200, 326])
    RoaringBitmap([326])
    >>> bitmap ^ RoaringBitmap([200, 326])
    RoaringBitmap([1, 200, 4572])

Since the bitmaps are ordered, indexing (including negative) is
supported:

::

    >>> bitmap[1]
    326
    >>> bitmap[-1]
    4572

Finally, you can construct a bitmap from a range, similar to the
arguments to Python's built-in ``range``:

::

    >>> RoaringBitmap.range(10)
    RoaringBitmap([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
    >>> RoaringBitmap.range(2, 10)
    RoaringBitmap([2, 3, 4, 5, 6, 7, 8, 9])
    >>> RoaringBitmap.range(2, 10, 3)
    RoaringBitmap([2, 5, 8])

License
-------

CRoaring is licensed under the Apache License v2.0:

    Copyright 2016 The CRoaring authors

    Licensed under the Apache License, Version 2.0 (the "License"); you
    may not use this file except in compliance with the License. You may
    obtain a copy of the License at

    ::

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
    implied. See the License for the specific language governing
    permissions and limitations under the License.

All other code is released under the Unlicense:

    This is free and unencumbered software released into the public
    domain.

    Anyone is free to copy, modify, publish, use, compile, sell, or
    distribute this software, either in source code form or as a
    compiled binary, for any purpose, commercial or non-commercial, and
    by any means.

    In jurisdictions that recognize copyright laws, the author or
    authors of this software dedicate any and all copyright interest in
    the software to the public domain. We make this dedication for the
    benefit of the public at large and to the detriment of our heirs and
    successors. We intend this dedication to be an overt act of
    relinquishment in perpetuity of all present and future rights to
    this software under copyright law.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
    CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

    For more information, please refer to http://unlicense.org/