/*
*	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   Sparse 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 default or user defined 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
- (BOOL)		dirty;				//	Answers if the instance is dirty
- (NSUInteger)	bytesInBase;		//	Answers how many bytes are allocated in the base array
- (NSUInteger)	bitsInBase;			//	Answers how many bits are allocated in the base array
- (BOOL)		extentsAllowed;		//	Answers if extents are allowed
- (NSUInteger)	extentCount;		//	Answers how many extents there are
- (NSUInteger)	bytesInExtent;		//	Answers how many bytes will be allocated for extents
- (NSUInteger)	bitsInExtent;		//	Answers how many bits will be allocated for extents

/*!
 @function(bit)
 Returns the state of the bit specified in bitIndex
 */
- (BOOL)		bit:(NSUInteger) bitIndex error:(NSError **)err;

#pragma mark -
#pragma mark Mutators

/*!
 Clears (turns off) the bit specified in bitIndex
 */
- (void)	clearBit:(NSUInteger) bitIndex error:(NSError **) err;

/*!
 Clears all bits in the base array
 */
- (void)	clear;

/*!
 Clears all the bits in the extent framing bitIndex
 */

- (void)	clearExtentWithBit:(NSUInteger) bitIndex error:(NSError **)err;

/*!
 Sets (turns on) the bit specified in bitIndex
 */
- (void)	setBit:(NSUInteger) bitIndex error:(NSError **) err;
- (void)	set;
- (void)	setExtentWithBit:(NSUInteger) bitIndex error:(NSError **)err;
@end