/**
@page Intro Introduction
<p>B++ has its origins in BOB, an approach to a minimalist object-oriented (and C++-like) language developed by David Michael Betz and <a href="https://www.drdobbs.com/open-source/bob-a-tiny-object-oriented-language/184409401" target="_blank">published</a> in 1991 in Dr. Dobbs Journal.</p>
<p>In order to make the language suitable for practical use, some additions to the language scope itself, in particular memory management, as well as the provision of a number of elementary predefined functions were essential. The result was called BOB+ and was essentially an extension of BOB, which was largely based on the original code. The focus of the development of BOB+ was initially on minimally equipped MS-DOS-based systems. That's why special emphasis was placed on minimal space requirements - both on the data storage medium and in the main memory.</p>
<p>B++ is intended primarily as an easily integrated scripting language for custom extension/control of applications, for quickly creating smaller utility programs and for prototyping.<br>
Achieving this goal required a completely new internal architecture, which also entailed a complete reimplementation.</p>

@section AboutBpp About B++
<p>B++ is a hybrid language in several ways.</p>
<p>According to its concept, it is initially a procedural language with object-oriented extensions.<br>
Functors and anonymous functions, which are also part of B++, allow the use of functional paradigms.
<p>B++ is neither a real compiler nor a real interpreter. The source code of a program is first translated into bytecode, which is then interpreted in a virtual machine. This allows very easy porting of B++ to different target platforms and the execution of existing B++ programs on any supported platform (as long as no platform specific API functions are used directly).</p>
<p>As usual for scripting languages, B++ allows you to work with dynamically typed variables. Static typing is available too, whereby the type checking is carried out partly by the compiler and partly by the runtime system. Both forms can also be used mixed.</p>
<p>Syntactically (and to a certain extent semantically) B++ borrows heavily from C/C++, with some elements from other scripting languages, particularly JavaScript.</p>
<p>The name &quot;B++&quot; refers to its similarity to C++ and its &quot;ancestor&quot; BOB+.</p>
@section Features
<p>B++ is a reletively small language with a total of 36 keywords, and the basics of it an be learned quickly and easily. But it is also a very powerful and expressive language that supports object orientation and modularization as well as access to system functions.<p>
<p>The following (incomplete) list includes some essential language features of B++, which are presented in more detail below.
<ul>
<li>Support for floating point arithmetic (float and double data types) on all platforms, via emulation if necessary</li>
<li>explicitly usable integer data types from 8 to 64 bits wide, each signed and unsigned, with 32 bits being the standard size</li>
<li>Integrated data types for strings, buffers, vectors (dynamic arrays) and dictionaries (associative containers)</li>
<li>integer numeric literals in decimal, binary, octal or hexadecimal notation</li>
<li>Literal representations for vectors and dictionaries</li>
<li>Function and method pointers</li>
<li>anonymous functions and methods</li>
<li>asymmetric coroutines</li>
<li>variable parameter lists and default parameters for functions</li>
<li>polymorphic classes, automatic destructors and initialized static member variables</li>
<li>partial classes</li>
<li>custom operators for objects</li>
<li>Type information at runtime (RTTI)</li>
<li>Access to system functions</li>
<li>Integrated serialization of any data</li>
<li>Use of precompiled bytecode libraries</li>
<li>dynamic loading of libraries at runtime</li>
<li>Either explicit memory management or automatic memory management with reference counting</li>
<li>optional static typing</li>
</ul>
There are also a variety of predefined functions that fulfill the tasks of a standard library, as well as predefined classes to support regular expressions and to emulate C structures.</p>

@section Distrib The B++ distribution
B++ is currently available for the following platforms:
<ul>
<li>MS-DOS from version 3.01: ZIP archive with the binaries for the DOS version and some examples</li>
<li>Windows desktop 32 bit (Vista, Win7 .. 11) : MSI Installer</li>
<li>Windows desktop 64 bit (Vista, Win 7 .. 11) : MSI Installer</li>
<li>Linux (source code only)</li>
</li>
<p>The B++ sources also contain project files for Borland C++ (DOS), Visual Studio 2005 and 2022 (Windows Desktop), CodeLite (Linux) and Embedded Visual Tools 3.0 (Windows CE, deprecated).</p>
<p>The Windows versions also come with a simple IDE whose task, in addition to making it easier to create B++ programs, is to show how B++ can be embedded in other applications.</p>
<p>The core of all distributions is the <tt><b>bpplib</b></tt> library.<br>
It contains the virtual machine with all necessary additional components (compiler, interpreter, predefined functions, etc.). It is available as a dynamic library (DLL) in the Windows versions and in the DOS version as a static C++ library (LIB). For Linux it can be created either as a dynamic or static library.</p>
<p>There is also a command line version <tt><b>bp2.exe</b></tt> for all platforms, which is basically a minimal application of the library with a command line interface. It allows the direct use of B++ from a console or the integration of B++ programs in command scripts. There is a modified version of the command line version, <tt><b>bp2r.exe</b></tt>, which can be linked to a B++ bytecode module to form an independently executable program. In the Windows desktop versions there is an additional variant <tt><b>bp2rw.exe</b></tt>, which differs from bp2r.exe in that it does not contain a console. It is intended for creating 'typical' Windows applications.<br>
In order to be able to use the different versions of Windows in parallel, specific suffixes are appended to the names of the executable files, where <b>u</b> stands for a UNICODE variant and <b>_64</b> for a 64-bit variant.<br>
For the DOS version there is a variant with the suffix <b>_386</b>, which requires at least an 80386 processor. It can use its 32-bit register set and is therefore faster than the standard version, which runs on an 8088 processor too. Both variants use an existing numerical coprocessor or emulation (if no such processor is available) for floating point operations. Due to memory limitations under MS-DOS, there are also 'minimal variants' <tt>bp2m.exe</tt>/<tt>bp2mr.exe</tt> and <tt>bp2m386.exe</tt>/<tt>bp2rm386.exe</tt>, which lack support for dynamic libraries, regular expressions and character set conversions, but require about 70 KB less memory.<br>
The Windows versions include an extension library <tt><b>bp2class</b></tt>, which is primarily intended for demonstrating the implementation of extensions. It contains some general classes (string, container, emulation of structures) as well as basic classes for Windows GUI programming. Building on this, the core of a Windows GUI framework is provided as B++ source code. An example that implements a Notepad clone in B++ serves to demonstrate how to use this.</p>


@section ENVVARS Environment variables
<p>B++ can load extensions in the form of dynamic libraries (usually with the .dll extension) at runtime. The search for such libraries is carried out using the search path1 specified in the <tt>PATH</tt> environment variable.</p>
<p>The search path specified in the <tt>BPPINC</tt> environment variable is used to search for source files that are included using the <tt>#include</tt> processing instruction.</p>
<p>The <tt>BPPLIB</tt> environment variable serves as a search path for precompiled modules to load.
As in <tt>PATH</tt>, several paths can be stored in <tt>BPPINC</tt> and <tt>BPPLIB</tt>, each separated by a semicolon (;).</p>

@section Usage Using B++ from command line

<p>B++ is started from the command line by calling <tt>bp2.exe</tt> (or its variants). To simplify calls from anywhere, the path to this file (or files) should be included in the <tt>PATH</tt> environment variable.<br>The following syntax then applies to the actual call:</p>
<pre><tt>
bp2 [-i][-d][-l][-v][-t][-c][-e][-E][-L rtname] [-Dsymbol[=value][..]]
[sourcefile [..]] [-r objfile [..]] [-o outfile] [# userarg [..]]
</tt></pre>
<p>The individual options have the following meaning:
<ul>
<li>-i (info) Displays copyright and function names.</li>
<li>-d (debug) Output of the generated bytecode when compiling.</li>
<li>-l (line info) Source file names and line numbers are included in the bytecode for debugging purposes.</li>
<li>-v (variables) Names of local variables are written into bytecode for debugging purposes.</li>
<li>-t (trace) Traces bytecode when programm is executed.</li>
<li>-c (compile) The specified sources are not executed, but translated into bytecode only.</li>
<li>-e (make exe) Creates an independently executable program (sources given are translated and the result is linked to the standard runtime module)</li>
<li>-E (make exe) Creates a standalone program without a console (sources given will be translated and the result with the Standard runtime module without console bound).<br>
The option only exists in the Windows desktop versions.</li>
<li>-L (link exe) Creates an independently executable program (specified sources are translated and the result is linked to with the Runtime module specified in <tt>rtname</tt>.
<li>-D (define symbol) A symbol <tt>symbol</tt> is defined for the subsequent translation, optionally with the value <tt>value</tt>. The symbol defined is a <i>named literal</i> of <tt>string</tt>, if a value was specified, otherwise it has the value <tt>null</tt>.</li>
<li>-r (read / run) Reads (and executes if needed) precompiled bytecode modules</li>
<li>-o (output) Name of the file to be output. This option is evaluated only, if c, e, E or -L is set too. If the information is missing, the default value out.bpm or out.exe is used.</li>
</ul></p>
<p>Source files and modules to be read can be specified without file extensions. In such cases, the extensions .bpp or .bpm are implicitly appended.</p>
<p>If multiple source files are specified, they will be translated into bytecode in the specified order before actual program execution begins. The precompiled modules to be loaded are read <i>before</i> compiling the sources (and also in the order specified).</p>
<p>B++ also allows specifying a list of user arguments that are passed on to the program to be executed.<br>
This list is introduced by a hash symbol (#) and forms the end of the command line. Within a B++ program, the entire or the user argument list can be accessed using the predefined functions #getargs() or #getusrargs().<br>
The complete argument list is also passed to the entry function main when called from the command line, so that access to the arguments is also possible using the functions argcnt(), arg(i) or argv().
Unlike BOB+, B++ uses a dynamic stack whose size is limited only by available memory. An explicit definition of size using an environment variable is therefore neither necessary nor possible.


@page LangRef Short language reference

@section ProgStructure The Structure of a B++ Program

<p>Each B++ program consists - as in C - of a <i>set of functions</i>. The entry point is usually the <tt>main()</tt> function. In addition to pure functions, the highest structural level can also contain <i>processing instructions</i>, <i>variable definitions</i> and <i>class declarations/definitions</i>.</p>
<p>Unlike in C, global variables can be created within the implementation of functions using the <tt>#defvar</tt> processing instruction.</p>
<p>As in C and C++, it is not possible to define functions locally, i.e. within other functions.</p>
<p>In principle, <i>every identifier must be declared before the first reference</i> to it.</p>
<p>The following inevitable &quot;Hello World&quot; example, which is intentionally a little more complicated than necessary, shows the typical program structure:</p>
@code{.c}
/* B++ Hello World example */
 
// write a string to console
void printString(var str)
{
   var n = strlen(str);
   for (var i=0; i<n; ++i)
      putc(str[i], stdout);
}
 
var main()
{
    printString(Hello World - this is B++\n); 
    return 0;  
}
@endcode
<p>As you can see, there is a great syntactic similarity to C/C++.</p>
<p>First of all, it should be said that B++ is format-free. This means that indentations, blank lines, line breaks, etc. have no syntactic meaning. They only serve to make the source text easier to read. There is no limit to the length of a single line of source text, but to make the text easier to read, it is advisable not to use unnecessarily long lines.</p>
<p>Lines 1 and 3 in the example above contain comments. A function <tt>printString</tt> is then defined, which takes a character string in the <tt>str</tt> parameter and outputs its content character by character to the console.<br>
It uses the predefined functions #strlen (determines the length of the character string) and #putc (file output of a character) as well as the also predefined variable <tt>stdout</tt>, which represents a reference to the standard output - usually the console.<br>
In lines 6 and 7, the locally (i.e. within the function) valid variables <tt>i</tt> and <tt>n</tt> are defined using the keyword <tt>var</tt>.</p>
<p>The keyword <tt>var</tt> is used in two other contexts in the example too: In line 11 it indicates that the <tt>main</tt> function returns a value. In line 4 it appears before the <tt>str</tt> parameter in the function header as a replacement for a type identifier, as it would have to be written in C.<br>
In front of the function header in line 4 there is also the keyword <tt>void</tt>, which indicates that the <tt>printString</tt> function does not return a value.</p>
<p>In these contexts, the keywords <tt>var</tt> and <tt>void</tt> are not absolutely necessary and could therefore be omitted. Its purpose is, among other things, also in using automatic documentation generators for B++ sources, such as Doxygen, which are actually designed for the syntax of C or C++.<br> They can also improve the understandability of the source code. If you mark a function with <tt>void</tt>, the compiler also prevents the return of a value, but if you specify <tt>var</tt>, a value must actually be returned with <tt>return</tt> statement.</p>
<p>The entry function <tt>main</tt> now calls <tt>printString</tt> with the character string to be output as an argument.</p>
The special meaning of the return value of the <tt>main</tt> function should be pointed out here. Since there is no caller of this function within the program, the value is returned to the operating system itself (under DOS and in the Windows console as an 'errorlevel'). This results in the restriction that the return value can only be an integer. For this reason, B++ first checks the type of the return value after the main function ends. If it is an integer value, it is returned, otherwise 0.</p>
<p>The "Hello World" example looks even more C-like when you use the optional static type definitions:</p>
@code {.c}
/* B++ Hello World example */

// write a string to console
void printString(string str)
{
   int n = strlen(str);
   for (int i=0; i<n; ++i)
      putc(str[i], stdout);
}

int main()
{
    printString(Hello World - this is B++\n); 
    return 0;  
}
@endcode
<p>Here, instead of the keyword <tt>var</tt>, a type identifier is used (<tt>%string</tt> and <tt>int</tt> in the example). In addition to improved readability, a large part of any necessary validity checks can be delegated from the source code - and thus the responsibility of the programmer - to the compiler or the runtime environment, which in the best case leads to shorter source code and better (more stable) programs - in order to price of a slightly slower runtime behavior.</p>
@section Syntax Syntax Elements
<p>This chapter explains the basic syntactic elements that are important for writing B++ programs. This is not a complete formal syntax description. Rather, the most important language elements are presented in comparison to C/C++.</p>

