Apple-2-SW/prog8
1
0
Fork 0
mirror of https://github.com/irmen/prog8.git synced 2024-06-09 14:29:32 +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
$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).

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
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.