{
"HarbourReference": {
"Entry": [
{
"TEMPLATE": "Document",
"NAME": "Welcome to Harbour",
"ONELINER": "A starter's guide",
"CATEGORY": "Document",
"SUBCATEGORY": "Intro",
"DESCRIPTION": "Clipper is a trademark of Computer Associates and will often be referred to as CA-Cl*pper within Harbour documents. Regardless of this variant, Clipper is recognized as Computer Associates' trademark.\nHarbour is a free software compiler for the xBase superset language often referred to as Clipper (the language that is implemented by the compiler Clipper). The goal of Harbour is to produce a cross platform CA-Cl*pper compatible compiler.\nThe Harbour website is at . If you have any problem with this copy of Harbour please visit our web site and ensure that you are using the latest release.\nIf you are reading this file as part of a source distribution of Harbour you probably want to start by reading doc/dirstruc.txt because this is your map to the Harbour source directories.\nHarbour is a superset of Clipper and is backwards compatible with nearly 100% of all Clipper 5.2x or 5.3 code. Most Clipper S'87 code will also compile and run fine, but may require some modifications to run well.",
"PLATFORMS": "Available on all platforms",
"TAGS": "Document, Intro"
},
{
"TEMPLATE": "Document",
"NAME": "Compiler Options",
"CATEGORY": "Document",
"SUBCATEGORY": "Compiler",
"DESCRIPTION": "Invoking the Harbour compiler: ==============================\n```\nharbour [options]\n```\n or\n```\nharbour [options] \n```\n or\n```\nharbour [options] [options]\n```\nThe command-line options have to be separated by at least one space. The option can start with either `-` character or `/` character.\nThe Harbour command-line options: =================================\n`-a` automatic memvar declaration\nThis causes all variables declared by PARAMETER, PRIVATE or PUBLIC statements to be automatically declared as MEMVAR variables.\n================= `-b` debug info\nThe compiler generates all information required for debugging\n================= `-build` display detailed version info\n================= `-credits` display credits\n================= `-d[=]` `#define `\n================= `-es[]` set exit severity\n`-es` or `-es0` - all warnings are ignored and exit code returned by\nthe compiler is equal to 0 if there are no errors in compiled source file.\n`-es1` - any warnings generate a non-zero exit code, but\noutput is still created.\n`-es2` - all warnings are treated as errors and no output\nfile is created. The exit code is set to a non-zero value.\n================= `-fn[:[l|u]|-]` set file name casing (`l`=lower `u`=upper)\n================= `-fd[:[l|u]|-]` set directory casing (`l`=lower `u`=upper)\n================= `-fp[:]` set path separator\n================= `-fs[-]` turn file name space trimming on or off (default)\n================= `-g` output type generated is \n`-gc[]` output type: C source `.c` (default)\n: `0`=compact (default) `1`=normal `2`=verbose\n`3`=generate real C code\n`-gh` output type: Harbour Portable Object `.hrb`\n`-gd[.]` generate dependencies list into `.d` file\n`-ge[]` error output : `0`=Clipper (default)\n`1`=IDE friendly\n================= `-i` #include file search path\n================= `-i[-|+]` disable/enable support for INCLUDE envvar\n================= `-j[]` generate i18n gettext file `.pot`\n================= `-k` compilation mode (type `-k?` for more data)\n`-kc` clear all flags (strict Clipper mode)\n`-kh` Harbour mode (default)\n`-ko` allow operator optimizations\n`-ki` enable support for HB_INLINE (default)\n`-kr` runtime settings enabled\n`-ks` allow indexed assignment on all types\n`-kx` extended Xbase++ mode (default)\n`-ku` strings in user encoding\n`-kd` accept macros with declared symbols\n`-km` turn off macro-text substitution\n`-kj` turn off jump optimization in pcode\n`-k?` this info\n================= `-l` suppress line number information\nThe compiler does not generate the source code line numbers in the output file. The ProcLine() function will return 0 for modules compiled using this option.\n================= `-m` compile module only\n================= `-n[]` no implicit starting procedure\n: `0`=no implicit starting procedure\n`1`=no starting procedure at all `2`=add starting procedure if necessary\nThe compiler does not create a procedure with the same name as the compiled file. This means that any declarations placed before the first PROCEDURE or FUNCTION statement have file- wide scope and can be accessed/used in all functions/procedures defined in the compiled source file. All executable statements placed at the beginning of the file and before the first PROCEDURE/FUNCTION statement are ignored.\n================= `-o` object file drive and/or path\n================= `-p` generate pre-processed output `.ppo` file\nThe compiler only creates the file that contains the result of pre-processing the source file.\n================= `-p+` generate pre-processor trace `.ppt` file\n================= `-q` quiet\nThe compiler does not print any messages during compiling (except the copyright info).\n`-q0` quiet and don't display program header\n`-q2` disable all output messages\n`-ql` suppress line number information\n================= `-r[]` request linker to search (or none)\nCurrently not supported in Harbour.\n================= `-r=` sets maximum number of preprocessor iterations\nThis set the maximum number of preprocessor iterations during processing the source code. If this switch is not used then the preprocessor stops after 1024 iterations. This value is used to stop processing of infinite loops, for example: `#command ( => (,7`\n================= `-s[m]` syntax check only [minimal for dependencies list]\nThe compiler checks the syntax only. No output file is generated.\n================= `-t` path for temp file creation\nCurrently not used in Harbour (the Harbour compiler does not create any temporary files).\n================= `-u[]` use command def set in (or none)\n================= `-u+` add command def set from \n================= `-undef:` `#undef `\n================= `-v` variables are assumed `M->`\nAll undeclared or unaliased variables are assumed MEMVAR variables (private or public variables). If this switch is not used then the scope of such variables is checked at runtime.\n================= `-w[]` set warning level number (0..3, default 1)\n`-w0` - no warnings\n`-w` or `-w1` - CA-Cl*pper compatible warnings\n`-w2` - some useful warnings missed in CA-Cl*pper\n`-w3` - warnings generated for Harbour language extensions\nand also enables strong type checking but only warns against declared types, or types which may be calculated at compile time\n================= `-x[]` set symbol init function name prefix (for `.c` only)\nSets the prefix added to the generated symbol init function name (in C output currently). This function is generated automatically for every PRG module compiled. This additional prefix can be used to suppress problems with duplicated symbols during linking an application with some third party libraries.\n================= `-z` suppress shortcutting (`.AND.` & `.OR.`)\nCompilation in batch mode. ==========================\n`@file` compile list of modules in \nNot supported yet.\nKnown incompatibilities between Harbour and CA-Cl*pper compilers =============================================================\nNote:\nIf you want a 100% compatible runtime libraries then you have to define HB_CLP_STRICT, using `HB_USER_CFLAGS=-DHB_CLP_STRICT`, then rebuild.\nPassing an undeclared variable by the reference ===============================================\nThe CA-Cl*pper compiler uses the special opcode PUSHP to pass a reference to an undeclared variable (`@` operator). The type of passed variable is checked at runtime (field or memvar). However, field variables cannot be passed by reference. This means that CA-Cl*pper checks the memvar variable only and doesn't look for a field. This is the reason why the Harbour compiler uses the usual PUSHMEMVARREF opcode in such cases. Notice that the runtime behavior is the same in CA-Cl*pper and in Harbour - only the generated opcodes are different.\nHandling of object messages ===========================\nThe HB_CLP_STRICT setting determines the way chained send messages are handled.\nFor example, the following code:\n`a:b( COUNT() ):c += 1`\nwill be handled as:\n`a:b( COUNT() ):c := a:b( COUNT() ):c + 1`\nin strict CA-Cl*pper compatibility mode and\n`temp := a:b( COUNT() ), temp:c += 1`\nin non-strict mode.\nIn practice, CA-Cl*pper will call the COUNT() function two times: the first time before addition and the second one after addition. In Harbour, COUNT() will be called only once, before addition.\nThe Harbour (non-strict) method is:\n1) faster\n2) it guarantees that the same instance variable of the same object will be changed\n(See also: include/hbexpra.c, include/hbexprb.c)\nInitialization of static variables ==================================\nThere is a difference in the initialization of static variables that are initialized with a codeblock that refers to a local variable. For example:\n\nLOCAL MyLocalVar\nSTATIC s_MyStaticVar := {|| MyLocalVar }\n\nMyLocalVar := 0\n? Eval( s_MyStaticVar )\n\nThe above code compiles fine in CA-Cl*pper, but it generates a runtime error `Error/BASE 1132 Bound error: array access Called form (b)STATICS$(0)`\nIn Harbour this code generates a compile time error: `Error E0009 Illegal variable (b) initializer: 'MyLocalVar'`\nBoth CA-Cl*pper and Harbour are handling all local variables used in a codeblock in a special way: they are detached from the local stack of function/procedure where they are declared. This allows access to these variables after the exit from a function/procedure. However, all static variables are initialized in a separate procedure (`STATICS$` in CA-Cl*pper and `(_INITSTATICS)` in Harbour) before the main procedure and before all INIT procedures. The local variables don't exist on the eval stack when static variables are initialized, so they cannot be detached.",
"PLATFORMS": "Available on all platforms",
"TAGS": "Document, Compiler"
},
{
"TEMPLATE": "Document",
"NAME": "Macro compiler",
"CATEGORY": "Document",
"SUBCATEGORY": "Compiler",
"DESCRIPTION": "Invoking the macro compiler:\n```\n&variable\n```\n or\n```\n&( expression )\n```\n or\n```\n&variable.text\n```",
"PLATFORMS": "Available on all platforms",
"TAGS": "Document, Compiler"
},
{
"TEMPLATE": "Document",
"NAME": "Harbour Extensions",
"CATEGORY": "Document",
"DESCRIPTION": "Language extensions: --------------------\n* Class generation and management.\nCA-Cl*pper only allowed creation of objects from a few standard classes.\nIn Harbour, you can create your own classes--complete with Methods, Instance Variables, Class Variables and Inheritance. Entire applications can be designed and coded in Object Oriented style.\n* `@()`\nReturns the pointer (address) to a function.\nThe returned value is not useful to application-level programming, but is used at a low level to implement object oriented coding. (Internally, a class method is a static function and there is no symbol for it, so it is accessed via its address).\n* Class HBGetList()\nObject oriented support for GetLists management.\n* ProcName() support for class Method names.\nClass Methods can be retrieved from the call stack.\n* Memory() has new return values.\nSee hbmemory.ch\n* Transform() --> new function in format string\n@0 Make a zero padded string out of the number.\n* SToD() --> dDate\nNew function that converts a `yyyymmdd` string to a Date value.\n* Optional Compile Time *strong type* declaration (and compile time\n*type mismatch* warnings)\nExample: LOCAL/STATIC Var `AS` ...\n* The Harbour debugger provides new interesting classes:\n- Class HBDbWindow() could be the foundation for a generic multi-platform\n- Class HBDbInput()\n- Class HBDbMenu() implement both pull-down and popup menus.\nRTL enhanced functionality: ---------------------------\n- `hb_vfDirSpace( , )`\nThe second parameter is a Harbour (optional) parameter and indicates the type of disk info being requested. See doc/en/diskspac.txt for info.",
"PLATFORMS": "Available on all platforms",
"TAGS": "Document"
},
{
"TEMPLATE": "Document",
"NAME": "The Garbage Collector",
"ONELINER": "Readme for Harbour Garbage Collect Feature",
"CATEGORY": "Document",
"DESCRIPTION": "The garbage collector uses the following logic: - first collect all memory allocations that can cause garbage; - next scan all variables if these memory blocks are still referenced.\nNotice that only arrays, objects and codeblocks are collected because these are the only datatypes that can cause self-references `a[ 1 ] := a` or circular references `a[ 1 ] := b; b[ 1 ] := c; c[ 1 ] := a` that cannot be properly deallocated by simple reference counting.\nSince all variables in Harbour are stored inside some available tables (the eval stack, memvars table and array of static variables) then checking if the reference is still alive is quite easy and doesn't require any special treatment during memory allocation. Additionally the garbage collector is scanning some internal data used by Harbour objects implementation that also stores some values that can contain memory references. These data are used to initialize class instance variables and are stored in class shared variables.\nIn special cases when the value of a Harbour variable is stored internally in some static area (at C or assembler level), the garbage collector will be not able to scan such values since it doesn't know their location. This could cause some memory blocks to be released prematurely. To prevent the premature deallocation of such memory blocks the static data have to store a pointer to the value created with hb_itemNew() function. Example:\n```c\nstatic HB_ITEM s_item; /* this item can be released by the GC */\n\nstatic PHB_ITEM pItem; /* this item will be maintained correctly */\npItem = hb_itemNew( hb_param( 1, IT_BLOCK ) );\n```\nHowever, scanning of all variables can be a time consuming operation. It requires that all allocated arrays have to be traversed through all their elements to find more arrays. Also all codeblocks are scanned for detached local variables they are referencing. For this reason, looking for unreferenced memory blocks is performed during the idle states.\nThe idle state is a state when there is no real application code executed. For example, the user code is stopped for 0.1 of a second during `Inkey( 0.1 )` - Harbour is checking the keyboard only during this time. It leaves however quite enough time for many other background tasks. One such background task can be looking for unreferenced memory blocks.\nAllocating memory -----------------\nThe garbage collector collects memory blocks allocated with hb_gcAlloc() function calls. Memory allocated by hb_gcAlloc() should be released with hb_gcFree() function.\nThe garbage collecting ----------------------\nDuring scanning of unreferenced memory the GC is using a mark & sweep algorithm. This is done in three steps:\n1) mark all memory blocks allocated by the GC with unused flag;\n2) sweep (scan) all known places and clear unused flag for memory blocks that are referenced there;\n3) finalize collecting by deallocation of all memory blocks that are still marked as unused and that are not locked.\nTo speed things up, the mark step is simplified by swapping the meaning of the unused flag. After deallocation of unused blocks all still alive memory blocks are marked with the same 'used' flag so we can reverse the meaning of this flag to 'unused' state in the next collecting. All new or unlocked memory blocks are automatically marked as 'unused' using the current flag, which assures that all memory blocks are marked with the same flag before the sweep step will start. See hb_gcCollectAll() and hb_gcItemRef()\nCalling the garbage collector from Harbour code -----------------------------------------------\nThe garbage collector can be called directly from the Harbour code. This is useful in situations where there is no idle states available or the application is working in the loop with no user interaction and there is many memory allocations. See hb_gcAll() for explanation of how to call this function from your Harbour code.",
"PLATFORMS": "Available on all platforms",
"TAGS": "Document",
"SEEALSO": "hb_gcAlloc(), hb_gcFree(), hb_gcCollectAll(), hb_gcItemRef(), hb_gcAll(), hb_idleState()"
},
{
"TEMPLATE": "Document",
"NAME": "The idle states",
"ONELINER": "Readme file for Idle States",
"CATEGORY": "Document",
"DESCRIPTION": "The idle state is the state of the Harbour virtual machine when it waits for the user input from the keyboard or the mouse. The idle state is entered during Inkey() calls currently. All applications that don't use Inkey() function call can signal the idle states with the call of hb_idleState() function (or hb_idleState() on C level).\nDuring idle states the virtual machine calls the garbage collector and it can call user defined actions (background tasks). It also releases the CPU time slices for some poor platforms that are not smart enough to detect it automatically.\nFor defining the background tasks see the hb_idleAdd() and hb_idleDel() functions.\nFor direct call for background actions see hb_idleState() function.\nFor signaling the idle state from C code see the hb_idleState() API function.",
"PLATFORMS": "Available on all platforms",
"TAGS": "Document",
"SEEALSO": "hb_idleAdd(), hb_idleDel()"
},
{
"TEMPLATE": "Function",
"NAME": "Do()",
"ONELINER": "Calls a procedure or a function",
"CATEGORY": "API",
"SUBCATEGORY": "Application",
"SYNTAX": "Do( [, ] ) --> xRetVal",
"ARGUMENTS": " = Either a string with a function/procedure name to be called or a codeblock to evaluate.\n = arguments passed to a called function/procedure or to a codeblock.",
"RETURNS": " A value that was returned from called function.",
"DESCRIPTION": "This function can be called either by the Harbour compiler or by user. The compiler always passes the item of HB_IT_SYMBOL type that stores the name of procedure specified in `DO WITH ...` statement.\nIf called procedure/function doesn't exist then a runtime error is generated.\nThis function can be used as replacement of macro operator. It is also used internally to implement `DO WITH ` In this case is of type HB_SYMB.",
"EXAMPLES": {
"_preformatted": "yes",
"__text": "LOCAL cFunction := \"MyFunc\"\n\n? Do( cFunction, 1 ) // Old style\nDO &cFunction WITH 2 // Old style with macro\n\n? Do( {| n | MyFunc( n ) }, 3 )\n? Do( @MyFunc(), 4 )\n\nFUNCTION MyFunc( n ) /* must be a public function for old style calls */\n ? n\n RETURN n + 1"
},
"COMPLIANCE": "CA-Cl*pper v5.x compatible",
"PLATFORMS": "Available on all platforms",
"FILES": "Library is core",
"TAGS": "API, Application"
},
{
"TEMPLATE": "Function",
"NAME": "hb_PValue()",
"ONELINER": "Retrieves the value of an argument.",
"CATEGORY": "API",
"SUBCATEGORY": "Application",
"SYNTAX": "hb_PValue( ) --> xExp",
"ARGUMENTS": "A number that indicates the argument to check.",
"RETURNS": " Returns the value stored by an argument.",
"DESCRIPTION": "This function is useful to check the value stored in an argument.",
"EXAMPLES": {
"_preformatted": "yes",
"__text": "Test( 123, \"abc\" )\nSTATIC PROCEDURE Test( nValue, cString )\n IF PCount() == 2\n ? hb_PValue( 1 ), nValue\n ? hb_PValue( 2 ), cString\n ENDIF\n RETURN"
},
"STATUS": "Ready",
"COMPLIANCE": "Harbour specific",
"PLATFORMS": "Available on all platforms",
"FILES": "Library is core",
"TAGS": "API, Application",
"SEEALSO": "PCount()"
},
{
"TEMPLATE": "Function",
"NAME": "PCount()",
"ONELINER": "Retrieves the number of arguments passed to a function.",
"CATEGORY": "API",
"SUBCATEGORY": "Application",
"SYNTAX": "PCount() --> nArgs",
"ARGUMENTS": "None",
"RETURNS": " A number that indicates the number of arguments passed to a function or procedure.",
"DESCRIPTION": "This function is useful to check if a function or procedure has received the required number of arguments.",
"EXAMPLES": {
"_preformatted": "yes",
"__text": "Test()\nTest( \"abc\" )\nSTATIC PROCEDURE Test( xExp )\n IF PCount() == 0\n ? \"This function needs a parameter\"\n ELSE\n ? xExp\n ENDIF\n RETURN"
},
"STATUS": "Ready",
"COMPLIANCE": "CA-Cl*pper v5.x compatible",
"PLATFORMS": "Available on all platforms",
"FILES": "Library is core",
"TAGS": "API, Application",
"SEEALSO": "hb_PValue()"
},
{
"TEMPLATE": "Function",
"NAME": "ProcFile()",
"ONELINER": "This function always returns an empty string.",
"CATEGORY": "API",
"SUBCATEGORY": "Application",
"SYNTAX": "ProcFile( ) --> cEmptyString",
"ARGUMENTS": " is any valid type.",
"RETURNS": " Return an empty string",
"DESCRIPTION": "This function is added to the RTL for full compatibility. It always returns an empty string.",
"EXAMPLES": {
"_preformatted": "yes",
"__text": "? ProcFile()\n? ProcFile( NIL )\n? ProcFile( 2 )"
},
"STATUS": "Ready",
"COMPLIANCE": "CA-Cl*pper v5.x compatible",
"PLATFORMS": "Available on all platforms",
"FILES": "Library is core",
"TAGS": "API, Application",
"SEEALSO": "ProcName(), ProcLine()"
},
{
"TEMPLATE": "Function",
"NAME": "ProcLine()",
"ONELINER": "Gets the line number of the current function on the stack.",
"CATEGORY": "API",
"SUBCATEGORY": "Application",
"SYNTAX": "ProcLine( ) --> nLine",
"ARGUMENTS": " is the function level required.",
"RETURNS": " The line number of the function that it is being executed.",
"DESCRIPTION": "This function looks at the top of the stack and gets the current line number of the executed function if no arguments are passed. Otherwise it returns the line number of the function or procedure at .",
"EXAMPLES": {
"_preformatted": "yes",
"__text": "? ProcLine( 0 )\n? ProcName( 2 )"
},
"STATUS": "Ready",
"COMPLIANCE": "CA-Cl*pper v5.x compatible",
"PLATFORMS": "Available on all platforms",
"FILES": "Library is core",
"TAGS": "API, Application",
"SEEALSO": "ProcName(), ProcFile()"
},
{
"TEMPLATE": "Function",
"NAME": "ProcName()",
"ONELINER": "Gets the name of the current function on the stack",
"CATEGORY": "API",
"SUBCATEGORY": "Application",
"SYNTAX": "ProcName( ) --> cProcName",
"ARGUMENTS": " is the function level required.",
"RETURNS": " The name of the function that it is being executed.",
"DESCRIPTION": "This function looks at the top of the stack and gets the current executed function if no arguments are passed. Otherwise it returns the name of the function or procedure at .",
"EXAMPLES": {
"_preformatted": "yes",
"__text": "// This test will show the functions and procedures in stack.\n// before executing it.\nLOCAL n := 1\nDO WHILE ! Empty( ProcName( n ) )\n ? ProcName( n++ )\nENDDO"
},
"STATUS": "Ready",
"COMPLIANCE": "CA-Cl*pper v5.x compatible",
"PLATFORMS": "Available on all platforms",
"FILES": "Library is core",
"TAGS": "API, Application",
"SEEALSO": "ProcLine(), ProcFile()"
},
{
"TEMPLATE": "Function",
"NAME": "AAdd()",
"ONELINER": "Dynamically add an element to an array",
"CATEGORY": "API",
"SUBCATEGORY": "Array",
"SYNTAX": "AAdd( , [] ) --> xValue",
"ARGUMENTS": " The name of an array\n Element to add to array ",
"RETURNS": " if specified , will be returned, otherwise this function returns a NIL value.",
"DESCRIPTION": "This function dynamically increases the length of the by adding one new element to the end of the array and optionally stores the value to that newly created element.\n may be of an data type, including an array reference pointer, which in turn may be stored to an array's subscript position.",
"EXAMPLES": {
"_preformatted": "yes",
"__text": "LOCAL aArray := {}, tmp\nAAdd( aArray, 10 )\nFOR tmp := 1 TO 10\n AAdd( aArray, tmp )\nNEXT\n? hb_ValToExp( aArray ) // --> { 10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 }"
},
"STATUS": "Ready",
"COMPLIANCE": "CA-Cl*pper v5.x compatible",
"PLATFORMS": "Available on all platforms",
"FILES": "Library is core",
"TAGS": "API, Array",
"SEEALSO": "AIns(), ASize()"
},
{
"TEMPLATE": "Function",
"NAME": "AClone()",
"ONELINER": "Duplicate a multidimensional array",
"CATEGORY": "API",
"SUBCATEGORY": "Array",
"SYNTAX": "AClone( ) --> aDuplicate",
"ARGUMENTS": " Name of the array to be cloned.",
"RETURNS": " A new array pointer reference complete with nested array values.",
"DESCRIPTION": "This function makes a complete copy of the array expressed as and return a cloned set of array values. This provides a complete set of arrays values for all dimensions within the original array ",
"EXAMPLES": {
"_preformatted": "yes",
"__text": "LOCAL aOne := { \"Harbour\", \" is \", \"POWER\" }\nLOCAL aTwo := AClone( aOne )\n? hb_ValToExp( aTwo ) // --> { \"Harbour\", \" is \", \"POWER\" }\naOne[ 1 ] := \"The Harbour Compiler\"\n? hb_ValToExp( aOne ) // --> { \"The Harbour Compiler\", \" is \", \"POWER\" }\n? hb_ValToExp( aTwo ) // --> { \"Harbour\", \" is \", \"POWER\" }"
},
"STATUS": "Ready",
"COMPLIANCE": "CA-Cl*pper will return NIL if the parameter is not an array.",
"PLATFORMS": "Available on all platforms",
"FILES": "Library is core",
"TAGS": "API, Array",
"SEEALSO": "ACopy(), ADel(), AIns(), ASize()"
},
{
"TEMPLATE": "Function",
"NAME": "ACopy()",
"ONELINER": "Copy elements from one array to another",
"CATEGORY": "API",
"SUBCATEGORY": "Array",
"SYNTAX": "ACopy( , , [], [], [] ) --> aTarget",
"ARGUMENTS": " is the array to copy elements from.\n is the array to copy elements to.\n is the beginning subscript position to copy from \n the number of subscript elements to copy from .\n the starting subscript position in to copy elements to.",
"RETURNS": " an array pointer reference",
"DESCRIPTION": "This function copies array elements from to . is the beginning element to be copied from ; the default is 1.\n is the number of elements to be copied from ; the default is the entire array. is the subscript number in the target array, , to which array elements are to be copied; the default is 1.\nThis function will copy all data types in to . If an array element in is a pointer reference to another array, that array pointer will be copied to ; not all subdimensions will be copied from one array to the next. This must be accomplished via the AClone() function.\nNote: If array is larger then , array elements will start copying at and continue copying until the end of array is reached. The ACopy() function doesn't append subscript positions to the target array, the size of the target array remains constant.",
"EXAMPLES": {
"_preformatted": "yes",
"__text": "LOCAL nCount := 2, nStart := 1\nLOCAL aOne := { \"Harbour\", \" is \", \"Power\" }\nLOCAL aTwo := { \"Clipper\", \" was \", \"Power\" }\nACopy( aOne, aTwo, nStart, nCount )\n? hb_ValToExp( aTwo ) // --> { \"Harbour\", \" is \", \"Power\" }"
},
"STATUS": "Ready",
"COMPLIANCE": "CA-Cl*pper v5.x compatible",
"PLATFORMS": "Available on all platforms",
"FILES": "Library is core",
"TAGS": "API, Array",
"SEEALSO": "AClone(), ADel(), AEval(), AFill(), AIns(), ASort()"
},
{
"TEMPLATE": "Function",
"NAME": "ADel()",
"ONELINER": "Delete an element from an array.",
"CATEGORY": "API",
"SUBCATEGORY": "Array",
"SYNTAX": "ADel( , ) --> aArray",
"ARGUMENTS": " Name of array from which an element is to be removed.\n Subscript of the element to be removed.",
"RETURNS": " an array pointer reference.",
"DESCRIPTION": "This function deletes the element found at subscript position in the array . All elements in the array below the given subscript position will move up one position in the array.\nIn other words, what was formerly the sixth subscript position will become the fifth subscript position. The length of the array will remain unchanged, as the last element in the array will become a NIL data type.\nNote: To completely remove an element and decrease the length of array you can use hb_ADel() that supports auto-sizing.",
"EXAMPLES": {
"_preformatted": "yes",
"__text": "LOCAL aArray := { \"Harbour\", \"is\", \"Power\" }\nADel( aArray, 2 )\n? hb_ValToExp( aArray ) // --> { \"Harbour\", \"Power\", NIL }"
},
"STATUS": "Ready",
"COMPLIANCE": "CA-Cl*pper v5.x compatible",
"PLATFORMS": "Available on all platforms",
"FILES": "Library is core",
"TAGS": "API, Array",
"SEEALSO": "hb_ADel(), ACopy(), AIns(), AFill()"
},
{
"TEMPLATE": "Function",
"NAME": "AEval()",
"ONELINER": "Evaluates the subscript element of an array",
"CATEGORY": "API",
"SUBCATEGORY": "Array",
"SYNTAX": "AEval( , , [], [] ) --> aArray",
"ARGUMENTS": " Is the array to be evaluated.\n Is a code block to evaluate for each element processed.\n The beginning array element index to evaluate.\n The number of elements to process.",
"RETURNS": " an array pointer reference.",
"DESCRIPTION": "This function evaluates the elements of , and executes for each of them the processing that's defined with . By default, all the elements of array are being processed, starting from 1st and up to the last element.\nIf and/or parameters are given, then the processing starts from element and continues for the next elements (if defined) or up to the last element of the array.\nThe code block receives two parameters: the element value and element's index (position) into the array. i.e. `{| xValue, nIndex | ... }` Worth to note that elements are passed to code block 'by value', thus any change being made to this value doesn't affects the value of element in the array.",
"EXAMPLES": {
"_preformatted": "yes",
"__text": "LOCAL a := { 10, 20, 30 }\nAEval( a, {| e, n | QOut( e * n + 1 , a[ n ] ) } )\n? a[ 1 ], a[ 2 ], a[ 3 ] // array elements unchanged\n? \"----\"\nAEval( a, {| e, n | QOut( e * n + 1, a[ n ] *= n + 1 ) }, 2, 1 )\n/* Here the 2nd element been changed, because we've explicitly used\n its pointer 'a[ n ] *= ...' into array */\n? a[ 1 ], a[ 2 ], a[ 3 ]"
},
"STATUS": "Ready",
"COMPLIANCE": "CA-Cl*pper v5.x compatible",
"PLATFORMS": "Available on all platforms",
"FILES": "Library is core",
"TAGS": "API, Array",
"SEEALSO": "Eval(), dbEval()"
},
{
"TEMPLATE": "Function",
"NAME": "AFill()",
"ONELINER": "Fill an array with a specified value",
"CATEGORY": "API",
"SUBCATEGORY": "Array",
"SYNTAX": "AFill( , , [], [] ) --> aArray",
"ARGUMENTS": " Name of array to be filled.\n Expression to be globally filled in \n Subscript starting position\n Number of subscript to be filled",
"RETURNS": " pointer to the array.",
"DESCRIPTION": "This function will fill each element of an array named with the value . If specified, denotes the beginning element to be filled and the array elements will continue to be filled for positions.\nIf neither / specified, the value of will be 1, and the value of will be the value of `Len( )`; thus, all subscript positions in the array will be filled with the value of .\nThis function will work on only a single dimension of . If there are array pointer references within a subscript , those values will be lost, since this function will overwrite those values with new values.",
"EXAMPLES": {
"_preformatted": "yes",
"__text": "LOCAL aArray := { NIL, 0, 1, 2 }\nAFill( aArray, 5 )\n? hb_ValToExp( aArray )"
},
"STATUS": "Ready",
"COMPLIANCE": "CA-Cl*pper v5.x compatible",
"PLATFORMS": "Available on all platforms",
"FILES": "Library is core",
"TAGS": "API, Array",
"SEEALSO": "AAdd(), AEval(), dbStruct()"
},
{
"TEMPLATE": "Function",
"NAME": "AIns()",
"ONELINER": "Insert a NIL value at an array subscript position.",
"CATEGORY": "API",
"SUBCATEGORY": "Array",
"SYNTAX": "AIns( , ) --> aArray",
"ARGUMENTS": " Array name.\n Subscript position in ",
"RETURNS": "a reference to .",
"DESCRIPTION": "This function inserts a NIL value in the array named at the th position.\nAll array elements starting with the th position will be shifted down one subscript position in the array list and the last item in the array will be removed completely. In other words, if an array element were to be inserted at the fifth subscript position, the element previously in the fifth position would now be located at the sixth position. The length of the array will remain unchanged.\nNote: To avoid loosing last element, you can use hb_AIns() which supports auto-sizing of array.",
"EXAMPLES": {
"_preformatted": "yes",
"__text": "LOCAL aArray := { \"Harbour\", \"is\", \"Power!\", \"!!!\" }\nAIns( aArray, 4 )\n? hb_ValToExp( aArray )"
},
"STATUS": "Ready",
"COMPLIANCE": "CA-Cl*pper v5.x compatible",
"PLATFORMS": "Available on all platforms",
"FILES": "Library is core",
"TAGS": "API, Array",
"SEEALSO": "hb_AIns(), AAdd(), ACopy(), ADel(), AEval(), AFill(), ASize()"
},
{
"TEMPLATE": "Function",
"NAME": "Array()",
"ONELINER": "Create an uninitialized array of specified length",
"CATEGORY": "API",
"SUBCATEGORY": "Array",
"SYNTAX": "Array( [, ...] ) --> aArray",
"ARGUMENTS": " is the number of elements in the specified dimension.",
"RETURNS": " an array of specified dimensions.",
"DESCRIPTION": "This function returns an uninitialized array with the length of .\nNested arrays are uninitialized within the same array pointer reference if additional parameters are specified.\nEstablishing a memory variable with the same name as the array may destroy the original array and release the entire contents of the array. This depends, of course, on the data storage type of either the array or the variable with the same name as the array.\nCA-Cl*pper v5.x compliant except that arrays in Harbour can have an unlimited number of elements.",
"EXAMPLES": {
"_preformatted": "yes",
"__text": "LOCAL aArray := Array( 10 ), tmp\nFOR tmp := 1 TO Len( aArray )\n aArray[ tmp ] := Array( tmp )\nNEXT\n? hb_ValToExp( aArray ) // --> { { NIL }, { NIL, NIL }, ... }"
},
"STATUS": "Ready",
"COMPLIANCE": "CA-Cl*pper v5.x compatible",
"PLATFORMS": "Available on all platforms",
"FILES": "Library is core",
"TAGS": "API, Array",
"SEEALSO": "AAdd(), ADel(), AFill(), AIns()"
},
{
"TEMPLATE": "Function",
"NAME": "AScan()",
"ONELINER": "Scan array elements for a specified condition",
"CATEGORY": "API",
"SUBCATEGORY": "Array",
"SYNTAX": "AScan( , , [], [] ) --> nStoppedAt",
"ARGUMENTS": " Array to be scanned.\n Expression to search for in \n Beginning subscript position at which to start the search.\n Number of elements to scan with .",
"RETURNS": " A numeric value of subscript position where was found, or 0 if is not found.",
"DESCRIPTION": "This function scan the content of array named for the value of . The return value is the position in the array in which was found. If it was not found, the return value will be 0.\n is the position from which to start scanning. The default is 1. (1st element) , if specified, is the number of array elements to be scanned. The default is all elements in the array .\nIf is a code block, the operation of the function is slightly different. Each array subscript pointer reference is passed to the code block to be evaluated. The scanning routine will continue until the value obtained from the code block is a logical true (.T.) or until the end of the array has been reached.",
"EXAMPLES": {
"_preformatted": "yes",
"__text": "#include \"directry.ch\"\nLOCAL aDir := hb_vfDirectory( \"*.prg\" )\n? AScan( aDir,,, ;\n {| aFile, nPos | HB_SYMBOL_UNUSED( nPos ), aFile[ F_NAME ] == \"test.prg\" } )"
},
"STATUS": "Ready",
"COMPLIANCE": "This function is not CA-Cl*pper compatible. CA-Cl*pper AScan() is affected by the `SET EXACT ON`/`OFF` Condition",
"PLATFORMS": "Available on all platforms",
"FILES": "Library is core",
"TAGS": "API, Array",
"SEEALSO": "AEval()"
},
{
"TEMPLATE": "Function",
"NAME": "ASize()",
"ONELINER": "Adjust the size of an array",
"CATEGORY": "API",
"SUBCATEGORY": "Array",
"SYNTAX": "ASize( , ) --> aArray",
"ARGUMENTS": " Name of array to be dynamically altered\n Numeric value representing the new size (i.e. number of elements)\nof ",
"RETURNS": "The function returns a reference to .",
"DESCRIPTION": "This function will dynamically increase or decrease the size of by adjusting the length of the array to subscript positions.\nIf the length of the array is shortened, the redundant elements are removed from the end of array. If the length of the array is lengthened the new elements are added to the end of array and they are assigned a NIL value.",
"EXAMPLES": {
"_preformatted": "yes",
"__text": "LOCAL aArray := { 1 }\n? hb_ValToExp( aArray ) // --> { 1 }\nASize( aArray, 3 )\n? hb_ValToExp( aArray ) // --> { 1, NIL, NIL }\nASize( aArray, 1 )\n? hb_ValToExp( aArray ) // --> { 1 }"
},
"STATUS": "Ready",
"COMPLIANCE": "If HB_COMPAT_C53 is defined, the function generates an Error, else it will return the array itself.",
"PLATFORMS": "Available on all platforms",
"FILES": "Library is core",
"TAGS": "API, Array",
"SEEALSO": "AAdd(), ADel(), AFill(), AIns()"
},
{
"TEMPLATE": "Function",
"NAME": "ASort()",
"ONELINER": "Sort an array",
"CATEGORY": "API",
"SUBCATEGORY": "Array",
"SYNTAX": "ASort( , [], [], [] ) --> aArray",
"ARGUMENTS": " Array to be sorted.\n The first element to start the sort from, default is 1.\n Number of elements starting from to sort, default\nis all elements.\n Code block for sorting order, default is ascending order `{| x, y | x < y }`. The code block should accept two parameters and must return .T. if the sort is in order, .F. if not.",
"RETURNS": " reference to the now sorted or NIL if the passed is not an array.",
"DESCRIPTION": "ASort() sort all or part of a given array. If is omitted, the function expect to be one dimensional array containing single data type (one of: Character, Date, Logical, Numeric) and sort this array in ascending order: Character are sorted by their ASCII value, Dates are sorted chronologically, Logical put .F. values before .T., Numeric are sorted by their value. If is specified, it is used to handle the sorting order. With each time the block is evaluate, two array elements are passed to the code block, and must return a logical value that state if those elements are in order (.T.) or not (.F.). Using this block you can sort multidimensional array, descending orders or even (but why would you want to do that) sort array that contain different data type.\nCodeblock calling frequency and order differs from CA-Cl*pper, since Harbour uses a different (faster) sorting algorithm (quicksort).",
"EXAMPLES": {
"_preformatted": "yes",
"__text": "LOCAL aKeys, bSort, aPair\n\n// Sort numeric values in ascending order\naKeys := { 3, 1, 4, 42, 5, 9 }\nASort( aKeys )\n? hb_ValToExp( aKeys ) // --> { 1, 3, 4, 5, 9, 42 }\n\n// Sort character strings in descending lexical order\naKeys := { \"Ctrl\", \"Alt\", \"Delete\" }\nbSort := {| x, y | Upper( x ) > Upper( y ) }\nASort( aKeys,,, bSort )\n? hb_ValToExp( aKeys ) // --> { \"Delete\", \"Ctrl\", \"Alt\" }\n\n// Sort two-dimensional array according to 2nd element of each pair\naPair := { { \"Sun\", 8 }, { \"Mon\", 1 }, { \"Tue\", 57 }, { \"Wed\", -6 } }\nASort( aPair,,, {| x, y | x[ 2 ] < y[ 2 ] } )\n? hb_ValToExp( aPair ) // --> { { \"Wed\", -6 }, { \"Mon\", 1 }, { \"Sun\", 8 }, { \"Tue\", 57 } }"
},
"STATUS": "Ready",
"COMPLIANCE": "CA-Cl*pper v5.x compatible",
"PLATFORMS": "Available on all platforms",
"FILES": "Library is core",
"TAGS": "API, Array",
"SEEALSO": "AScan(), Eval(), SORT"
},
{
"TEMPLATE": "Function",
"NAME": "ATail()",
"ONELINER": "Returns the last element of an array",
"CATEGORY": "API",
"SUBCATEGORY": "Array",
"SYNTAX": "ATail( ) --> xValue",
"ARGUMENTS": " is the array.",
"RETURNS": " the value of the last element in the array.",
"DESCRIPTION": "This function return the value of the last element in the array named . Same as `xValue := aArray[ Len( aArray ) ]`",
"EXAMPLES": {
"_preformatted": "yes",
"__text": "LOCAL aArray := { \"Harbour\", \"is\", \"Supreme\", \"Power\" }\n? ATail( aArray ) // --> \"Power\""
},
"STATUS": "Ready",
"COMPLIANCE": "CA-Cl*pper v5.x compatible",
"PLATFORMS": "Available on all platforms",
"FILES": "Library is core",
"TAGS": "API, Array",
"SEEALSO": "Len(), Array(), ASize(), AAdd()"
},
{
"TEMPLATE": "Function",
"NAME": "hb_ADel()",
"ONELINER": "Delete an element from an array.",
"CATEGORY": "API",
"SUBCATEGORY": "Array",
"SYNTAX": "hb_ADel( , [], [] ) --> aArray",
"ARGUMENTS": " Name of array from which an element is to be removed.\n Subscript of the element to be removed. Default value: 1.\n Boolean flag specifying if the array will be resized or not.\nDefault value: .F. (no resize).",
"RETURNS": " an array pointer reference.",
"DESCRIPTION": "This function deletes the element value (not the element itself!) stored in position and shifts all the following values, one position up.\nIf is .T., then the last element is removed and the size of the array is decreased by one, otherwise the length of the array remains unchanged and a NIL value will be stored in the last element, just like in ADel().",
"EXAMPLES": {
"_preformatted": "yes",
"__text": "LOCAL aArray := { \"Harbour\", \"is\", \"Power\" }\nhb_ADel( aArray, 2 )\n? hb_ValToExp( aArray ) // --> { \"Harbour\", \"Power\", NIL } - length unchanged\nhb_ADel( aArray, 2, .T. )\n? hb_ValToExp( aArray ) // --> a{ \"Harbour\", \"Power\" } - length decreased"
},
"STATUS": "Ready",
"COMPLIANCE": "Harbour specific",
"PLATFORMS": "Available on all platforms",
"FILES": "Library is core",
"TAGS": "API, Array",
"SEEALSO": "ADel(), ACopy(), AIns(), AFill()"
},
{
"TEMPLATE": "Function",
"NAME": "hb_AIns()",
"ONELINER": "Inserts a value at an array subscript position and optionally increases the length of array.",
"CATEGORY": "API",
"SUBCATEGORY": "Array",
"SYNTAX": "hb_AIns( , [], [], [] ) --> aArray",
"ARGUMENTS": " The array name into which the value will be inserted.\n Subscript position in . Default: 1st position\n Value to be inserted\n Boolean flag to increase or not the size of .\nDefault value: .F.",
"RETURNS": "A reference to array ",
"DESCRIPTION": "This function inserts in the position of the array, moving all the items one position down in the array list. If is .T., a new element will be added at the end of array, making room for the previous last element, which means the length of array will be increased by 1.\nIf is .F. (or is not passed) the function behaves like AIns(), that is, the size of won't change and the last item of will be lost.",
"EXAMPLES": {
"_preformatted": "yes",
"__text": "LOCAL aArray := { \"Harbour\", \"Power!\" }\nhb_AIns( aArray, 2, \"is\", .F. )\n? hb_ValToExp( aArray ) // --> { \"Harbour\", \"is\" }\nhb_AIns( aArray, 2, \"is\", .T. )\n? hb_ValToExp( aArray ) // --> { \"Harbour\", \"is\", \"Power!\" }"
},
"STATUS": "Ready",
"COMPLIANCE": "Harbour specific",
"PLATFORMS": "Available on all platforms",
"FILES": "Library is core",
"TAGS": "API, Array",
"SEEALSO": "AIns(), AAdd(), ADel(), AFill(), ASize()"
},
{
"TEMPLATE": "Function",
"NAME": "hb_AScan()",
"ONELINER": "Scan array elements for a specified condition",
"CATEGORY": "API",
"SUBCATEGORY": "Array",
"SYNTAX": "hb_AScan( , , [], [], [] ) --> nPosition",
"ARGUMENTS": "