/ 
Bit-Set-0.07
/ Bit::Set::OO

NAME

Bit::Set::OO - Perl Object Oriented (OO) interface to the 'bit' C library

VERSION

version 0.07

SYNOPSIS

use Bit::Set::OO;         ## OO interface to Bit C library
use Bit::Set qw(:all);    ## Procedural interface to Bit C library
                          ## (but do you need this if you use OO?)

# Create a new bitset
my $set = Bit::Set::OO->new(1024);

# Set some bits
$set->bset(0);
$set->bset(42);

# Get population count
my $count = $set->count();

# Free the bitset
undef $set;

DESCRIPTION

This module provides an OO Perl interface to the C library Bit, for creating and manipulating bitsets. The interface mirrors the procedural interface provided by Bit::Set, with methods corresponding to the functions in that module.

As currently implemented the OO interfaces are currently layered on top of the procedural API, and thus incur some overhead compared to direct calls to the procedural API.

Methods

The methods in the Bit::Set::OO module are grouped into several categories for clarity, as described below. The method names correspond to the function names in the procedural interface without the Bit_ prefix. Note that the methods are created in the Bit::Set namespace.

Creation

Bit::Set->new(length)

Creates a new bitset with the specified capacity (=length) in bits. The object is of type Bit::Set (not Bit::Set::OO).

Bit::Set->load(length, buffer)

Loads an externally allocated bitset into a new Bit_T structure in C and returns it as a Perl object of type Bit::Set.

$bitset->extract(buffer)

Extracts the bitset from a Bit_T into an externally allocated buffer. Look at EXAMPLES for usage of the load and extract functions using FFI::Platypus.

Properties

Bit::Set->buffer_size(length)

Returns the number of bytes needed to store a bitset of given length.

$bitset->length() Returns the length (capacity) of the bitset in bits.
$bitset->count()

Returns the population count (number of set bits) of the bitset.

Manipulation

$bitset->aset(indices, n)

Sets an array of bits specified by indices.

$bitset->bset(index)

Sets a single bit at the specified index to 1.

$bitset->aclear(indices, n)

Clears an array of bits specified by indices.

$bitset->bclear(index)

Clears a single bit at the specified index to 0.

$bitset->clear(lo, hi)

Clears a range of bits from lo to hi (inclusive).

$bitset->get(index)

Returns the value of the bit at the specified index.

$bitset->not(lo, hi)

Inverts a range of bits from lo to hi (inclusive).

$bitset->put(n, val)

Sets the nth bit to val and returns the previous value.

$bitset->set(lo, hi)

Sets a range of bits from lo to hi (inclusive) to 1.

Comparisons

$bitset->eq(other)

Returns 1 if the bitset other is equal to this bitset, 0 otherwise.

$bitset->leq(other)

Returns 1 if this bitset is a subset of or equal to other, 0 otherwise.

$bitset->lt(other)

Returns 1 if this bitset is a proper subset of other, 0 otherwise.

Set Operations

$bitset->diff(other)

Returns a new bitset containing the difference of this bitset and other.

$bitset->inter(other)

Returns a new bitset containing the intersection of this bitset and other .

$bitset->minus(other)

Returns a new bitset containing the symmetric difference of this bitset and other.

$bitset->union(other)

Returns a new bitset containing the union of this bitset and other.

Set Operation Counts

$bitset->diff_count(other)

Returns the population count of the difference of this bitset and other without creating a new bitset.

$bitset->inter_count(other)

Returns the population count of the intersection of this bitset and other without creating a new bitset.

$bitset->minus_count(other)

Returns the population count of the symmetric difference of this bitset and other without creating a new bitset.

$bitset->union_count(other)

Returns the population count of the union of this bitset and other without creating a new bitset.

EXAMPLES

Examples of the use of the Bit::Set::OO module. These examples are the OO "traslations" of examples in the Bit::Set module.

Example 1: Creating and using a bitset

Simple example in which we create, set and test for setting of individual bits into a bitset.

use Bit::Set::OO;    ## OO interface to Bit C library

my $bitset = Bit::Set->new(64);
$bitset->set(1);
$bitset->set(3);
$bitset->set(5);

print "Bit 1 is ", $bitset->get(1) ? "set" : "not set", "\n";
print "Bit 2 is ", $bitset->get(2) ? "set" : "not set", "\n";
print "Bit 3 is ", $bitset->get(3) ? "set" : "not set", "\n";

undef $bitset;  ## free the bitset
Example 2: Comparison operations between bitsets

This example illustrates the use of the comparison functions provided by the Bit::Set::OO module. The equality comparison function is shown for simplicity, but the example can serve as blue print for other comparisons functions e.g. less than equal to.

use Bit::Set::OO;    ## OO interface to Bit C library

my $set1 = Bit::Set->new(64);
my $set2 = Bit::Set->new(64);

$set1->set(1);
$set1->set(3);
$set1->set(5);

$set2->set(1);
$set2->set(3);
$set2->set(5);

if ( $set1->eq($set2) ) {
    print "The two bitsets are equal\n";
} else {
    print "The two bitsets are not equal\n";
}

undef $set1;
undef $set2;

SEE ALSO

Alien::Bit

This distribution provides the library Bit so that it can be used by other Perl distributions that are on CPAN. It will download Bit from Github and will build the (static and dynamic) versions of the library for use by other Perl modules.

Bit

Bit is a high-performance, uncompressed bitset implementation in C, optimized for modern architectures. The library provides an efficient way to create, manipulate, and query bitsets with a focus on performance and memory alignment. The API and the interface is largely based on David Hanson's Bit_T library discussed in Chapter 13 of "C Interfaces and Implementations", Addison-Wesley ISBN 0-201-49841-3 extended to incorporate additional operations (such as counts on unions/differences/intersections of sets), fast population counts using the libpocnt library and GPU operations for packed containers of (collections) of Bit(sets).

Bit::Set

Bit::Set is a Perl module that provides a high-level procedural interface for working with bitsets. It is built on top of the Bit library and offers a more user-friendly Perl API for common bitset operations.

TO DO

Implement Performant Object Oriented interfaces

Explore Joe Scahefer's sealed in order to create efficient OO interfaces without the overhead of traditional Perl OO systems by "sealing" the methods at compile time. Subroutine attribute for compile-time method lookups on its typed lexicals. As Joe points out:

"Perl 5s OO runtime method lookup has 50% more performance overhead than a 
direct, named subroutine invocation."

Doug MacEachern proposed a very solution which however never made it into the core. Joe's sealed package implements Doug's idea in a modern way, allowing the creation of efficient OO interfaces without the overhead of traditional Perl OO systems by "sealing" the methods at compile time.

AUTHOR

Christos Argyropoulos.

COPYRIGHT AND LICENSE

This software is copyright (c) 2025 by Christos Argyropoulos.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.