<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet type="text/xsl" href="http://www.germane-software.com/~ser/Software/documentation.xsl"?>
<!DOCTYPE documentation>
<documentation> 
	<head> 
		<title>Balanced Ternary</title>
		<base>bternary</base>
		<version>0.2</version> 
		<date>2001-310</date>
		<home>http://www.germane-software.com/~ser/software/balancedternary</home>
		<archive type="unix">balancedternary.tgz</archive> 
		<language>ruby</language>
		<author email="ser@germane-software.com" href="http://www.germane-software.com/~ser">Sean Russell</author>
	</head>


	<overview> 
		<purpose> 
			<p>BTernary is an implementation of the base-3 Balanced Ternary 
				number system.  BTernary provides a class which acts as most
				Integer numbers, and provides mechanisms for performing arithmetic
				and converting to and from decimal.
			</p>
		</purpose> 


		<general> 
			<p>The balanced ternary numbering system has several 
				advantages, most of which are not realizeable here.  In 
				particular, theoretically, the most efficient numbering system 
				(mathematically) is the numbering system where if r is the radix 
				and w is the width in digits, r*w is minimized while holding r**w
				constant.  It turns out that base-e (~2.718) is the most
				efficient, with base-3 being the best possible integer.  Most of
				the benefits would come from a computer that had ternary bits, but
				none exist at the moment.  There are some benefits that derive
				from not just the computational efficiency.
			</p>
			<p>A balanced ternary system doesn't use 0,1,2 to count, but -1,0,1
				instead. I'm not going to go into the details of why this is a
				nice system; read <link
					href="http://www.sigmaxi.org/amsci/amsci/issues/comsci01/compsci2001-11.html">this
					American Scientist article</link> for more details.  Some
				interesting items about balanced ternary is that there is no sign
				bit: if the MSB is bar-1, the whole number is negative.  Negating
				the number is done by inverting all of the bits.  Numbers are not
				as straightforward as non-balanced systems, but don't require any
				more mathematical operations and are curiously, aesthetically,
				pleasing.
			</p>
			<p>Bar-one is a 1 with a bar over the top.  Since bar-one isn't a
				common character, BTernary uses 'T', which is pretty close.
				Bar-one is shorthand for -1.  Therefore, 1 = 1, 0 = 0, T = -1.
				Balanced ternary systems use the same algorithm as other bases,
				with the addition of the sign.  Therefore, 11 is 1*3**1 + 1*3**0,
				or 4.  110 is 1*3**2 + 1*3**1 + 0*3**0, or 12.  1T is 1*3**1 +
				-1*3**0, or 2.  It is pretty easy once you get used to it.</p>
			<example title="Example b-ternary numbers">1TT = 9 - 3 - 1 = 5
1T1 = 9 - 3 + 1 = 7
1000 = 27
1T00 = 27 - 9 = 18
1T1T = 27 - 9 + 3 - 1 = 20</example>
			<p>I discoverd a few things about B-Ternarys during this
				implementation.  Most, if not all, were already known by other
				people or myself, and some are similar to rules that apply in
				binary numbering, and I'd forgotten them. In any case, that didn't
				stop me from being excited when I discovered them again.
			</p>
			<list>
				<item>Any arbitrary bit a_i (a-sub-i) at index i in a BTernary
					representation of a decimal number 'n' can be calculated
					with:</item>
				<pre>ai = [ (n - f(i)) / 3**i  % 3   | 0 -> 0   ]
        [                          | 1 -> 1   ]
		  [                          | 2 -> -1  ]</pre>
				<item>If a BTernary number ends in 0, it is divisible by
					three</item>
				<item>There is no easy way of determining whether a number is even
					or odd</item>
				<item>Adding:  1 + 0 -> 1 ; 1 - 1 -> 0 ; 1 + 1 -> 1T.  Therefore,
					the only operation that carries is when the sign is the
					same.</item>
			</list>
			<p>This class has most of the same operators as Integer, is a
				Comparable, and can be used in a Range.
			</p>
			<p>All of the algorithms herein are of my own devising, and are nobody's fault but my own.  I learned almost everything I know pertaining specifically to balanced ternary systems from the aforementioned URL.
			</p>
		</general>

		<features>
			<item>Basic arithmetic operation +, -, *, /</item>
			<item>Bit-wise operators &amp;, |</item>
			<item>includes Comparable</item>
			<item>Supports Range</item>
			<item>Converts to and from decimal</item>
			<item>to_s generates bar notation representation of number (bar-1 is
				written as 'T')</item>
		</features>
	</overview>

	<operation lang="en">
		<subsection title="Usage">
			<p>BTernary comes with a full test suite in the file test.rb.  Refer
				to this file for examples of using the BTernary class.  The file
				to include is "ternary.rb"; the class name is BTernary.
			</p>
		</subsection>
	</operation>

	<status>
		<todo lang="en">
			<item>*, /, &amp;, and | cheat, and perform operations on decimals.  I need to
				convert these to bitwise operations.</item>
			<item>% needs to be implemented</item>
			<item>Fractions shouldn't be hard, but I need to write a new class
				for that; the usefullness of such a class is questionable, and as
				the implementation shouldn't provide any intellectual excercise,
				I'll probably eschew it.</item>
		</todo>
	</status>


	<credits>
		<p>As mentioned before, I got interested in balanced ternary systems
			after reading the <link
				href="http://www.sigmaxi.org/amsci/amsci/issues/comsci01/compsci2001-11.html">American
				Scientist article</link>, which first came to my attention via
			<link href="http://www.slashdot.org">Slashdot</link>.
		</p>
	</credits>
</documentation>
