.. Bitwise operators

.. include:: /includes/standard.rst

===================
 Bitwise operators
===================

Bitwise operators operate in individual bits. You'll often see numbers used in these
operations defined in hex (beginning with $), as it is easier to see the bit layout with hexadecimal numbers.

Bitwise AND: &
===============

Compares two bits and generates a 1 result if both bits are 1, otherwise it returns 0::

	// Result will equal 5.
	(= Result (& $85 $0F))

Often used to set for things like control colors, since onControl() returns a bit mask::

	(if (& ctlGREEN (send gEgo:onControl()))
		// Ego is on green.
	)

Bitwise OR: |
==============

Compares two bits and generates a 1 result if either or both bits are 1, otherwise it returns 0::

	 Result will equal $8F.
	(= Result (| $85 $0F))

Often used to OR two flags together

	(send theActor:signal(| ignAct fixPriOn))


Bitwise exclusive OR: ^
========================

Compares two bits and generates a 1 result if the bits are complementary, otherwise it returns 0::

	Result will equal $8A
	(= Result (^ $85 $0F))


Bitwise shift left: <<
========================

Bitwise shift left; moves the bits to the left, it discards the far left bit and assigns 0 to the right most bit::

	Result will equal $14
	(= Result (<< $85 2))

Bitwise shift right: >>
=========================

Bitwise shift right; moves the bits to the right, discards the far right bit and if unsigned assigns 0 to the left most bit, otherwise sign extends::

	Result will equal $21
	(= Result (>> $85 2))


Binary NOT: bnot
=====================

A binary not. It inverts the bits in an integer::

	(= Result bnot $F00F) // the result will be $0FF0 (1111000000001111b->0000111111110000b)
	(= Result bnot $78) // the result will be $FF87 (0000000001111000b->1111111110000111b)
	(= Result bnot 0) // the result will be $FFFF (0000000000000000->1111111111111111b)
	(= Result bnot $183D) // the result will be $E7C2 (0001100000111101->1110011111000010b)

