fbdoc manual update 2019-08-25

doc/manual/cache/CatPgProgrammer.wakka

@@ -32,7 +32,7 @@
 		{{fbdoc item="keyword" value="ProPgFixLenArrays|Fixed-length Arrays"}}
 		{{fbdoc item="keyword" value="ProPgVarLenArrays|Variable-length Arrays"}}
 		{{fbdoc item="keyword" value="ProPgArrayIndex|Array Indexing"}}
-		Passing Arrays to Procedures
+		{{fbdoc item="keyword" value="ProPgPassingArrays|Passing Arrays to Procedures"}}
 
 	{{fbdoc item="subsect" value="Pointers"}}
 		{{fbdoc item="keyword" value="ProPgPointers|Overview"}}
@@ -42,9 +42,10 @@
 	{{fbdoc item="keyword" value="ProPgImplicitdeclarations|Implicit Declarations"}}
 	{{fbdoc item="keyword" value="ProPgInitialization|Initialization"}}
 	{{fbdoc item="keyword" value="ProPgStorageClasses|Storage Classes"}}
-	Variable Lifetime
 	{{fbdoc item="keyword" value="ProPgVariableScope|Variable Scope"}}
-	Namespaces
+	{{fbdoc item="keyword" value="ProPgVariableLifetime|Simple Variable Lifetime vs Scope"}}
+	{{fbdoc item="keyword" value="ProPgObjectLifetime|Dynamic Object and Data Lifetime"}}
+	{{fbdoc item="keyword" value="ProPgNamespaces|Namespaces"}}
 	{{fbdoc item="keyword" value="ProPgVarProcLinkage|Variable and Procedure Linkage"}}
 
 {{fbdoc item="section" value="User Defined Types"}}
@@ -56,8 +57,8 @@
 	{{fbdoc item="keyword" value="ProPgProperties|Properties"}}
 	{{fbdoc item="keyword" value="ProPgMemberAccessRights|Member Access Rights"}}
 	{{fbdoc item="keyword" value="ProPgOperatorOverloading|Operator Overloading"}}
-	Iterators
-	New and Delete
+	{{fbdoc item="keyword" value="ProPgTypeIterators|Iterators"}}
+	{{fbdoc item="keyword" value="ProPgNewDelete|New and Delete"}}
 	{{fbdoc item="keyword" value="ProPgTypeObjects|Types as Objects"}}
 <<>>{{fbdoc item="section" value="Statements and Expressions"}}
 	Assignments
@@ -71,7 +72,7 @@
 	{{fbdoc item="keyword" value="ProPgReturnValue|Returning a Value"}}
 	Procedure Scopes
 	{{fbdoc item="keyword" value="ProPgCallingConventions|Calling Conventions"}}
-	Recursion
+	{{fbdoc item="keyword" value="ProPgRecursion|Recursion"}}
 	Constructors and Destructors
 	{{fbdoc item="keyword" value="ProPgProcedurePointers|Pointers to Procedures"}}
 	{{fbdoc item="keyword" value="CatPgVarArg|Variable Arguments"}}

doc/manual/cache/DevArrays.wakka

