Apple-2-SW/prog8
1
0
Fork 0
mirror of https://github.com/irmen/prog8.git synced 2025-02-09 07:31:34 +00:00
Code Issues Projects Releases Wiki Activity

update docs about boolean type

Browse Source
This commit is contained in:
Irmen de Jong 2024-03-12 18:54:56 +01:00
parent 820541e427
commit a5a918df84
2 changed files with 18 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
docs/source/programming.rst
View File

@ -194,6 +194,7 @@ Values will usually be part of an expression or assignment statement::
12345 ; integer number 12345 ; integer number
$aa43 ; hex integer number $aa43 ; hex integer number
%100101 ; binary integer number (% is also remainder operator so be careful) %100101 ; binary integer number (% is also remainder operator so be careful)
false ; boolean false
-33.456e52 ; floating point number -33.456e52 ; floating point number
"Hi, I am a string" ; text string, encoded with default encoding "Hi, I am a string" ; text string, encoded with default encoding
'a' ; byte value (ubyte) for the letter a 'a' ; byte value (ubyte) for the letter a
@ -247,17 +248,18 @@ and -32768..32767 for words.
stick to unsigned integers for efficiency. 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 Booleans are a distinct type in Prog8 and can have only the values ``true`` or ``false``.
converted to boolean) is ``false`` (0) when it is zero and ``true`` (1) for all other values. It can be casted to and from other integer types though
Logical expressions, comparisons and some other code might compile more efficiently if where a nonzero integer is considered to be true, and zero is false.
you explicitly use ``bool`` types instead of integers there because that will avoid this conversion. Logical expressions, comparisons and some other code tends to compile more efficiently if
In the end the compiler translates boolean variables to a byte that stores just 0 or 1. 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, 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. 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 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 (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. 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:: 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] 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) 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 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) value = array[3] ; the fourth value in the array (index is 0-based)
char = string[4] ; the fifth character (=byte) in the string char = string[4] ; the fifth character (=byte) in the string
@ -835,10 +838,10 @@ Array operations
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
any (x) 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) 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) len (x)
Number of values in the array value x, or the number of characters in a string (excluding the 0-byte). Number of values in the array value x, or the number of characters in a string (excluding the 0-byte).

16
docs/source/syntaxreference.rst
View File

@ -357,6 +357,7 @@ Various examples::
ubyte x,y,z ; declare three ubyte variables x y and z ubyte x,y,z ; declare three ubyte variables x y and z
str name = "my name is Alice" str name = "my name is Alice"
uword address = &counter uword address = &counter
bool flag = true
byte[] values = [11, 22, 33, 44, 55] byte[] values = [11, 22, 33, 44, 55]
byte[5] values ; array of 5 bytes, initially set to zero byte[5] values ; array of 5 bytes, initially set to zero
byte[5] values = 255 ; initialize with five 255 bytes 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`` ``byte`` signed byte 1 byte = 8 bits ``byte myvar = -22``
``ubyte`` unsigned byte 1 byte = 8 bits ``ubyte myvar = $8f``, ``ubyte c = 'a'`` ``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`` ``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`` ``word`` signed word 2 bytes = 16 bits ``word myvar = -12345``
``uword`` unsigned word 2 bytes = 16 bits ``uword myvar = $8fee`` ``uword`` unsigned word 2 bytes = 16 bits ``uword myvar = $8fee``
``float`` floating-point 5 bytes = 40 bits ``float myvar = 1.2345`` ``float`` floating-point 5 bytes = 40 bits ``float myvar = 1.2345``
@ -595,20 +594,13 @@ postfix increment and decrement: ``++`` ``--``
comparison: ``==`` ``!=`` ``<`` ``>`` ``<=`` ``>=`` comparison: ``==`` ``!=`` ``<`` ``>`` ``<=`` ``>=``
Equality, Inequality, Less-than, Greater-than, Less-or-Equal-than, Greater-or-Equal-than comparisons. 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`` logical: ``not`` ``and`` ``or`` ``xor``
These operators are the usual logical operations that are part of a logical expression to reason 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' about truths (boolean values). The result of such an expression is a boolean, 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.
Prog8 applies short-circuit aka McCarthy evaluation for ``and`` and ``or``. 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`` range creation: ``to``, ``downto``
Creates a range of values from the LHS value to the RHS value, inclusive. 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. These are mainly used in for loops to set the loop range.
@ -616,7 +608,7 @@ range creation: ``to``, ``downto``
containment check: ``in`` 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. 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 Consider using this instead of chaining multiple value tests with ``or``, because the
containment check is more efficient. 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. 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.