Back To Home

• AAdd( <aArray>, [<xValue>] ) ➜ xValue|NIL
  This function attempts to add an element to the end of <aArray> and optionally assigns the value <xValue> to this new element.
  If the addition succeeds, the length of the array increases by one and the function returns either the value <xValue>, if one specified, or NIL.
  Note that the presence of the 2nd argument (or at least the comma next to the 1st one, in which case NIL is implied as xValue) is mandatory, even if a specific xValue is not meant to be simultaneously added, otherwise RTE occurs; in such a case, the effect is identical to ASize(aArray, Len(aArray)+1).

• Abs( <nExp> ) ➜ nPositive
  returns the absolute value of the passed argument. The result is always greater than or equal to 0 (zero).

• AChoice(<nTop>,<nLeft>,<nBottom>,<nRight>,<acMenuItems>,[<xSelect>],[<xUserFunction>],[<nPos>],[<nHiLiteRow>]) ➜ nItemSelected
  displays a Pop-up-like menu with selectable menu items, waiting for a selection by user. Returns the index number of the selected item, which is the ordinal position of the item into the array; if the selection aborted, (when for example, the Esc key pressed) the value returned is 0 (zero).

  • <acMenuItems> is an array of character strings to display as the menu items.
  • <xSelect> is used to determine whether one or more menu items will be selectable or not! It can be either:
    • a parallel array of logical or character values, one element for each item in <acMenuItems>. If the element is a character string, it is evaluated as a macro expression which should evaluate to a logical data type.
    • or a single logical value, in which case all menu items will be either available when .T. or unavailable when .F.; default is .T. (i.e., all items be available).
    • or codeblocks, function pointers or character expression, being supplied both 'as is' or 'as an array'. When passed as a single value and the next parameter <xUserFunction> is empty, it's being used as <xUserFunction> (surrogate), while all the items become selectable. This is a new Harbour extension!
  • <xUserFunction> is the name of a user-defined function or a function Symbol or a Code-block that executes when an unrecognizable key is pressed. Must be noted that the behavior of Achoice() is significantly affected by the presence or not of this argument. Refer to Clipper Reference Guide for more...
  • <nPos> is the position in the <acMenuItems> array of the item that will be highlighted when the menu is initially displayed.
  • <nHiLiteRow> is the zero-based number of the window row on which the initial menu item will appear.

• AClone( <aSource> ) ➜ aDuplicate
  duplicates an array. Works with multidimensional arrays.

• ACopy(<aSource>, <aTarget>, [<nStart>], [<nCount>], [<nTagetPos>]) ➜ aTarget
  copy elements from a source array into a target array. Operates only on one-dimensional arrays.

• ADays() ➜ aDays
  returns an array with all the days names in the selected current language.
  (note: that's a hbMisc contrib library function)

• ADel(<aArray>, <nPosition>) ➜ aArray
  deletes the element at position <nPosition> from the array <aArray>. All subsequent elements are shifted up by one position so that the last element contains the value NIL. See hb_Adel() for extra functionality.

• ADir([<cFileSpec>], [<aFilenames>], [<aSizes>], [<aDates>], [<aTimes>], [<aAttributes>]) ➜ nFiles
  depreciated compatibility function! use Directory() or hb_Directory() instead.

• AddMonth([<dDate>,] <nMonths>) ➜ dShiftedDate
  (note: that's a hbct contrib library function)

• AEval(<aArray>, <bBlock>, [<nStart>], [<nCount>]) ➜ aArray
  Evaluates the <bBlock> for each element into <aArray>, starting from <nStart> and continues until <nCount>[¹] elements or all array elements have been evaluated (i.e. processed).
  Default values for <nStart> & <nCount> parameters are: nStart=1, nCount=Len(aArray).
  The code-block receives two argument values: 1) the current element being evaluated (value may be of whatever type) and 2) the numeric position (index) of that element into the array.
  Example: AEval( aArray, {|e,n| Qout(n, e)} )
  [¹] please note that in case the <nCount> exceeding the array elements the function does not issue any kind of 'out of range' error (practically, it means that the number of evaluations may not necessarily be equal to <nCount>). This behavior stands also for other array functions.

• AFields([<aFieldsnames>], [<aTypes>], [<aWidths>], [<aDecimals>], [<aFlags>]) ➜ nFields
  depreciated compatibility function! use 'DbSTruct()' which retrieves all structural information in a multi-dimensional array.

• AFill(<aArray>, <xValue>, [<nStart>], [<nCount>]) ➜ aArray
  assigns the value of <xValue> to the <nCount> elements, beginning at position <nStart>. Multi-dimensional arrays cannot be filled using 'AFill()'. Default values for <nStart>/<nCount> optional parameters: <nStart> = 1, <nCount> = Len( aArray ) (i.e. all elements).

