/*
* A1BitSet.h
* BitArray is a framework that provides a scalable class that uses sparse allocation for
* addressing disjoint bits sets. This is an ideal framework for handling large amounts of
* preferences or as a front end to large data sets that need sparse indexes.
*
* Created by frankcastellucci on 1/3/11.
* Copyright 2011 Axiom:1, Inc. All rights reserved. (mailto:information@axiom1inc.com)
*
* This file is part of BitArray.
* BitArray is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
* BitArray is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* called "COPYING" along with BitArray. If not, see <http://www.gnu.org/licenses/>.
*
*/
#import <Foundation/Foundation.h>
/*!
@header A1BitArray
@abstract Bit array that supports sparse addressing and extents
@discussion A1BitArray enables the use of large bit blocks. The base array holds 1024 bits
and, using the appropriate initializer, can support extents. Users can also specify the
size of extents
*/
/*!
@const
@abstract com.axiom1.BitArray.BitArrayError
*/
FOUNDATION_EXPORT NSString *const BitArrayErrorDomain;
/*!
@enum
@abstract BitArray potential errors
@constant BitArrayUnknownError not used... and hopefully never will be!
@constant BitIndexOutOfRange a supplied bit index is not in the base or extents arrays
@constant UnableToAllocateExtent a allocation failure occured when attempting to 'fault' in an extent
@constant UnableToIncreaseExtentControl the newly faulted extent can't be added to the internal control structure
@constant NullInstanceError a null BitArray was sent in a message, but the operation requires a valid instance
*/
enum BitArrayErrors {
BitArrayUnknownError= 1,
BitIndexOutOfRange = 100,
UnableToAllocateExtent = 200,
UnableToIncreaseExtentControl = 210,
NullInstanceError = 300
};
@interface A1BitArray : NSObject<NSCopying,NSCoding> {
@private
void *control;
}
#pragma mark -
#pragma mark Initializers
/*!
@method initWithExtentsAllowed
@abstract Initializes bit array to allow automatic extent creation
@discussion Bit arrays initialized with extent support enable the instance to
create a block of bits if you address a location (using clearBit or setBit)
that is not already part of the array. Unlike other array types, these
addresses (bits) do not allocate filler memory to make it contigous with
the base array (sparse).
@result A1BitArray initialzed to support extents
*/
- (id) initWithExtentsAllowed;
/*!
@method initWithExtentSize:
@abstract Initializes bit array to support extents of size extentSizeInBytes
@discussion The default extent size, 128 bytes (1024 bits), may not be the right size
given the use of the instance. The caller may specify the size of the
extents, in bytes. The supplied value is rounded to 64 bytes, so the
minimum block the instance allocates will be 512 bits in size.
@param extentSizeInBytes Number of bytes in extent size
@result A1BitArray iniitialized to support extents of a byte size provided by
the caller, rounded to multiples of 64 bytes.
*/
- (id) initWithExtentSize:(unsigned short) extentSizeInBytes;
#pragma mark -
#pragma mark Accessors
/*!
@method dirty
@abstract Whether the instance has been modified
@discussion For the standard 'init', the dirty flag is set to YES until, if ever,
it is encoded. All clear and set mutators raise the dirty flag as well as creation of
extents.
@result YES if instance has been modified
*/
- (BOOL) dirty;
/*!
@method bytesInBase
@abstract The base array is a fixed block
@result Total bytes in the base array
*/
- (NSUInteger) bytesInBase;
/*!
@method bitsInBase
@abstract The base array is a fixed block
@result Total number of bits in the base array
*/
- (NSUInteger) bitsInBase;
/*!
@method extentsAllowed
@abstract Determines if this instance can create extents
@result YES if extents are allowed, NO if not
*/
- (BOOL) extentsAllowed;
/*!
@method extentCount
@abstract The number of extents in this instance
@result 0 or more based on usage
*/
- (NSUInteger) extentCount;
/*!
@method bytesInExtent
@abstract Number of bytes used for new extents
@result 0 if not initialized with extents, otherwise size in bytes
*/
- (NSUInteger) bytesInExtent;
/*!
@method bitsInExtent
@abstract Number of bit used for new extents
@result 0 if not initialized with extents, otherwise size in bits
*/
- (NSUInteger) bitsInExtent;
/*!
@method bit:error
@abstract Returns the state of the bit specified at bitIndex
@discussion For this implementation, if a bit is outside the
array (either the base or extents) you will not get an error
and the result will be NO (i.e. clear). Theoretically
I've decided that it too would be clear!
@result YES is bit is set, NO if clear
*/
- (BOOL) bit:(NSUInteger) bitIndex error:(NSError **)err;
#pragma mark -
#pragma mark Mutators
/*!
@method clearBit:error:
@abstract Clears a bit at a given location
@discussion If the bit index is outside of the base range
or, if initialzed with extents, outside any extents a new
extent will be created
@param bitIndex the location of the bit to clear
@param err an error encountered in the operation
*/
- (void) clearBit:(NSUInteger) bitIndex error:(NSError **) err;
/*!
@method clear
@abstract Clears all the bits in the instance base array only.
*/
- (void) clear;
/*!
@method clearExtentWithBit:error:
@abstract Clears the bits in an extent
@discussion This locates the extent that the bit lives in
and clears all bits in the extent. If not found (not exist) an
extent will be created
@param bitIndex the bit in the extent you want to clear
@param err an error encountered in the operation
*/
- (void) clearExtentWithBit:(NSUInteger) bitIndex error:(NSError **)err;
/*!
@method setBit:error:
@abstract Sets a bit at a given location
@discussion If the bit index is outside of the base range
or, if initialzed with extents, outside any extents a new
extent will be created
@param bitIndex the location of the bit to set
@param err an error encountered in the operation
*/
- (void) setBit:(NSUInteger) bitIndex error:(NSError **) err;
/*!
@method set
@abstract Sets all the bits in the instance base array only.
*/
- (void) set;
/*!
@method setExtentWithBit:error:
@abstract Sets the bits in an extent
@discussion This locates the extent that the bit lives in
and sets all bits in the extent. If not found (not exist) an
extent will be created
@param bitIndex the bit in the extent you want to set
@param err an error encountered in the operation
*/
- (void) setExtentWithBit:(NSUInteger) bitIndex error:(NSError **)err;
#pragma mark -
#pragma mark Unions Intersections and Complements
- (A1BitArray *) arrayFromUnionWith:(A1BitArray *)secondBitArray error:(NSError **)error;
@end
