@c DO NOT EDIT!  Generated automatically by munge-texi.

@c Copyright (C) 2007 John W. Eaton
@c This is part of the Octave manual.
@c For copying conditions, see the file gpl.texi.

@node Bit Manipulations
@chapter Bit Manipulations

Octave provides the following functions for bit twiddling.

@anchor{doc-bitset}
@deftypefn {Function File} {@var{x} =} bitset (@var{a}, @var{n})
@deftypefnx {Function File} {@var{x} =} bitset (@var{a}, @var{n}, @var{v})
Set or reset bit(s) @var{n} of unsigned integers in @var{a}.
@var{v} = 0 resets and @var{v} = 1 sets the bits.
The lowest significant bit is: @var{n} = 1

@example
dec2bin (bitset (10, 1))
@result{} 1011
@end example
@seealso{bitand, bitor, bitxor, bitget, bitcmp, bitshift, bitmax}
@end deftypefn


@anchor{doc-bitget}
@deftypefn {Function File} {@var{X} =} bitget (@var{a},@var{n})
Return the status of bit(s) @var{n} of unsigned integers in @var{a}
the lowest significant bit is @var{n} = 1.

@example
bitget (100, 8:-1:1)
@result{} 0  1  1  0  0  1  0  0 
@end example
@seealso{bitand, bitor, bitxor, bitset, bitcmp, bitshift, bitmax}
@end deftypefn


@anchor{doc-bitcmp}
@deftypefn {Function File} {} bitcmp (@var{a}, @var{k})
Return the @var{k}-bit complement of integers in @var{a}.  If
@var{k} is omitted @code{k = log2 (bitmax) + 1} is assumed.

@example
bitcmp(7,4)
@result{} 8
dec2bin(11)
@result{} 1011
dec2bin(bitcmp(11, 6))
@result{} 110100
@end example
@seealso{bitand, bitor, bitxor, bitset, bitget, bitcmp, bitshift, bitmax}
@end deftypefn


@anchor{doc-bitshift}
@deftypefn {Function File} {} bitshift (@var{a}, @var{k})
@deftypefnx {Function File} {} bitshift (@var{a}, @var{k}, @var{n})
Return a @var{k} bit shift of @var{n}- digit unsigned
integers in @var{a}.  A positive @var{k} leads to a left shift.
A negative value to a right shift.  If @var{n} is omitted it defaults
to log2(bitmax)+1.
@var{n} must be in range [1,log2(bitmax)+1] usually [1,33]

@example
bitshift (eye (3), 1))
@result{}
@group
2 0 0
0 2 0
0 0 2
@end group

bitshift (10, [-2, -1, 0, 1, 2])
@result{} 2   5  10  20  40
@c FIXME -- restore this example when third arg is allowed to be an array.
@c 
@c 
@c bitshift ([1, 10], 2, [3,4])
@c @result{} 4  8
@end example
@seealso{bitand, bitor, bitxor, bitset, bitget, bitcmp, bitmax}
@end deftypefn


@anchor{doc-bitand}
@deftypefn {Built-in Function} {} bitand (@var{x}, @var{y})
Return the bitwise AND of nonnegative integers.
@var{x}, @var{y} must be in range [0..bitmax]
@seealso{bitor, bitxor, bitset, bitget, bitcmp, bitshift, bitmax}
@end deftypefn


@anchor{doc-bitor}
@deftypefn {Built-in Function} {} bitor (@var{x}, @var{y})
Return the bitwise OR of nonnegative integers.
@var{x}, @var{y} must be in range [0..bitmax]
@seealso{bitor, bitxor, bitset, bitget, bitcmp, bitshift, bitmax}
@end deftypefn


@anchor{doc-bitxor}
@deftypefn {Built-in Function} {} bitxor (@var{x}, @var{y})
Return the bitwise XOR of nonnegative integers.
@var{x}, @var{y} must be in range [0..bitmax]
@seealso{bitand, bitor, bitset, bitget, bitcmp, bitshift, bitmax}
@end deftypefn


@anchor{doc-bitmax}
@deftypefn {Built-in Function} {} bitmax ()
Return the largest integer that can be represented as a floating point
value.  On IEEE-754 compatiable systems, @code{bitmax} is @code{2^53 - 1}.
@end deftypefn

