# ***********************************************
# 
# !!!! DO NOT EDIT !!!!
# 
# This file was auto-generated by Build.PL.
# 
# ***********************************************
# 
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements.  See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You 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.

=encoding utf8

=head1 NAME

Lucy::Object::BitVector - An array of bits.

=head1 SYNOPSIS

    my $bit_vec = Lucy::Object::BitVector->new( capacity => 8 );
    my $other   = Lucy::Object::BitVector->new( capacity => 8 );
    $bit_vec->set($_) for ( 0, 2, 4, 6 );
    $other->set($_)   for ( 1, 3, 5, 7 );
    $bit_vec->or($other);
    print "$_\n" for @{ $bit_vec->to_array };    # prints 0 through 7.

=head1 DESCRIPTION

BitVector is a growable array of bits.  All bits are initially zero.

=head1 CONSTRUCTORS

=head2 new

    my $bit_vec = Lucy::Object::BitVector->new( 
        capacity => $doc_max + 1,   # default 0,
    );

Create a new BitVector.

=over

=item *

B<capacity> - The number of bits that the initial array should be
able to hold.

=back

=head1 METHODS

=head2 get

    my $bool = $bit_vector->get($tick);

Return true if the bit at C<tick> has been set, false if it
hasn’t (regardless of whether it lies within the bounds of the
object’s capacity).

=over

=item *

B<tick> - The requested bit.

=back

=head2 set

    $bit_vector->set($tick);

Set the bit at C<tick> to 1.

=over

=item *

B<tick> - The bit to be set.

=back

=head2 next_hit

    my $int = $bit_vector->next_hit($tick);

Returns the next set bit equal to or greater than C<tick>,
or -1 if no such bit exists.

=head2 clear

    $bit_vector->clear($tick);

Clear the indicated bit. (i.e. set it to 0).

=over

=item *

B<tick> - The bit to be cleared.

=back

=head2 clear_all

    $bit_vector->clear_all();

Clear all bits.

=head2 grow

    $bit_vector->grow($capacity);

If the BitVector does not already have enough room to hold the
indicated number of bits, allocate more memory so that it can.

=over

=item *

B<capacity> - Least number of bits the BitVector should accomodate.

=back

=head2 and

    $bit_vector->and($other);

Modify the BitVector so that only bits which remain set are those
which 1) were already set in this BitVector, and 2) were also set in
the other BitVector.

=over

=item *

B<other> - Another BitVector.

=back

=head2 or

    $bit_vector->or($other);

Modify the BitVector, setting all bits which are set in the other
BitVector if they were not already set.

=over

=item *

B<other> - Another BitVector.

=back

=head2 xor

    $bit_vector->xor($other);

Modify the BitVector, performing an XOR operation against the other.

=over

=item *

B<other> - Another BitVector.

=back

=head2 and_not

    $bit_vector->and_not($other);

Modify the BitVector, clearing all bits which are set in the other.

=over

=item *

B<other> - Another BitVector.

=back

=head2 flip

    $bit_vector->flip($tick);

Invert the value of a bit.

=over

=item *

B<tick> - The bit to invert.

=back

=head2 flip_block

    $bit_vector->flip_block(
        offset => $offset  # required
        length => $length  # required
    );

Invert each bit within a contiguous block.

=over

=item *

B<offset> - Lower bound.

=item *

B<length> - The number of bits to flip.

=back

=head2 count

    my $int = $bit_vector->count();

Return a count of the number of set bits.

=head2 to_array

    my $i32_array = $bit_vector->to_array();

Return an array where each element represents a set bit.

=head2 clone

    my $result = $bit_vector->clone();

Return a clone of the object.

=head1 INHERITANCE

Lucy::Object::BitVector isa Clownfish::Obj.

=cut