@subsection Comments Comments
<p>There are three types of comments in B++:</p>
<ul>
<li><b>C-style comments:</b><br>
Such comments have the form <tt>/&lowast; comment text &lowast;/</tt>.<br>
They can span multiple lines but cannot be nested.</li>
<li><b>C++ style comments:</b><br>
These comments are written in the form <tt>// comment text</tt>.<br>
They reach to the end of the current source code line.</li>
<li><b>Comments starting With <tt>\@</tt> or <tt>\#!</tt>:</b><br>
This form of comment is used to embed B++ sources in shell scripts (batch files under DOS). For B++ itself it is identical to the C++ comments. However, since the \@ character in batch scripts (or the combination \#! in Unix shell scripts) initiates a valid command line whose output is simply suppressed, this type of comment can be used to include B++ code in such scripts.</li> 
</ul>
@subsection Identifiers Identifiers
<p>For identifiers in B++ essentially the same rules apply as in C or C++.</p>
<p>Identifiers consist of a sequence of letters (without umlauts and other language specific characters) and numbers or the underscore (_) and the dollar symbol ($). They must not start with a number; the notation of identifiers is case sensitive.</p>
<p>There is no limit on the length of identifiers or the number of significant characters in B++.</p>
<p><b>Examples of identifiers:</b></p>
<pre><tt>
MyClass
myValue
_anInternalVariable
%p1
%$A
</tt></pre>
<p>In general, identifiers should be chosen so that they make it easier to read the source code later. This means in particular that identifiers should, if possible, allow a direct conclusion about their intended use.</p>

@subsection Literals Literals
<p>Literals in the narrower sense are constant values noted directly in the source code. This initially includes the notations of values of the various elementary data types. In addition, in B++ there are extended forms for initializing vectors and dictionaries as well as function literals and literally expressions.</p>

@subsubsection Characters Character Literals
<p>A character literal is a single character with a character code between 0 and 255 (up to FFFFH for UNICODE source files), enclosed in quotes, e.g. 'A','x','','7','\\n'.<br>
The last character in the list above has a special feature. It does not represent a printable character, but a <i>control character</i>. The representation of special characters is always started with a backslash (\\), often also called an <i>escape character</i>.<br>ollowing table lists the escape codes interpreted by B++ with their meaning.</p>

| Escape-Code | Meaning | Character Code (HEX) |
| :---------: | :-----: | :------------------: |
| \\0 | NUL-Byte | 00 |
| \\a | Beep | 07 |
| \\b | Backspace | 08 |
| \\f | Page Break | 0C |
| \\n | Line Break | 10 |
| \\r | Carriage Return | 0D |
| \\t | Hor. Tabulator | 09 |
| \\v | Vert. Tabulator | 0B |
| \\\\ | Backslash | 5C |
| \\' | Single Quote | 27 |
| \\\" | Double Quote | 22 |


<p>Like C/C++ (and following the same rules), B++ allows the use of escape sequences to notate the code of non-printable characters as character literals. The code can be specified in hexadecimal or octal. So a construct like <tt>'\\xFF'</tt> or <tt>'\\377'</tt> corresponds to the character with code 255.<br>
It is also possible to specify the value in binary form in an escape sequence. In this case it starts with <tt>\\0b</tt>. The character with code 255 could also be specified as <tt>'\\0b11111111'</tt>.</p>
<p>In addition, the escape sequences <tt>'\\uXXXX'</tt> (UTF-16 characters) and <tt>'\\UXXXXXXXX'</tt> (UTF-32 characters) are also interpreted analogously to C++11, where XXXX stands for a sequence of hexadecimal digits.</p>
<p>Character literals (or character types) are integral types and can be treated like integers (type <tt>%int</tt>), where the character code corresponds to the numerical value. Accordingly, they can be used in the source code wherever an integer can appear.</p>

@subsubsection Strings String Literals
<p>%String literals are sequences of any printable characters or escape codes (see Table above) or escape sequences, enclosed in quotation marks. If the quotation mark itself occurs in a character string, it must be specified as an escape code. %String literals can be of any length.</p>
<p><b>Examples of string literals:</b></p>
@code{.c}
"Hello World!"
"He said, 'I'm tired.'"
"Address:\n\tName:\n\tStreet:\n\tCity:\n"
"c:\\prog\\bp2\\bpp c hello o hello.bpm"
"This string says 'Beep'\7 on the console!"
@endcode
<p>As in C++, %string literals can be concatenated directly. This allows long string literals to be easily spread across multiple lines.</p>
<p><b>Example:</b></p>
@code{.c}
var s = "This String parts "
"belong together."
@endcode
<p>Unlike C/C++, line breaks are allowed within string literals without a backslash (\\) at the end of the line. If there is a backslash at the end of the line, the line break in the resulting string is suppressed.</p>
<p><b>Example:</b></p>
@code
"It's hard to believe:
   This string works
      across multiple lines \
and also remembers the indentations
and line breaks."
@endcode
<p>B++ also allows the use of "raw strings", analogous to C++11. A raw string is a sequence of arbitrary characters whose content is not interpreted.<br>
The notation is as in C++11, i.e. according to the syntax</p>
@code{.unparsed}
rawstring ::= 'R"' [tag] '(' { any_character } ')' [tag] '"' .
@endcode
<p>The optional <tt><i>tag</i></tt> is an arbitrary identifier that is used as an extended end identifier if the character string ')\"' occurs in the text itself.</p>
<p><b>Examples:</b></p>
@code{.c}
var s1 = R"(Here \n or \0xFF and " are not interpreted.
Line breaks are also simply adopted.)";

var s2 = R"end( If the combination )" occurs in the text,
you need a tag to mark the end.)end";
@endcode

@subsubsection IntegerLiterals Integer Literals
<p>Integer literals are representations of whole numbers in decimal, binary, octal, or hexadecimal notation, which can optionally be preceded by a sign (+ or -). Octal numbers - like in C - are characterized by the fact that the first digit is a zero and all other digits are in the range between 0 and 7. Binary numbers start with <tt>0b</tt>, hexadecimal numbers start with <tt>0x</tt>. All other numbers are decimal numbers. By default, integer literals are mapped internally as 32-bit integers (type <tt>%int</tt>) and therefore have a value range of -2<sup>31</sup> to +2<sup>31</sup>-1. If the value of a literal exceeds this range, the internal representation is as a 64-bit integer (<tt>long</tt> type), value range -2<sup>63</sup> to +2<sup>63</sup>-1.</p>
<p>As in C++, the suffixes U and L or LL (can be combined, case-insensitive) can be appended to the literal to specify the internal representation as an unsigned constant or to have wide of 64 bit.</p>
<p>As in C++11, it is allowed to insert apostrophes into the notation to separate groups of numbers for better readability.</p>
<p>Some possible variants of notations are shown below:</p>
@code{.cpp}
17               // 32-bit integer in decimal representation
-234567L         // 64-bit integer in decimal representation
0x7FFFFFFUL      // unsigned 64-bit integer, hexadecimal
021U             // unsigned 32-bit integer, octal
0b1000'1001'0001 // 32-bit integer in binary representation with groups of digits
0x2dff0          // 32-bit integer in hexadecimal representation
@endcode

<p><b>Extended suffixes:</b></p>

<p>Starting with version 1.3 of B++, the interpretation of suffixes of integer literals was modified and expanded. The goal is to be able to specify the data type of the resulting value exactly.</p>
<p>The following rules apply in detail:</p>
<ul>
<li>The suffix S (or s) forces a signed value. It cannot be combined with the U suffix.</li>
<li>The suffix L can be followed by a number 0, 1, 2, 4 or 8. The number 0 specifies that the 'smallest' data type that can represent the value should be used; the remaining digits specify the required data type size in bytes.</li>
<li>If no suffix L is specified, the result is 32 or 64 bits wide, depending on the value.</li>
<li>If no suffix U or S is specified, the signed type is preferred, which means that the signed type is used if the magnitude of the value can be represented with it, otherwise the unsigned type is used.</li>
<li>If the data type size is explicitly specified, it is guaranteed that the value can be represented with the resulting type.</li>
<li>If the suffix S is specified and the value is written in decimal notation, it is guaranteed that the magnitude of the value can be represented in the positive value range of the resulting type</li>.
<li>Violations of the stated guarantees will result in an error in the translation.</li>
</ul>
<p>The following example demonstrates some variants of extended suffix notation:</p>
@code{.cpp}
17L1      // 8-bit integer in signed decimal representation (implicit)
128L1     // 8-bit integer in unsigned decimal representation (implicit)
17SL1     // 8-bit integer in signed decimal representation (explicit)
17UL1     // 8-bit integer in unsigned decimal representation (explicit)
128SL1    // --> Error: 128 cannot be displayed in the range 0..127
0x80SL1   // 8-bit signed hexadecimal integer (explicit)
0x8000SL0 // 32-bit signed integer
0x8000L0  // 16-bit unsigned integer
@endcode
@note The extended suffix rules are largely compatible with the previous ones. If the extensions are not used, the result is the same as before - with one exception: If the value of a literal without specifying the suffix U exceeds the positive value range of the <tt>long</tt> type, but not that of <tt>ulong</tt>, no error is reported, but a silent result of type <tt>ulong</tt> created.

@subsubsection FPLiterals Floating point literals
<p>Floating point literals are representations of real1 numbers according to the syntax</p>
@code{.unparsed}
fltlit ::= [+|-] digit[.digit {digit}][e|E [+|-] digit{digit}] .
@endcode
<p>where <tt>digit</tt> is a decimal digit. By default, the internal representation is double precision (8 bytes, type <tt>double</tt>), which limits the precision to 15 digits of the mantissa and the value range is between -1.7*10<sup>308</sup> and 1.7*10<sup>308</sup>. The suffix F (or f) explicitly specifies the use of single precision (4 bytes, type <tt>float</tt>, value range between -3.4*10<sup>38</sup> and 3.4*10<sup>38</sup> with 7 digits of the mantissa).</p>
<p>Examples of floating point literals:</p>
@code{.cpp}
3.141593      // double
-123.4567E23  // double, expotential representation
123e-4F       // float, expotential representation, no decimal places
-1.234567e-2f // float, expotential representation
2.5E+6        // double, with optional + before exponents
3E14          // double, exponential representation, no decimal places
@endcode

@subsubsection ExtendedLiterals Extended Literals
<p>Variables of the container data types <tt>\ref BufferType "buffer"</tt>, <tt>\ref VectorType "vector"</tt> and <tt>\ref DictionaryType "dictionary"</tt> can be initialized using literals. Additionally, literals can be used wherever a constant instance of such a container is needed. The notation of these literals is described in connection with the corresponding data types.</p>
<p><i>Function literals</i> allow the creation of so-called <i>anonymous functions</i> that can be assigned as a value to a variable, used as temporary inline functions or similar to the function macros known from C/C++. They are discussed in the chapter about \ref Functions "functions" below.</p>