@@ -0,0 +1,143 @@
+{{fbdoc item="title" value="Arrays"}}----
+An array in fbc is a collection of elements where each element has the same type and is accessed with an index in to the array.
+
+Example:
+%%(freebasic)
+	'' one dimensional array (1 index)
+	dim a(1 to 10) as integer
+	print a(1)  '' first element (integer)
+	print a(10) '' last element (integer)
+
+	'' two dimensional array (2 indexes)
+	dim b(1 to 2, 1 to 5) as integer
+	print b(1,1) '' first element (integer)
+	print b(2,5) '' last element (integer)
+%%
+
+{{fbdoc item="section" value="Array Dimensions and Bounds"}}
+
+The number of dimensions refers to the number of indexes that are required to be given to access an element of an array.  The number of dimensions may or may not be part of the declaration.  If the number of dimensions are known at compile time within the scope that the array is used, fbc can check and error if the wrong number of indexes are specified.
+
+The bounds of an array are the allowable minimum and maximum index values for each dimension.  Accessing an array element with an index or indexes that are outside the array bounds of a dimension is undefined behaviour.
+
+fbc can check and error if an index or indexes (access) are outside the bounds of the array when compiled with '-exx' or '-earray' compile options.  If the array bounds are compile-time constant, and the array access is compile-time constant, fbc can check if an array access is outside the bounds of the array at compile time.  Otherwise, the array bounds check must occur at run-time if either the bounds or the access is non-constant.
+
+{{fbdoc item="section" value="Fixed dimension versus unknown dimension"}}
+
+The number of dimensions may be fixed or unknown.  fbc will attempt to determine the number of dimensions an array is expected to have based on declarations for the array.  If fbc cannot determine the number of dimensions at compile time, the number of dimensions will become fixed on first redimension of the array at run time.
+
+Example: fixed 2 dimension, dynamic bounds
+%%(freebasic)
+dim a(any, any) as integer
+redim a(1 to 2, 1 to 5)
+%%
+
+Example: Dynamic dimension, dynamic bounds
+%%(freebasic)
+dim a() as integer
+
+'' then only one of on first time use ...
+redim a(1 to 10)
+redim a(1 to 2, 1 to 5)
+redim a(1 to 2, 1 to 5, 1 to 3)
+%%
+
+Once number of dimensions are known to fbc, within the scope of the array, fbc will error if any access to the error has wrong number of dimensions.  Or if still unknown at compile time, as in the case of an array passed as argument to a procedure and resized, the number of dimensions become fixed at run time.
+
+{{fbdoc item="section" value="Fixed bounds versus Dynamic bounds"}}
+
+Fixed length arrays have array bounds that are known at compile-time.  Dynamic (or variable length) arrays have array bounds that can be altered and resized at run-time, and may be considered unknown at compile time.
+
+Example: fixed (constant) bounds and constant access
+%%(freebasic)
+dim a(1 to 10) as integer
+print a(11) '' compile time array out-of-bounds
+%%
+
+Example: fixed bounds and non-constant access
+%%(freebasic)
+dim a(1 to 10) as integer
+dim i as integer
+print a(i) '' run time array out-of-bounds
+%%
+
+Example: dynamic bounds
+%%(freebasic)
+dim a(any) as integer '' 1 dimensional, empty
+redim a(1 to 10)      '' resized to 10 elements
+print a(11) '' run time array out-of-bounds
+print a(i)  '' run time array out-of-bounds
+%%
+
+{{fbdoc item="section" value="Static Array versus Dynamic Array"}}
+
+Arrays may have static or dynamic memory allocation.  The descriptor may be static or dynamic, and memory space for the data may be static or dynamic.  The terms static and dynamic may be overused and so may lose meaning when describing an array.  In this context static versus dynamic should not be confused with fixed-length or variable-length.  In this context we are referring to how and where the array descriptor and it's associated data are allocated in memory, and to some extent the life time of the variable.
+
+For an array descriptor to be valid, it must be initialized.  An uninitialized array descriptor will almost certainly lead to undefined behaviour at run time.
+
+The array descriptor itself may be allocated in .bss, .data, on stack or on heap, depending on the declaration of the array.  Though typically not in .bss section because an array descriptor usually must be initialized to some non-zero default values to be usable.
+
+The array's data may be located in .bss section, .data section, on stack or on heap, depending on the declaration of the array.  In fbc's current implementation, the array data for variable-length arrays is always allocated on the heap (i.e. malloc()).
+
+{{fbdoc item="section" value="Array Descriptor"}}
+
+At compile time, fbc allocates an array descriptor to store and track information about the array.
+
+From ##./inc/fbc-int/array.bi##):
+%%(freebasic)
+	const FB_MAXDIMENSIONS as integer = 8
+
+	type FBARRAYDIM
+		dim as uinteger elements     '' number of elements
+		dim as integer lbound        '' dimension lower bound
+		dim as integer ubound        '' dimension upper bound
+	end type
+
+	type FBARRAY
+		dim as any ptr index_ptr     '' @array(0, 0, 0, ... )
+		dim as any ptr base_ptr      '' start of memory at array lowest bounds
+		dim as uinteger size         '' byte size of allocated contents
+		dim as uinteger element_len  '' byte size of single element
+		dim as uinteger dimensions   '' number of dimensions
+		dim as FBARRAYDIM dimTb(0 to FB_MAXDIMENSIONS-1)
+	end type
+%%
+
+If the number of dimensions is unknown at compile time, then the full ##FB_MAXDIMENSIONS## is allocated in the ##dimTb()## field.  Otherwise, if the number dimensions is known at compile time, then only the number of dimensions needed are allocated.  Therefore the allocated ##FBARRAY## data may be smaller than the declared ##FBARRAY## structure.
+
+If an array is passed as argument to a procedure, an array descriptor is allocated.  However, if the array is static, fixed length, and never passed as an argument, then all information about the array is known at compile time, including memory locations, and the allocation of a descriptor is optimized out, since all expressions involving the array are compile time constant.
+
+The array descriptor may also be allocated at run time, as would be in the case of allocating a new UDT containing a variable-length array field member.
+
+{{fbdoc item="subsect" value="FBARRAY.index_ptr"}}
+Pointer to the array data ##@array(0, 0, ...)##.  This pointer may be outside of the actual array data as a kind of virtual pointer to use when calculating offsets using indexes in to the array.
+
+{{fbdoc item="subsect" value="FBARRAY.base_ptr"}}
+Pointer to the array's memory at the array's lowest bound.  For variable-length arrays allocated at run time, this points to the allocated memory region (i.e. malloc)
+
+{{fbdoc item="subsect" value="FBARRAY.size"}}
+Total size in bytes of the array data.  Size is equal to total number of elements in the array (all dimensions) multiplied by element length.  i.e. ##size = dimTb(0).elements * element_len + dimTb(1).elements * element_len + ...##
+
+{{fbdoc item="subsect" value="FBARRAY.element_len"}}
+Size in bytes of an individual element.  Must be set to non-zero value.
+
+{{fbdoc item="subsect" value="FBARRAY.dimensions"}}
+Number of valid dimensions in the dimTb() table.  A value of zero (0) indicates that dimTb() has ##FB_MAXDIMENSIONS## avaiable, but the array does not yet have number of dimensions defined.  On first REDIM, the number of dimensions will be set.
+
+{{fbdoc item="subsect" value="FBARRAY.dimTb()"}}
+dimTb() is an array of ##FBARRAYDIM## to indicate the bounds of each dimension.
+
+If the number of dimensions is unknown at compile time, then the full ##FB_MAXDIMENSIONS## is allocated in the ##dimTb()## field. Otherwise, if the number dimensions is known at compile time, then only the number of dimensions needed are allocated. Therefore the allocated ##FBARRAY## data may be smaller than the declared ##FBARRAY## structure.
+
+{{fbdoc item="subsect" value="FBARRAYDIM.elements"}}
+Number of elements in the dimension.  i.e. ##(ubound-lbound+1)##
+
+{{fbdoc item="subsect" value="FBARRAYDIM.lbound"}}
+Lower bound is the lowest valid index in this dimension.
+
+{{fbdoc item="subsect" value="FBARRAYDIM.ubound"}}
+Upper bound is the highest valid index in this dimension.
+
+
+{{fbdoc item="back" value="DevToc|FreeBASIC Developer Information"}}
+{{fbdoc item="back" value="DocToc|Table of Contents"}}

