/*
*	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>

/*
 Error management
 */

FOUNDATION_EXPORT	NSString	*const	BitArrayErrorDomain;

enum {
	BitArrayUnknownError= 1,				//	Unknown general error
	BitIndexOutOfRange	= 100,				//	Good indication that extents are turned off
	UnableToAllocateExtent	= 200,			//	Failure in calloc
	UnableToIncreaseExtentControl = 210		//	Failure in realloc
};

/*!
    @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
*/

@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
	@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;
@end