@subsubsection LiteralExpressions Literal expressions
<p>B++ allows the creation of <i>literal expressions</i>. This means expressions in which all operands themselves represent literals. All operators  that are applicable to constant operands can be used in such expressions.</p>
<p>Literal expressions are not evaluated at runtime, but directly by the compiler. Your result is a literal again. They can be used in a program anywhere where a constant value is syntactically permitted.<br>
In addition, they are important in context of conditional translation for evaluating conditions.</p>
<p>Since version 1.7, the concept of literal expressions was expanded so that they are evaluated either directly by the compiler (as before and by default) or by temporarily translating them into bytecode and interpreting the result.<br>
The latter method enables all global and static symbols present in the translation context to be used as operands in literal expressions. These include global variables, constants and functions, predefined classes and static members of classes, as well as static local variables and constants in functions.<br>
However, this extension increases compilation time. For each literal expression, bytecode is first generated in the form of a temporary function, and then interpreted.<br>
As this extension is usually needed in rare cases only, it is disabled by default. It can be enabled and disabled using the <tt>\#pragma compexpr</tt> processing instruction.</p>
@note <table border="0"><tr><td align="left"><p>B++'s compiler does not automatically optimize code. This means that expressions are normally evaluated at runtime unless they are used to statically initialize variables - even if their operands are literals (and therefore constant).</p>
<p>With the help of the keyword <tt>litexp</tt> an expression <tt>\<expr\></tt> in the form</p>
<pre>          <tt>litexp(\<expr\>)</tt></pre>
<p>can explicitly marked as a literal expression and thus its calculation can be forced by the compiler (i.e. during program compilation), which leads to more compact and, above all, faster code.</p>
<p>Since version 1.7, marking can be done in the following form too:</p>
<pre>          <tt>compexp(\<expr\>)</tt></pre>
<p>where the keyword <tt>compexp</tt> enforces the extended form of interpretation.</p>
<p>The keywords <tt>litexp</tt> (for the simple form) and <tt>compexp</tt> (for the extended form) override the default behaviour for interpreting literal expressions (<tt>\#pragma compexp</tt>) for the respective expression. These keywords can also be used together within an expression to control the interpretation of parts of a more complex literal expression.</p>
</td></tr></table>

@subsubsection NamedLiterals Named Literals
<p>Literals can be assigned a symbolic name (an identifier). In this way, symbolic constants or  with the help of function literals  inline functions can be created. Named literals are defined using the processing instructions <tt>\#deflit</tt> or <tt>\#literal</tt>. 
@note Because the compiler treats each individual source file as a separate translation unit, the identifiers of named literals are only valid within the source file in which they were defined. If you want to use symbolic constants defined in this way in several translation units, they should be defined in their own (header) file and this file should be integrated into the related source files using <tt>\#include</tt> instruction.

@subsubsection PredefinedLiterals Predefined literals
<p>The predefined literals <tt>true</tt> and <tt>false</tt> exist for the <tt>%bool</tt> data type to represent its possible values.</p>
<p>The predefined literals \c UNICODE, \c WIN32, \c WINCE, \c MSDOS, \c UNIX, \c LINUX and \c BPPI64 provide information about which platform the currently used B++ compiler itself was compiled and whether it is the Unicode version. These literals are of type <tt>%int</tt> and have the value 1 (or <tt><i>%true</i></tt>) if the given condition applies at compile time, and 0 (or <tt><i>%false</i></tt>) if not.</p>
<p>The predefined literal <tt>__bplusplus</tt> is of type <tt>%uint</tt> and contains 100 times the version number of the compiler when compiling, e.g. 130 for version 1.30.</p>
<p>Also predefined are \c PTRSIZE (type <tt>%uint</tt>), which specifies the size in bytes of an address of the system used during translation, and \c NPOS (since version 1.4 and defined as <tt>%uint(-1)</tt>) to identify an invalid index value.</p>
<p>Starting with version 1.5 there are also the predefined literals \c CHARSIZE and \c WCHARSIZE (both <tt>%uint</tt>), which specify the size of the internal character representation and the type size of <tt>%wchar_t</tt>, respectively.</p>
<p>The literals \c EDOM (Domain Error) and \c ERANGE (Range Error) are predefined as the (unfortunately only) standardized error identifiers in the C library. They can occur in connection with numeric functions when invalid argument values used or number ranges are exceeded.</p>
<p>To simplify work with type information, named literals are predefined as symbolic names of the data types supported by B++. Following table contains a complete overview.</p>
| Literal | Type ID | Data Type |
| :-----: | :-----: | :------: |
| \c BVT_NULL | 0 | \b null |
| \c BVT_VOID | 1 | no value (return type of functions) |
| \c BVT_AUTO | 2 | uninitialized auto-variable |
| \c BVT_NIL | 3 | \c null (return type of functions) |
| \c BVT_SBYTE | 64 | \b sbyte |
| \c BVT_BOOL | 65 | \b bool |
| \c BVT_CHAR | 66 | \b char |
| \c BVT_BYTE | 68 | \b byte |
| \c BVT_UCHAR | 70 | \b uchar |
| \c BVT_CHAR8 | 71 | \b char8_t |
| \c BVT_SHORT | 72 | \b short |
| \c BVT_USHORT | 76 | \b ushort |
| \c BVT_CHAR16 | 78 | \b char16_t |
| \c BVT_WCHAR | 79 | \b wchar_t |
| \c BVT_INT | 80 | \b int |
| \c BVT_INTPTR | 81 | \b intptr |
| \c BVT_UINT | 84 | \b uint |
| \c BVT_UINTPTR | 85 | \b uintptr |
| \c BVT_CHAR32 | 86 | \b char32_t |
| \c BVT_LONG | 88 | \b long |
| \c BVT_ULONG | 92 | \b ulong |
| \c BVT_FLOAT | 112 | \b float |
| \c BVT_DOUBLE | 120 | \b double |
| \c BVT_FILE | 128 | \b FILE |
| \c BVT_CODE | 129 | \b function (native) |
| \c BVT_VAR | 130 | variable/element of dictionary |
| \c BVT_OBJECT | 160 | \b object  |
| \c BVT_STRONGOBJECT | 161 | object variable of fixed class type |
| \c BVT_CLASS | 168 | \b Class  |
| \c BVT_STRING | 176 | \b string |
| \c BVT_BUFFER | 177 | \b buffer |
| \c BVT_CHARBUFFER | 178 | \b charbuffer |
| \c BVT_VECTOR | 180 | \b vector |
| \c BVT_BYTECODE | 181 | \b function (B++) |
| \c BVT_LOCALVARINFO | 182 | variable info (intern) |
| \c BVT_DICTIONARY | 184 | \b dictionary |
| \c BVT_OBJECTREF | 224 | reference to \c object  |
| \c BVT_CLASSREF | 232 | reference to \c Class  |
| \c BVT_STRINGREF | 240 | reference to \c string  |
| \c BVT_BUFFERREF | 241 | reference to \c buffer  |
| \c BVT_CHARBUFFERREF | 242 | reference to \c charbuffer  |
| \c BVT_VECTORREF | 244 | reference to \c vector  |
| \c BVT_BYTECODEREF | 246 | reference to \c function (B++) |
| \c BVT_DICTIONARYREF | 248 | reference to \c dictionary |

<p>The \"Literal\" column contains the symbolic names, \"Type ID\" is the associated numerical value, e.g. used by the predefined functions #gettype and #gettypename. The words in \b bold in the \"Data Type\" column can be used as type identifiers for the explicit typing of variables.</p>
<p>Also predefined are the literals \c LC_ALL (0), \c LC_COLLATE (1), \c LC_CTYPE (2), \c LC_MONETARY (3), \c LC_NUMERIC (4): and \c LC_TIME (5) for the categories of the #setlocale function as well as \c SEEK_SET (0), \c SEEK_CUR (1) and \c SEEK_END (2) for the origin of the #fseek function.</p>
<p>In addition, based on the C99 standard, there are predefined literals \c \__func__ (\c string), \c \__FILE__ (\c string) and \c \__LINE__ (\c int) to specify the current method or function name, the file name or the current line number during translation. The values of these literals are formed by the scanner depending on the current position in the source text.</p>

@subsection Statements Definitions, Statements and Blocks
<p>As already mentioned, a B++ program essentially consists of class declarations, variable and function definitions at the highest source code level. Additionally there are processing instructions too.</p>
<p>Function definitions consist of a \e header, which contains the name of the code object, as well as a \e block that contains the actual content.<br>
A block is a collection of consecutive \e statements and (optionally) <i>variable definitions</i>.<br>
In B++ a block - such as in C/C++  is delimited by curly brackets \( { and } \).</p>
<p>Every statement or definition contained in a block must (as in C/C++) be terminated with a semicolon (;). A block can appear wherever a statement is syntactically allowed. This is particularly important in connection with control structures.</p>

@subsection ProcessingInstructions Processing Instructions
<p>Processing instructions, unlike all other instructions, are executed by the compiler during source code translation and not by the bytecode interpreter.</p>
<p>Although B++ does not have a preprocessor, they are very similar to preprocessor instructions in C/C++ and are written the same way. In particular, this means that they are not terminated with a semicolon. Like preprocessor instructions in C/C++, processing instructions can also be notated anywhere in a source text.</p>
<p>The processing instructions available in B++ are described in detail below.</p>

@subsubsection IncludeInstruction The \#include Statement
<p>The \c \#include processing instruction includes a source file in the currently translated source text as if its contents had been noted at the location of the \c \#include instruction.</p>
<p>As in C or C++, there are two forms of notation:</p>
<p>\c \#include \"<i>filename.ext</i>\" or<br>
\c \#include \<<i>filename.ext</i>\>.</p>
<p>The difference between the two forms of notation lies in the way in which the search for the file to be included is done.<br>
In the first variant, the search is carried out first in the current directory (the directory of the file that contains the \c \#include directive), then in all directories of the files that contain higher-level \c \#include directives, and finally along the path via the environment variable \c BPPINC specified search path. With the second variant, search in \"superior\" directories is not done.<br>
In both cases, a relative or absolute directory path can be specified before the file name.</p>

@subsubsection UseInstruction The \#use Statement
<p>The \c \#use statement includes a precompiled bytecode library in the current program. The symbols contained in the library are then adopted into the program. This means that when compiling a program that includes a library with \c \#use, bytecode is created that contains the entire contents of the library.</p>
<p>Usage: \c \#use \"<i>filename.ext</i>\"</p>
<p>The file name can be preceded by a relative or absolute path. B++ first looks for the specified file in the current directory (the directory of the file containing the \c \#use statement). If the search there is unsuccessful, the directories specified in the \c BPPLIB environment variable are also searched.</p>
<p><b>Application example:</b></p>
<p>Let a library be named <tt>tstfunc.bpp</tt> and export a function named \t testfunc.</p>
@code{.cpp}
// using #use example  module tstfunc.bpp 
void testfunc(var n)
{
     print("testfunc(",n,") from tstfunc.bpp\n");
}
@endcode
<p>The library is now translated into bytecode:</p>
<tt>bp2 -c tstfunc -o tstfunc.bpm</tt>
<p>... and used by the following program:</p>
@code{.cpp}
// using #use example  main module 
#use tstfunc.bpm

void main()
{
   testfunc(Hello World);
}
@endcode
@note
If the filename used as an argument contains an asterisk \(*\), this character is replaced with a build-specific identifier, which can contain the following components:
<ul>
<li>u : denotes a Unicode version</li>
<li>d : denotes a debug version</li>
<li>_64 : indicates a 64-bit version</li>
</ul>
This allows the integration of different bytecode modules depending on the build variant of the runtime environment used for execution.

@subsubsection ImportInstruction The \#import statement
<p>The \#import statement allows dynamic B++ extension libraries (DLLs) to be included at compile time.</p>
<p>Usage: \c \#import \"<i>filename.ext</i>\"</p>
<p>Here, the file name can be preceded by an absolute or relative path too.<br>
The search for the library to be loaded occurs first in the current directory (the directory of the file containing the \#import statement) and then in the search path specified by the \c PATH environment variable.</p>
@note
If the filename used as an argument contains an asterisk \(*\), this character is replaced with a build-specific identifier, which can contain the following components:
<ul>
<li>u : denotes a Unicode version</li>
<li>d : denotes a debug version</li>
<li>_64 : indicates a 64-bit version</li>
</ul>
This allows bytecode modules to be created that may incorporate other extension libraries when executed on a different target platform.

@subsubsection LiteralInstruction The \#deflit, \#literal and \#undeflit statements
<p>These processing instructions are used to define named literals or to remove the definition of a named literal.</p>
<p>With<br>
\c \#deflit <tt>&lt;identifier&gt; &lt;litexpr&gt;</tt> or<br>
\c #literal <tt>&lt;identifier&gt; &lt;litexpr&gt;</tt><br>
a named literal is defined with the specified identifier. Any literal expression can be used as the assigned value.</p>
<p>The difference between the two forms is that \c \#literal only takes effect if there is not already a literal definition under the specified name, while \c \#deflit overwrites an existing definition if necessary.</p>
<p>With<br>
\c \#undeflit <tt>&lt;identifier&gt;</tt><br>
an existing definition of a named literal can be removed.</p>
<p>Examples:</p>
@code {.bpp}
#deflit PI 3.141593
#literal TRUE 1
#literal FALSE 0
#literal HIWORD function(x) { return (x >> 16) & 0xFFFF;}
#literal LOWORD function(x) { return x & 0xFFFF;}
@endcode
<p>The last two lines define two functions as literals that extract the high order or low order 16-bit word from a 32-bit word, respectively. This form is comparable to function macros. The main difference is that these are "real" (anonymous) functions, not macros that are only expanded when they are used.</p>

@subsubsection DefineInstruction The \#define and \#undef statements
<p>Until version 1.4, \c \#define was an alias for \c \#literal and \c \#undef was an alias for \c \#undeflit.</p>
<p>Since version 1.5, these instructions largely correspond to the preprocessor commands of the same name in C/C++, i.e., they are used to define macros.</p>
<p>In particular, variadic macros, i.e. those with a variable number of arguments, are supported in accordance with the C99 standard.<br>The gcc-specific extension is also supported, which allows the notation of <tt>\#\#</tt> before \c \__VA_ARGS__ to suppress a comma in front of a variable argument list if the variable argument list is empty.<br>
In addition, the concatenation operator <tt>\#\#</tt> can also be written after \c \__VA_ARGS__. In this case, it suppresses any comma that may appear after an empty variable argument list.</p>
<p>Since version 1.7, support for \c __VA_OPT__(x) was addad (\x is expanded, if \c __VA_ARGS__ is not empty. As a converse, there is also  there is also \c _VA_DEF(x)__, where \c x is expanded if \c __VA_ARGS__ is empty.
<p><b><u>Additional notes about macros:</u></b></p>
<p>Because B++ does not have a real preprocessor, both the macro names and formal parameters must always be identifiers in the B++ sense. Replacing keywords is not possible.<br>The macros themselves are not stored internally as text, but as a token list. Accordingly, the replacement is also based on the existing token list. This means that operations performed in lexical analysis are not possible in macro expansion. This applies, for example, to the recognition of numeric literals.</p>
<p>When macros are expanded, any existing parameters are first replaced across the entire macro content, including the handling of variable argument lists, as described above.</p>
The next step handles the remaining concatenation operators (<tt>\#\#</tt>). The following combinations of tokens (left <tt>\#\#</tt> right) are possible for concatenation:
<ul>
<li>identifier or keyword <tt>\#\#</tt> identifier, keyword, or decimal integer<br>
Result is an identifier or a keyword.</li>
<li>special character <tt>\#\#</tt> special character, if the combination results in a token<br>
Result is the corresponding (operator) token.</li>
<li>string with any other token (left or right of <tt>\#\#</tt>)<br>
Result is a string.
</ul>
<p>Next, stringify operators (<tt>\#</tt>) are processed. Any token can be used for argument (follow-up token), except for processing instruction identifiers.</p>
<p>In the final step, consecutive character strings are combined to carry out the concatenation that would otherwise be performed by the scanner.</p></div>

@subsubsection DefvarInstruction The \#defvar statement
<p>Using \c \#defvar, initialized global variables can be defined inside and outside of functions.</p>
<p>Use:<br>
<tt> \#defvar &lt;varname&gt; &lt;value&gt;</tt><br>
Where <tt>&lt;varname&gt;</tt> is a valid identifier and <tt>&lt;value&gt;</tt> is the associated value.<br>
The variable value is initialized at compilation time and not at runtime. Therefore, only literals (or literal expressions) can be specified for value.</p>

Examples:
@code{.bpp}
#defvar version 2.1.0
#defvar bufSize 2048
@endcode
@note <ul>
<li>In contrast to the definition of named literals, which are only evaluated when they are used, \"real\" variables are actually created here and initialized with the value of the literal specified as a parameter. The visibility of these variables is not limited to the current translation unit.</li>
<li>Since version 1.4, the behavior of the \c \#defvar statement when a variable already exists has been changed: it is now ignored, whereas previously the existing definition was overwritten.</li>
</ul>

@subsubsection IfdefInstruction The statements \#ifdef, \#ifndef, \#if, \#elif, \#else and \#endif
<p>Since version 1.2, B++ supports the conditional translation of sections of source code in a notation that largely corresponds to that of the C preprocessor.</p>
The following table provides an overview of the syntax and meaning of the conditional translation instructions.
<table><tr><th>Instruction</th><th>Meaning</th></tr>
<tr><td><tt>\#ifdef \e defname</tt></td><td>Translation if a named literal or a macro <tt>\e name</tt> is defined.</td></tr>
<tr><td><tt>\#ifndef \e defname</tt></td><td>Translation if no named literal or macro <tt>\e name</tt> is defined.</td></tr>
<tr><td><tt>\#if \e literal_expression</tt></td><td>Translation if <tt>\e literal_expression</tt> equals \c true.</td></tr>
<tr><td><tt>\#elif \e literal_expression</tt></td><td>Conditional alternative branch. Translation if <tt>\e literal_expression</tt> equals \c true.</td></tr>
<tr><td><tt>\#else</tt></td><td>Unconditional alternative branch.</td></tr>
<tr><td><tt>\#endif</tt></td><td>End of conditional translation section.</td></tr>
</table>
<p>In table above, <tt>\e literal_expression</tt> means a literal expression, which can also contain expanded macros as components.<br>
Within a literal expression the pseudo operator</p>
<tt>defined(<i>name</i>)</tt>
<p>can be used to check the existence of a named literal or a macro. The bracketing of <tt>\e name</tt> is optional.</p>

@subsubsection ErrorInstruction The \#error and \#warning statements
<p>These instructions are used to output a message text during translation.</p>
<p><tt>\#error &lt;message&gt;</tt> or<br>
<tt>\#warning &lt;message&gt;</tt>,</p>
<p>where <tt>&lt;message&gt;</tt> is a literal expression that results in a %string.</p>
<p>While \c \#warning only outputs a message with line number and position, \c \#error aborts the translation.</p>

@subsubsection PragmaInstruction The \#pragma statement
<p>The \c \#pragma statement is used to control the compiler during translation.<br>
It has the general syntax</p>
<tt>\#pragma &lt;<i>function</i>&gt; &lt;<i>parameter</i>&gt;</tt>,
<p>where the following functions (identifier for <tt>&lt;<i>function</i>&gt;</tt>) are supported:</p>
<table><tr><th>Function</th><th>Parameter</th><th>Description</th></tr>
<tr><td>\c cdefine</td><td>\c on, \c off, \c push or \c pop</td>
<td>Determines whether \c \#define and \c \#undef are used according to the C standard (\c on, default) or are simply aliases for \c \#deflit and \c \#undeflit, respectively (\c off). The latter is primarily used for compatibility with earlier versions.<br>
The current state can be saved to a stack with \c push and restored with \c pop.<br>
If \c pop is called without prior \p push (when the stack is empty), this will result in a compiler error.</td></tr>
<tr><td>\c compexpr</td><td>\c on, \c off, \c push or \c pop</td>
<td>Determines whether literal expressions are evaluated directly by the compiler (off, default setting) or temporarily 
translated into bytecode and interpreted (on).<br>
The current state can be saved to a stack with \c push and restored with \c pop.<br>
If \c pop is called without prior \p push (when the stack is empty), this will result in a compiler error.</td></tr>
<tr><td>\c message</td><td>Output text<br>(literal expression)</td>
<td>Outputs text during translation. This corresponds to the behavior of \c #warning.</td></tr>
<tr><td>\c codepage</td><td>number or %string<br>(literal expression)</td>
<td>Sets the encoding of the current source file. If an integer is specified as the parameter, this is interpreted as the code page number (according to the Windows standard). Otherwise, an attempt is made to interpret the parameter as an encoding identifier (e.g. "iso8859-1", "Latin-1" or "UTF-8").<br>
By default, the standard operating system character set is assumed.</td></tr>
</table>

@subsubsection MarkLitInstruction Marking literal expressions with \#()
<p>This processing instruction was required until version 1.2 of B++ to explicitly mark literal expressions. Since version 1.3, the use of the \c litexp keyword is preferred instead, but it is still supported for backwards compatibility and can be used in the form</p>
<pre><tt>   \#(&lt;expr&gt;)</tt></pre>
<p>to mark <tt>&lt;expr&gt;</tt> as a literal expression. There must be no space between the hash symbol (\#) and the opening bracket.</p>

@subsubsection The \#endsrc statement
The \c \#endsrc statement marks the (early) end of a B++ source code, or in other words, any text after \c \#endsrc is ignored by the compiler.<br>
The purpose of its application is primarily to integrate B++ sources into shell scriopts (batch scripts).</p>
<p>The folloeing example program is a batch script for MS-DOS, called <tt>graph.bat</tt> that contains B++ source code:</p>
@code{.bpp}
@bp2 graph.bat
@goto end
// global settings
#define sizeX 240
#define sizeY 64
#define graphMode 4
#define textMode 7

main() {
	var px=sizeX;
	var py=sizeY;
	setscrmode(graphMode); // switch to graph mode
	var ms = timer();
	var n=0;
	for (var x=0;x<px;x+=2) {
		++n;
		var x2= px -x;
		line(x,0,x2,py-1,1);
	}
	for (var y=0;y<py;y+=2) {
		++n;
		var y2= py-1 -y;
		line(0,y,px-1,y2,2);
	}
	ms = timer() - ms;
	var r = n*1000 / ms;
	gets();
	setscrmode(textMode); // switch back to text mode
	print(r, " lines per second\n");
}
#endsrc
:end
@endcode

<p>The program fills a screen area (set with \c sizeX and \c sizeY) with lines and measures the time required for this.<br>
At the end the drawing speed (lines per second) is output.</p>
<p>The first two lines contain instructions for the DOS command processor. The preceding \@ character suppresses the screen echo under DOS and marks the lines as comments under B++.<br>
The B++ source code ends with the \c \#endsrc statement.</p>
<p>The last line belongs to the command processor again - it is the jump label that marks the end of the program.</p>


@section VariablesMain Variables, Constants and Datatypes
<p>B++ is primarily a language that is usually referred to as \e weakly or \e dynamically typed. This means a little more precisely:</p>
<p><i>In B++, not the variables, but only the values have a data type.</i></p>
<p>Optional static typing is achieved by restricting variables to only accept values of the same type as the value with which they were initialized.</p>

@subsection Variables Variables
<p>Variables are basically simply storage locations for any value that carry a lfreely selectable identifier.</p>
<p>In B++, variables <i>must always be defined before they are used for the first time</i>.</p>
<p>If a variable is defined at the "outermost" program level - i.e. outside of classes or functions - its scope is <i>global</i>, i.e. the variable can be accessed from anywhere in the program. This can lead to unwanted side effects in larger programs if you accidentally use the same variable in different places for different purposes.</p>
<p>In order to keep this risk low, there is <i>no implicit definition of global variables</i> in B++ by assigning a value to an arbitrary identifier, as is possible, for example, in JavaScript. <br>
A global variable must therefore be defined explicitly - either at the global program level (outside all functions and classes) or with the help of the processing instruction \c \#defvar.</p>
<p>In real programs, global variables are rather an exception and are used almost exclusively to exchange data between individual, more or less independent program parts.<br>
In order to create reusable and easily maintainable programs, global variables should be avoided as much as possible and - if they are absolutely necessary - well documented</p>
<p>In B++, the \e scope of local variables (and their lifetime) extends to the \e function within which they are defined. The definition takes place either in the form of a list of local variable identifiers at the end of the function header, separated from the parameter list by a semicolon, or by using the keyword \c var or a type identifier. Below is an example:</p>
@code{.bpp}
// using function-level variables 
// calculate n!
var fac(n; i, f)
{
	if (n==0)
		return 1;
	for(f=n, i=n-1; i>1; --i)
		f *= i;
	return f;
}

void main()
{
	for (var i=1;i<=10;++i)
		print("fac(",i,"")=",fac(i),"\n");
}
@endcode
<p>When developing new programs, variable declaration/definition with \c var (or an explicit type specification) is preferred. It allows local variables to be defined anywhere in the implementation body of a function while initializing them at the same time.<br>
On the one hand, this improves the readability of the code, but on the other hand, it can also improve the efficiency of the program by only executing initializations when necessary, i.e. the relevant program branch is actually reached.</p>

@subsection Constants
<p>Constants were introduced with version 1.5 of B++.</p>
<p>Technically, constants are variables with the restriction that after they have been initialized they can only be accessed by reading.<br>
Their definition is analogous to that of variables, with the type or the (then optional) keyword \c var being preceded by the \c const keyword.</p>
<p>Like variables, constants can also be declared globally, as members of classes or temporarily (within the implementation of functions). The same rules apply to scopes and lifetimes as to variables.</p>
<p>Unlike variables, constants must always be initialized immediately.<(p>
<p>There is no equivalent to the <tt>\#defvar</tt> processing instruction for constants, and there is also no way to define constants in the function header.</p>

@subsection Datatypes Data Types
<p>In B++, all values occurring in a program are stored in so-called <i>value objects</i>. Such an object essentially has a type information as well as the assigned value itself or a reference to it. Accordingly, one can distinguish between <i>value types</i> and <i>reference types</i>. This distinction is important for use in two ways:</p>
<ul>
<li>When assigning to variables, value types are copied completely, whereas in case of reference types only the reference to the data area is copied. Therefore, data changes here affect all variables that refer to the respective value.<br>
An example:
@code{.bpp}
main()
{
	var s1 = "Hello"; // initialize s1 as string
	var s2 = s1; // assign variable s1 to s2
	s2[1] = 'a'; // modify second character in s2
	print(s1,"\n"); // print value of s1
}
@endcode
The output here is "Hallo" and not  as you might expect  "Hello".<br>
The simple reason is that the variables \c s1 and \c s2 only contain references to the same data area. A "real" copy of the character string in \c s1 could be created, for example, using the #string function.</li>
<li>Constants are always copied (deep copy) when assigned to variables, regardless of whether they are a value or reference type.<br>
Example:
@code{.bpp}
main()
{
	const var s1 = "Hello"; // initialize s1 as string
	var s2 = s1; // assign copy of s1 to s2
	s2[1] = 'a'; // modify second character in s2
	print(s1,"\n"); // print value of s1
}
@endcode
In contrast to first example, \s1 is defined here as a constant whose value is completely copied when assigned to the variable \c s2. Consequently, the output here is "Hello" because the change in the second character only affects the variable \c s2.<br>
The \c var keyword in the declaration of \c s1 could also have been omitted.</li>
<li>The value objects mentioned and with them the data of the value types are created on the stack and cleaned up with it. The situation is different with reference types. Their data area is normally managed using reference counting, i.e. it is released when it is no longer used by any variables. There is also the option of explicit memory management by the user program.</li>
</ul>

@subsubsection ValueTypes Value Types
<p>Value types in B++ are the numeric types and the type \c null.</p>
@anchor IntegralTypes
<p><b>Integral data types</b></p>
<p>These types represent integer values of varying precision. Following table provides an overview of this.</p>
<table><tr><th>Type</th><th>Width (bits)</th><th>Value range</th><th>Remark</th></tr>
<tr><td>\c bool</td><td>8</td><td>\c false, \c true</td><td>Boolesn value, internally unsigned byte</td></tr>
<tr><td>\c sbyte</td><td>8</td><td>-128 ... 127</td><td>Signed byte</td></tr>
<tr><td>\c char</td><td>8</td><td>-128 ... 127</td><td>Signed single-byte character<br>(like \c char in C)</td></tr>
<tr><td>\c byte</td><td>8</td><td>0 ... 255</td><td>Unsigned byte</td></tr>
<tr><td>\c uchar</td><td>8</td><td>0 ... 255</td><td>Unsigned single-byte character<br>(like \c unsigned \c char in C)</td></tr>
<tr><td>\c short</td><td>16</td><td>-2<sup>15</sup> ... 2<sup>15</sup>-1</td><td>\c WORD with sign</td></tr>
<tr><td>\c ushort</td><td>16</td><td>0 ... 2<sup>16</sup></td><td>\c WORD unsigned<br>(like \c unsigned \c short in C)</td></tr>
<tr><td>\c char16_t</td><td>16</td><td>0 ... 2<sup>16</sup>-1</td><td>16-bit Unicode characters</td></tr>
<tr><td>\c int</td><td>32</td><td>-2<sup>31</sup> ... 2<sup>31</sup>-1</td><td>\c DWORD with sign</td></tr>
<tr><td>\c uint</td><td>32</td><td>0 ... 2<sup>32</sup>-1</td><td>\c DWORD unsigned</td></tr>
<tr><td>\c char32_t</td><td>32</td><td>0 ... 2<sup>32</sup>-1</td><td>32-bit Unicode characters</td></tr>
<tr><td>\c char8_t</td><td>32</td><td>sequence of characters</td><td>%String representation of an UTF-8 character, LSB is first character</td></tr>
<tr><td>\c wchar_t</td><td>8, 16 or 32</td><td>Like \c uchar, \c char16_t or \c char32_t <br>(platform dependent)</td><td>Wide character<br>(like \c wchar_t in C)</td></tr>
<tr><td>\c intptr</td><td>32 or 64</td><td>like \c int or \t long<br>(platform dependent)</td><td>Representation of an address<br>(signed)</td></tr>
<tr><td>\c uintptr</td><td>32 or 64</td><td>like \c uint or \t ulong<br>(platform dependent)</td><td>Representation of an address<br>(unsigned)</td></tr>
<tr><td>\c long</td><td>64</td><td>-2<sup>63</sup> ... 2<sup>63</sup>-1</td><td>like \c long \c long in C</td></tr>
<tr><td>\c ulong</td><td>64</td><td>0...2<sup>64</sup>-1</td><td>like <tt>unsigned long long</tt> in C</td></tr>
</table>
<p>Unlike in C/C++, signed and unsigned types are not distinguished by a modifier (\c signed or \c unsigned), but rather the distinction belongs directly to the type identifier. The \c signed and \c unsigned modifiers can be used in conjunction with the types \c char, \c byte, \c short, \c int and \c long (and according to the same rules as in C/C++) for C/C++ syntax compatibility, but are not part of a type name.<br>
This corresponds to e.g. a variable declaration</p>
<pre><tt>   unsigned short x</tt></pre>
exactly the declaration
<pre><tt>   ushort x</tt>.</pre>
<p>Additionally, the integral types in B++, with the exception of \c wchar_t, \c intptr, and \c uintptr, have a fixed width regardless of the compiler and the execution platform. This makes it easier to transfer programs - even in precompiled form - between different platforms.</p>
<p>The \c intptr and \c uintptr data types are used to record platform-specific addresses, usually temporarily. They are therefore 32 bits wide on 16- and 32-bit platforms and 64 bits wide on 64-bit platforms. Internally, \c intptr is treated like a signed integer, \c uintptr like an unsigned integer, so that address calculations can also be carried out.</p>
<p>The basic type of integral data types is the \c int data type. This means that integer literals are interpreted as \c int if their value can be mapped to the \c int type and type is not explicitly marked.</p>
<p>Until version 1.3, B++ did not recognize a "real" Boolean data type; instead, \c int values were used, with the value zero (0) being considered \e false and all other values being considered \e true. However, the reserved identifier \c bool could be used to declare variables to better clarify the intention.<br>
Since version 1.4 \c bool is an independent data type. In numeric operations, \c bool values are treated as unsigned bytes.<br>
The character types were introduced with version 1.5. Previously, individual characters (or character literals) were also represented as \c int. Values of character types are integral types and can therefore be used in numeric expressions, where the character code represents the value.</p>
<p>The following operations can be applied to values ??of integral data types:</p>
<ul>
<li>Assignment to a variable</li>
<li>Use in numerical expressions</li>
<li>Use in string expressions</li>
<li>Bit operations</li>
<li>numerical comparisons</li>
<li>Use as a function parameter</li>
</ul>
<p>Values of integral types can be combined with values of \c float and \c double types in numeric expressions and comparisons without explicit type conversion. In this case, the entire expression is implicitly converted to \c float or \c double. The same applies to the assignment to a statically typed variable of type \c float or \c double.<br>
When using integral values in string expressions (concatenation), there is an implicit conversion to an \c int value, which is interpreted as a character code.</p>

@anchor FloatType
<p><b>Data type \c float</b></p>
<p>The \c float data type represents a single-precision (32-bit) floating-point real number. The value range is between -3.4E38 and +3.4E38 with a numerical precision of 6 digits. Smallest amount that can be represented is 1.2E-37.</p>
<p>Allowed operations for the \c float type are:</p>
<ul>
<li>Assignment to a variable</li>
<li>Use in numerical expressions</li>
<li>numerical comparisons</li>
<li>Use as a function parameter</li>
</ul>
<p>Values of type \c float can be combined with values of integral types and \c double type in numeric expressions and comparisons without explicit type conversion. This involves an implicit conversion of the entire expression into the "larger" data type, i.e.  when combined with integral types the value is of type \c float, when combined with \c double it is of type \c double. When assigned to a statically typed variable of integral types or \c double type, an implicit conversion to the corresponding type occurs.</p>

@anchor DoubleType
<p><b>Data type \c double</b></p>
<p>The \c double data type represents a double-precision (64-bit) floating-point real number. The value range is between -1.7E308 and +1.7E308 with a numerical precision of 15 digits. Smallest amount that can be represented is 2.2E-308.</p>
<p>Allowed operations for the \c double type are:</p>
<ul>
<li>Assignment to a variable</li>
<li>Use in numerical expressions</li>
<li>numerical comparisons</li>
<li>Use as a function parameter</li>
</ul>
<p>Values of type \c double can be combined with values of integral types and \c float type in numeric expressions and comparisons without explicit type conversion. This involves an implicit conversion of the entire expression into the "larger" data type, i.e. the type \c double. When assigned to a statically typed variable of integral types or \c float type, an implicit conversion to the corresponding type occurs.</p>

@anchor NullType
<p><b>Data type \c null</b></p>
<p>The \c null data type denotes an uninitialized value. In the source code of a B++ program, data of this type are described by the keyword \c null, which can also be interpreted as a constant and the only possible value of the type \c null. Additionally, a number of predefined functions can return \c null.</p>
<p>Allowed operations for type null are:</p>
<ul>
<li>Assignment to a variable</li>
<li>Use in comparisons</li>
<li>Use as a function parameter</li>
</ul>
<p>Values of type \c null can be combined with all other types in comparisons without explicit type conversion. The value \c null is smaller than any other value.</p>

@subsubsection ReferenceTypes Reference types
<p>All data types in B++ that are not value types are reference types.</p>

@anchor StringType
<p><b>Data type \c string</b></p>
<p>The \c string data type represents a character string. Values of this type can be created explicitly using string literals, by the predefined function #newstring or the conversion function #string. In addition, they arise when using the concatenation operator (+) and as the return value of some other predefined functions.</p>
<p>Allowed operations for the string type are:</p>
<ul>
<li>Assignment to a variable</li>
<li>Use in string expressions</li>
<li>Use in comparisons</li>
<li>Use as a function parameter</li>
<li>Access individual characters using the [] operator</li>
</ul>
@note Direct access to elements of a (named) string literal using the <tt>[]</tt> operator is not permitted.<br>
When assigning a string literal to a variable, a copy of the string is created. They can be accessed without restriction.

@anchor FileType
<p><b>Data type \c FILE</b></p>
<p>The \c FILE data type is a reference to an open file. Instances of this type are created with the predefined function #fopen and released again with #fclose.</p>
<p>Permitted operations for the FILE data type are:</p>
<ul>
<li>Assignment to a variable</li>
<li>Use in comparisons</li>
<li>Use as a function parameter (especially for predefined \ref IOFuncs)</li>
</ul>

@anchor VectorType
<p><b>Data type \c vector</b></p>
<p>The \c vector data type represents data field of fixed (i.e. defined at creation time) or dynamic size. Its elements can be any values, even of different types. Instances of \c vector type are created using the predefined functions #newvector or #Vec or #T.<br>
Alternatively, a value of type \c vector can also be created (initialized) as a literal. The following syntax is used for this:</p>
<pre><tt>   vectorliteral ::= '[' [ literal { ',' literal }] ']' .</tt></pre>
<p>So a comma-separated list of values, enclosed in square brackets, is noted, where the values themselves are arbitrary literals (including vector literals).</p>
Following example illustrates this:
@code{.bpp}
var intvec = [1,2,3,4,5];
var mixedVec = [1, Hello, 3.14, null];
var matrix2d = [
	[1, 2, 3],
	[4, 5, 6],
	[7, 8, 9]
  ];
@endcode
<p>Valid operations for the vector data type are:</p>
<ul>
<li>Assignment to a variable</li>
<li>Use as a function parameter</li>
<li>Access individual elements using the operator <tt>[]</tt></li>
</ul>
@note Direct access to elements of a (named) vector literal using the <tt>[]</tt> operator is not permitted.<br>
When assigning a vector literal to a variable, a copy of the entire data field is created, which can be accessed 
without restriction.

@anchor DictionaryType
<p><b>Data type \c dictionary</b></p>
<p>The \c dictionary data type represents an associative array, i.e. a set of key-value pairs, where the keys are character strings and the values are of any type. By using values of the \c dictionary type, arbitrarily complex hierarchical data structures can be built. The keys are always unique within a hierarchy level.</p>
<p>Instances of type \c dictionary are created using the predefined function #newdict(sorted=0). The \e sorted argument can be used to specify whether the elements should be physically sorted according to the alphanumeric sequence of the keys (value <> 0) or left in the order in which they were added (value = 0).</p>
<p>Alternatively, a value of type \c dictionary can also be created (initialized) as a literal. The following syntax is used for this:</p>
<pre><tt>   dictliteral ::='{' ['!'] [key ':' literal {',' key ':' literal}]'}' .</tt></pre>
<p>So a comma-separated list of key-value pairs enclosed in curly brackets is noted, with keys and values, each separated by a colon. Character strings (in quotation marks) or valid identifiers can be specified for the keys. The values are arbitrary literals, including vector and dictionary literals.</p>
<p>Since version 1.4 of B++, an exclamation mark (!) can be written after the opening curly bracket, which forces a physical sorting according to the keys - like the sorted argument of the newdict function.</p>
Example:
@code{.bpp}
var person = {
	first name: Hugo,
	lastname: Meyer,
	years: 25
};
@endcode
<p>Permitted operations for the dictionary data type are:</p>
<ul>
<li>Assignment to a variable</li>
<li>Use as a function parameter</li>
<li>Access to individual elements / creation of new elements using operators <tt>.</tt> and <tt>[]</tt></li>
</ul>
@note Direct access to elements of a (named) \c dictionary literal using the operator <tt>[]</tt> or the dot operator is not permitted.<br>
When assigning a dictionary literal to a variable, a copy of the entire data field is created. They can be accessed without restriction.

@anchor BufferType
<p><b>Data type \c buffer</b></p>
The \c buffer data type provides a buffer for unstructured binary data. Variables of this type serve as read or write buffers for binary input/output functions (see \ref IOFuncs) and for transferring data areas to system functions.</p>
<p>Instances of type \c buffer are created explicitly using the #newbuffer(size, fillByte=0) function. Alternatively, a value of type \c string or \c charbuffer can be passed to the #newbuffer function. In this case, the buffer is created with a copy of the contents of the argument passed.<br>
In addition, buffer variables can be created from \c int, \c float and \c double values using the conversion function #buffer(arg), for example for passing as reference parameters to system functions.</p>
<p>Since version 1.4 of B++ there is also a literal representation for creating a buffer in the form</p>
<pre><tt>   bufferliteral ::= << litexpr .</tt></pre>
<p>\c litexpr is a literal expression that returns the absolute or relative path to a file from which the buffer contents are initialized. This allows constant data (resources) to be included directly in the generated program, similar to including source files.<br>
The search for the file determined by \c litexpr follows the same rules as for include files enclosed in quotation marks.</p>
Example using a buffer to include an external file as a resource:
@code{.bpp}
#literal textres << "externtext.txt"
void main() {
   print(string(charbuffer(textres)));
}
@endcode
<p>Valid operations for the \c buffer data type are:</p>
<ul>
<li>Assignment to a variable</li>
<li>Use as a function parameter</li>
<li>Individual elements (bytes) are accessed using the <tt>[]</tt> operator, where the elements are treated as unsigned integer values.</li>
</ul>
@note Direct access to elements of a (named) \c buffer literal with the operator <tt>[]</tt> is not permitted.<br>
When assigning a buffer literal to a variable, a copy of the entire buffer is created. They can be accessed without restriction.

@anchor CharbufferType
<p><b>Data type \c charbuffer</b></p>
<p>The \c charbuffer data type provides a character buffer. The individual elements are 8 or 16 bits wide, depending on whether you are working with ASCII/ANSI or Unicode. Variables of this type serve as buffers for character string manipulations and for passing data areas to system functions.</p>
<p>Instances of type \c charbuffer are created explicitly using the function #newcbuffer(size, fillChar=0). Alternatively, a value of type \c string, \c buffer or \c charbuffer can be passed to the #newcbuffer function. In this case, the buffer is created with a copy of the contents of the argument passed.<br>
In addition, instances of this type can be created as a concatenation of individual values of the types \c string, \c buffer and \c int using the constructor function #CBuf.</p>
<p>Allowed operations for the charbuffer data type are:</p>
<ul>
<li>Assignment to a variable</li>
<li>Use as a function parameter</li>
<li>Individual elements (characters) are accessed using the operator <tt>[]</tt>, where the elements are treated as integer values.</li>
</ul>

@anchor FunctionType
<p><b>Data type \c function</b></p>
<p>The \c function data type represents a function that can be called within the program. Internally, a distinction is made between predefined and user-defined functions (i.e. even written in B++)1. From the user's perspective, this distinction is not necessary. Explicit creation of instances of functions is not possible. There is always exactly one instance of a function, which is created for predefined functions when initializing B++ and for user-defined functions during the translation of the function declaration.</p>
<p>Valid operations for the function data type are:</p>
<ul>
<li>Assignment to a variable</li>
<li>Call</li>
<li>Use as a function parameter</li>
</ul>
@note If a function literal that contains at least one static variable in its definition or represents a coroutine (i.e. contains a <tt>yield</tt> statement in its implementation) is assigned to a variable, a new instance of the function is created. In this way, several functions with identical implementation can be created, but strictly speaking they are different functions because their static variables are independent of each other.

@anchor ClassType
<p><b>Data type \c Class</b></p>
<p>The \c Class data type represents a class available within the program. Classes are templates for concrete objects, which is why explicit instantiation of classes is not possible. There is always exactly one instance of a class, which is created during the translation of the class definition.</p>
<p>Classes are the only user-defined data types in B++.</p>
<p>Valid operations for the Class data type are:</p>
<ul>
<li>Assignment to a variable</li>
<li>Access to static variables defined within the class</li>
<li>Calling static functions defined in the class</li>
<li>Use as a function parameter in the RTTI functions</li>
<li>Use as a template for creating object instances with the \c new operator</li>
</ul>

@anchor ObjectType
<p><b>Data type \c object</b></p>
<p>The data type \c object represents concrete instances of a class in the sense of objects whose structure is formed according to a template given by a class. Objects are created from templates (\c Class type) using the \c new operator.</p>
<p>Permitted operations for the object data type are:</p>
<ul>
<li>Calling member functions</li>
<li>Assignment to a variable</li>
<li>Use as a function parameter</li>
<li>Use in expressions if appropriate operators have been defined</li>
</ul>

@subsection StaticTypedVars Statically Typed Variables
<p>Statically typed variables are declared by explicitly specifying a data type instead of the \c var keyword. This can be one of the predefined type identifiers or the name of a previously defined class.</p>
<p>To Variables defined in this way can only be assigned values that are of the declared type. If possible, an implicit type conversion takes place. The following general conversion rules apply:</p>
<ul>
<li>All numeric types (including the \c bool type in this context) can be converted to each other. If the value range of the target type is smaller than that of the source type, dada loss may occur.<br>
When converting between integer and real values, there may also be a loss of precision in the number representation.</li>
<li>The value \c null is assignment compatible with all reference types.</li>
<li>A variable of type \c FILE can be assigned with the integer value 0 (to indicate an uninitialized file variable). Values of type \c intptr are generally assignment compatible to \c FILE too.</li>
<li>The types \c string and \c charbuffer can be implicitly converted to each other. The conversion creates a copy of the value.</li>
<li>Any objects (instances of classes) can be assigned to variables of type \c object.</li>
<li>An instance (object) of a class type can be assigned to a variable of specified class type, if class of object is of same class type as defined for the variable or of e derived class.</li>
<li>Classes can additionally define conversion operators that allow the implicit conversion of their instances into different data types.</li>
</ul>
<p>In addition, there are standard functions for explicit type conversion for values into the predefined data types (see \ref RTTIFuncs).</p>
<p>Variables that are declared with the \c auto keyword are a special case. Such variables also have a fixed (static) data type, but - as in C++11 - this is set to the type of the assigned value when they are first initialized. Therefore they must be initialized immediately during definition.</p>
@note <ul>
<li>The compatibility check for assignments takes place at runtime, unless the type of the assigned value is already determined at compile time, which is the case with literals. As a result, type compatibility violations lead to runtime errors that are signaled as exceptions of type \c string and can be handled by the program.</li>
<li>The behavior of \auto variables is not entirely identical to that of C++-11. In B++, the type of local (temporary) \a auto variables in functions is determined at runtime.</li>
</ul>

@subsection InitVars Initialization of variables and constants
<p>The initialization of global variables, member variables in a class definition as well as static variables in functions and default values for function parameters takes place at compilation time. Thus, the initial value must be a literal (or the result of a literal expression).</p>
<p>Local (temporary) variables within a function are initialized at runtime. Therefore, the result of any expression can be used for initialization here.</p>
<p>When initializing statically typed variables, the type compatibility of the assigned value is checked during initialization.</p>
<p>The initialization of variables at compile time is done using the assignment operator (=) in the form</p>
<pre><tt>     type \e varname = \e initexpr </tt>or
<tt>     var \e varname = \e initexpr </tt></pre>
<p>For statically typed variables that are initialized at runtime - analogous to C++ - also (alternatively) the 'constructor notation', i.e. the form</p>
<tt>    type \e varname(\e initexpr)</tt>
<p>can be used.<br>
If variables of the built-in standard types are initialized in this way, the conversion function into target type is implicitly called. When objects (variables of a specific class type) are initialized, an instance of the corresponding class is created and its constructor is called.</p>
<p>The initialization of constants is exactly the same as that of variables; the distinction is achieved by prefixing the declaration with the keyword \c const.</p>
@note <ul>
<li>Because the scope of constants (as well as variables) defined at the function level is the function, constants should not be defined inside loops. This would lead to a runtime error on the second loop pass.</li>
<li>A variable of type \c FILE can be initialized in 'constructor notation' too. This is identical to an initialization by assignment with a call to the #fopen function. A definition<br>
<tt>   FILE fp(filename,mode)</tt><br>
corresponds exactly to the form<br>
<tt>   FILE fp = fopen(filename,mode)</tt><br>
In both variants, the file opened in this way must (or should) be explicitly closed again with #fclose.</li>
</ul>

<p><b>Implicit initialization</b></p>
<p>If a variable is not explicitly initialized when it is defined, it implicitly receives a default value. The following general rules apply:</p>
<ul>
<li>A dynamically typed variable (type \c var) has an initial value of \c null.</li>
<li>Variables of type \c bool are initialized with the value \c false.</li>
<li>Variables of numerical types are initialized with the numerical value zero (according to specific type)</li>.
<li>Variables of type \c string are initialized as an empty string.</li>
<li>Variables of container types (\c buffer, \c charbuffer, \c vector, \c dictionary) are initialized with an empty container.</li>
<li>Variables of other reference types (<tt>FILE</tt>, object types) generally have the initial value \c null unless they are strictly typed local (temporary) object variables in functions.</li>
<li>For temporary strictly typed object variables, an object instance is created and the respective constructor is called without arguments. This assumes that the respective class provides a constructor that can be called without parameters.</li>
</ul>
@note Implicit initialization of constants is not permitted; they must always be explicitly initialized when declared.

@subsection TypeConversions Implicit and Explicit Type Conversions
<p>Whenever data of different types is used in an expression, appropriate data conversions (or type conversions) are required. The rules applicable to such conversions in B++ are summarized below.</p>
<p>Within purely numerical expressions, the operands involved are implicitly converted to the type with the largest positive value range, but at least to the \c int type, unless only \c bool type operands occur. The rules that apply here essentially correspond to those of C/C++:</p>
<ul>
<li>Values of types \c bool (in mixed expressions), \c sbyte, \c char, \c uchar, \c byte, \c char16_t, \c short and \c ushort, \c char8_t and \c wchar_t are generally converted to \c int.</li>
<li>Values of type \c wchar32_t are converted to \c uint.</li>
<li>For the size of the numeric types applies<br>
<tt>   int &lt; uint &lt; long &lt; ulong &lt; float &lt; double</tt>.</li>
<li>The sizes of the \c intptr and \c uintptr types depend on the platform. On 64-bit platforms, they correspond to the types \c long and \c ulong, otherwise they correspond to the types \c int and \c uint.</li>
</ul>
<p>Strictly speaking, implicit type conversion in numerical expressions only takes place for operators with two operands (infix forms). The conversion affects the operands involved in an individual operation.<br>
For example this would be in an expression</p>
<tt>    2 * 3u - 1.7</tt>
<p>first the int value 2 is converted to the \c uint type for the multiplication and then the result is converted to the \c double type.</p>
<p>If objects appear as operands in a numeric expression, any existing operator methods of the objects for the relevant arithmetic or bit operator are preferred over a type conversion. If no such operators exist, a conversion operator is searched for in the target type.</p>
<p>For all other non-numeric values, no implicit typecasting is performed in expressions. Here it is the programmer's job to carry out an explicit type conversion if necessary.</p>
<p>Explicit type casts occur in the form</p>
<tt>   \e typename(\e expr)</tt>,
<p>where <tt>\e typename</tt> is the target type and <tt>\e expr</tt> is an expression whose result should be converted to the target type.</p>
<p>Predefined functions are available for explicit conversion to the built-in data types - see \ref RTTIFuncs.</p>
<p>For user-defined object types (classes), type conversion operators can be defined as member functions. It is also possible to define explicit conversions to object types as global functions.</p>
<p>Implicit type casts are also performed when assigning values to variables or to arguments of function calls, as long as the assignment target (the variable or the argument) is statically typed. In this case, the functions for explicit type conversion or the corresponding operators of objects are called automatically.</p>

@subsection PredefinedVars  Predefined variables and constants
<p>In B++, as in C, there are three predefined global variables of the \c FILE type that point to the system's standard input and output files:</p>
<ul>
<li><tt><b><i>stdin</i></b></tt>: standard input</li>
<li><tt><b><i>stdout</i></b></tt>: standard output</li>
<li><tt><b><i>stderr</i></b></tt>: standard error output</li>
</ul>
<p>These standard files cannot be opened with #fopen nor closed with #fclose.</p>
<p>In addition, there are the following predefined constants (from version 1.5, previously they were variables too):</p>
<ul>
<li>\c \__OSTYPE__: name of the operating system (\c string) on which the B++ runtime environment is running.<br>
Possible values are currently "WIN32" for the Windows desktop version, "WINCE" for Windows CE, "DOS" for MS-DOS systems, "LINUX" for Linux systems or "UNIX" for other UNIX systems.</li>
<li>\c \__UNICODE__: build variant of the runtime environment (\c int).<br>
It has the value 1 in the Unicode version, otherwise 0.</li>
<li>\c \__PTRSIZE__: Size of an address (pointer) of the runtime environment in bytes (\c uint).<br>
It thas the value 8 on 64-bit systems, otherwise the value 4.</li>
</ul>
<p>With the help of these constants, a B++ program can adapt its behavior at runtime to the peculiarities of the environment in which it is being executed - in contrast to the predefined literals, which are evaluated at compilation time. This is important because the bytecode generated by the compiler is independent of the platform on which it is later executed - only the runtime environment is platform-specific. However, it may be that different system-specific functions are available on different target platforms or that certain system properties must be taken into account.</p>
@code{.bpp}
if (__OSTYPE__ == "WINCE")
	Window(0,240,320,
	   WS_OVERLAPPEDWINDOW|WS_CLIPCHILDREN,WS_EX_OVERLAPPEDWINDOW|
	   WS_EX_CONTROLPARENT|WS_MAXIMIZE,title,_mainMenu);
else
	Window(0,640,480,
	   WS_OVERLAPPEDWINDOW|WS_CLIPCHILDREN,WS_EX_OVERLAPPEDWINDOW|
	   WS_EX_CONTROLPARENT,title,_mainMenu);
	   @endcode
<p>Example above shows an excerpt from the initialization of the main window of a Windows application implemented with B++. Here, depending on whether the application is running on Windows CE or not, the main window is initialized with different sizes and styles.</p>

@section Operators
<p>The concept of operators in B++ largely corresponds to that of C or C++. This chapter is therefore limited to a brief reference to the operators available in B++ and existing differences to C++. For classes (or objects) some of the operators can be defined or redefined.</p>

@subsection ArithmeticOps Arithmetic Operators
<p>The arithmetic operators implement the four basic arithmetic operations in conjunction with numerical operands. The addition operator can also be used on character strings (\c string data type). In this case it serves as a <i>concatenation operator</i>.</p>
<p>B++ knows the following arithmetic operators:</p>
| Operator | Meaning | Example |
| :------: | :-----: | :-----: |
| + (unary) | positive sign | +a |
| - (unary) | negative sign | -a |
| * | multiplication | a * b |
| / | division | a / b |
| % | remainder of division (modulo) | a % b |
| + | addition | a + b |
| - | subtraction | a - b |

@note <ul>
<li>The behavior of the operators depends on the data types of the operands. If both operands have integral data types, an integer operation is carried out, if at least one operand has the type \c float or \c double, a floating point operation.</li>
<li>If the operands have different data types, a conversion to the type of the larger value range takes place before the operation is executed.</li>
<li>The result of floating point operations is of type \c float if none of the operands is of type \c double, otherwise of type \c double. The result of integer operations is at least of type \c int.</li>
<li>If an operand of the addition operator (+) is of type \c string, the operator acts as a concatenation operator. The other operand must then either be of type \c string or of an integral type. In the latter case, the least significant byte (or word in UNICODE builds) of the numeric operand is interpreted as the code of a single character, unless the second operand is of a character type. If the operand is of a character type, it is converted into the internal character set.</li>
<li>The sign operators behave like those in C/C++. In particular, this means that they convert an integral operand with a smaller range of values to a value of type \c int. The unary minus also reverses the sign of numeric values.</li>
<li>All arithmetic operators can be defined as member functions for object types</li>
</ul>.

@subsection CompOps Comparison Operators
<p>The comparison operators - also known as <i>relational operators</i> - are used to compare their (always two) operands.</p>
<p>B++ knows the following comparison operators:</p>
| Operator | Meaning | Example |
| :------: | :-----: | :-----: |
| == | equality | a == b |
| != | unequality | a != b |
| &gt; | greater than | a &gt; b |
| &gt;= | greater than or equal to | a &gt;= b |
| &lt; | less than | a &lt; b |
| &lt;= | less than or equal to | a &lt;= b |

@note <ul>
<li>If numeric values of different types appear as operands, an implicit conversion is initially carried out into the type with the largest range of values. This can lead to problems due to numerical inaccuracies that occur during type conversion, especially in case of operators <tt>==</tt> and <tt>!=</tt>.</li>
<li>If one of the operands is numeric, the other operand must be numeric too.<br>
A comparison of a numeric value with a value of object type is also possible,if the object provides a conversion to the corresponding numeric type or a suitable implementation of the \c equals or \c compare methods.</li>
<li>Character strings (\c string) can be compared with character strings or with \c null.</li>
<li>Values of all other reference types can be compared with values of the same type (including weak references of the corresponding type) or with \c null. The following applies in detail:<ul>
<li>An element-by-element comparison is made for the types \c buffer, \c charbuffer and \c vector.</li>
<li>For the remaining reference types, the addresses of the data areas are compared, unless they are object types (classes) that implement the \c compare or \c equals methods and thereby define a changed behavior of the comparison operators.</li></ul></li>
<li>Values of type \c null are less than all other values.</li>
</ul>

@subsection LogicalOps Logical Operators
<p>The logical operators link truth values with each other. The following rules apply when interpreting values that are not of type bool as truth values:<ul>
<li>Values of type \c null have the truth value \c false.</li>
<li>Numeric values have the truth value \c false if their absolute value is 0, otherwise \c true.</li>
<li>All other values (values of reference types) have the truth value \c false if their value is \c null, otherwise \c true.</li>
</ul></p>
<p>The following logical operators are defined in B++:</p>
| Operator | Meaning | Example |
| :------: | :-----: | :-----: |
|! | NOT | !a |
| &amp;&amp; | AND | a &amp;&amp; b |
| \|\| | OR | a \|\| b |

@note <ul>
<li>The operator ! always returns a result of type \c bool, i.e. \c true or \c false.</li>
<li>Expressions with the operators &amp;&amp; or \|\| are evaluated from left to right. The evaluation stops when the result of the expression is determined. The return value is then the operand that caused the evaluation to be aborted. For this reason, the results of the operators must not be implicitly considered as \c bool values. Using the #bool conversion function, they can be explicitly converted into the Boolean values \c true or \c false.</li>
<li>The NOT operator can be defined as an element function for object types (classes).</li>
</ul>

@subsection BitOps Bit Operators
<p>The bit operators are only directly applicable to operands of integral types. They implement operations on the individual bits of the operands. In addition, they can be defined for object types (classes).</p>
<p>The following bit operators are defined in B++:</p>
| Operator | Meaning | Example |
| :------: | :-----: | :-----: |
| ~ | bitwise NOT | ~a |
| & | bitwise AND | a & b |
| \| | bitwise OR | a \| b |
| <span>^</span> | bitwise XOR | a ^ b |
| &lt;&lt; | shift left bitwise | a &lt;&lt; 3 |
| &gt;&gt; | shift right bitwise |  a &gt;&gt; 3 |

<p>The value of the right operand of shift operators cannot be negative and should not exceed the number of bits of the left operand.</p>
<p> The behavior of the &gt;&gt; operator depends, as in C/C++, on the type of the left operand. If the left operand is signed, the sign is preserved (for negative values, the most significant bit is set to 1). If the left operand is unsigned, the MSB is always set to 0.</p>
<p>If the operands of the operators &, \| or ^ are of different types, they are converted to the larger type before the operation is executed - the rules of C/C++ apply here as well, analogous to the \ref ArithmeticOps "arithmetic operators").</p>

@subsection AssignOps Assignment Operators
<p>The assignment operators are used to assign a value to a variable. As in C/C++, assignment is implemented with the = operator, which can be combined with the two-valued arithmetic or bit operators. The table below shows the options:</p>
| Operator | Meaning | Example |
| :------: | :-----: | :-----: |
| = | simple assignment | a = b |
| += | assignment with addition | a += b |
| -= | assignment with subtraction | a -= b |
| *= | assignment with multiplication | a *= b |
| /= | assignment with division | a /= b |
| \%= | assignment with remainder | a \%= b |
| \|= | assignment with bitwise OR | a \|= b |
| \&= | assignment with bitwise AND | a \&= b |
| <span>^=</span> | asignment with bitwise XOR | a ^= b |
| \<\<= | assignment with left shift | a \<\<= 2 |
| \>= | assignment with right shift | a \>\>= 2 |

@note <ul>
<li>The simple assignment operator can be used with all data types. Note that when assigning values of reference types, no copy of the value is assigned, but only a reference to it.<br>
When using static typing, an assignment is only possible if the value to be assigned has the same data type as the target of the assignment or can be implicitly converted to this type - see also \ref StaticTypedVars.</li>
<li>The compound assignment operators are combinations of the simple assignment operator and an \ref ArithmeticOps "arithmetic" or \ref BitOps "bit operator", where the assignment target serves as the left operand of the respective operation.<br>
For example, the expression <tt>a += b</tt> is identical to <tt>a = a + b</tt>.</li>
<li>The operands of compound assignment operators follow the same rules as the corresponding simple operators.</li>
</ul>

@subsection IncDecOps Increments and Decrement Operators
<p>The increment and decrement operators are unary operators. They increase (operator ++) or decrease (operator --) their operand by the value 1. The operand must be a variable initialized with an integral type or an object type.</p>
<p>Both operators can be used in prefix or postfix notation. A difference between these notations is when they are used within expressions. In prefix notation, the value of the subexpression is equal to the value of the operand after the increment/decrement, while in postfix notation, the value of the operand before the increment/decrement is returned.</p>
The following table illustrates the variants:
| Operator | Meaning | Example | Corresponding Expr. |
| :------: | :-----: | :-----: | :-----------------: |
| ++x | increment (prefix) | b = ++a | a = a+1, b = a |
| x++ | increment (postfix) | b = a++ | b = a, a = a+1 |
| \--x | decrement (prefix) | b = \--a * 7 | a = a-1, b = a * 7 |
| x\-- | decrement (postfix) | b = a\-- * 7 | b = a * 7, a = a-1 |

@note <ul>
<li>The increment and decrement operators produce shorter and faster bytecode than their "written out" equivalents (see Table above). They are therefore particularly useful for modifying counting variables in loops.</li>
<li>The byte code generated by the prefix notation is shorter and therefore faster than that of the postfix notation. Therefore, the prefix notation should be preferred if the special behavior of the postfix variant is not required.</li>
<li>In compound expressions, these operators should be used with caution, and only when the slightly higher efficiency is really necessary, as undesirable side effects may occur in addition to poorer readability. For example, in an expression<br>
<tt>c = a \|\| (\--b == 1)</tt><br>
the variable \c b is never decremented as long as \a a evaluates to \c true.</li>
<li>The operators can also be defined for object types (classes).</li>
<li>Due to the implementation, the operators cannot be applied directly to the return value of a function, even if it is an object that provides suitable operator functions. A true L-value is required for the operand.</li>
</ul>

@subsection MiscOps Miscellaneous operators

@subsubsection IndexOp Index Operator
<p>The index operator is expressed by square brackets <tt>[]</tt>. It is used for index-based access to single elements of a container (\c dictionary, \c vector, \c buffer, \c charbuffer) or a \c string.</p>
Usung example:
@code{.bpp}
// Operator [] Example 
main()
{
	var vec = T(1,2,3,4); // creates a vector
	vec[1] = 7;           // assigns 7 to the second element of vec
	print(vec[1],"\n");   // prints 7 to the console
}
@endcode
<p>For use with a dictionary, the operand in the parentheses must be of type \c string (key), in all other cases of an integral type (index).</p>
<p>The operator can also be defined for object types, where the type of the index operand depends on the implementation.</p>

@subsubsection DotOp Dot Operator (Property Operator)
<p>The dot is used in many programming languages to refer to elements of structured data types (structures, objects). In B++ it is a predefined operator for the type \c dictionary and its semantics are the same as the index operator. For objects, it is used to access non-static data elements. In addition, the dot operator can be redefined for objects or their classes, e.g. to define pseudo-properties.</p>
<p>The operator has the following general form</p>
<tt>    variable . identifier</tt>,
<p>where \c variable must be of either \c dictionary or \c object type.</p>
<p>For \c dictionary variables, \c identifier is the identifier (key) of an entry.</p>
For example:
@code{.bpp}
// operator . example
main()
{
	auto dict = { a: 1, b: 2 }; // defines a dictionary
	dict.c = dict.a + dict.b;   // adds new value c to dictionary
	print(dict.c);              // prints the value
}
@endcode 

@subsubsection Parentheses
<p>Parentheses are operators too. They are used in two contexts:</p>
<ul>
<li>as a delimiter for the argument list of functions when declaring and calling<br>
<tt>    myFunc(a, b, c)</tt></li>
<li>to control the order in which expressions are evaluated - \"We'll evaluate parentheses first!\"<br>
<tt>    x = (a + b) * c</tt></li>
</ul>
<p>Classes can define the operator as a member function. Instances of these classes can then be called like functions.</p>

@subsubsection CondOp Condition Operator
<p>The condition operator has the general form:</p>
<tt>    condexpr ? expr1 : expr2</tt> .
<p>The expression \c condexpr (a condition) is evaluated first. Its result is interpreted as a Boolean value. If the result is \c true, \c expr1 is evaluated, otherwise \c expr2 is evaluated. The result is the result of the whole expression.</p>
Example:
@code{.bpp}
// Get minimum
var min(var a, var b)
{
  return a < b ? a : b;
}
@endcode

@note The return type of the function in the example above is not necessarily known. For example, if \c a is of type \c int and \c b is of type \c float, the condition (<tt>a&lt;b</tt>) is temporarily converted to \c float. Depending on the result, the function's return value will be of type \c int or \c float.

@subsubsection CommaOp Comma Operator
<p>The comma operator allows you to concatenate multiple expressions into an expression list. In other words: This operator can be used to record multiple expressions where syntactically only one is expected. The result of the whole expression (i.e. of the list) is the result of the last partial expression.</p>
@note The comma operator should not be confused with the <i>delimiter comma</i> used in parameter- or variable lists.

@subsubsection NewDeleteOp New, Delete, ::, and -&gt; Operators
<p>These operators are important in connection with classes and objects or for explicit memory management (\c delete operator). They are explained in more detail in context of operator definitions, and are listed in the table below for completeness.</p>
| Operator | Meaning | Example |
| :------: | :-----: | :-----: |
| new | Creates an object instance of a class type. | <tt>a = new A()</tt> |
| delete | Deletes an object instance. | <tt>delete a</tt> |
| <span>::</span> | Definition of methods,<br>Call of class methods | <tt>A::A() `{ ... }`<br>`i = A::getMaxId()`</tt> | 
| -&gt; | Calls instance methods. | <tt>name = a-\>getName()</tt> |

<p>The :: operator is also used to explicitly reference global symbols within the implementation of functions and members of namespaces.</p>

@subsubsection UnaryRefOps Unary reference operators \& and *.
<p>These two operators are applicable to reference types and allow the conversion of a value into a weak reference (operator <tt>\&</tt>) or the conversion of a weak reference into a value (operator <tt>*</tt>).</p>
<p>A weak reference is a reference to a data object of a reference type that is explicitly excluded from reference counting and therefore from automatic memory management. Its main purpose is to prevent memory leaks caused by cyclic references in data structures. They can also be used to implement explicit memory management.</p>
@note <ul>
<li>Weak references cannot be assigned to statically typed variables.</li>
<li>The unary dereference operator <tt>*</tt> can also be explicitly defined for objects (or their classes). The corresponding operator function is called when the operator is used on a "real" object, i.e. not on a weak reference.</li>
</ul>

@subsection OpPrecedence Precedence of operators
<p>When multiple operators are used in an expression, there is a question about the order of evaluation. To determine such an order, a ranking (hierarchy) of operators is defined. B++ largely follows here the rules of C/C++.<br>
The following table shows the hierarchy of the operators in B++. Operators with higher priority are evaluated before those with lower priority. Operators of equal priority are evaluated from left to right according to notation.</p>
<table>
<tr><th>Priority</th><th>Category</th><th>Operators</th></tr>
<tr><td align="center">0</td><td align="center">comma</td><td align="center"><span>,</span></td></tr>
<tr><td align="center">1</td><td align="center">assignment</td><td align="center"><span>= += -= *= /= \%= \&= ~= ^= \<\<= \>\>=</span></td></tr>
<tr><td align="center">2</td><td align="center">decision</td><td align="center">?:</td></tr>
<tr><td align="center">3</td><td align="center">OR (logical)</td><td align="center">\|\|</td></tr>
<tr><td align="center">4</td><td align="center">AND (logical)</td><td align="center">\&\&</td></tr>
<tr><td align="center">5</td><td align="center">OR (bitwise)</td><td align="center">\|</td></tr>
<tr><td align="center">6</td><td align="center">XOR (bitwise)</td><td align="center"><span>^</span></td></tr>
<tr><td align="center">7</td><td align="center">AND (bitwise)</td><td align="center">\&</td></tr>
<tr><td align="center">8</td><td align="center">equality</td><td align="center">== !=</td></tr>
<tr><td align="center">9</td><td align="center">relation</td><td align="center">\< \<= \>= \></td></tr>
<tr><td align="center">10</td><td align="center">shift</td><td align="center">\<\< \>\></td></tr>
<tr><td align="center">11</td><td align="center">addition</td><td align="center">+ -</td></tr>
<tr><td align="center">12</td><td align="center">multiplication</td><td align="center">* / \%</td></tr>
<tr><td align="center">13</td><td align="center">prefix</td><td align="center">+ - ! ~ \& * ++ \-- new delete</td></tr>
<tr><td align="center">14</td><td align="center">postfix</td><td align="center">() [] . ++ \-- -\></td></tr>
<tr><td align="center">15</td><td align="center">range</td><td align="center">\::</td></tr>
</table>

@section KeywordsAndReserved Keywords and reserved identifiers
<p>Keywords are terminal symbols in the syntactic sense. This means that they are identified during lexical analysis and assigned to special internal symbols. Within a program, keywords have a fixed (central) meaning. Therefore, it is not possible to create custom identifiers that match the keywords.</p>
<p>Most of the keywords in B++ are borrowed from C or C++ and have an analogous meaning. The following table gives an overview.</p>

| Keyword | Category | Meaning |
| :-----: | :------: | :------ |
| \c null | Type constant | Identifier for data type \c null and its only value. |
| \c void | Type constant | Identification of functions without a return value<br>(instead of a return type) |
| \c do | Program control | Construction of loop statements |
| \c while | Program control | Construction of loop statements |
| \c for | Program control | Construction of loop statements |
| \c break | Program control | Cancels a loop or selection statement |
| \c continue | Program control | Jumps to the start of a loop statement |
| \c if | Program control | Construction of conditional statements |
| \c else | Program control | Construction of conditional statements |
| \c switch | Program control | Initial identifier of a selection instruction (case distinction) |
| \c case | Program control | Identification of a selection value in a selection statement |
| \c default | Program control | Identifier of the standard branch of a selection statement |
| \c return | Program control | (early) return from a function |
| \c yield | Program control | return from a coroutine |
| \c try | Exceptions | Initiation of a protected block |
| \c catch | Exceptions | Start of exception handling |
| \c throw | Exceptions | Throws an exception |
| \c var | Declaration | Declaration of a variable of dynamic (arbitrary) type |
| \c const | Declaration | Declaration of a constant, can be used as a modifier together with var or a data type, or modifier of a method declaration; can also be used as a modifier of the return value of a function. |
| \c mutable | Declaration | Declaration of a member variable that can also be changed for constant objects; can be used as a modifier with var or a data type. |
| \c auto | Declaration | Declaration of a statically typed variable with type determination by initialization |
| \c function | Declaration | Declaration of a function literal |
| \c class | Declaration | Start of a class declaration |
| \c namespace | Declaration | Start of the declaration of a namespace |
| \c static | Declaration | Declaration of a class member or a static local variable |
| \c public | Declaration |  Introducing a public section in a class declaration |
| \c protected | Declaration |  Introducing a protected section in a class declaration |
| \c private | Declaration |  Introducing a private section in a class declaration |
| \c new | Memory management | Creating an object instance |
| \c delete | Memory management | Destroying an object instance or value from a different reference type (weak reference) |
| \c operator | Declaration | Declaration of an operator function |
| \c litexp | Declaration | Marking a literal expression |
| \c compexp | Declaration | Marking a compiled literal expression |
| \c TRON | Debugging | Turn on trace mode |
| \c TROFF | Debugging | Turn off trace mode |
| \c TRSTEP | Debugging | Turn on single step mode |

<p>The \c TRON, \c TROFF, and \c TRSTEP keywords, which are written as separate statements in the source code, support elementary debugging at the level of the bytecode generated by the compiler.<br>
In trace mode, which is turned on with \c TRON and turned off with \c TROFF, the program flow is output in textual form at the bytecode level, e.g. to a console when using the command-line version of B++, or to a special output window of a GUI.<br>
\c TRSTEP also turns on trace mode, but also causes the program to stop after each bytecode instruction is executed. The single step operation is terminated when reaching a \c TROFF instruction or by a special keyboard input (ESC in the command line version).<br>
The trace output shows the program addresses, the executed bytecodes, the position of the stack pointer, and the types and values of the affected operands.</p>
<p>In addition, B++ recognizes the following <b>reserved identifiers</b> (sometimes called "magic names")</p>
<ul>
<li>\c this : Reference to the current object in member functions</li>
<li>\c self : Reference to the current function (method)</li>
<li>\c dtor : Alias identifier for the destructor of a class</li>
<li>\c defined : Pseudo-operator to test if a named literal is defined</li>
<li><tt> OP_CALL, OP_VREF, OP_VSET, OP_PREF, OP_PSET, OP_NEG, OP_PLUS, OP_INC, OP_PIC, OP_DEC, OP_PDEC, OP_ADD, OP_ADD_R, OP_SUB, OP_SUB_R, OP_MUL, OP_MUL_R, OP_DIV, OP_DIV_R, OP_REM, OP_REM_R, OP_BOR, OP_BOR_R, OP_BAND, OP_BAND_R, OP_XOR, OP_XOR_R, OP_SHL, OP_SHL_R, OP_SHR, OP_SHR_R, OP_NOT, OP_BNOT, OP_UNREF</tt><br>
Special function names for defining operators</li>
</ul>
<p>The reserved identifiers are not keywords in the sense described above. However, they implicitly have a special meaning in the program and should not be used as general identifiers. The same applies to the names of the predefined \ref Datatypes "data types" and the identifiers of the \ref PredefinedLiterals "predefined named literals" as well as the \ref PredefinedVars "predefined variables and constants".</p>

@section ProgramControl Program Control
<p>Any program that is intended to be more than just a series of instructions requires ways to control the flow of the program. A basic distinction is made between <i>branching based on conditions</i> and </i>repeating program sections</i>.</p>
<p>Many programming languages also allow unconditional branch statements. Such instructions are not provided in B++ and are therefore not discussed further.</p>

@subsection IfElse Conditions (if-else)
<p>The <b></i>if-else statement</i></b>, which has the same syntax and semantics as the C/C++ if-else construct, is used to control program execution depending on a condition:</p>
<pre><tt>   if (\e condition) \e statement1 [ else \e statement2 ] .</tt></pre>
<p>If the expression <tt>\e condition</tt> is \c true, <i>\c statement1</i> is executed, otherwise <i>\c statement2</i> is executed. The statements to be executed can be single statements or blocks of statements. In particular, the <i>if-else statement itself</i> can be used to formulate nested conditions or case distinctions.</p>
Example:
@code{.bpp}
main()
{
	FILE fp = fopen("testfile.txt","rt");
	if (fp) // same as fp != null
	{
		// do something
		fclose(fp);
	}
	else
		print("Could not open testfile.txt");
}
@endcode

@subsection SwitchCase Case distinctions (switch-case)
<p>B++ supports case distinction using the <b><i>switch-case statement</i></b>, which is based on the corresponding construct in C/C++ in syntax and semantics, and is exactly the same as in JavaScript.</p>
<p>Unlike C++, \c case can be followed by any expression, not just a constant. As long as a comparison with the values after \c case is defined, the expression after switch can be of any type (not only an integral type).</p>
<p>As in C/C++, there is a "fall through", i.e. if a case branch is not exited with \c break, the statements of the following branch are also executed.</p>
<p>The \c default branch is optional. If used, it must appear <i>after</i> the case branches.</p>
Example:
@code{.bpp}
switch (myVariable)
{
	case 1:
		// do something
		break;
	case 2:
		// do something else
	// fall through
	default:
		// do something else
}
@endcode

@subsection Repetitions Repetitions (Loops)
<p>B++ uses the \c while, <tt>do-while</tt>, and \c for statements to formulate repetitions of sections of code. The syntax and semantics of these statements are the same as the corresponding constructs in C/C++.</p>

@subsubsection WhileLoop The while statement
<p>The <b></i>while statement</i></b> has the general form</p>
<pre><tt>    while ( \e condition ) \e statement </tt></pre>

<p>The statement is executed (repeatedly) as long as the <tt>\e condition</tt> returns \c true.</p>
Example:
@code{.bpp}
// Prints contents of a file to console
void main()
{
	FILE fp = fopen("testfile.txt","rt")
	if (fp) // same as fp != null
	{
		while(!feof(fp))
		{
			string s = fgets(fp);
			print(s);
		}
		fclose(fp);
	}
	else
		print("Could not open testfile.txt");
}
@endcode

@subsubsection DoWhile The do-while statement
<p>The <b><i>do-while</i></b> statement has the general form</p>
<pre><tt>    do \e statement while (\e condition)</tt></pre>
<p>It is very similar to the \c while statement. Again, the <tt>\e statement</tt> is executed as long as the <tt>\e condition</tt> is \c true. The main difference is that the condition is only checked at the end, so the <tt>\e statement</tt> is always executed at least once.</p>
Example:
@code{.bpp}
// Prompt user for input until a blank line is entered 
void main()
{
	string s;
	do
	{
		print("Input line: ");
		s = gets();
		// do something
	}
	while (strlen(s) > 0);
}
@endcode

@subsubsection ForLoop The for statement
<p>The <b><i>for</i></b> statement is the most powerful form of iteration. As in C/C++ (and unlike languages such as BASIC or PASCAL), it is not necessarily used to process a fixed number of loops, but is a generalization or extension of the while statement. The for statement has the following general form</p>
<pre><tt>    for ( \e init ; \e condition ; \e reinit) \e statement </tt></pre>
<p>Before the processing of a \c for loop begins, the initialization expression <tt>\e init</tt> is executed once. The <tt>\e condition</tt> expression is evaluated before each iteration of the loop. If it returns \c true, the <tt>\e statement</tt> is executed, otherwise the loop is exited. The <tt>\e reinit</tt> expression is executed at the end of each loop iteration (i.e., after the <tt>\e statement</tt> was executed).</p>
Example:
@code{.bpp}
// Lists all arguments of command line to console 
void main()
{
	auto argvec = getargs(); // gets argument vector
	int n = vecsize(argvec); // gets number of elements
	for(int i=0; i<n; ++i)   // prints each element to the console
		print(argvec[i],"\n");
}
@endcode 
@note The expressions in the head of a \c for statement can also be empty (omitted). In this case, no action is taken for <tt>\e init</tt> or reinit. If <tt>\e condition</tt> is omitted, an infinite loop is created that can only be aborted explicitly with \c break  or an exception. The generated bytecode then contains no condition check, which means that an endless loop of the form <tt>for(;;) ...</tt> is processed faster than one constructed with <tt>while(true)....</tt>

@subsubsection NestedLoops Nested Loops
<p>Loops can be nested. A typical case for using nested loops is to fill a multi-dimensional array, as shown in the following example:</p>
@code{.bpp}
// creates and fills a 2-dim array 
void main()
{
	int rows = 8;
	int cols = 8;
	// creates a table 
	vector array = newvector(rows);
	for (int i=0; i<rows; ++i) 
		array[i] = newvector(cols);
	// initialize table 
	for (i=0; i<rows; ++i)
		for (int j=0; j<columns; ++j)
			array[i][j] = rows * i + j;
	// do something
	// ...
}
@endcode 
<p>There is no limit to the maximum nesting depth in B++.</p>

@subsubsection BreakContinue The break and continue Statements
<p>The \c break and \c continue statements can be used within loops for additional flow control. With \c break, you can terminate a loop early, i.e., regardless of the actual termination condition. With \c continue, the rest of the current statement block of a loop is skipped and - if the termination condition is not fulfilled - the next loop pass is executed.</p>
Example:
@code{.bpp}
// Writes all printable characters from testfile.txt to the console 
int main()
{
	FILE fp = fopen("testfile.txt","rt");
	if (!fp)
	{
		print("Error opening file\n");
		return 1;
	}
	while(true) // loop forever
	{
		if (feof(fp))
			break;      // abort loop when reaching end of file
		var c = get(fp);
		if ((c < ' ') && (c != '\n'))
			continue;   // ignore control characters except EOL
		putc(c,stdout); // write character to console
	}
	fclose(fp);
	return 0;
}
@endcode

@subsection ExceptionHandling Error Handling (try - catch - throw)
<p>The error handling concept is based on that of C++. Accordingly, a "protected block" is introduced with the keyword \c try, followed by an exception handling block introduced with \c catch.
<p>A <tt>try-catch</tt> block has the following general form</p>
<pre><tt>    try \e statementblock catch ( \e exceptionid ) \e statementblock </tt></pre>
<p>Using<br>
<tt>   throw exception</tt><br>
an exception can be thrown within an executable program section (a function).<br>
Within a \c catch block, \c throw can be used without specifying an exception to rethrow the already caught exception.<br>
B++ - like C++ - allows the use of any data type to throw exceptions.</p>
Example:
@code{.bpp}
try
{
	var myVar = anyFunc();
	if (myVar) < 0)
		throw "myVar must not be negative";
	// do something else
}
catch (e)
{
	print(e, "caught\n");
	throw; // rethrow exception
}
@endcode

@note <ul>
<li>The identifier used for the exception to be handled in the \c catch block is arbitrary and, unlike other local variables, it is visible only within this block (not throughout the enclosing function). It also overrides a local variable of the same name in case of a name conflict.</li>
<li>Since B++ does not have static typing of exceptions, the definition of several catch blocks in a row does not make sense and is therefore not allowed.</li>
</ul>

@section Functions 
As already mentioned \ref ProgStructure "above", functions are the central structuring elements of any B++ program.
<br>Basically, there are two types of functions: \e predefined and \e user-defined. \ref Bp2Functions "Predefined functions" are an integral part of the B++ runtime system. They are available in every program and can be called by the user, i.e. the programmer, but normally theycannot be changed.</p>
<p>The actual behavior of a program is determined by user-defined functions. The entry point \c main - see chapter \ref ProgStructure - is such a function itself.</p>

@subsection FunctionDefinition Function Definition
<p>A custom (user-defined)function has the general form</p>
<pre><tt>   [\e returntype\] \e funcname ( \e parameterlist [; \e localvarlist] ) \e body </tt></pre>
<p>where <tt>\e funcnam</tt>e is the function name, which must be a valid \ref Identifiers "identifier"). <tt>\e parameterlist</tt> is a comma-separated list of named function parameters, and <tt>\e localvarlist</tt> defines the names of other local variables valid within the function (also a comma-separated list). Finally, <tt>\e body</tt> is a statement block containing the body of the function. Both <tt>\e parameterlist</tt> and <tt>\e localvarlist</tt> are optional. If <tt>\e localvarlist</tt> is omitted, the semicolon used to separate the lists can also be omitted.</p>
<p>The names of the formal parameters listed in <tt>\e parameterlist</tt> can optionally be preceded by a data type and the \c const modifier (to define a constant parameter). When a parameter is defined as constant, the function can only have read access to its value.</p>
<p>A return type can optionally be specified before the function name, using one of the keywords \c var, \c null, \c void, or a specific type name. In this case, \c void prohibits the return of a value, while the specification of \c var, \c null, or a type name requires that a \c return statement with a return value is actually used.<br>
The keyword \c var or the specification of a type identifier is optionally allowed before the named parameters. If a type identifier is specified here, the corresponding argument is statically typed.</p>
<p>Local variables can be defined not only in the list in the function header, but also anywhere in the function body using the \c var keyword or by specifying a type identifier or the \c auto keyword (to define a statically typed variable). This also allows (or, in the case of \c auto, forces) immediate initialization of the variables when they are defined.<br>
Variables defined in the function body are also visible within the entire function, not just the statement block surrounding it.<br>
Variable definition must be done in the source code before using a local variable.</p>
<p>Named parameters are treated as local variables within the function body. Global identifiers are visible within a function unless they are covered by local identifiers of the same name. In the case of coverage, global variables can be referenced using the prefixed \c \:: operator.</p>
<p>Unlike most other scripting languages, B++ does not <i>allow implicit definition of global variables by simply assigning a value to an arbitrary identifier</i>. This definition avoids the risk of unintentionally creating global variables through typing errors. If it is actually intended to create a global variable within a function body, this must be done explicitly using the \ref DefvarInstruction "#defvar" processing instruction.</p>
<p>Unlike C/C++, B++ functions strictly speaking \e always return a function value. If a function is exited with \c return followed by an argument, the value of that argument is the function value. Otherwise, the value is undefined - it is the value currently at the top of the stack.<br>
When the return type of a function is explicitly specified, the type of the function value is checked after the function is called. If necessary and possible, an implicit conversion to the required return type is performed.</p>
Examples of function definitions:
@code{.bpp}
// parameterless function without return value 
void sayHello()
{
   print(Text from function body\n);
}

// named parameter, local variables and return value
var factorial(n; i, result)
{
   for(result=1, i=n; i>1; --i)
     result *= i;
   return result;
}

// same as above, but using static typed variables declared in body
int factorial(int n)
{
   int result = 1; 
   for(var i=n; i>1; --i)
     result *= i;
   return result;
}

/* no named parameters but local variable and return value */
var queryName(;name)
{
   name =;
   while (strlen(name) == 0)
   {
      print(Tell me your name: );
      name = fgets(stdin);
   }
   return name;
}
/* same as above but using static typed variable definition in body */
string queryName2()
{
   string name =;
   while (strlen(name) == 0)
   {
      print(Tell me your name: );
      name = fgets(stdin);
   }
   return name;
}
@endcode

@subsection FunctionCall Calling Functions
<p>A function is called by specifying the function name followed by a comma-separated list of parameters. Syntactically, a function call can stand alone as a statement or in place of a value within an expression.</p>
Examples:
@code{.bpp}
main()
{
	sayHello();              // single statement - return value is ignored
	var f = factorial(17);   // assigns return value to variable
	var g = sqrt(2.0) * 0.5; // uses function in expression
	print(queryName());      // uses function for parameter of another function
}
@endcode
@note <ul>
<li>When calling a function, you must specify <i>at least</i> as many parameters as specified in the function declaration, unless default values for parameters have been defined. If more parameters are specified, the first (i.e. leftmost) parameter values are assigned to the named parameters.</li>
<li>The number of parameters passed is checked at runtime. If fewer parameters are passed when calling a function than required by the declaration, this does not lead to a compiler error, but to a runtime error.</li>
</ul>

<p>Like C/C++, B++ supports recursive function calls.</p>
Example:
@code{.bpp}
var factorial(var n) // recursive version of the factorial function
{
	if (n > 1)
	return n * factorial(n-1);
	return 1;
}
@endcode

<p>The possible depth of recursion is limited only by the size of the stack.<br>
Since B++ uses a dynamic stack, this is of no practical importance, provided there is enough memory. For very large recursion depths, a limitation comes more from the size of the stack available to the execution environment, since the B++ VM itself processes function calls recursively (in MS-DOS environments the stack has a maximum size of 64 KB, in Win32 it is 1 MB by default).</p>

@subsection EmulateRefParams Emulation of reference parameters
<p>In B++, parameters are always passed to functions by value.</p>
<p>If the passed value itself is of a \ref ReferenceTypes "reference type", this does not matter - the referenced value can be modified by the function if necessary, provided the argument was not declared as \c const. Parameters of \ref ValueTypes "value types", on the other hand, cannot be modified to "outside", because a copy of the value is passed to the function.</p>
<p>If it is necessary or intended to modify a value type variable passed as a parameter within a function, it must be encapsulated in a reference type.</p>
<p>As of version 1.5, B++ provides ox classes for all predefined value types, as well as a box class for each value type in the \ref RefParams "boxtypes library".<br>
The general box class is called #B_var, the specialized ones have the name of the respective base type with the prefix \c B_. All these classes have a public property "val" that represents the encapsulated value, and the specialized forms also have a conversion operator to the encapsulated type.</p>
Example:
@code{.bpp}
#use "boxtypes.bpm"

void incInt(B_int v) {
	++ v.val;
}

void main() {
	vector v = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
	auto n = v.size();
	for (uint i=0;i<n;++i) {
		B_int vi(v[i]);
		incInt(vi);
		v[i] = vi.val;
	}
}
@endcode

<p>The example demonstrates the use of the #B_int type to emulate passing numbers as reference parameters.</p>
<p>The \c boxtypes library can be included in precompiled form using \ref UseInstruction "#use" (as in the example) or included in the compilation process as the source file <tt>boxtypes.bpp</tt> before the source file used.</p>

@subsection VarListsVariable Variable Parameter Lists and Default Parameters
<p>As mentioned \ref FunctionCall "above", it is possible to pass more parameters to a function than are specified in the declaration. Taking advantage of this feature, B++ allows the construction of functions with any number of parameters. To access the passed parameters, the predefined function #arg is used instead of the parameter names. The number of parameters can be get with #argcnt.<br>
Since version 1.2 of B++, the 'ellipse' (...) can optionally be used as the last element of the formal parameter list of a function to explicitly mark the parameter list as of variable size and achieve a notation analogous to C/C++.</p>
Usage example:
@code{.bpp}
var sum(...)
{
	var result = 0;
	var n = argcnt();
	for (var i=0; i<n; ++i)
	result += arg(i);
	return result;
}

void main()
{
	print(sum(0,1,2,3,4,5,6,7,8,9),"\n");
}
@endcode
<p>You can also specify default values for named parameters in a function declaration. Such values are used implicitly when the function is called with fewer than the declared number of parameters. Any literal value (including literal expressions) is allowed as a default value.</p>
See also an example:
@code{.bpp}
// creates a string serialization of a vector
string serializeVector(vector vec, string delimiter = ",")
{
	string result = "";
	int n = size(vec);
	for (int i=0; i<n; ++i)
	{
		if (i>0) result += delimiter;
		result += vec[i];
	}
	return result;
}

void main()
{
	// Print comma-separated list of command line arguments
	print(serializeVector(getargs()),"\n");
	// Print command line arguments, each argument on its own line
	print(serializeVector(getargs(),"\n"),"\n");
}
@endcode
<p>This prints the command line parameters specified during the call first as a comma-separated list (using the default value for the delimiter argument), and then line by line.</p>

@subsection StaticVersInFuncs Static Variables in Functions
<p>Within a function, the keyword \c static can be used to define static variables whose visibility is limited to the function body, but which - unlike 'normal' local variables - have a fixed address (and are not temporarily created on the stack when function is called).</p>
<p>Static (local) variables are defined in the form</p>
<pre><tt>    static [\e type] \e name [<i>= value</i>]; </tt></pre>
<p>The variable identifier (<tt>\e name</tt>) may be preceded by an explicit type specification (<tt>\e type</tt>). Optionally, the variable can be initialized with an initial value. Initialization occurs at compile time (not at runtime), so value must be a \ref Literals "literal".</p>
<p>Static variables retain their value between function calls, allowing state information to be used within a function. Typical applications for this are counting and generator functions - for a simple example see below.</p>
@code{.bpp}
// Simple ID generator function
uint createID()
{
	static uint _id = 0;
	return +++id;
}
@endcode

@subsection FunctionPointers Function Pointers
In Section \ref Datatypes was explained the data type \c function, which is associated with a value of type \c function. In fact, a function can be treated like a "normal" value within certain limits, i.e., it can be assigned to a variable, passed as a parameter to other functions, or used as the return value of a function itself. Since function type values store nothing but a reference to the executable code of the respective function, they are comparable to function pointers in C/C++ and can be used in an analogous way.</p>
Example for defining and using a Function Pointer:
@code{.bpp}
void myFunc()
{
	print("myFunc called\n");
}

main(;f)
{
	f = myFunc; // assign myFunc to variable f
	f(); // call function
}
@endcode 

@subsection FunctionOverloading Function Overloading
<p>B++ identifies a function only by its name and not (like C++) by its full signature. This means overloading, i.e. defining more than one function with the same name is not really possible. Redefining an existing function will not cause an error, but will completely replace the previously defined function of the same name.</p>
However, "pseudo-overloading" is possible in B++ using the variable parameter lists and function pointers described in the previous sections. Following example shows the principle:</p>
@code{.bpp}
var myFunc1 = null;

myFunc(i) { 
	print("myFunc()")
	print("myFunc(",i,") called\n");
}

myFunc2() {
	if (argcnt() != 2)
		myFunc1(arg(0));
	else 
		print("myFunc(", arg(0), ",", arg(1), ") called\n");
}

main() {
	myFunc1 = myFunc;
	myFunc = myFunc2;
	myFunc(1,2);
	myFunc(1);
}
@endcode

<p>The goal here is to define two functions that can both be called with the name myFunc, where one processes one parameter and the other processes two parameters.</p>
<p>First, the single-parameter variant is defined under the name \c myFunc. The two-parameter variant is initially given a different name (\c myFunc2) and is implemented so that it can process a variable number of parameters. If the number of parameters passed is not two, it calls a function \c myFunc1, otherwise it executes its own code.<br>
The main function then assigns the code from \c myFunc to the (global) variable \c myFunc1 and the code from \c myFunc2 to \c myFunc.</p>

@subsection AnonymousFunctions Anonymous Functions and Function Literals
<p>An anonymous function is a function without an associated name. An anonymous function is always defined using a <i>function literal</i> of the form</p>
<pre><tt>    function [ [\e classid] ] [\e returntype]( \e parameterlist ; \e localvarlist ) body</tt></pre>
<p>It differs from a "normal" function definition in that it is introduced by the keyword \c function.<br>
Behind \c function, you can optionally specify a reference to a class (<tt>\e classid</tt>) enclosed in square brackets, where <tt>\e classid</tt> stands for the identifier of a class. This allows you to define <i>anonymous methods</i>, i.e. functions that are associated with a class. The type of return value is then specified, again optionally, followed by the specification of the parameters and, if applicable, the local variables and the implementation block.</p>
<p>Anonymous functions do not differ in their behavior from regular functions, but they open up some additional possibilities:</p>
<ul>
<li>They can be assigned to local variables within a function (or to member variables of an object), making them visible only locally.</li>
<li>They can be used like literals, so they can be used anywhere a literal value can appear - especially as part of literal expressions and as the value of default parameters , or within the literal constructors of the vector and dictionary types.</li>
<li>They can be used in place of a value, e.g. defined inline within a function call or expression and executed immediately.</li>
</ul>
Example:
@code{.bpp}
// Defines replacement for WIN HIWORD/LOWORD macros using named literals
#literal HIWORD function(x) { return (x >> 16) & 0xFFFF;}
#literal LOWORD function(x) { return x & 0xFFFF;}

// use anonymous compare function for argument of qsort function
var myVec = [4,2,1,7,0,8,9];
qsort(myVec, function (a,b) { return a-b; });

// call anonymous function in an expression
var str = function() {
   var result = "";
   for (var c = getc(); c >= ' '; c = getc()) result += c;
   return result;
}();
print(str);
@endcode
@note <div>A (compiled) function literal that is called directly as an anonymous function in an expression or as an argument, as in the example above, has a temporary instance created on each call if the function defines at least one local static variable or represents a coroutine (i.e. contains <tt>yield</tt> statement), which takes a certain amount of time.<br>
For very frequent calls, e.g. in a loop, it makes sense to first assign the literal to a local variable and use it in the expression. The above sorting could also be written as follows
@code{.bpp}
// use anonymous compare function for argument of qsort function
var myVec = [4,2,1,7,0,8,9];
var cmpfunc = function (a,b) { return a-b; };
qsort(myVec,cmpfunc);
@endcode
In this case, however, there are no runtime differences because the comparison function used here does not define any static variables.</div>

<p><b>Recursive Calls to Anonymous Functions</b></p>
<p>Since an anonymous function has no name, the question arises how to implement recursive calls. For this, B++ uses the reserved identifier \c self, which can be used within a statement (or expression) to reference the enclosing function itself. It is used like a normal function name.</p>
<p>Example for using \c self for recursion in anonymous functions:</p>
@code{.bpp}
// recursively calculate the Fibonacci number
var fib = function int(int arg) { 
	return arg < 2 ? arg : self(arg-1)+self(arg-2);
};
print(fib(12)); // prints 144
@endcode

<p>Using \c self for recursive calls is not necessarily limited to anonymous functions, but is also possible in named functions and member functions (methods) of objects.</p>

@subsection Coroutines Coroutines
<p>Starting with version 1.6 of B++, a simple concept of asymmetric coroutines was introduced.</p>
<p>In B++, a coroutine is a special function that exits the
function body with <tt>yield <i>[retvalue]</i></tt> instead of <tt>return <i>[retvalue]</i></tt>.</p>
<p>A coroutine is defined and called like a "normal" function. When you exit it with <tt>yield</tt>, its current state (values of the current parameters, local variables, reference to the following instruction) are stored. The next time it is called, it goes directly to the stored instruction position, where the local variables and, if necessary, the argument values are restored.
The latter are only restored if they are used again, i.e. if no values were set at the time of the call - so the saved values become default values for optional arguments and replace the original default values if necessary.</p>
<p>Following example demonstrates the behavior of a coroutine:</p>
@code
int cofunc(int i=0) {
	int j = i;
	while (j>0) {
		print (__func__," ",i,"\n");
	yield j--;
	}
	return j;
}

int main() {
	for (int j=0;j=cofunc(j+10);)
		print(j,"\n");
	return 0;
}

/* prints following:
cofunc 10
10
cofunc 20
9
cofunc 19
8
cofunc 18
7
cofunc 17
6
cofunc 16
5
cofunc 15
4
cofunc 14
3
cofunc 13
2
cofunc 12
1
*/
@endcode
<p>A simple backward counter is implemented in this example.<br>
The coroutine <tt>cofunc</tt> receives a start value as a parameter, which is initially assigned to the local
(temporary) variable <tt><i>j</i></tt>.<br>
The <tt>while</tt>-loop outputs the function name and call parameters. Then
it returns value of <tt><i>j</i></tt> using <tt>yield</tt> keyword and decrements <tt><i>j</i></tt>. If j==0, <tt>resturn</tt> is used. instead of <tt>yield</tt> to exit.<br>
The <tt>main</tt> function calls <tt>cofunc</tt> ten times, each time with an incremented argument.<br>
As you can see from the output, the newly passed argument is used in the repeated calls, but the cached value of variable <tt><i>j</i></tt> is used internally.<br>
When called repeatedly, <tt>cofunc</tt> is continued behind the <tt>yield</tt> statement, here at the end of the
<tt>while</tt> loop.</p>
@note 
<ul>
<li>Like all functions, coroutines can be used as member functions of objects and/or defined as
and/or defined as a function literal.</li>
<li>Because a coroutine has only one place to cache its state (this memory behaves like a hidden static variable), coroutines cannot be called recursively and cannot call each other.<br>
You can work around this limitation by creating a new instance of the coroutine before each recursive call. This can be done either by using the <tt>clone</tt> function, or by defining the coroutine as a function literal and assigning that literal to a variable before calling it.</li>
<li>If a coroutine is defined with named parameters but no default values, the corresponding parameters must also be specified when it is called repeatedly. Otherwise a compiler error will occur. This is because calling a coroutine is no different to calling a normal function for the compiler, and a coroutine is not an independent data type in B++.</li>
<li>When a coroutine is exited with return (even implicitly at the end of the body), it temporarily loses its coroutine property, i.e. no call state is cached and calling it again behaves like calling a normal function.</li>
<li>Calling a coroutine generally takes significantly more time than calling a normal function, because the state must be saved and restored at each call.
Therefore, coroutines should only be used where they are really useful, i.e. if they simplify the code.</li>
</ul>
*/