doc/manual/cache/DevBuildConfig.wakka

@@ -79,6 +79,12 @@ make install-rtlib install-gfxlib2 TARGET=i686-w64-mingw32
 	- ##ENABLE_STANDALONE=1##
 		Build a standalone FB setup instead of the normal Unix-style setup, see also: [[DevNormalVsStandalone|the standalone vs. normal comparison]]. This causes the makefile to use the standalone directory layout and to use ##-d ENABLE_STANDALONE## when building the compiler.
 
+	- ##ENABLE_STRIPALL=1##
+		Enable the ##[[CompilerOptstrip|-strip]]## compiler option by default.  If ##ENABLE_STRIPALL=1## is not given, this is the default for dos/win.
+
+	- ##ENABLE_STRIPALL=0##
+		Enable the ##[[CompilerOptnostrip|-nostrip]]## compiler option by default.  If ##ENABLE_STRIPALL=1## is not given, this is the default for linux (basically, everything other target besides dos.win).
+
 	- ##ENABLE_PREFIX=1##
 		This causes the makefile to use ##-d ENABLE_PREFIX=$(prefix)## when building the compiler.
 
@@ -99,6 +105,9 @@ make install-rtlib install-gfxlib2 TARGET=i686-w64-mingw32
 	- ##-d ENABLE_STANDALONE##
 		This makes the compiler behave as a standalone tool that cannot rely on the system to have certain programs or libraries. See [[DevNormalVsStandalone|the normal vs. standalone comparison]] for more information.
 
