diff --git a/docs/source/programming.rst b/docs/source/programming.rst index c1e4570d2..ce9713789 100644 --- a/docs/source/programming.rst +++ b/docs/source/programming.rst @@ -194,6 +194,7 @@ Values will usually be part of an expression or assignment statement:: 12345 ; integer number $aa43 ; hex integer number %100101 ; binary integer number (% is also remainder operator so be careful) + false ; boolean false -33.456e52 ; floating point number "Hi, I am a string" ; text string, encoded with default encoding 'a' ; byte value (ubyte) for the letter a @@ -247,17 +248,18 @@ and -32768..32767 for words. stick to unsigned integers for efficiency. -Boolean values -^^^^^^^^^^^^^^ +Booleans +^^^^^^^^ -These values are only ``true`` or ``false``, or 1 or 0. An integer's "truthy" value (i.e. a number -converted to boolean) is ``false`` (0) when it is zero and ``true`` (1) for all other values. -Logical expressions, comparisons and some other code might compile more efficiently if -you explicitly use ``bool`` types instead of integers there because that will avoid this conversion. -In the end the compiler translates boolean variables to a byte that stores just 0 or 1. +Booleans are a distinct type in Prog8 and can have only the values ``true`` or ``false``. +It can be casted to and from other integer types though +where a nonzero integer is considered to be true, and zero is false. +Logical expressions, comparisons and some other code tends to compile more efficiently if +you explicitly use ``bool`` types instead of 0/1 integers. +The in-memory representation of a boolean value is just a byte containing 0 or 1. If you find that you need a whole bunch of boolean variables or perhaps even an array of them, -consider using bit masks in regular integer variables instead. +consider using integer bit mask variable + bitwise operators instead. This saves a lot of memory and may be faster as well. @@ -284,7 +286,7 @@ The largest 5-byte MFLPT float that can be stored is: **1.7014118345e+38** (ne Arrays ^^^^^^ -Array types are also supported. They can be formed from a list of bytes, words, floats, or addresses of other variables +Array types are also supported. They can be formed from a list of booleans, bytes, words, floats, or addresses of other variables (such as explicit address-of expressions, strings, or other array variables) - values in an array literal always have to be constants. Putting variables inside an array has to be done on a value-by-value basis. Here are some examples of arrays:: @@ -295,6 +297,7 @@ Here are some examples of arrays:: byte[] array = 100 to 199 ; initialize array with [100, 101, ..., 198, 199] str[] names = ["ally", "pete"] ; array of string pointers/addresses (equivalent to array of uwords) uword[] others = [names, array] ; array of pointers/addresses to other arrays + bool[2] flags = [true, false] ; array of two boolean values (take up 1 byte each, like a byte array) value = array[3] ; the fourth value in the array (index is 0-based) char = string[4] ; the fifth character (=byte) in the string @@ -835,10 +838,10 @@ Array operations ^^^^^^^^^^^^^^^^ any (x) - 1 ('true') if any of the values in the array value x is 'true' (not zero), else 0 ('false') + true if any of the values in the array value x is 'true' (not zero), else false. all (x) - 1 ('true') if all of the values in the array value x are 'true' (not zero), else 0 ('false') + true if all of the values in the array value x are 'true' (not zero), else false. len (x) Number of values in the array value x, or the number of characters in a string (excluding the 0-byte). diff --git a/docs/source/syntaxreference.rst b/docs/source/syntaxreference.rst index 622ac7f09..b89dea6d6 100644 --- a/docs/source/syntaxreference.rst +++ b/docs/source/syntaxreference.rst @@ -357,6 +357,7 @@ Various examples:: ubyte x,y,z ; declare three ubyte variables x y and z str name = "my name is Alice" uword address = &counter + bool flag = true byte[] values = [11, 22, 33, 44, 55] byte[5] values ; array of 5 bytes, initially set to zero byte[5] values = 255 ; initialize with five 255 bytes @@ -377,8 +378,6 @@ type identifier type storage size example var declara ``byte`` signed byte 1 byte = 8 bits ``byte myvar = -22`` ``ubyte`` unsigned byte 1 byte = 8 bits ``ubyte myvar = $8f``, ``ubyte c = 'a'`` ``bool`` boolean 1 byte = 8 bits ``bool myvar = true`` or ``bool myvar == false`` - The true and false are actually just aliases - for the byte values 1 and 0. ``word`` signed word 2 bytes = 16 bits ``word myvar = -12345`` ``uword`` unsigned word 2 bytes = 16 bits ``uword myvar = $8fee`` ``float`` floating-point 5 bytes = 40 bits ``float myvar = 1.2345`` @@ -595,20 +594,13 @@ postfix increment and decrement: ``++`` ``--`` comparison: ``==`` ``!=`` ``<`` ``>`` ``<=`` ``>=`` Equality, Inequality, Less-than, Greater-than, Less-or-Equal-than, Greater-or-Equal-than comparisons. - The result is a boolean value 'true' or 'false' (1 or 0). + The result is a boolean, true or false. logical: ``not`` ``and`` ``or`` ``xor`` These operators are the usual logical operations that are part of a logical expression to reason - about truths (boolean values). The result of such an expression is a 'boolean' value 'true' or 'false' - (which in reality is just a byte value of 1 or 0). - Notice that the expression ``not x`` is equivalent to ``x==0``, and the compiler will treat it as such. + about truths (boolean values). The result of such an expression is a boolean, true or false. Prog8 applies short-circuit aka McCarthy evaluation for ``and`` and ``or``. - .. note:: - You can use regular integers directly in logical expressions but these have to be converted to - the boolean value 0 or 1 every time, resulting in larger and slower code. Consider using - the ``bool`` variable type instead, where this conversion doesn't need to occur. - range creation: ``to``, ``downto`` Creates a range of values from the LHS value to the RHS value, inclusive. These are mainly used in for loops to set the loop range. @@ -616,7 +608,7 @@ range creation: ``to``, ``downto`` containment check: ``in`` Tests if a value is present in a list of values, which can be a string, or an array, or a range expression. - The result is a simple boolean ``true`` or ``false``. + The result is a simple boolean true or false. Consider using this instead of chaining multiple value tests with ``or``, because the containment check is more efficient. Checking N in a range from x to y, is identical to x<=N and N<=y; the actual range of values is never created.