• AIns( <aArray>, <nPosition> ) ➜ aArray
  Inserts a new element at <nPosition> into the array <aArray>. All subsequent elements are shifted down by one position so that the last element is lost. The number of elements remain unchanged. See hb_AIns() which allows auto-sizing of array.

• Alert(<cMessage>, [<aOptions>]) ➜ nChoice
  displays a simple modal dialog box with a message and one or more options the user can select. <cMessage> is the message text displayed. If it contains one or more semicolons ; the text after each semicolon is displayed at the next (new) line. <aOptions> defines a list of up to 4 possible options. the function returns a numeric value indicating which option was chosen. If the Esc key was pressed, returns 0 (zero).

• Alias([<nWorkarea>]) ➜ cAlias | ""
  returns the alias of the <nWorkArea> or the alias of the current work area if <nWorkArea> is not provided. If no database file is opened in current or given work area, it returns null string.
  (NOTE: if no explicit alias specified during opening, the default alias of the opened dbf, is the filename without path and extension.)

• AllTrim( <cString> ) ➜ cTrimString
  removes all the leading and trailing spaces from the <cString>.
  Note: The carriage return, line feed and tab characters (i.e. Chr(13), Chr(10), Chr(9) respectively) are treated as space characters and are removed. However, other non-printable character (i.e. those below ASCII Chr(32)) are not affected and this fact may be important, particularly with Chr(0), which might cause "unexpected" behavior when the supposedly trimmed string is passed to functions like Empty().

• AltD([<nAction>]) ➜ NIL
  Invokes debugger. Optional argument [<nAction>] can be 1=enable debuger or 0=disable debugger. In order the debugger to be activated, the -b compiler switch must have been used during building.

• AMPM([<cTime>]) ➜ cTime
  returns the [<cTime>] time string in 12-hour format (HH:MM:SS pm/am), that is, the hour (HH) part is displayed as a <= 12 value and an added suffix which is either am if [<cTime>] is an 'ante meridiem' (before midday) hour or pm if it is 'post meridiem' (after midday). If [<cTime>] is not given the function returns 12 am.

• AMonths() ➜ aMonths
  returns an array with all the months names in the selected current language.

• Array( <nDim1> [, <nDimN,...>] ) ➜ aArray
  returns an array dimensioned according to the passed parameters. All elements of the array contain the value NIL.

• Asc( <cExp> ) ➜ nCode
  returns the ASCII value of the leftmost character of any character expression.

• AScan( <aArray>, <xSearch>, [<nStart>], [<nCount>] ) ➜ nStoppedAt
  search into <aArray> for <xSearch> value starting from <nStart> up to <nCount>]. (default values are: nStart=1, nCount=All elements).
  returns the position of element that matches the searched value or 0 if no match is found. See also hb_AScan()

• ASize(<aArray>, <nLength>) ➜ aArray
  dynamically increases or decreases the size of <aArray> to <nLength> elements. When the array is enlarged, new elements are added to the end of <aArray> and are initialized with NIL. When the number of elements is decreased, elements are removed from the end of <aArray and their values are lost. returns reference to sized array.

• ASort( <aArray>, [<nStart>], [<nCount>], [<bSort>] ) ➜ aArray
  sorts an array entirely or partially. Usage of the code block <bSort> is mandatory when the array is multidimensional, otherwise sorting won't be possible. The code-block, during the sorting process, receives two elements as block parameters and shall return .T. when they're in order. Examples:

  // Ascending sorting of the array aArray
     aArray := ASort( aArray,,, { |x,y| x < y } )       
  // Descending sorting of a multidimensional array based on 3rd sub-array element.
     aArray := ASort( aArray,,, { |x,y| x[3] > y[3] } )

  • Sorting is case sensitive for character elements.
  • Logical value .F. is considered smaller than .T.
  • Order of precedence of different data types:
    • objects, arrays, code-blocks, strings, booleans, timestamps, dates, numbers, hash arrays
    • any attempt of sorting arrays with elements of different data type, shall produce RTE if actualized without proper handling of block-parameters (i.e., without conversion to same type).

• At( <cSearchFor>, <cIntoString> ) ➜ nPosition
  returns the position in <cIntoString> where <cSearchFor> is found or 0 (zero) when <cSearchFor> is not found. NOTE: Search is case sensitive!

• ATail(<aArray>) ➜ xValue
  returns the value stored in the last element of <aArray>.
  Back to top
  Back to Home