+	- ##-d ENABLE_STRIPALL##
+		Enable the ##[[CompilerOptstrip|-strip]]## by default, otherwise ##[[CompilerOptnostrip|-nostrip]]## is default.
+
 	- ##-d ENABLE_SUFFIX=foo##
 		This makes the compiler append the given suffix to the ##lib/freebasic/## directory name when searching for its own ##lib/freebasic/## directory. For example, ##-d ENABLE_SUFFIX=-0.24## causes it to look for ##lib/freebasic-0.24/## instead of ##lib/freebasic/##. Corresponding the ENABLE_SUFFIX=foo makefile option, this adjust the compiler to work in the new directory layout.
 

doc/manual/cache/DevToc.wakka

@@ -40,6 +40,7 @@ This area of the Wiki is for documenting everything about the compiler and the r
 		{{fbdoc item="keyword" value="DevFbcParserSymbols|Symbols"}}
 		{{fbdoc item="keyword" value="DevFbcTypes|Representation of data types"}}
 
+	{{fbdoc item="keyword" value="DevArrays|Arrays"}}
 	{{fbdoc item="keyword" value="DevSelectCase|SELECT CASE"}}
 	{{fbdoc item="keyword" value="ProPgProfiling|Profiling FB programs"}}
 	{{fbdoc item="keyword" value="DevStructLayout|Structure packing/field alignment"}}

doc/manual/cache/KeyPgDots.wakka

@@ -27,6 +27,8 @@ Used in place of procedure parameter to pass a variable number of arguments, or
 
 	Using an ellipsis behind the last parameter in a ##[[KeyPgPpdefine|#define]]## or ##[[KeyPgPpmacro|#macro]]## declaration allows creation of a variadic macro. This means it is possible to pass any number of arguments to the //variadic_parameter//, which can be used in the //body// as if it was a normal macro parameter. The //variadic_parameter// will expand to the full list of arguments passed to it, including commas, and can also be completely empty.
 
+	**Note:** To distinguish between the different arguments passed by //variadic_parameter//, you can first convert //variadic_parameter// to a string using the ##[[KeyPgOpPpStringize|Operator # (Preprocessor Stringize)]]##, then differentiate in this string (//#variadic_parameter//) each passed argument by locating the separators (usually a comma).
+
 	__Array Upper Bound__
 
 	Using an ellipsis in place of the upper bound in an array declaration causes the upper bound to be set according to the data that appears in the ##//expression_list//##.  When the ellipsis is used in this manner, an initializer must appear, and cannot be ##[[KeyPgAny|Any]]##.

