This is part of the HicEst documentation

BITS: Handling BITS and BYTES in string and numeric arrays

Perform operations like set, flip, clear, copy, move, shift, rotate, translate, lows, highs, count bits in groups of rows, columns, boxes, and rings.

⇾Home ⇾Contents ⇾more Programming ⇾ Examples

Optional keywords:
(Syntax of optional keywords)
AND BOX Base BitCount BoxDim CLR CoPy EOR ERROR FLiP GetVal High0 High1 IFClr IFEq IFGt IFLOC IFLt IFNeq IFSet JumpBase LocGet Low0 Low1 MoVe OR ORIGin POOL RING ROTate RowsColsBits SHiFt SetBit SetVal X XLate Y

HicEst bit handling operators are IAND, IOR, IEOR and NOT. These functions work on numeric scalars.
The BITS function extends these and other operations to strings and arrays of arbitrary length
- BITS(Base=.., [RowsColsBit=..,] [X=..,] [Y=..,] [RING=..,] [BoxDim=..,] [actions..,] [ERRor])
Options are worked off sequentially.
Options may occur repeatedly

options	type	BITS(Base=String,... BITS(Base=Num,... BITS(Base=Array,...	Base= ... must be first keyword, RowsColsBits must follow if used.
Base	txt	Base=String	LEN(String) tokens, default 8 bit. Use RowsColsBits to change defaults.
	num	Base=Num	Num is a 1 token numerical scalar, 64 bit max
		Base=Array	Array is a numeric vector or a matrix. Base is divided in LEN(Array) tokens, 64 bit max
RowsColsBits	num	B=Array, RCB=nBits,...	nBits<64. This reduces the default 64 bit per token to nBits per token. nBits=52 is the maximum number of bits that can be used without loss of precision outside the BITS function (standard HicEst variables are 64 bit floating point numbers with a 11 bit exponent and 1 sign bit).
		B=Array, RCB=n...	Array with rows*columns tokens, only the lowest n bits of each token are used.
		B=String, RCB=b,...	a single token String with b addressable bits BITS(B=txt, RCB=8*8000, SetBit=12345) ! sets bit 12345 of string txt to 1
		B=String, RCB=(c,b)...	String divided in c tokens, b bit each (b rounded up to multiple of 8)
		B=String, RCB=(r,c,b)...	String with rc tokens (rowscolumns), b bit each (b rounded up to multiple of 8)

options	type	code snippet	options to select parts of Base for following actions
X	num	...X=columnNr...	selects columnNr for all selected rows (String or Array). If no rows are selected: the following operations work on all rows
		...X=(colA, colZ)...	selects the range of columns colA to colZ of String or Array.
Y	num	...Y=rowNr ...	selects rowNr for all columns selected (String or Array). If no columnss are selected: the following operations work on all columns
		...Y=(rowA, rowZ)...	selects the range of rows rowA to rowZ of String or Array.
BoxDim	num	...BD=(br,bc)...	divides Base in equal size boxes of br rows * bc columns. Boxes are aligned left to right in RCB space and top to bottom. Boxes are not broken.
BOX	num	..BOX=n...	selects the n-th box of a box-grid defined by BoxDim=...
		...BOX=(bA,bZ)...	selects the range of boxes bA to bZ .
RING	num	...RING=r...	selects the r-nearest neighbors of token(r,c) instead of token(r,c) itself. BITS(B=array, X=3, Y=3, RING=2, ...) ! selects the 16 ring=2 neighbors around array(3,3) Ring 1 has 8 tokens, ring 2 has 16, ring 3 has 24 etc
JumpBase	num	...JB=1000...	start at linearPosition 1000 of base NumOrTxt
		...jb=(2,3)...	start at RowColPosition (2,3) of base NumOrTxt
ORIGin	num	...orig = 0...	set the index origin of row, col, bit, box, ring. Default is = 1.

options	type	b either scalar or range=(from,to)	Conditional execution: if TRUE execute NEXT option, ELSE skip next option
IFSet	num	...IFS=b...	execute next option only if current baseToken BIT b set BITS(.. ifs=n, SetBit=6, ...) ! if BIT n is set then also set bit 6
IFClr	num	...IFC=b...	execute next option only if current baseToken BIT b not set BITS(.. ifc=5, BitCount=x) ! if BIT 5 is 0 count token-Bits
IFLt	num	...IFL=b...	execute next option only if current baseToken VALUE is less than b BITS(.. ifl=2, RING=1, SET) ! if token VALUE < 2 set ring1 bits
IFEq	num	...IFE=b...	execute next option only if current baseToken VALUE is equal to b BITS(.. ife=2, BitCount=x) ! BIT-sum if VALUE == 2
IFNeq	num	...IFN=b...	execute next option only if current baseToken VALUE is not equal to b BITS(.. ifn=(3,6), FlipBit) ! flip all BITs if token VALUE < 3 or > 6
IFGt	num	...IFG=b...	execute next option only if current baseToken VALUE is greater than b BITS(.. ifg=91, ClrB) ! zero token if tokenvalue > 91
IFLOC	num	...IFLOC=b...	execute next option only if current baseToken LOCATION is equal to b BITS(.. ifloc=(12,15), SetVal='?') ! mark tokens 12-15 by a '?'

options	type	code snippet	options to change selected tokens of Base
CLR	num	...CLR=b ...	clear bits b BITS(Base=S2, SetVal='a', CLR=5) ! S2 is set to "AA"
		...CLR=(a,z)...	clear bits in range a to z to 0
		...CLR...	set tokens to 0 (clear all bits)
FLiP	num	...FLP= n...	flip bits n BITS(Base=x, CLR, FLiP=6) ! x is set to 64
		...FLP=(a,z)...	flip bits in range a to z
		...FLP...	flip all bits
SetBit	num	...SB=n ...	set bits n to 1 BITS(Base=S2, SetVal='A', SetBit=5) ! S2 is set to "aa"
		...SB=(a,z)...	set bits in range a to z
		...SB...	set all bits in all selected tokens to 1
SetVal	num	...SV=n...	set selected token values to n
		...SV='A'...	set selected token values to 'A' BITS(Base=S12, RCB=(4,3*8), SetVal="ABC") ! S12 is set to "ABCABCABCABC"
POOL	num txt	...POOL=XY...	A data pool supplies in (cyclic) sequence values to a string or numeric base. XY = (3,4,70, 2, 8, 39) ! numeric pool BITS(Base=B, POOL=XY, X=XY, Y=XY, SetVal=XY) ! result B(3,4)=70, B(2,8)=39 XY can be a string, or a numeric scalar, vector, or matrix. If empty the pool is restarted. All calling tokens are supplied with a value XY = " 13 15 17" ! string pool BiTS(Base=C, POOL=XY, SetVal=XY, ...) ! C(1)=13, C(2)=15, C(3)=17, C(4)=13, C(5)=15, C(6)=17, etc A string pool with no separators is emptied byte by byte XY = "3253" BITS(Base=D, POOL=XY, SetBit=XY) ! D(1)=8, D(2)=4, D(3)=32, D(4)=8)
AND	num	...AND=n...	bitwise AND: BaseValue = BaseValue AND n BITS(Base=x, SetVal=1, AND=255) ! x is set to 1
EOR	num	...EOR=n...	bitwise exclusive EOR: BaseValue = BaseValue EOR n BITS(Base=x, SetVal=1, EOR=255) ! x is set to 254
OR	num	...OR=n...	bitwise OR: BaseValue = BaseValue OR n BITS(Base=x, SetVal=1, OR=255) ! x is set to 255
CoPy	num	...CP=dX...	copy tokens by linear displacement dx ! same as txt(3-1) = txt(3)
		...CP=(dX,dY)...	copy tokens by dX columns and dY rows. BITS(B=txt, RCB=(8,8,8), Y=3, CoPy=(1,0) ! copy row 3 to row 3+1
MoVe	num	...MV=dX...	move tokens by dX columns. BITS(B=txt, RCB=(8,8,8), X=3, MoVe=-1) ! move column 3 to column 3-1
		...MV=(dX,dY)...	move tokens by dX columns and dY rows. BITS(B=txt, RCB=(8,8,8), X=3, Y=4, MoVe=(1,1)) ! move txt(3,4) to txt (4,5)
SHiFt	num	...SHF=b...	shift Base left (b>0) or right (b<0) bits BITS(Base=x, SetVal=64, shift=-1) ! same as x = x/2
ROTate	num	...ROT=b...	rotate Base left (b>0) or right (b<0) bits BITS(Base=x, rotate=n) ! circular shift of n rightmost bits
XLate	txt	...XL="bin:txt, bin:txt"...	translate binary characters to (readable) txt BITS(B=S8, xlate='0:?,1:x,32:-') ! S8= CHAR(1)&& CHAR(0) is translated to "x-0-----"

options	type	code snippet	options that will receive a value
GetVal	num	...GV=x...	x is to get the token value BITS(Base="ABC", X=2, getval=x) ! same as x = ICHAR("B")
	txt	...GV=txt...	txt is to get the token value BITS(B=string, RCB=(5,9,16), X=2, getval=txt) ! 5*2 byte string(1_5, 2) copied to txt]
			BITS(B=string, RCB=(5,9,16), X=2,Y=2,RING=1, GV=txt) ! txt gets 2*8 bytes ring tokens around string(2,2)
BitCount	num	...BC=x...	x gets the total number of bits in base BITS(Base='g', BitCount=x) ! 'g' == '01100111', x is set to 5
	txt	...BC=txt...	txt(i) gets bitcount of baseToken(i) BITS(Base=string, BitCount=txt)
		...RING=r, BC=txt...	txt(i) gets sum of bitcounts of ring tokens around baseToken i
	vector	...BC=vec...	vector gets bitcount of baseToken i
		...RING=r, BC=vec...	vec(i) gets bitcount of ring token aroung baseToken i
	matrix	...BOX=b, BC=mtx...	mtx(b, element_j) gets the occurence count of element == j in box b
Low0	num	...L0= posLowZero...	posLowZero is the lowest position of a 0 in base BITS(Base='g', Low0=posLowZero) ! posLowZero is set to 3
High0	num	...H0=posHighZero...	posHighZero is the highest position of a 1 in base BITS(Base='g', High0=posHighZero) ! posHighZero set to 7
Low1	num	...L1=posLowOne...	posLowOne is the lowest position of a 1 in base BITS(Base='g', Low1=posLowOne) ! posLowOne set to 0
High1	num	...L1=posHighOne...	posHighOne is the highest position of a 1 in base BITS(Base='g', High1=posHighOne) ! posHighOne set to 6
LocGet	num	...LG=TokenPos...	TokenPos is the current token number in base BITS(B='0123456789', LG=n, NxtIFSet=2, LG=vec) ! n set to 10, vec set to (5,6,7,8,0,0,..)
ERROR	label	...ERR=999,...	On error branch to the error label. Error messages are not shown)