doc/manual/cache/KeyPgExtendsZstring.wakka

@@ -89,7 +89,7 @@ End Destructor
 
 Operator Len (Byref v As vZstring) As Integer
   Return Len(Type<String>(v))        '' found nothing better than this ('vZstring.l' being private)
-End Operator
+End Operator                         ''     (or: 'Return Len(Str(v))')
 
 Dim As vZstring v = "FreeBASIC"
 Print "'" & v & "'", Len(v)
@@ -114,7 +114,7 @@ v[0] = Asc("-")
 Print "'" & v & "'", Len(v)
 
 'Print "'" & Right(v, 5) & "'"      '' 'Right' does not yet support types with 'Extends Zstring'
-Print "'" & Right(Str(v), 5) & "'"  '' workaround
+Print "'" & Right(Str(v), 5) & "'"  '' workaround (or: 'Right(Type<String>(v), 5)')
 
 Sleep
 %%

doc/manual/cache/KeyPgPperror.wakka

@@ -9,9 +9,11 @@ Preprocessor diagnostic directive
 		The display message
 
 {{fbdoc item="desc"}}
-	##**#error**## stops compiling and displays ##//error_text//## when compiler finds it. 
+	##**#error**## interrupts compiling to display ##//error_text//## when compiler finds it, and then parsing continues. 
 
 	This keyword must be surrounded by an ##[[KeyPgPpif|#if]] //<condition>//## ...##[[KeyPgPpendif|#endif]]##, so the compiler can reach ##**#error**## only if ##//<condition>//## is met.
+
+	In any case, the final status will be "Failed to compile".
 
 {{fbdoc item="ex"}}
 {{fbdoc item="filename" value="examples/manual/prepro/error.bas"}}%%(freebasic)

doc/manual/cache/PrintToc.wakka

@@ -102,7 +102,8 @@
 		[[KeyPgAccess|ACCESS]]
 		[[KeyPgAcos|ACOS]]
 		[[KeyPgAddGfx|ADD (Graphics PUT)]]
-		[[KeyPgAlias|ALIAS]]
+		[[KeyPgAlias|ALIAS (Name)]]
+		[[KeyPgAliasModifier|ALIAS (Modifier)]]
 		[[KeyPgAllocate|ALLOCATE]]
 		[[KeyPgAlphaGfx|ALPHA (Graphics PUT)]]
 		[[KeyPgOpAnd|AND]]
@@ -185,6 +186,11 @@
 		[[KeyPgCurdir|CURDIR]]
 		[[KeyPgCushort|CUSHORT]]
 		[[KeyPgCustomgfx|CUSTOM (Graphics PUT)]]
+		[[KeyPgCvaArg|CVA_ARG]]
+		[[KeyPgCvaCopy|CVA_COPY]]
+		[[KeyPgCvaEnd|CVA_END]]
+		[[KeyPgCvaList|CVA_LIST]]
+		[[KeyPgCvaStart|CVA_START]]
 		[[KeyPgCvd|CVD]]
 		[[KeyPgCvi|CVI]]
 		[[KeyPgCvl|CVL]]
@@ -255,6 +261,8 @@
 		[[KeyPgExp|EXP]]
 		[[KeyPgExport|EXPORT]]
 		[[KeyPgExtends|EXTENDS]]
+		[[KeyPgExtendsWstring|EXTENDS WSTRING]]
+		[[KeyPgExtendsZstring|EXTENDS ZSTRING]]
 		[[KeyPgExtern|EXTERN]]
 		[[KeyPgExternBlock|EXTERN...END EXTERN]]
 
@@ -773,6 +781,7 @@
 			[[ProPgFixLenArrays|Fixed-length Arrays]]
 			[[ProPgVarLenArrays|Variable-length Arrays]]
 			[[ProPgArrayIndex|Array Indexing]]
+			[[ProPgPassingArrays|Passing Arrays to Procedures]]
 
 		{{fbdoc item="subsect" value="Pointers"}}
 			[[ProPgPointers|Overview]]
@@ -783,6 +792,9 @@
 		[[ProPgInitialization|Initialization]]
 		[[ProPgStorageClasses|Storage Classes]]
 		[[ProPgVariableScope|Variable Scope]]
+		[[ProPgVariableLifetime|Simple Variable Lifetime vs Scope]]
+		[[ProPgObjectLifetime|Dynamic Object and Data Lifetime]]
+		[[ProPgNamespaces|Namespaces]]
 		[[ProPgVarProcLinkage|Variable and Procedure Linkage]]
 
 	{{fbdoc item="subsect" value="User Defined Types"}}
@@ -794,6 +806,8 @@
 		[[ProPgProperties|Properties]]
 		[[ProPgMemberAccessRights|Member Access Rights]]
 		[[ProPgOperatorOverloading|Operator Overloading]]
+		[[ProPgTypeIterators|Iterators]]
+		[[ProPgNewDelete|New and Delete]]
 		[[ProPgTypeObjects|Types as Objects]]
 
 	{{fbdoc item="subsect" value="Statements and Expressions"}}
@@ -805,6 +819,7 @@
 		[[ProPgPassingArguments|Passing Arguments to Procedures]]
 		[[ProPgReturnValue|Returning a Value]]
 		[[ProPgCallingConventions|Calling Conventions]]
+		[[ProPgRecursion|Recursion]]
 		[[ProPgProcedurePointers|Pointers to Procedures]]
 		[[CatPgVarArg|Variable Arguments]]
 
@@ -961,6 +976,12 @@
 		[[CompilerOptdll|-dll]]
 		[[CompilerOptdylib|-dylib]]
 		[[CompilerOpte|-e]]
+		[[CompilerOptearray|-earray]]
+		[[CompilerOpteassert|-eassert]]
+		[[CompilerOptedebug|-edebug]]
+		[[CompilerOptedebuginfo|-edebuginfo]]
+		[[CompilerOptelocation|-elocation]]
+		[[CompilerOptenullptr|-enullptr]]
 		[[CompilerOptex|-ex]]
 		[[CompilerOptexx|-exx]]
 		[[CompilerOptexport|-export]]
@@ -981,6 +1002,7 @@
 		[[CompilerOptnodeflibs|-nodeflibs]]
 		[[CompilerOptnoerrline|-noerrline]]
 		[[CompilerOptnoobjinfo|-noobjinfo]]
+		[[CompilerOptnostrip|-nostrip]]
 		[[CompilerOpto|-o < name >]]
 		[[CompilerOptoptimization|-O < level >]]
 		[[CompilerOptp|-p < name >]]
@@ -996,6 +1018,7 @@
 		[[CompilerOpts|-s < name >]]
 		[[CompilerOptshowincludes|-showincludes]]
 		[[CompilerOptstatic|-static]]
+		[[CompilerOptstrip|-strip]]
 		[[CompilerOptt|-t < value >]]
 		[[CompilerOpttarget|-target < platform >]]
 		[[CompilerOptv|-v]]

doc/manual/cache/ProPgArrays.wakka

@@ -67,6 +67,8 @@ Dim as integer multidim(1 to 2,1 to 5) = {{0,0,0,0,0},{0,0,0,0,0}}
 {{fbdoc item="see"}}
 	- [[ProPgFixLenArrays|Fixed-length Arrays]]
 	- [[ProPgVarLenArrays|Variable-length Arrays]]
+	- [[ProPgArrayIndex|Array Indexing]]
+	- [[ProPgPassingArrays|Passing Arrays to Procedures]]
 	- [[ProPgVariableScope|Variable Scope]]
 
 {{fbdoc item="back" value="CatPgProgrammer|Programmer's Guide"}}