'
'
'
'         ###############
'       ###################
'      ###               ###
'     ###    ###          ###
'    ###    ## ##         ###
'    ###   ##   ##        ###
'    ###  ##     ##       ###
'    ###  ##      ##      ###
'    ###  ##      ##      ###
'    ###   ####  ##      ###
'     ###    ####       ###
'      ###             ###
'       ###           ###
'         #############
'           #########



OxyDatabase.txt
OxygenBasic database


' __     show white space

check:
  NEW WORDS:
  ==========
  internal 18
  #tally
  #unquote
updated:  26/03/25
.

FIELDS:
=======

'UNIT RECORD

'key:     "keyname metatype"
same:     
action:   
use:     
incfile1:
incfile2: 
example:  
result:   
remarks:  
related:  
group:    
updated:  03/03/25
.

'GROUP RECORD

'key:
members:
keylinks:
action:   
use:      
example:
result:   
remarks:  
group:
related:    
updated:  05/02/2026
.


      'GROUPED BY METATYPE
      '----------------------
      case 0  : w="various"
      case 1  : w="def macro"
      case 2  : w="defs enumeration"
      case 3  : w="type / class"
      case 4  : w="low level functions"
      case 5  : w="proc / sub / function / method"
      case 8  : w="struct from typedef"
      case 9  : w="common reserved words"
      case 10 : w="x86 CPU registerS"
      case 11 : w="attributes"
      case 12 : w="namespace"
      case 13 : w="major keywords group 1"
      case 14 : w="major keywords group 2"
      case 15 : w="primitive types"
      case 16 : w="functions"
      case 17 : w="float macros"
      case 30 : w="labels"
      case 18 : w="low level macros"
      case 19 : w="internal macros"
      case 20 : w="high level macros"
      '----------------------
      'SECONDARY KEYWORDS
      '----------------------
      case 51 : w="operators"
      case 52 : w="control / loops"
      case 53 : w="declaratives"
      case 54 : w="secondary keywords"
      case 55 : w="calling conventions"
      case 56 : w="comment symbols"
      case 57 : w="meta language keywords
      case 59 : w="macro operator keywords"
     'case 99 : w="macro functions & dim"
      '----------------------
updated: 03/03/2025
.


'=========================
'>>OXYGEN LOW LEVEL MACROS
'=========================


key:      "string_constants "
members:  cr, crlf, tab, qu, spc, cm
use:      widely used string constants
example:  print 1 cm 2 cm 3 cr
          print 1 tab 2 tab 3 cr
          print qu "helo" qu  ' "helo"
          'Others are easily created
          def cln ":"
          ...
remarks:  
related:  space
group:    system macro
updated:  06/02/2026
.


key:      "true 18"
action:   insert -1
use:      universal value for boolean true
example:  int a=true
remarks:
related:  false, not__bits, not__conditional
group:    system macro
updated:  27/03/2017
.


key:      "false 18"
action:   insert 0
use:      universal value for boolean false
example:  int a=false
remarks:
related:  true, not__bits, not__conditional
group:    system macro
updated:  27/03/2017
.


key:      "#view 18"
key:      "#endv 18"
action:   creates a window for compiler listings.
use:      Allows the programmer to see a selected part of the compiled code
example:  sys a,b,c
  ###
  a=b+c
  ###
  s="Value "+str(a)
remarks:  These markers restrict the listing to a window so that the code can be studied in detail.
  #view and #endv are generated internally from the pair of '###' symbols.
related:  #show
group:    directives
updated:  11/02/2025
.


key:      "version 18"
action:   returns current version number and DateTimeStamp.
use:      identification of version
example:  print version
related:  o2version
group:    info string
updated:  24/06/2019
.


key:      "o2version 18"
action:   returns current version number.
use:      version matching 
example:  $ rtlversion "0.2.1"
  '
  #if not match(rtlversion,o2version)
    #error "RTL version mismatches o2 version "+o2version
  #endif
related:  version
group:    info string
updated:  24/06/2019
.


key:      "lobyte 18"
action:   return the lower 8 bits of an integer expression
example:  wl=lobyte(wParam)
related:  hibyte, loword, hiword
group:    system macro
updated:  14/02/2018
.


key:      "loword 18"
action:   return the lower 16 bits of an integer expression
example:  wl=loword(wParam)
related:  hiword, hibyte, lobyte
group:    system macro
updated:  14/02/2018
.


key:      "hibyte 18"
action:   return bits 8..15 of an integer expression
example:  wh=hibyte(wParam)
related:  lobyte, loword, hiword
group:    system macro
updated:  14/02/2018
.


key:      "hiword 18"
action:   return bits 16..31 of an integer expression
example:  wh=hiword(wParam)
related:  loword, lobyte, hibyte
group:    system macro
updated:  14/02/2018
.


key:      "view 18"
action:   Displays a variable's name and its value
example:  
  string  s="Helo"
  view i
  'result: s    "Helo"
related:  print, mbox, #show, #view  
group:    system macro
updated:  02/03/2025
.


key:      "dyn 18"
action:   create a low-level dynamic array
use:      create an extendable array at run-time
example:  
  int n=64
  dyn string s(n)
  ...
  del s
remarks: dyn variable do not have array attributes, like uound. Use redim
  when you intend to use ubound, dims, etc.
related:  stretch, redim remap, dim, del, 
group:    system macro
updated:  02/03/2025
.


key:      "stretch 18"
action:   resize a low-level dynamic array
use:      to resize a dyn array at run-time
example:  
  int n=64
  dyn string s(n)
  ...
  stretch s(n+32)
  ...
  del s 'or freememory @s
remarks:  The array contents are preserved, except
  when the array size is reduced.
related:  dyn, redim remap, del
group:    system macro
updated:  02/03/2025
.


key:      "remap 18"
action:   overlay a dynamic array or memory space
use:      map an array onto any memory location
example:
  string s = nuls(10000)  
  remap byte bt(100,100)
  @bt = strptr(s)
  '
  sys p=getmemory 10000
  @bt=p

remarks:  

related:  redim, dim, lbound, ubound, getmemory, indexbase
group:    system macro
updated:  10/02/2025
.


key:      "redim 18"
action:   create or resize a dynamic array, preserving contents within range
use:      extend or reduce an array size at run-time
example:  
  redim string s(n)
  redim string s(1000)
  redim string s(100) clear
  int y=100, x=100
  redim int a2d (y,x)

  'use [redim] when passing to a procedure:

  sub f(int *fa2d[redim], int y, x)
    redim fa2d(y,x)
  end sub
  ...
  del a2d
remarks:  
  The remaining element values are preserved unless
  the 'clear' directive is given.

  redim cannot be directly used inside a Type or Class.
related:  remap, dim, dyn, lbound, ubound, del, new, indexbase
group:    system macro
updated:  02/03/2025
.


key:      "dims  18"
action:   specifies number of dimensions of an array
use:      iterating over array dimension metrics
example:
  indexbase 1 'default
  dim int a(200,10)
  print dims(a) '2
remarks:  
related:  ubound, lbound, scaler, strider, dim, redim
group:    system macro
updated   10/02/2025
.


key:      "lbound  18"
action:   specifies min index of an array dimension
use:      checking array limits
example:
  indexbase 1 'default
  dim int a(200,10)
  print lbound(a) '1
  print lbound(a,1) '1
  print lbound(a,2) '1
remarks:  
related:  dims, ubound, scaler, strider, dim, redim
group:    system macro
updated   10/02/2025
.


key:      "ubound  18"
action:   specifies max index of an array dimension
use:      checking array limits
example:
  indexbase 1 'default
  dim int a(200,10)
  print ubound(a) '2000
  print ubound(a,1) '200
  print ubound(a,2) '10
remarks:  
related:  dims, lbound, scaler, strider, dim, redim
group:    system macro
updated   10/02/2025
.


key:      "scaler  18"
action:   specifies step size of an array dimension
use:      calculating a position offset in the array
example:
  indexbase 1 'default
  #majorminor 'default dimension order
  dim int a(200,10)
  print scaler(a,1) '10
  print scaler(a,2) '1
remarks:  
related:  dims, lbound, strider, dim, redim
group:    system macro
updated   10/02/2025
.


key:      "strider  18"
action:   specifies step size of an array dimension
use:      calculating a position offset in the array
example:
  indexbase 1 'default
  #majorminor 'default dimension order
  dim int a(200,10)
  print strider(a,1) '40
  print strider(a,2) '4
remarks:  
related:  dims, lbound, scaler, dim, redim
group:    system macro
updated   10/02/2025
.


key:      "new 18"
action:   create a dynamic object and call its constructor method.
use:      to create and initialise objects
example:
  '  
  'creating object cuboid in dynamic space
  new shape cuboid(1,1,1)
  '
  'creating object cuboid on the stack
  new shape cuboid(1.0, 2.0, 1.0) local
  '
  'creating object cuboid in global or static space
  new shape cuboid(1.0, 1.5, 1.0) static
  '
remarks:
related:  classes, type, del, dim
group:    system macro
updated:  10/02/2025
.


key:      "del 18"
action:   Call a dynamic object's destructor method and disallocate its memory block.
use:      to delete objects and dynamic strings
example:  del cuboid
remarks:  
  'del' may also be used to delete the content of individual strings and bstrings, and 'del' can be used
  to delete the contents of dynamic arrays.
  Strings are set to null; the contents are released and removed from the garbage collector's lists.
related:  classes, new, redim, undef
group:    system macro
updated:  10/05/2025
.


'==================================
'>>OXYGEN SYSTEM TERMINATION MACROS
'==================================



key:      "terminate 19"
action:   Deallocate all Strings, static variables and free DLL libraries (at end of program).
  This is automatically appended unless it is detected in the program.
  It is composed of the three macros below: FreeLibs FreeStrings. If either
  of these are used then Terminate itself will not be automatically appended.
use:      explicit termination of program
example:  terminate
related:  freestrings, freelibs
group:    system macro
updated:  11/02/2025
.


key:      "freestrings 19"
action:   deallocate all remaining static strings only (at end of program)
use:      allow the program to terminate without freeing libraries
example:  freestrings
related:  terminate, freelibs
group:    system macro
updated:  11/02/2025
.


key:      "freelibs 19"
action:   free all loaded DLL libraries only (at end of program)
use:      allow the program to terminate but all static strings are retained
example:  freelibs
related:  terminate, freestrings
group:    system macro
updated:  11/02/2025
.




'==========================
'>>OXYGEN HIGH LEVEL MACROS
'==========================

key:      "right 20"
action:   returns right part of a string by length
use:      string=right(sourcestring, length)
example:  s=right("abcdef",3)
result:   s="def"
related:  left, mid, ltrim, rtrim
group:    system macro
updated:  28/02/2017
.


key:      "reindex 20"
action:   create an index for a data array
use:      filter and index a set of data, with user-defined criteria
example:  
  uses console
  int d={8,9,6,7,4,5,2,3,0,1}
  int m=10
  '
  macro filter(r,i)
  if d[i]>=5
    r=1
  endif
  end macro
  '
  macro compare(r,i,j)
  if d[i]>d[j] 'ascending
  'if d[i]<d[j] 'descending
    r=1
  endif
  end macro
  '
  reindex idx,m,n,filter,compare
  '
  print "total " n cr cr
  int i,j
  for i=indexbase to n+indexbase-1
    j=idx[i]
    print i tab j tab d[j] cr
  next
  print cr cr
  del idx
  wait
remarks:  
related:  
group:    system macro
updated:  07/11/2022
.



'========================
'>>O2 LOW LEVEL FUNCTIONS
'========================



key:      "getmemory 4"
action:   allocate block of memory and return its base address
use:      address=getmemory bytes
example:  m=getmemory 8000
related:  freememory, news, frees
group:    low level functions
updated:  11/02/2025
.


key:      "freememory 4"
action:   free previously allocated memory block
use:      freememory address
example:  freememory m
related:  getmemory, news, frees
group:    low level functions
updated:  11/02/2025
.


key:      "loadlibrary 4"
action:   load a library (if not already loaded) and return its handle
use:      handle=loadlibrary "library filename"
example:  h=loadlibrary "kernel32.dll"
related:  freelibrary, library, getprocaddress
group:    low level functions
updated:  11/02/2025
.

key:      "freelibrary 4"
action:   free library
use:      freelibrary handle
example:  freelibrary h
related:  loadlibrary, library, getprocaddress
group:    low level functions
updated:  11/02/2025
.


key:      "getprocaddress 4"
action:   get procedure address
use:      getprocaddress libraryHandle "proc name"
example:  a=getprocaddress h, "AllocConsole"
related:  loadlibrary, freelibrary, library
group:    low level functions
updated:  11/02/2025
.


key:      "copy0 4"
action:   copy null terminated string to another location
use:      copy DestinationAddress, SourceAddress
example:  copy0 &a,&b
related:  copy00, copy
group:    low level functions
updated:  11/02/2025
.


key:      "copy00 4"
action:   copy null terminated string of wide (2 byte) characters to another location
use:      copy DestinationAddress, SourceAddress
example:  copy00 &v,&w
related:  copy0, copy, copyn
group:    low level functions
updated:  11/02/2025
.


key:      "copyn 4"
key:      "copy 4"
action:   string to another location by a specified number of bytes
use:      copy DestinationAddress, SourceAddress, NumberOfBytes
example:  copy &dest,&src,n
remarks:  copy and copyn are the same
related:  copy0, copy00
group:    low level functions
updated:  11/02/2025
.


key:      "mbox 4"
action:   display message null-terminated ascii string
use:      mbox String-expression
example:  mbox "Value " v
remarks:  
  unlike <b>print</b>, <b>mbox</b> does not check the expression-type so
  it is impertant to start with a string or char expression
related:  print, str
group:    low level functions
updated:  21/06/2022
.


key:      "comparestr 4"
action:   compare first string with second string
use:      comparestr bstr1, bstr2 : jg ifgreater : jl ifless : jz ifequal      
example:  comparestr bs1,bs2
related:  string, char, str
group:    low level functions
updated:  21/06/2022
.

'=============================
'>>COMMON RESERVED WORDS
'=============================

'key:      common_asm
'members:  exit, repeat, call, jump, and, or, xor, not, neg,
           test ,ja, jb, jg, jl, jae, jbe, jge, jle,
           db, dw, dd, dq,
           mov, lea, add, sub, mul, div, imul, idiv,
           jz, jnz, shl, shr, sal, sar, rol, ror, rcl, rcr,
'group:    common x86 assembly instructions
'updated:  05/02/2026





'===========================
'>>O2 ATTRIBUTE MACROS
'===========================



key:      "sizeof 11"
action:   return length of variable element (in bytes)
use:      nbytes=sizeof variable
example:  n=sizeof a
related:  offsetof, spanof, typeof typecodeof
group:    attributes
updated:  11/02/2025
.


key:      "offsetof 11"
action:   return offset of variable from index register
use:      nbytes=offsetof variable
example:  n=offsetof a
related:  sizeof, spanof, typeof, typecodeof, recordof
group:    attributes
updated:  11/02/2025
.


key:      "spanof 11"
same:     countof
action:   return span of array variable dimension
use:      nbytes=spanof variable dimension
example:  dim as long v(10) : n=spanof v
result:   n=10
related:  sizeof, bytesof,offsetof, typeof, typecodeof, recordof
group:    attributes
updated:  10/03/2024
.


key:      "bytesof 11"
action:   return space used by an array variable
use:      nbytes=spanof variable dimensionion
example:  dim as long v(10) : n=bytesof v
result:   n=40
related:  sizeof, spanof, offsetof, typeof, typecodeof, recordof
group:    attributes
updated:  10/03/2024
.


key:      "typeof 11"
action:   return name of the variable type
use:      name=typeof variable
example:  dim as long v : s=typeof v
result:   s="long"
related:  typecodeof sizeof, offsetof, spanof, recordof
group:    attributes
updated:  11/02/2025
.


key:      "structureof 11"
action:   return data structure of compund (UDT) or variabe
use:      obtain data for diagnostics or reflective programming
example:  type vt long v,double d
  dim as vt v :  r=recordof v
result:   r="
  v 0 4 1 A0 , long
  d 4 4 1 A0 , double
  "
related:  prototypeof sizeof, offsetof, spanof, typeof, typecodeof, recordof, #recordof
group:    attributes
updated:  11/02/2025
.


key:      "encodingof  11"
action:   return the operand encoding of a variable or macro
use:      obtain data for diagnostics or reflective programming
example:  sys v
  print encodingof v 'example: [ebx+4100]
related:  prototypeof, sizeof, offsetof, spanof, typeof, typecodeof, recordof, #recordof
group:    attributes
updated:  11/02/2025
.


key:      "prototypeof  11"
action:   return prototype(s) of functions, subs and high level macros
use:      obtain data for diagnostics or reflective programming
related:  recordof, sizeof, offsetof, spanof, typeof, typecoedof, #recordof
group:    attributes
updated:  11/02/2025
.


key:      "typecodeof  11"
action:   return type code number of variables and literals.
use:      obtain data for diagnostics or reflective programming
example:  
  #if typecodeof(A) > 0
    #print "A type: " + typeof(A) ' int
  #endif
related:  typeof recordof, sizeof, offsetof, spanof, prototypeof, #recordof
group:    attributes
updated:  17/06/2022  
.


key:      "recordof    11"
action:   return record of compound (UDT) variable
use:      obtain data for diagnostics or reflective programming
example:  type vt long v,double d
  dim as vt v :  r=recordof v
result:   r="
  v 0 4 1 A0 , long
  d 4 4 1 A0 , double
  "
related:  #recordof prototypeof, sizeof, offsetof, spanof, typeof, typecodeof, #recordof
remarks:  use #recordof to display the record during compilation.
group:    attributes
updated:  11/02/2025
.


key:      "strptr 11"
action:   return a string pointer
use:      obtain base address of string contents
example:  string s="Hello"
  sys a=strptr s
related:  typecodeof, addr
group:    attributes
updated:  27/03/2017
.


key:      "lpartof 11"
action:   return left part of dotted name
use:      exract main part from dotted name
  for use in macros.
example:  lpartof(a.b.c).x 'returns a.x
related:  rpartof, vtypeof
group:    attributes
updated:  11/01/2021
.


key:      "rpartof 11"
action:   return mid part of dotted name
use:      exract part from dotted name, for use
  in macros.
example:  rpartof(a.b.c) 'returns b.c
related:  lpartof, vtypeof
group:    attributes
updated:  11/01/2021
.


key:      "vtypeof 11"
action:   return typename of variable
use:      refer to variable type , for use
  in macros.
example:   double a
  vtypeof(a) 'returns double
related:  lpartof, rpartof, sizeof
group:    attributes
updated:  11/01/2021
.


'===========================
'>>O2 KEYWORDS
'===========================




key:      "incl 13"
action:   expand macro non recursively without parameter substitutions
use:      incl aMacro   
example:  def helo "hello " %1
  incl helo
result:   substitution: "hello " %1
related:  def
group:    commands
updated:  11/02/2025
.

key:      "#semicolon 13"
action:   switch use of semicolon as comment marker or separator
use:      so semicolons can be recognised as separators when using C syntax
example:  #semicolon separator
  s="ok"  ; print s
  #semicolon comment
  print "ok" ; this is a comment
remarks:  #semicolon can be confined to a scope (function etc)
related:  #case, indexbase
group:    commands
updated:  11/02/2025
.

key:      "retn 13"
action:   macro ret n. Releases correct number of bytes at end of procedure (in stdcall convention)
use:      internal
example:  
related:  ret, return, function
group:    commands
updated:  10/01/2018
.



key:      "with 13"
action:   specify a variable name prefix for assignments
use:      Allows long names to be shortened when assigning values
example:  dim as vector4 vectorI
  with vectorI : .x=1 : .y=0 : .z=13 : .w=0 : end with
group:    commands
updated:  25/04/2018
.


key:      "o2 13"
action:   start a block of o2 machine code notation
use:      inserting inline machine code and other binary data.
  direct use of o2 language (used by the o2 linker)
example:  o2 b8 00 01 00 00 'machine code for mov eax,256
related:  Blocks
group:    commands
updated:  02/03/2017
.


key:      "bind 13"
action:   bind a list of procedures from a Dynamic Link Library (DLL)
use:      for low level (without protoype) calls to DLL functions.
  the first name is the one used in the program. The second is the name used in the DLL.
example:
  sys Kernel32
  kernel32=LoadLibrary "kernel32.dll"

  bind kernel32
  (
  GetExitCodeProcess GetExitCodeProcess   ; @8
  ExitProcess        ExitProcess          ; @4
  GetCommandLine     GetCommandLineA      ; @0
  GetModuleHandle    GetModuleHandleA     ; @4
  QueryPerformanceCounter QueryPerformanceCounter ; @4
  )
result:   the first column of keywords is recognised as procedure calls. A prototype may be attached
  to any of these keywords later. Otherwise the programmer must ensure that the parameters
  passed are a perfect match for each procedure call.
remarks:  Comments are supported - both semicolon and single quote marks.
related:  loadlibrary, freelibrary, getprocaddress, declare, library
group:    commands
updated:  11/02/2025
.  


key:      "enum 13"
action:   create an enumeration
use:      assign a numeric identity to a name
example:  
incfile1: demos\basics\Enumerations.o2bas

remarks:  C syntax is supported for this construct. Also <b>enum bit</b>
  assigns values 1,2,4,8,16.. instead of 0,1,2,3,4..
related:  typedef, enum, #define, (%)
group:    commands
updated:  16/06/2018  
.


key:      "def 13"
same:     #def
action:   define a low level macro
use:      
example: 
  'DEFINE MACRO:

  def Create
    dim as %1 %2
    %2.new("%2")
  end def

  'INVOKE MACRO

  create SomeClass SomeObject
  
  'EXPANDS TO:

  dim as SomeClass SomeObject
  SomeObject.new("SomeObject")
  '
  'CREATING UNIQUE SYMBOLS INSIDE DEF
  'BY USING %0 PREFIX
  int i=1
  def HiddenI
    int %0i
    i=21
    print i '21
  end def
  HiddenI
  print i '1
remarks:  often used in conjunction with macros and meta-language, 
related:  macro, #define, deff, #if, scope
group:    commands
updated:  11/03/2025
.


key:      "type 13"
action:   define a compound variable type
use:      
example:
  type rgbacolor
    red   as byte
    green as byte
    blue  as byte
    alpha as byte
  end type

  rgbacolor c
  c.red=100 : c.green=50 : c.blue=100

related:  typedef, struct, class
group:    commands
updated:  11/02/2025
. 


key:      "struct 13"
action:   define a compound variable type (C Syntax)
use:      
example:  
  struct rgbacolor
  {
    red   as byte
    green as byte
    blue  as byte
    alpha as byte
  }
related:  type, typedef, class
group:    commands
updated:  11/02/2025
.


key:      "class 13"
action:   define a class (strucure and methods for objects)
use:      
example:
  'DEFINE CLASS
  '  
  class rgbacolor
    '
    byte red,green,blue,alpha
    = 'union
    int c
    '
    function in(int r,g,b,a)
      red=r : green=g : blue=b : alpha=a
    end function
    '
    function color() as int
      return c
    end function
    '
  end class

  'INSTANTIATE

  dim rgbaColor c

  'CALL METHODS
  '
  c.in(100,200,100,128)
  print hex c.color()

remarks:  
  Classes are an extenstion of <b>type</b>. They may also contain their own
  equates, macros and static variables, accessable only within the class functions.
group:    commands
related:  Classes, type, new, del
updated:  02/05/2023
.


key:      "var 13"
action:   define a set of variables
use:      low-level dimensioning of variables
example:  var string s,t,u(64),v  
remarks:  var is normally only used internally. it accepts * for indirect variables
  and "at" for variable mapping. Arrays are also supported.
related:  dim
group:    commands
updated:  11/02/2025
.


key:      "include 13"
same:     #include
action:   include source code from another file
use:      used for including header files and other files of source code
example:  #include "rtl32.inc"
remarks:  include and #include are the same
related:  uses, includepath
group:    commands
updated:  24/03/2025  
.


key:      "use 18"
same:     uses
same:     using
action:   include source code from another file
use:      for including header files and other files of source code
example:  uses RTL32 'include once "RTL32.inc"
remarks:  use, uses, using are equivalent
related:  include, includepath
group:    commands
updated:  24/03/2025  
.


key:      "packed 13"
action:   prevent padding between members of a <b>type</b> or <b>typedef</b>
use:      allow programmer to have full control over padding to align the members
example:  
  packed type point
    word x,y,z
    dword color
  end type
  
  packed type point
    word x,y,z
    align 4
    dword color
  end type
remarks:  By default, the members will be aligned to a boundary matching their size.
related:  type, typedef, struct
group:    commands
updated:  20/06/2022
.


key:      "_def 13"
action:   define a low level system macro
remarks:  the <b>terminate</b>, <b>freelibs</b> and <b>freestatics</b> macros are specified in <b>RTL32.inc</b> and <b>RTL64.inc</b>
group:    commands
updated:  27/03/2017
.


key:      "includepath 13"
action:   define a filepath for source files specified by <b>include</b>.
use:      
example:  
related:  include, librarypath
group:    commands
updated:  11/02/2025
.


key:      "librarypath 13"
action:   define a filepath for DLL files
use:      tells the computer where to find Dynamic Link Libraries
  required to run the program. (System DLLs  do not require this.)
example:  
related:  library, extern, includepath
group:    commands
updated:  11/02/2025
.


key:      "#file 13"
action:   specifiy a filename for compiled code ( .EXE or .DLL )
use:      creates an executable <b>.EXE</b> or  Dynamic Link Library <b>.DLL</b> file
example:  #file FileName independent 64 bit
remarks:  only used in runtimes: rtl32.inc and rl64.inc
related:  
group:    commands
updated:  18/10/2022
.


key:      "quote 13"
action:   specify tagname for superquotes
use:      supports almost unlimited nesting of quotes. Can be used for containing
  embedded scripts which themselves use quotes and have different syntax.
example:  quote !!! this quote contains other quotes "containing "other quotes"   " !!!
related:  "    `
group:    commands
updated:  11/02/2025
.


key:      "typedef 13"
action:   define a set of types (C syntax)
use:      create type definitions for creating other types
example:
  typedef Double *pDouble

  'CREATE TYPES FROM ANONYMOUS STRUCT

  typedef struct
   {
     single x;
     single y;
     single z;
   } vector, *pVector;

   'CREATE VARIABLE

   vector v;

   v.x=42.01

   'FROM WINBASE.H:
   '
   typedef struct _OVERLAPPED {
       ULONG_PTR Internal;
       ULONG_PTR InternalHigh;
       union {
           struct {
       DWORD Offset;
       DWORD OffsetHigh;
           };

           PVOID Pointer;
       };

       HANDLE  hEvent;
   } OVERLAPPED, *LPOVERLAPPED;

related:  type, struct, class, union, enum
group:    commands
updated:  27/02/2017
.




key:      "union 13"
action:   define a union (C syntax)
use:      allows different variables to occupy the same space.
example:  
  union utype
  {
    byte  b
    short w
    long  i
  }


  utype v

  v.b=42
result:   v.b=42 : v.w=42 : v.i=42
remarks:  a union may also be nested inside a type.
related:  typedef, type, struct, class, enum
group:    commands
updated:  11/02/2025
.


key:      "#case 13"
action:   specify mode of case sensitivity.
use:      case can be <b>sensitive</b>, <b>insensitive</b>, or <b>capital</b>
example:   
  #case insensitive 'AbC is the same as 'aBC' and 'ABC'
  #case sensitive   'AbC and 'abc' are not the same
  #case capital     'AbC is the same as 'aBC' but not 'ABC'
remarks:  The default is 'insensitive'.
  #case has block scope and reverts to its previous state when
  the block ends.
related:  #semicolon, indexbase
group:    directives
updated:  27/03/2017
.



key:      "#lookahead 13"
action:   internally creates header declarations for all procedures.
use:      allows procedure calls to forward reference
example:  
  #lookahead
  ff "ok"
  '...
  sub ff(s as string)
    print s
  end sub

remarks:  
  procedures in inner blocks are ignored, so each block must
  have its own '#lookahead'
related:  scope
group:    directives
updated:  23/06/2022
.


key:      "#autodim 13"
action:   enable variables to be created without a Dim statement
use:      for mall, informal programs.
example:  #autodim on
related:  
group:    directives
updated:  24/04/2019
.


key:      "#alert 13"
action:   generates a compiler message (like an error)
use:      used to alert programmer about an area of code
  that requires attention
example:  #alert (please implement methods for this interface)
related:  #error, #print
group:    directives
updated:  16/06/2018
.


key:      "#error 13"
action:   generates a compiler error message
use:      used to alert programmer about inconsistencies
  that require attention.
example:  #error (please implement methods for this interface)
related:  #alert, #print
group:    directives
updated:  16/06/2018
.


key:      "#pragma 13"
action:   ignored (C style compiler directives)
use:      compilers use it for platform or compiler-specific mode changes
example:  #pragma warning(push)
related:  
group:    directives
updated:  11/02/2025
.


key:      "#unique 13"
action:   flags an error if a a symbol definition is not unique (in the same nesting level)
use:      prevent symbols from being redefined
example:  #unique enabled
  #unique disabled 'default
group:    directives
updated:  11/02/2025
.


key:      "#console 13"
action:   programs compiled to EXE/DLL will run in an existing console (MS Subsystem 3)
use:      prevents new console from being created. Inputs and outputs are with the existing console.
example:  #console
remarks:  When Oxygen is embedded it will use the Host's subsystem'
group:    directives
updated:  11/02/2025
.


key:      "#show 13"
action:   displays the translated code of a statement during compilation
use:      Allows the programmer to see a selected part of the compiled code
example:  sys a,b,c
  #show a=b+c 'display coding in a messagebox
   #show "s.txt" a=b+c 'save coding in file 's.txt'
related:  #view, view
group:    directives
updated:  02/03/2025
.


key:      "@ 51"
action:   return the address of a variable
use:      reading writing data of variables and arrays of variables, by reference
example:  int a=42
  print @a 'address of a
  int *b 'indirect (pointer) variable
  @b=@a   'coupled by address
  print b '42
remarks:  Unlike C, pointer resolution is handled implictly. So the <b>@</b> operator is required
  for manipulating pointers. It is similar to the <b>&</b> operator in C. 
related:  *, ?, strptr, addr
group:    operators
updated:  28/03/2017
.


key:      "* 51"
action:   return the integer value located by the address contained in the variable
use:      reading writing data, using pointers
example:  int a=42
  print @a 'address of a
  sys b    'sys' ensures an integer large enough to hold a pointer
  b=@a     'assin address of a to b
  print *b '42
remarks:  Unlike C, pointer resolution is normally handled implictly. 
related:  @, ?, strptr, addr
group:    operators
updated:  28/03/2017
.


key:      "? 51"
action:   return the integer value contained in the variable
use:      casting variables as integers
example:  float f=100
  print hex(?f) 'display the hexadecimal form of float f
remarks:  
related:  cast, *, @, strptr, addr
group:    operators
updated:  28/03/2017
.


key:      "addr 13"
action:   resolve address of a variable (assembler)
use:      load address of a variable to a register
example:  sys a
  addr ecx,a
related:  @, *, ?, strptr
group:    directives
updated:  27/03/2017
.


key:      "cast 51"
action:   change or specify the type of a variable temporarily, in an expression
use:      
example:  float f=100
  print hex( cast(int) f) 'display the hexadecimal form of float f
  print hex( (int) f )    'the same without using the 'cast' word
remarks:  
related:  convert, ?, union
group:    operators
updated:  28/03/2017
.


key:      "convert 51"
action:   explicitly convert the type of an expression.
use:      pass values, in the required type, to an unprototyped function
example:  float f=2.5
  sleep ( convert int ( f*1000 ) )
remarks:  
related:  cast
group:    operators
updated:  28/03/2017
.


key:      "#compact 13"
action:   remove unused code
use:      minimise size of compiled binaries
example   #compact on
remarks:  removes unused methods from classes, as well as unused general functions.
related:  #file
group:    directives
updated:  28/03/2017
.


'===========================
'>>OXYGEN KEYWORDS
'===========================

key:      "let 14"
action:   defines a variable or object
use:      create a new variable or indirect object
example:  
  let s="Hello World"
  print typeof s 'result: 'string'
related:  dim, var
remarks:  Similar to using 'dim' but the type is inferred from the assigned value.
group:    structures
updated:  10/02/2025 
.



key:      "const 14"
action:   create read-only variables
use:      constants
example:
  const int a=40, b=60
  const float f[]={ 1, 1.5, 2, 2.5, 3.0 }  
  const as string s="HelloWorld"
remarks:   
related:  dim, #unique
group:    keywords
updated:  23/06/2022
.


key:      "dim 14"
action:   define a set of one or more variables
use:      create variables and arrays of variables with optional initial values
example:  
  dim as string s="Hello World"
  dim int i(100)
  dim float yx[480,640]
  dim as string s[]<=( "one","two","three" )
  dim as string s[]<={ "one","two","three" }
  dim as string s={ "one","two","three" }
  dim as string s={ "one","two","three" }
  dim c as char*10  'c(10)
  dim c(10) as char*16 'c(10,16)
  '
  'C style:
  '
  int a[1000,2]
  int a[]={2,4,6,8}
  int a={2,4,6,8}
remarks:  A variety of dim expressions to support various coding styles
related:  local, static, redim, let, var, const,type, indexbase
group:    keywords
updated:  10/02/2022
.


key:      "local 14"
action:   define a local set of variables
example:
  local string s
  dim local string t
related:  dim, static
group:    keywords
updated:  30/09/2022
.


key:      "static 14"
action:   define a static set of variables, (persistant but invisible outsid the block)
example:  
  static string s
related:  dim, local
group:    keywords
updated:  30/09/2022
.


key:      "! 14"
action:   declare a procedure with its prototype (may be external or declared in advance)
example:  
  ! fun(float a,b,c,d) as float
  ! function fun(float a,b,c,d) as float
remarks:  There is a wide range of options for Declare statements. Please look at the examples and header files.
related:  declare, library, lib, alias, dim
group:    keywords
updated:  24/02/2017
.


key:      "declare 14"
action:   declare a procedure with its prototype (may be external or declared in advance)
example:  
  declare fun(float a,b,c,d) as float
  declare function fun(float a,b,c,d) as float
remarks:  There is a wide range of options for Declare statements. Please look at the examples and header files.
related:  !, library, lib, alias, dim
group:    keywords
updated:  11/02/2025
.


key:      "function 14"
action:   define a function
example:  
  function triple(i as int) as int
    return i*3
  end function
  print triple(5) '15
  '
  function triple(i as int=1) as int
    return i*3
  end function
  print triple(4) '12 'using specified value
  print triple()  '3  'using default nalue
remarks:  
related:  Procedures, sub, method, subroutine
group:    procedures
updated:  11/02/2025
.


key:      "sub 14"
same:     procedure
action:   define a procedure. (like a function but not returning a value)
example:  
  sub triple(j as int ptr)
    j=i*3
  end sub
  int v=3
  triple(v) '9
remarks:
related:  Procedures, function, method, subroutine
group:    procedures
updated:  11/02/2025
.


key:      "method 14"
action:   
use:      define a procedure for objects.
example:  
  method triple(int i) as int
    return i*3
  end method
remarks:  Any function or sub defined inside a 
  class/methods block are treated as methods
  of the class, unless it is 'static'
related:  Procedures, function, sub, methods, subroutine
group:    procedures
updated:  11/02/2025
.


key:      "subroutine 14"
action:   define a subroutine block (for gosub)
example:
  subroutine triple
    j*=3
    'exit subroutine
  end subroutine
  '
  j=12 : gosub triple '36
  '
remarks:  A more structured and  scoped target for gosub. 
related:  labels, Procedures, function, method
group:    procedures
updated:  11/02/2025
.



key:      "operator 14"
action:   define a customised operator
use:      for operations between objects and other user defined types
example:  
  operator max 1 'name and precedence level
  '
  type hInt int v
  '
  macro hInt_"move"(a,b)
    a.v=b.v
  end macro
  macro hInt_"max"(acc,a,b)
    if b.v>a.v
      acc.v=b.v
    else
      acc.v=a.v
    endif
  end macro
  '
  hInt a,b,c,d
  a.v=1 : b.v=10 : c.v=-10
  d=a max b max c
  print d.v '10

related:  type, class, macro
group:     operators
updated:  11/02/2025
.


key:      "if 14"
action:   start a conditional block with a test
use:      conditional execution
example:  
  'single liner
  if a<b then a=b
  '
  'block ('then' is optional)
  if a<b
    a=b
  endif
related:  Conditionals, then, else, elseif, endif, while
group:    control structures
updated:  23/06/2022
.


key:      "then 14"
action:   starts the conditional block where the prior test is met.
use:      conditional execution
example:  
  'single line
  if a>b then print a
  '
  'multi-line
  if a>b then
    print a
  endif       
remarks:  'then' is optional in mult-line blocks
related:  Conditionals, if, elseif, endif
group:    control structures
updated:  23/06/2022
.


key:      "else 14"
action:   starts the alternative block where none of the prior conditions are met
use:      conditional execution
example:  
  'single line
  if a>b then print a else print b 
  '
  'multi-line
  if a>b
    print a
  else
    print b
  endif
related:  Conditionals, if, elseif, endif
group:    control structures
updated:  23/06/2022
.


key:      "elseif 14"
action:   make an alternative test if the previous condition was not met.
use:      conditional execution
example:
  if a<=0
    'do nothing  
  elseif a>b
    print a
  else
    print b
  endif
related:  Conditionals, if, else, endif select, case
group:    control structures
updated:  23/06/2022
.


key:      "endif 14"
same:     end if
action:   end the conditional block
use:      conditional execution
example:  
  if a>b then
    a=b
  endif
related:  Conditionals, if, then, elseif, else, end if
group:    control structures
updated:  23/06/2022
.



key:      "endselect 14"
same:     end select
action:   end the select block
use:      
example:  
related:  Selection, select, switch, case
group:    control structures
updated:  12/09/2022
.


key:      "do 14"
action:   start a block for repetition (looping)
use:      
example:  
  a=0
  do
    '...
    a+=1 : if a=4 then exit do
  loop
result:   a=4 '4 loops
related:  Loops, while, continue, exit, enddo, loop
group:    control structures
updated:  23/06/2022
.


key:      "while 14"
action:   start a block for conditional repetition
use:      
example:  
  a=0
  while a<4
    a+=1
  wend
result:   a=4 '4 loops
remarks:  <b>while</b> is a combination of <b>do</b> and <b>if</b>.
related:  Loops, do, continue, exit, wend, enddo
group:    control structures
updated:  23/06/2022
.


key:      "loop 14"
same:     end do, enddo
action:   end a <b>do</b> repeating block 
related:  Loops, do, continue, exit
group:    control structures
updated:  12/01/2021
.

key:      "repeat 14"
same:     redo, continue
action:   goto the beginning of a do/while block 
related:  Loops, do, continue, exit
example:
  '
  do
    if a>b
      repeat do
      'same as continue do
    else
      exit do
  loop
  '
  'conditional repeating
  do
    ...
    repeat while a>b
    repeat when a>b
    repeat until a>b
    repeat if a>b
    exit loop
  loop
  '
  'structured assembler repeat
  (
   ...
   dec ecx
   jle exit
   repeat
  )
related:  exit, do, while, if, for
group:    control structures
updated:  21/06/2022
.


key:      "enddo 14"
same:     end do, loop
action:   end a <b>do</b>  repeating block 
related:  Loops, while, do, loop, continue, exit
group:    control structures
updated:  12/01/2021
.


key:      "endwhile 14"
key:      "wend 14"
same:     end while
action:   end a <b>while</b> block
related:  Loops, do, while, continue, exit
group:    control structures
updated:  12/01/2021
.


key:      "exit 14"
action:   exit a <b>do</b>  <b>while</b> <b>for</b>  <b>(...)</b> block immediately
use:      leave a loop, usually after a condition has been met
example:  
  a=0 : b=1
  do
    a+=1
    if a>4 then exit do
    b+=b
  end do
  '
  'conditional exit
  do
    ...
    exit when a>b
    exit if a>b
  loop
  '
  'structured assembler exit
  (
   ...
   dec ecx
   jle exit
   repeat
  )
related:  Loops, do, while, continue, repeat
group:    control structures
updated:  21/06/2022
.


'itr: exit 2 exit 3 repeat 2


key:      "continue 14"
action:   go back to the beginning of a <b>do</b>, <b>while</b> or <b>for</b> block
use:      to "short circuit" a loop
remarks:  <b>continue do</b> and <b>continue while</b> will loop back to the
  nearest <b>do</b> or <b>while</b> at the same nesting level.

  <b>continue for</b> will jump to the iterator stepper before looping back.
related:  Loops, do, while, for, break, exit, wend, enddo, repeat
group:    control structures
updated:  03/01/2018
.


key:      "break  14"
action:   exit a switch block or do/while block
related:  case, switch, while, do, continue
group:    control structures
updated:  02/01/2018 
.


key:      "switch 14"
key:      "select 14"
action:   Start a Case block (C style)
use:      
example:  
related:  Selection, case, endselect, end
group:    control structures
updated:  12/09/2022
.


key:      "case 14"
action:   specify a case to match followed by actions to perform
use:      
example:  
related:  Selection, select, endselect, end
group:    control structures
updated:  12/09/2022
.


key:      "for 14"
action:   start an iteration block
use:      
example:  
related:  Iteration, to, step, next
group:    control structures
updated:  24/02/2017
.


key:      "to 14"
action:   specify limit of an iteration
use:      
example:  
related:  Iteration, for, step, next
group:    control structures
updated:  24/02/2017
.


key:      "step 14"
action:   specify increment of an iteration
use:      for iterator = start to end step step increment
example:  for i=1 to 10 step 2 : ... : next
result:   i increeases by 2 with each cycle : 1 3 5 7 9
comments: step can be omitted, a step of 1 is then assumed.
  a negative step can also be used for down counting.
related:  Iteration, for, to, next
group:    control structures
updated:  24/02/2017
.


key:      "next 14"
action:   end iteration block
use:      
example:  
related:  Iteration, for, to, step
group:    control structures
updated:  24/02/2017
.


key:      "foreach 18"
action:   iterates operations for elements of an array.
use:      compact iteration statements   
example:  
  dim string s[100]
  foreach s { s[i]=space(16) }
remarks:  The operation is applied to all elements from 
  lound(a) to ubound(a). 'i' is a scoped index variable 
  which does not affect previously defined variables named 'i'.
related:  Iteration, for, to, step, next
group:    macros
updated:  02/03/2025
.


key:      "goto 14"
action:   jump to a specified label in the code
use:      go to to another part of the program
example:  
  if a>b then goto ending
  ...
  ending:
  print "Done"
  '
  'It is also possile to 'goto' an absolute address stored in a variable
  sys ad=@aa 'address of aa
  goto ad
  ...
  aa:
remarks:  Use this command with care, so that your code remains readable
  and easy to maintain.
related:  jmp, gosub
group:    control structures
updated:  02/03/2025
.


key:      "gosub 14"
action:   call a labelled subroutine
use:      invoke subroutines inside a procedure
example:
   'gosub a label
   function f() as int
     gosub report
     exit function
     report:
     print "complete"
     ret
   end function
   '
   'gosub a subroutine
   function f() as int
     gosub report
     exit function
     subroutine report
       print "complete"
     end subroutine
   end function
incfile1: demos\basics\Gosub.o2bas
remarks:  Always exit subroutines with 'ret'
related:  Procedures, subroutine, call, goto
group:    procedures
updated:  02/03/2025
.


key:      "subroutine 14"
action:   define a subroutine
use:      formally define subroutines inside a procedure
example:
  procedure pr(int i)
    gosub xx
    print "ending pr"
    '
    subroutine xx
      if i<1
        exit subroutine
      endif
      print i
    end subroutine
  end procedure
remarks:  subroutines always terminate with 'end subroutine'
related:  Procedures ,gosub, call, goto
group:    procedures
updated:  15/05/2023
.


key:      "on 18"
action:   on x goto / gosub / call { list }
use:      branch to an address using a list of locations
example:
  procedure f(int isr)
    subroutine sr1
      ...
    end subroutine
    subroutine sr2
      ...
    end subroutine
    subroutine sr3
      ...
    end subroutine
    '
    on isr gosub {@sr1,@sr2,@sr3}
    '
  end procedure
remarks:  lists of up to 128 suroutines are supported
related:  Procedures ,subroutine, label, gosub, call, goto
group:    macro
updated:  02/03/2025
.


key:      "methods 14"
action:   start a methods block for a class of objects.
use:      
example:  
related:  method, class
group:    structures
updated:  11/02/2025
.


key:      "return 14"
action:   exit from a procedure returning a value (in a function or method)
use:      
example:  float product(float a,b) { return a*b }
related:  Procedures, ret
group:    procedures
updated:  24/02/2017
.


key:      "% 14"
key:      "$ 14"
action:   define an equate
use:      as a single-line macro
example:
  '$' can be used instead of '%'
  '=' is optional
  % green = 0x00ff00
  % green 0x00ff00
  % BigPhi 1.618033
  % compiler "OxygenBasic"
  print compiler
  '
  'SPECIALISED EQUATES
  '
  '%=' precalculate 
  %  mol 42
  %= hmol mol*0.5 'stored as 21
  '
  '%*' iterative
  %* ResetNum %1=0  :
  %* ResetStr %1="" :
  int a,b,c,d
  string s,t,u,v
  ResetNum a,b,c,d  'a=0 : b=0 : ...
  ResetStr s,t,u,v  's="" : t="" : ...
  '
  'USE FOR PREFIXES
  '
  % ad Antediluvian
  ad.X 'AntediluvianX'

remarks:  Equates can be used instead of constants  
related:  Equates, Macros, #define. #def. def,deff
group:    macros
updated:  30/08/2022
.


key:      "intern 18"
action:   define a block to go inside a class methods block
use:      provide a block for class private functions etc
example:  
  class cc
    float a
    intern
      float hp=0.5*pi() 'only visible to functions of the class
    end intern
    function m() as float
      return a*hp
    end function
  end class
related:  Blocks, class, methods, scope
group:    structures
updated:  03/05/2023
.


key:      "scope 14"
action:   start a scope
use:      create a block where variables and functions may be locally defined
example:  :
incfile1: demos\basics\scope.o2bas
remarks:  when the scope ends any definitions created within the scope will
  be forgotten. The compiler   will dump all symbols created inside the scope.
  This promotes compiler efficiency.
related:  Blocks, namespace
group:    structures
updated:  11/03/2025
.


key:      "module 18"
action:   define a module block
use:      create a block of deployable code
example:  
  ===============
  module 'console
  ===============
    namespace cons
    uses console 'inc\console.inc'
    end namespace
    '
    interface
    ---------
    $ cprint  cons::output 
    $ cwait   cons::getkey
    $ tab     cons::tab
    $ cr      cons::cr
  end module
  '
  cprint 12345 tab "okay" cr
  cwait

remarks:  
  'Module' is currently a null definition. It can be redefined
  in macro form to generate custom code. To customize
  'end module' create a macro called module_end'.
related:  interface, namespace
group:    structures
updated:  24/03/2025
.


key:      "interface 18"
action:   mark the start of shared code
use:      define shareable code in a module
example:  
  'Interface' is currently a null definition.
  It can be redefined  in macro form to generate
  custom code.
related:  module, namespace
group:    structures
updated:  29/08/2022
.


key:  "namespace 13"
action:   create a namspace
use:      create a region where symbols are locally defined
example:
  '
  'SIMPLE NAMESPACE
  dim int x=1
  namespace a
    dim int x=21
  end namespace
  print x '1
  print a..x '21
  '
  'NESTABLE NAMESPACES
  dim int x=1
  namespace a
    dim int x=21
    namespace b
      namespace c
        print x '21
        dim int x=56
      end namespace
    end namespace
    print x '21
  end namespace
  '
  namespace a::b::c
    print x '56
  end namespace
  '
  print a::b::c::x '56
  print a::x '21
  print x '1b
remarks:  Namespaces allow blocks of code to be ported
  from one program to another without causing symbol conflicts.
related:  scope, macro, def, module
group:    structures
updated:  24/03/2025
.


key:      "indexbase 14"
action:   define the index base for an array
use:      most software assumes an indexbase of 0 or 1
example:  indexbase 0
remarks:  the default indexbase is 1 but C code normally assumes 0.
  If the indexbase is defined inside a scope, such as a function then it
  only applies within the scope and reverts to its previous value outside the scope.
related:  dim, #case, #semicolon
group:    directives
updated:  22/03/2017 
.


key:      "#majorminor 14"
action:   sets storage order for arrays
use:      row-major array compatibility
example:  
  #majorminor
  dim int yx[768,1024] 'y rows, x columns
remarks:  This is the default mode for multidimensional arrays
related:  #minormajor, indexbase, dim
group:    directives
updated:  30/09/2022
.


key:      "#minormajor 14"
action:   sets storage order for arrays
use:      column-major array compatibility
example:  
  #minormajor
  dim int xy[640,480] 'minor first
remarks:  
related:  #majorminor, indexbase, dim
group:    directives
updated:  30/09/2022
.


key:      "lib 14"
key:      "library 14"
action:   specify the name of a DLL library to associate
          with a set of procedure declarations
use:      
example:  lib "kernel32.dll"
related:  declare
group:    directives
updated:  11/02/2025
.


key:      "extern 14"
action:   associate declared procedures with a calling convention and/or dll name
use:      
example:  
  extern stdcall lib "kernel32.dll"
    declare function QueryPerformanceCounter(lpPerformanceCount as quad) as sys
    declare function QueryPerformanceFrequency(lpPerformanceFrequency as quad) as sys
  end extern
remarks:  
  note ther is no need to use an Alias in these declarations if you give the exact name
  of the procedures in their original case.
related:  lib, library, calling_conventions
group:    linkage
updated:  17/06/2022
.


key:      "that 14"
action:   suppress automatic "this" prefix inside OOP methods
use:      resolving name conflict between an object member and another variable
example:  this.voice=that voice
  voice=that voice
related:  method, this
group:    Objects
updated:  11/02/2025
.


key:      "this 14"
action:   explicitly refer to an object's own members
use:      distinguish a member from a local variable, param or function of the same name
example:  this.len=len(s)
incfile1: OOP\features\ThisThat.o2bas
related:  method, class, that
group:    Objects
updated:  11/02/2025
.


key:      "#noprec 14"
action:   directive to evaluate an expression from left to right, ignoring standard operator precedence rules.
use:      
example:  
related:  #noinit, indexbase, #byref, #byval, #assign
group:    directives
updated:  04/05/2019
.


key:      "#noinit 14"
action:   prevent variables from being automatically initialised to nul within a procedure
use:      
example:  
related:  #noprec, #byref, #byval, #assign, indexbase
group:    directives
updated:  04/05/2019
.


key:      "#byval 14"
action:   pass parameter by value (not by its address)
use:      
example:  
related:  #byref, #noinit, #noprec, #assign, indexbase
group:    directives
updated:  04/05/2019
.


key:      "#byref 14"
action:   pass parameter using its address instead of its value
use:      
example:  
related:  #byval, #noinit, #noprec, #assign, indexbase
group:    directives
updated:  04/05/2019
.


key:      "#assign 14"
action:   '=' always to be an assignment operator in conditional statements
use:      emulate the C convention for the '=' operator
example:  #assign on
  if hresult=QueryInterface(gu,ob) then ...
related:  #byref, #byval, #noinit, #noprec, indexbase
group:    directives
remarks:  when #assign is active then '==' must always be used to test equality
updated:  04/05/2019
.


key:      "deff 14"
action:   create an assembly code macro for the FPU  (metatype -17)
use:      to create floating point maths functions
example:  deff sine fsin
remarks:  Deff macros make use of the FPU. All float functions are defined this way.
  These are non-recursive macros and take no macro arguments. The expression parser is FPU- 
  aware and takes care of passing parameters onto the FPU stack.
related:  Macros, def, #define, macro, sin, cos 
group:    macros
updated:  24/02/2017
.


'============
'METACOMMANDS
'============


key:      "#if 13"
action:   include block of code if conditions are met
use:      
example:  
related:  #else, #elseif, #endif
group:    meta
updated:  08/02/2018
.


key:      "#else 13"
action:   alternative block of code to include if prior conditions are not met.
use:      
example:  
related:  #if, #elseif, #endif
group:    meta
updated:  08/02/2018
.


key:      "#endif 13"
action:   end of conditional code inclusion block
use:      
example:  
related:  #if, #elseif
group:    meta
updated:  08/02/2018
.


key:      "#elseif 13"
action:   include block of code if these alternative conditions are met
use:      
example:  
related:  #if, #else, #endif, #fi
group:    meta
updated:  08/02/2018
.


key:      "#define 13"
action:   define a macro (C syntax)
use:      C preprocessor statements
example:  #define X 32
related:  Macros, macro, def, #ifdef, #ifndef
group:    meta
updated:  24/02/2017
.


key:      "#ifdef 13"
key:      "#ifndef 13"
action:   include code if symbol already defined
use:      to allow blocks of code to be included or omitted at compile time
example:  #ifdef MSWIN
    #include "windows.inc"
  #endif
related:  #if, #elseif, #endif
group:    meta
updated:  08/02/2018
.


key:      "undef 13"
same:     #undef
same:     #undefine
action:   remove a previously defined symbol
use:      remove access to private symbols in a module.
example:  
  undef a,b,c,d
remarks:  will not work for procedures or labels.
related:  scope #define, def, deff, dim
group:    meta
updated:  23/06/2022
.


key:      "macro 13"
action:   define a high level macro
use:      many uses. Often a pseudo function for producing
  inline code instead of a call
example:  
incfile1: demos\basics\Macros.o2bas
related:  macros, #define, #def, def, deff
group:    macros
updated:  16/06/2018
.


key:      "#print 13"
action:   display a constant expression during compilation
use:      Compile time diagnostics.
example:  #print "not implemented"
related:  #recordof, #if, #alert, #error
group:    meta
updated:  16/06/2018
.

key:      "#blockdepth 13"
action:   return block nesting depth.
use:      to checking block depth at compile time.
example:  #blockdepth node x 'use any descriptive label on the line
remarks:  this command was introduced to catch unclosed blocks which
  are often hard to trace.
related:  scope, #recordof
group:    meta
updated:  
.


key:      "#recordof 13"
action:   return internal record of a declared entity.
use:      to check status at compile time.
example:  #recordof MyStructure
remarks:  this command was introduced to aid debugging at compile time
  are often hard to trace.
related:  #blockdepth
group:    meta
updated:  11/02/2025
.


'================================
'primitives (Basic and C style
'================================


key:  "void      15"
action:   
use:      specify a null type
example:  'Variables:
  void * pv = getmemory(100 * sizeof float)
  ...
  freememory pv
  '
  'In function headers:
  function foo(byref v as void) as void ptr
  void* foo(void*v)
  
  'Procedures not returning a value:
  void foo()
  '
remarks:  Void cannot be used directly.
related:  sys, any, types
group:    primitive types
updated:  15/02/2018
.

key:  "sbyte     15"
action:   
use:      specify a signed byte type (8 bits wide)
example:  sbyte x=-10
remarks:  limited to values ranging from -128 to 127 / 0x80 to 0x7F
related:  types
group:    primitive types
updated:  05/04/2017
.


key:  "byte     15"
action:   
use:      specify a byte type (8 bits wide)
example:  byte colon=58
remarks:  limited to values 0..255 / 0x00 to 0xFF
related:  types
group:    primitive types
updated:  05/04/2017
.


key:  "ubyte     15"
action:   
use:      specify a byte type (8 bits wide)
example:  ubyte semicolon=59
remarks:  limited to values 0..255 / 0x00 to 0xFF
related:  types
group:    primitive types
updated:  05/04/2017
.


key:  "string    15"
action:   
use:      specify a string type with 8-bit characters
example:  string s="name: "
remarks:  strings are automatically destroyed when out of scope.
related:  wstring, types
group:    primitive types
updated:  05/04/2017
.


key:  "wstring   15"
action:   
use:      specify a string type with 16-bit characters, supporting unicode
example:  wstring sw
  getfile "greek.txt",sw
remarks:  strings are automatically destroyed when out of scope.
related:  unic, types
group:    primitive types
updated:  05/04/2017
.

key:  "bstring   15"
action:   
use:      specify a bstring type with 8-bit characters
example:  bstring s="name: "
  ...
  frees s
remarks:  bstrings must be freed before going out of scope.
related:  wbstring, types
group:    primitive types
updated:  05/04/2017
.


.

key:  "bstr      15"
action:   
use:      specify a bstring type with 8-bit characters
example:  bstr s="name: "
  ...
  frees s
remarks:  bstrings must be freed before going out of scope.
related:  wbstring, types
group:    primitive types
updated:  05/04/2017
.


key:  "wbstring  15"
action:   
use:      specify a bstring type with 16-bit characters, supporting unicode
example:  wbstring sw
  getfile "greek.txt",sw
  ...
  frees sw
remarks:  bstrings must be freed before going out of scope.
related:  bstring, types
group:    primitive types
updated:  22/06/2019
.


key:  "char      15"
action:   
use:      specify a string of ascii characters (8 bits wide)
example:  char w="world"
  char buf[1024]
  buf=w
  print "hello "+buf
remarks:  similar to <b>C</b> char, but is not conflated with <b>byte</b> which is a numeric type
related:  wchar, types
group:    primitive types
updated:  05/04/2017
.


key:  "wchar     15"
action:   
use:      specify a string of wide characters (16 bits wide)
example:  wchar w="world"
  wchar buf[1024]
  buf=w
  print buf
remarks:  
related:  char, types
group:    primitive types
updated:  05/04/2017
.



key:  "asciiz    15"
action:   
use:      specify a string of ascii characters (8 bits wide)
example:  asciiz w="world"
  asciiz buf[1024]
  buf=w
  print "hello "+buf
remarks:  similar to <b>C</b> char, but is not conflated with <b>byte</b> which is a numeric type
related:  wchar, types
group:    primitive types
updated:  05/04/2017
.


key:  "zstring   15"
action:   
use:      specify a string of ascii characters (8 bits wide)
example:  zstring w="world"
  zstring buf[1024]
  buf=w
  print "hello "+buf
remarks:  similar to <b>C</b> char, but is not conflated with <b>byte</b> which is a numeric type
related:  wchar, types
group:    primitive types
updated:  05/04/2017
.


key:  "wzstring  15"
action:   
use:      specify a string of wide characters (16 bits wide)
example:  wzstring w="world"
  wzstring buf[1024]
  buf=w
  print buf
remarks:  
related:  char, types
group:    primitive types
updated:  22/06/2019
.


key:  "short     15"
use:      specify a short integer (16 bits wide). Also used in conjunction
  with other types to halve the bit width
example:  short a
  short int b
  short short c 'an sbyte
remarks:  
related:  long, types
group:    primitive types
updated:  05/04/2017
.


key:  "wide      15"
use:      specify a wide character string (16 bits wide). Also used in conjunction
  with other types to double the bit width
example:  wide s
  wide char sw
  wide float fw 'a double precision float
remarks:  
related:  short, types
group:    primitive types
updated:  05/04/2017
.


key:  "long      15"
use:      specify a long integer (32 bits wide). Also used in conjunction
  with other types to double the bit width
example:  long i
   long sbyte w  'a 16 bit integer
  long char sw  'a wchar character
  long float fw 'a double precision float
remarks:  
related:  short, types
group:    primitive types
updated:  05/04/2017
.


key:  "int       15"
use:      specify a long signed integer (32 bits wide)
example:  int i=0x7fffffff
remarks:  
related:  dword, types
group:    primitive types
updated:  05/04/2017
.


key:  "integer   15"
use:      specify a long signed integer (32 bits wide)
example:  integer i=0x7fffffff
remarks:  
related:  dword, types
group:    primitive types
updated:  05/04/2017
.


key:  "float     15"
use:      specify a floating point variable (32 bits wide)
example:  float f=1/100
remarks:  same as single
related:  single, double, extended, types
group:    primitive types
updated:  30/12/2017
.


key:  "single    15"
use:      specify a floating point variable (32 bits wide)
example:  single f=1/100
remarks:  same as float
related:  float, double, extended, types
group:    primitive types
updated:  30/12/2017
.


key:  "double    15"
use:      specify a double precision floating point variable (64 bits wide)
example:  double f=1/3
remarks:  
related:  single, float, extended, types
group:    primitive types
updated:  30/12/2017
.


key:  "extended  15"
use:      specify an extended precision floating point variable (80 bits wide)
example:  extended e=1/3
remarks:  this type holds the full precision of the pentium floatin point processor (FPU)
related:  single, float, double, types
group:    primitive types
updated:  30/12/2017
.


key:  "quad      15"
use:      specify a double precision signed integer (64 bits wide)
example:  quad q
remarks:  In a 64 bit system, these are processed directly on the CPU.
  In a 32 bit system, quads are passed to the FPU for processing
related:  qword, int, short, sbyte types
group:    primitive types
updated:  30/12/2017
.


key:  "word      15"
use:      specify a short unsigned integer (16 bits wide)
example:  word w=0xA000
remarks:  
related:  short, int, dword, types
group:    primitive types
updated:  30/12/2017
.


key:  "dword     15"
use:      specify a long unsigned integer (32 bits wide)
example:  dword ui=0xA0000000
remarks:  
related:  word, long, int, quad, types
group:    primitive types
updated:  30/12/2017
.


key:  "ulong     15"
use:      specify a long unsigned integer (32 bits wide)
example:  ulong u=0xA0000000
remarks:  same as uint  
related:  uint, word, types
group:    primitive types
updated:  30/12/2017
.


key:  "uint      15"
use:      specify a long unsigned integer (32 bits wide)
example:  uint u=0xA0000000
remarks:  same as dword and ulong  
related:  dword, word, byte, types
group:    primitive types
updated:  30/12/2017
.


key:  "qword     15"
use:      specify a 64 bit operand in assembly code
example:  fld qword d
remarks:  Only used in assembly code, not Basic.
related:  integer, quad, types
group:    primitive types
updated:  05/04/2017
.


key:  "any       15"
use:      specify a parameter of uncertain type, nominally a signed integer of system width (32/64 bits wide)
example:  function f(any*a) {...}
remarks:  Parameter of any type may be passed by-reference. Like C <b>void*</b>.
related:  sys, types
group:    primitive types
updated:  05/04/2017
.


key:  "sys       15"
use:      specify a signed integer of system width (32/64 bits wide)
example:  sys i=42
remarks:  this type is always wide enough to hold a pointer.
related:  any, int, quad, types
group:    primitive types
updated:  30/12/2017
.


key:  "bool      15"
use:      specify a variable to hold Boolean true/false states
example:  bool t=true
  if not t then ...
remarks:  Notionally a Boolean type, but in reality. it is a 32bit signed integer, as in <b>C</b>  
related:  any, types
group:    primitive types
related:  boolean, int, types
updated:  30/12/2017
.


key:  "boolean   15"
use:      specify a variable to hold Boolean true/false states
example:  boolean t=true
  if not t then ...
remarks:  Notionally a Boolean type, but in reality. it is an sbyte (8 bit signed integer  
related:  bool, byte, int, any, types
group:    primitive types
related:  boolean, types
updated:  30/12/2017
.


key:      "signed 15"
action:   specifies the type to be of signed integer
use:      signed type variable
example:  signed int v
result:   a signed int (long) called v is created.
related:  unsigned, int, long, types
group:    primitive types
updated:  30/12/2017
.


key:      "unsigned 15"
action:   specifies the type to be of positive numbers only
use:      unsigned type variable
example:  unsigned long v
result:   an unsigned long (dword) called v is created.
related:  signed, long, word, dword, types
group:    primitive types
updated:  30/12/2017
.


key:  "types "
members:  void, sbyte, ubyte, byte,
          string, wstring, bstring, bstr, wbstring, char, wchar,
          asciiz, zstring, wzstring,
          short, wide, long,int, integer,float, double,
          extended, quad, word, dword,
          ulong, uint, qword, any, sys, boolean, bool
keylinks: yes
use:      to specify the types of variables and create them
example:  int x
  dim as int x
  dim x as int
  var int x
group:    primitive types
related:  type, class, typedef, struct
updated:  05/02/2026
.


'===========================================
'>>CORE INTEGER AND STRING FUNCTIONS
'===========================================



key:      "news 16"
action:   allocates a bstring of null characters given the length in bytes
use:      bstring=news length
example:  
  b=news 1000
  '...
  frees b
result:   b contains address of a string of 1000 nul characters . Then the sting is freed
remarks:  Oxygen strings are automatically freed but Bstrings must be explicitly freed when no longer needed.
related:  frees, nuls, space, bstring, getmemory
group:    memory functions
updated:  11/02/2025
.


key:      "frees 16"
action:   deallocates a bstring
use:      frees bstring freememory
example:  b=news 1000
  '...
  frees b
result:   b contains address of a string of 1000 nul characters . Then the sting is freed
remarks:  Oxygen strings are automatically freed but Bstrings must be explicitly freed when no longer needed.
related:  news nuls, freememory, getmemory
group:    memory functions
updated:  11/02/2025
.


key:      "error 16"
action:   returns a string containing the most recent compile or runtime errors (cleared at start of compiling)
use:      to trap runtime errors
example:  string e=error
  if e then print e : 'followied by exit procedures
result:   displays the last error, if it exists.
remarks:  the error buffer is automatically cleared after using this function.
related:  #error, #alert
group:    string functions
updated:  11/02/2025
.


key:      "nuls 16"
action:   returns the address of a string of null characters given the length.
use:      string=nuls length
example:  s=nuls 1000
result:   s is a string of 1000 null characters
remarks:  for wide strings use string(n,wchr 0) instead
related:  space, string, news, frees, getmemory
group:    string functions
updated:  11/02/2025
.



key:      "val 16"
action:   returns numeric value of string
use:      value=val string
example:  v=val "2.5"
result:   v=2.5
related: str hex asc
group:    string functions
updated:  11/02/2025
.


key:      "ltrim 16"
action:   returns string with white space on the left trimmed off
use:      string=rtrim(string)
example:  s=ltrim "   abc"
result:   s="abc"
related:  rtrim, space, str, lcase, ucase
group:    string functions
updated:  11/02/2025
.


key:      "rtrim 16"
action:   returns string with white space on the right trimmed off
use:      string=rtrim(string)
example:  s=rtrim "abc   "
result:   s="abc"
related:  ltrim, space, str, lcase, ucase
group:    string functions
updated:  11/02/2025
.


key:      "lcase 16"
action:   returns lowercase of string
use:      string=lcase(string)
example:  s=lcase "ABCDEF"
result:   s="abcdef"
related:  ucase, ltrim, rtrim, asc
group:    string functions
updated:  11/02/2025
.


key:      "ucase 16"
action:   returns uppercase of string
use:      string=ucase(string)
example:  s=ucase "abcdef"
result:   s="ABCDEF"
related:  lcase, ltrim, rtrim, asc
group:    string functions
updated:  11/02/2025
.


key:      "string 16"
action:   returns a string of characters
use:      string=string(length,character)
example:  string=string(4,"a")
result:   s="aaaa"
related:  space, nuls, asc
group:    string functions
updated:  11/02/2025
.


key:      "space 16"
action:   returns a string of spaces
use:      string=space length
example:  s=space 10
result:   s="  " ' 10 spaces (ascii 32)
remarks:  for wide strings use string(n,wchr 32) instead
related:  nuls, string, ltrim, rtrim
group:    string functions
updated:  11/02/2025
.


key:      "left 16"
action:   returns left part of a string by length
use:      string=left string1,length
example:  s=left "abcdef",3
result:   s="abc"
related:  right, mid, ltrim, rtrim
group:    string functions
updated:  27/03/2017
.


key:      "mid__function 16"
title:    mid function
action:   returns part of string1 at position with length
use:      string=mid string1, position, length 'if length is omitted then the rest of string1 is returned
example:  s=mid "abcdef",3 : t=mid "abcdef",3,2
result:   s="cdef" : t="cd"
remarks:  also works with untyped pointers
related:   left, ltrim, rtrim, instr, mid__command
group:    string functions
updated:  27/03/2017
.


key:      "mid__command 16"
title:    mid command
action:   patches string2 into string1 as position
use:      mid(string1,position)=string2 : mid string1,position,string2
example:  s="abcdef" : mid s,2,"BC"
result:   s="aBCdef"
related:  mid__function, left, ltrim, rtrim
group:    string command
updated:  11/02/2025
.


key:      "instr 16"
action:   returns position of String2 within string1 searching from start position
use:      location=instr(string1,string2) : location=instr(start,string1,string2)
example:  p=instr("abcdef abcdef","def") : q=instr(8,"abcdef abcdef","def")
result:   p=4 : q=11
remarks:  also works with untyped pointers
related:  replace, mid
group:    string functions
updated:  11/02/2025
.


key:      "getfile 16"
action:   copies file content to a string
use:      String=getfile FileName : getfile FileName,String
example:  string s : getfile "t.txt",s
result:   s contains content of "t.txt"
related:  putfile, print
group:    string functions
updated:  11/02/2025
.


key:      "putfile 16"
action:   saves a string to a file
use:      putfile FileName, String
example:  putfile "t.txt","Hello"
result:   A file named "t.xt" is created or overwritten containing "Hello"
related:  getfile, print
group:    string functions
updated:  11/02/2025
.


key:      "print 16"
action:   Displays strings and numbers
use:      print String : print Number
example:  print "ABC" : print 123 : print "ABC: " 123 " DEF: " 456
result:   ABC
  123
  ABC: 123 DEF: 456
remarks:  strings can be combined with numbers as sys as the first element is a string
related:  val, str, hex, putfile, getfile
group:    string functions
updated:  11/02/2025
.


key:      "asc 16"
action:   returns ascii encoding of a character in a string
use:      AsciiCode=asc(String,CharacterPosition)
example:  
  'as function:
  a=asc("ABCDEF",2) 'a=66 'B'
  'as pseudo-command:
  asc(s,2)=98 's="AbCDEF"
related:  unic, chr, mid, val, len, str
group:    string functions
updated:  16/06/2022
.


key:      "unic 16"
action:   returns encoding of a character in a wide string
use:      uni=unic(String,CharacterPosition)
example:
  'as function:
  a=unic(L"ABCDEF",2) 'a=0x0042
  'as pseudo-command:
  unic(s,2)=0x0062 's=L"AbCDEF"
related:  asc, wchr, chr, val, mid, len, str
group:    string functions
updated:  10/01/2023
.


key:      "len 16"
action:   returns length of string in charaters
use:      length=len(string)
example:  v=len("Hello")
result:   v=5 characters
remarks:  characters may be one or two bytes (wide characters)
related:  string, space, mid, sizeof
group:    string functions
updated:  16/06/2022
.


key:      "chr 16"
action:   returns string of 1 character of ascii encoding (0..255)
use:      string=chr(AsciiValue)
example:  
  'as function:
  s=chr(65) 's="A"
  'as pseudo-command:
  string s="abcdef"
  chr(s,2)="B" 's="aBcdef"
related:  wchr, asc, unic, mid string
group:    string functions
updated:  16/06/2022
.


key:      "wchr 16"
action:   returns wide string of a 2 byte character (encoding 0..65535 / 0xffff)
use:      widestring=wchr(WideCharValue)
example:  wstring ws=wchr(65)
result:   ws contains unicode character 0x0041
remarks:  Can also be used as a pseudo-command like chr()
related:  unic, asc, mid, string
group:    string functions
updated:  16/06/2022
.


key:      "str 16"
action:   returns string representation of number
use:      String=str(value)
example:  s=str(-1.23456)   ' result: -1.23456
  s=str(-1.23456,3) ' result: -1.235
remarks:  rounding is automatically applied before decimal places are truncated.
related:  hex, val
group:    string functions
updated:  11/02/2025
.


key:      "hex 16"
action:   returns hexadecimal string representation of integer part of number
use:      hexString=hex(value)
example:  print hex(14.4)      'result 'E'
  print hex(14.4, 4)   'result '000E'
related:  str, val
group:    string functions
updated:  11/02/2025
.


key:      "guidval 16"
action:   converts guid string to guidval
use:      COM interfaces
example:  guid clsid
  guidval clsid,"{96749377-3391-11D2-9EE3-00C04F797396}"
related:  guidtxt, com
group:    string functions
updated:  11/02/2025
.


key:      "guidtxt 16"
action:   converts guidval to guidstring
use:      COM interfaces
example:  print guidtxt(clsid)
result:   displays: {96749377-3391-11D2-9EE3-00C04F797396}
related:  guidval, com
group:    string functions
updated:  11/02/2025
.


key:      "numberformat 16"
action:   control how numbers are converted to strings
use:      change the format of numbers
example:  numberformat 3,0,0,0 : print 3.14159
  'result: 3.142
remarks:  there are 6 parameters:
  1 decimal places (0..16)
  2 strip trailing zeros (0 or 1)
  3 always use scientic notation E format (0 or 1)
  4 suppress 0 before decimal point: 0.1 becomes .1 (0 or 1)
  5 insert extra leading space for non-negative numbers (0 or 1)
  6 width allocated before decimal point: (0..31)
    (inserting lead padding spaces)

  when no parameters are given, it reverts to the default settings:
  16,1,0,0,0,0
  rounding is automatically performed before the decimal places are truncated.
related:  print, frac, float
group:    directives
updated:  11/02/2025
.






'===========================
'>>FLOATING POINT MACRO
'===========================


key:      "abs 17"
action:   returns the absolute value of a number (removes negative sign)
use:      AbsoluteValue=abs(value)
example:  a=abs(-2.5)
result:   a=2.5
related:  round, frac, trunc, floor, ceil
group:    floating point macros
updated:  11/02/2025
.


key:      "acos 17"
action:   returns angle in radians given the ratio x/radius
use:      angle=acos(YRRatio)
example:  a=acos(0.5)
result:   a=pi/3
related:  cos, asin, atn, atan
group:    floating point macros
updated:  11/02/2025
.


key:      "asin 17"
action:   returns angle in radians given the ratio y/radius
use:      angle=asin(YRRatio)
example:  a=asin(0.5)
result:   a=pi/6
related:  sin, acos, atn, atan
group:    floating point macros
updated:  11/02/2025
.


key:      "atan  17"
action:   returns angle in radians given the values of y and x
use:      angle=atan(y,x)
example:  a=atan(0.5,sqr(0.75))
result:   a=pi/6
related:  atn, asin, acos, tan
group:    floating point macros
updated:  11/02/2025
.


key:      "atn 17"
action:   returns angle in radians given ratio y/x
use:      angle=atn(YXRatio)
example:  a=atn(1)*4
result:   a=pi
related:  atan, asin, acos, tan
group:    floating point macros
updated:  11/02/2025
.


key:      "cos 17"
action:   returns cosine value (ratio of x/r)  given angle in radians
use:      Cosine=cos(radians)
example:  c=cos(pi/3)
result:   c=0.5
related:  sin, tan
group:    floating point macros
updated:  11/02/2025
.


key:      "deg 17"
action:   returns degrees from value given in radians
use:      degrees=deg(radians)
example:  d=deg(pi)
result:   180
related:  rad, atan
group:    floating point macros
updated:  11/02/2025
.


key:      "frac 17"
action:   returns the fractional part of a value
use:      FractionValue=frac(value)
example:  n=frac(123.456)
result:   n=0.456
related:  round, abs
group:    floating point macros
updated:  11/02/2025
.


key:      "hypot 17"
action:   returns the hypotenuse (longest side) of a right angle triangle given the other 2 sides.
use:      hypotenuse=hypot(side1,side2)
example:  h=hypot(3,4)
result:   h=5
related:  sqr, pow
group:    floating point macros
updated:  11/02/2025
.


key:      "lin 17"
key:      "log 17"
action:   returns the logarthm of the first value to base e (2.71828182845904523536 .)
use:      LogValue=log(Value)
example:  a=log(10)
result:   a=2.30258092...
related:  lin2, log10, logn, pow
group:    floating point macros
updated:  11/02/2025
.


key:      "log2 17"
action:   returns the logarthm of the first value to base 2
use:      LogValue=log2(Value)
example:  a=log2(32)
result:   a=5
related:  log, log10, logn, pow
group:    floating point macros
updated:  11/02/2025
.


key:      "log10 17"
action:   returns the logarthm of the first value to base 10
use:      LogValue=log10(Value)
example:  a=log10(100)
result:   a=2
related:  log, log2, logn, pow
group:    floating point macros
updated:  11/02/2025
.


key:      "logn 17"
action:   returns the logarthm of the first value to the base of the second value.
use:      value=logn(value1,value2)
example:  u=logn 1000,10) : v=logn(pow(10,1.5),10)
result:   u=3 : v=1.5
related:  log, log2, log10, pow
group:    floating point macros
updated:  11/02/2025
.


key:      "mod 17"
action:   returns the remainder of first value divided by the second value
use:      modulus=mod(value1,value2)
example:  m=mod(83.5, 10)
result:   m=3.5
related:  round, trunc, floor, ceil, frac, abs
group:    floating point macros
updated:  11/02/2025
.


key:      "pi 17"
action:   returns pi, the ratio of the circumference of a circle to its diameter
use:      p=pi ' or pi()
example:  p=pi*2
result:   p=6.283185...
related:  tan, atan
group:    floating point macros
updated:  11/02/2025
.


key:      "exp 17"
action:   returns exponent of a value
use:      a=exp(value)
example:  a=exp(1)
result:   a=2.718281828
remarks:  This is the Euler number e, equivalent operation e^v
related:  pow,log, logn
group:    floating point macros
updated:  11/02/2025
.


key:      "pow 17"
action:   returns the value of the first value to the power of the second value
use:      a=pow(value,exponent)
example:  a=pow(2,3)
result:   a=8
remarks:  this is equivalent to 2^3
related:  log, logn
group:    floating point macros
updated:  11/02/2025
.


key:      "rad 17"
action:   returns value in radians, given degrees
use:      radians=rad(degrees)
example:  v=rad(180)
result:   v=pi
related:  deg, pi
group:    floating point macros
updated:  11/02/2025
.


key:      "recip 17"
action:   returns reciprocal of value: a=1/v
use:      reciprocal=recip(value)
example:  a=recip(5/4)
result:   a=0.8
related:  sqr, mod, round, pow, log
group:    floating point macros
updated:  11/02/2025
.


key:      "round 17"
action:   returns a value rounded to the nearest whole number (rounded up or down)
use:      WholeNumber=round(number)
example:  m=round(1.49) : n=round(1.5)
result:   m=1 : n=2
related:  frac, trunc, floor, ceil, mod, abs
group:    floating point macros
updated:  11/02/2025
.


key:      "sgn 17"
action:   returns -1 for negative values, 0 for zero and 1 for positive values
use:      extract the sign of a number
example:  a=sgn(-42)
result:   a=-1
related:  abs, frac, round, mod
group:    floating point macros
updated:  11/02/2025
.


key:      "sin 17"
action:   returns the sine of a value given in radians
use:      Sine=sin(Radians)
example:  v=sin(pi/6)
result:   v=0.5
related:  asin, cos, tan
group:    floating point macros
updated:  11/02/2025
.


key:      "sqr 17"
key:      "sqrt 17"
action:   returns the square root of a value
use:      SquareRoot=sqr(value)
example:  v=sqr(9)
result:   3
remarks:  sqr and sqrt are the same
related:  pow, log, hypot
group:    floating point macros
updated:  11/02/2025
.


key:      "tan 17"
action:   returns the tangent of a value given in radians
use:      tangent=tan(radians)
example:  t=tan(a)
result:   t= ratio y/x
related:  atan, atn, sin, cos
group:    floating point macros
updated:  11/02/2025
.


key:      "floor 17"
action:   round down the value to the most negative integer
use:      IntegerValue=floor(FloatValue)
example:  i=floor(-123.456)
result:   i=-124
related:  ceil, round, trunc, frac
group:    floating point macros
updated:  11/02/2025
.


key:      "ceil 17"
action:   round up the value to the most positive integer
use:      IntegerValue=ceil(FloatValue)
example:  i=ceil(123.456)
result:   i=124
related:  floor, round, trunc, frac
group:    floating point macros
updated:  11/02/2025
.


key:      "trunc 17"
action:   truncate the fractional part of a value and return it
use:      IntegerValue=trunc(FloatValue)
example:  i=trunc(123.456)
result:   i=123
group:    floating point macros
related:  round, floor, ceil, frac
updated:  11/02/2025
.





'==============
'OTHER KEYWORDS
'==============



'METACODINGS
'===========
' 50 misc
' 51 operators
' 52 conditionals and loops
' 53 metatypes
' 54 class qualifier keywords etc
' 55 calling conventions
' 56 comments
' 57 secondary metalanguage
'
' 99 topics (not keywords)
'updated:  16/06/2016
.


key:      "null 50"
action:   force pointer value to be 0
use:      passing 0 as a string or structure pointer
example:  ofn.lpstrFileTitle = null
   MessageBox null,"text","title",0
remarks:  When used as a parameter, null is equivalent to <b>byval 0</b>.
group:    misc
related: byval
updated:  15/02/2018
.


key:      "byval 50"
action:   pass a parameter by value  
use:      In function prototypes and calls
example:  'In prototypes: receiving a value directly
  function foo(byval v as long)
  'equivalent in C notation:
  long foo(long v)
  
  'In calls: passing a value directly
  err=CoCreateInstance VoiceObjGuid, pUnkouter, context, ISpVoiceGuid, byval @@voice
  
remarks:  
group:    misc
related:  byref, null, #byval, #byref
updated:  15/02/2018
.


key:      "byref 50"
action:   pass a parameter by reference (address)  
use:      In function prototypes and calls
example:  'In prototypes: receiving a value indirectly
  function foo(byref v as long) as long
  'equivalent in C notation:
  long foo(long * v)
  
  'In dim statements:
  dim as word byref a = getmemory(1024)
  'equivalent in C notation:
  word * v = getmemory(1024)
  'equivalent using 'at':
  word v at getmemory(1024)
  
group:    misc
remarks:  
related:  byval, null, #byref, #byval
updated:  15/02/2018
.

key:      "not__conditional 51"
action:   invert conditional logic
use:      inversion of condition
example:  'if not a>42 then' ...  'if a<=42 then'
remarks:  'not' inverts the outcome of the rest of the conditional expression
related:  true, false, not__bits
group:    operators
updated:  27/03/2017
.


key:      "not__bits 51"
action:   inverts bits
use:      invert bits of variable or expression
example:  int b=0x55 : a=not(b) 'bitwise inversion a=0xaa
remarks:
related:  not__conditional, true, false
group:    operators
updated:  27/03/2017
.


key:      "extends 54"
same:     of
same:     from
group:    secondary keyword
remarks:  'of', and 'from' and extends are equivalent. They 
  indicate derivation from a single parental class.
  COM interfaces us single inheritance
group:    classes
related:  has, class
updated:  01/05/2023
.


key:      "has 54"
group:    secondary keyword
example:
    class person
      has mind
      has body
      ...

remarks:  <b>'has'</b> is used when the class is derived from more than a single
  parental class. ie: multiple inheritance. 'has' may be omitted. It is sufficient
  to provide the class/type name without this qualifier.
group:    classes
related:  of, from, extends, class, classes
updated:  01/05/2023
.


key:      "lib 54"
group:    secondary keyword
remarks:  lib may be specified in the Declare statement or it may be
  specified in an extern statement, referring to an entire group
  of declarations.
group:    declaration
related:  library, declare, extern, alias, link, at
updated:  20/02/2017
.


key:      "export 54"
group:    secondary keyword
remarks:  procedures with this attribute are visible to external callers
  when they are compiled as part of a DLL (Dynamic Link Library)
group:    declaration
related:  external, function, sub, extern
updated:  20/02/2017
.


data:     "at 54"
group:    secondary keyword
remarks:  used to specify the loction of the procedure.
  This could be a register operand [ebx+4] or a simple variable
group:    declaration
related:  link, dim
updated:  20/02/2017
.


key:      "external 54"
group:    secondary keyword
remarks:  functions with the external attribute expect to be called from
  procedures external to Oxygen. Additional register management is
  enlisted to support external calls.

  Objects of classes with this attribute have virtual function table
  pointers embedded in their structures to enable their methods to
  be invoked externally. For internally used objects, the methods table
  is known to the objects at compile time so VFT pointers are not used.
group:    declaration
related:  extern, com, export, callback, com, virtual, function, sub, method
updated:  20/02/2017
.

key:      "com 54"
related:  virtual external export class of inherits
group:    classes
remarks:  COM is a protocol used by Microsoft to provide Object interfaces. Classes
  with this attribute are considered Virtual.
related:  extern, virtual, class
updated:  20/02/2017
.


key:      "virtual 54"
same:     pure
related:  com external export class
group:    classes
remarks:  objects of virtual classes are usually created by some
  kind of server or class factory. The client only receives
  a reference (pointer) to the object from the server and only knows
  how to invoke its methods. It assumes no knowledge of its inner workings.
related:  extern, com, class
updated:  10/04/2023
.


key:      "public 54"
use:      determines the scope of a class member
group:    classes
remarks:  this term is now ignored in class definitions
related:  protected, private
updated:  10/01/2018
.


key:      "protected 54"
use:      determines the scope of a class member
group:    classes
remarks:  this term is now ignored in class definitions
related:  public, private
updated:  10/01/2018
.


key:      "private 54"
use:      determines the scope of a class member
group:    classes
remarks:  this term is now ignored in class definitions
related:  protected, public
updated:  10/01/2018
.


'============
'GROUP TOPICS
'============

key:      "dimsyntax "
members:  dim, as, ptr, *, at, global, static, local
keylinks: yes
group:    variables
incfile1: demos\basics\DimSyntax.o2bas
remarks:  C style instantiations is a simpler alternative to using 'Dim'.

  When autodim is active (by default), variables can be automatically 
  instantiated unless they are arrays or referenced (byref) variables.
related:  global, local, static
updated:  05/02/2026
.

key:      "structures "
members:  type, class, typedef, struct
keylinks: yes
use:      specify compund structure for variables
group:    types
incfile1: demos\basics\types.o2bas
updated:  05/02/2026
.


key:      "end 53"
action:   marks the end of a code block
use:      terminating various block structures
example:  
  if a>b then
    b=a
  end if
remarks:  An isolated 'end' terminates the program.
related:  scope, if, do, while, select, function, sub, method, class, macro, def
group:    keywords
updated:  11/02/2025
.


key:      "includes "
members:  use, uses, using, once
keylinks:
group:    keywords
updated:  05/02/2026
.


key:      "once 54"
action:   ensures that a file is included in the
          source code once only.
example:  #include once "../../MinWin.inc"
related:  include, #include, includepath
group:    secondary keyword
updated:  11/02/2025
.


key:      "equates "
members:  %, $
keylinks: yes
group:    equates
incfile1: demos\basics\equates.o2bas
remarks:  $ and % are equivalent
related:  def, #def, macro, #define
updated:  05/02/2026
.


key:      "arrays "
members:  dim, redim
keylinks: yes
group:    variables
related:  
incfile1: demos\basics\Arrays.o2bas
updated:  05/02/2026
.


key:      "blocks "
members:  scope, module, interface, namespace, o2, (
keylinks: yes
group:    blocks
related:  procedures, macros
updated:  05/02/2026
.


key:      "macros "
members:  #define, def, deff, %, $
keylinks: yes
group:    macros
related:  macro__functions, macro__operators, procedures
updated:  05/02/2026
.


key:      "macro__operators "
members:  init,free, conv, move, save, neg
action:   supports operation on compund types  
use:      formulating expressions, in conjunction with higher operands
example:  
incfile1: demos\basics\OperatorsVector.o2bas
remarks:  
group:    structures
related:  macros, macro__functions, operators
updated:  05/02/2026
.


key:      "macro__functions 99"
action    replaces macro with a temp variable.
use:      invoke multi-line macros within expressions
example:  
incfile1: demos\basics\MacroFunctions.o2bas
remarks:  implements in-line functions
group:    structures
related:  macros, macro__operators
updated:  16/06/2018
.


key:      "procedures "
members:  function, sub, procedure, method, subroutine
keylinks: yes
group:    procedures
incfile1: demos\basics\procedures.o2bas
related:  macro
updated:  05/02/2026
.


key:      "conditionals "
members:  if, then, elseif,else, endif, while, wend
keylinks: yes
group:    conditionals
incfile1: demos\basics\conditionals.o2bas
related:  selection, loops
updated:  05/02/2026
.


key:      "loops "
members:  do, while, exit, continue, wend, enddo
keylinks: yes
group:    loops
incfile1: demos\basics\loops.o2bas
related:  iteration, conditionals
updated:  05/02/2026
.


key:      "iteration "
members:  for, to, step, next
keylinks: yes
group:    iteration
incfile1: demos\basics\iteration.o2bas
related:  loops
updated:  05/02/2026
.


key:      "selection "
members:  select, case, switch, endselect
keylinks: yes
group:    case selection
incfile1: demos\basics\select.o2bas
related:  conditionals
updated:  05/02/2026
.


key:      "declarations "
members:  declare, !, function, sub, procedure,
          ptr, alias, lib, stdcall, cdecl, ms64, as,
          export, extern, external, callback, link,
          at, =, label, nosig
keylinks: yes
group:    declaring procedures
keywords: 

  <b>Left-side keywords:</b>

  <b>declare</b>
  <b>!</b>
  same as 'declare'
  <b>function</b>
  optional
  <b>sub</b>
  optional 
  <b>ptr</b>
  function pointer
  <b>*</b>
  function pointer
  <b>alias</b>
  exact name of the function in the dll (dynamic link library)
  optional if the function name is an exact match
  <b>lib</b>
  name of dll
  <b>stdcall</b>
  calling convention (32bit default)
  <b>cdecl</b>
  C calling convention (32bit)
  <b>pascal</b>
  pascal calling convention (32bit)
  <b>ms64</b>
  MS calling convention (64bit default)


  <b>Right-side keywords:</b>

  <b>as</b>
  type of return value
  <b>link</b>
  store function location to specified variable.
  <b>at</b>
  specify pointer to the function location
  <b>=</b>
  same as 'at'
incfile1: 
related:  procedures, types
updated:  05/02/2026
.


key:      "type 53"
action:   define a compound structure for variables
use:      User defined types (UDT)
group:    compound structures
incfile1: demos\basics\types.o2bas
remarks:  
  type is now synonymous with class, and can
  contain functions/methods
related:  structures, classes, class
updated:  05/02/2026
.

key:      "classes "
same:     objects, OOP, Object Oriented Programming
members:  class, type, has, of, from, virtual, pure, com, new, del
keylinks: yes
incfile1: demos\basics\classes.o2bas
group:    classes
related:  structures
updated:  06/02/2026
.


key:      "' 56"
action:   comment till end of line
use:      
example:  'this is a comment
related:  /*   */   //  ;
group:    comments
updated:  25/02/2017
.


key:      "; 56"
action:   comment till end of line
use:      
example:  'this is a comment
related:  '   /*   */   //
group:    comments
updated:  25/02/2017
.


key:      "// 56"
action:   comment till end of line
use:      
example:  // this is a comment
related:  '   ;   /*   */
group:    comments
updated:  25/02/2017
.


key:      "/* 56"
action:   comment till end of block
use:      
example:  /* this is a comment */

  /*
    this is also a comment
  */
related:  skip '   ;   */   //
group:    comments
updated:  25/02/2017
.


key:      "*/ 56"
action:   terminate comment block
use:      
example:  /* this is a comment */

  /*
    this is also a comment
  */
related:  /*   //   ;
group:    comments
updated:  25/02/2017
.


'---------
'OPERATORS
'=========


key:  "+ 51"
related:  +=, -, *, /, operators
group:    operators
updated:  10/01/2018
.


key:  "- 51"
related:  +, -=, *, /, operators
group:    operators
updated:  06/02/2026
.


key:  "* 51"
related:  +, -, *=, /, operators
group:    operators
updated:  06/02/2026
.


key:  "/ 51"
related:  +, -, *, /=, operators
group:    operators
updated:  06/02/2026
.


key:  "+= 51"
related:  +, -, *, /, operators
group:    operators
updated:  10/01/2018
.


key:  "-= 51"
related:  +, -, *, /, operators
group:    operators
updated:  06/02/2026
.


key:  "*= 51"
related:  +, -, *, /, operators
group:    operators
updated:  06/02/2026
.


key:  "/= 51"
related:  +, -, *, /, operators
group:    operators
updated:  06/02/2026
.


key:  "and 51"
same:     &
remarks:  bitwise operator
related:  and, or, xor, operators
group:    operators
updated:  06/02/2026
.


key:  "or 51"
same:     |
remarks:  bitwise operator
related:  and, or=, xor, operators
group:    operators
updated:  10/01/2018
.


key:  "xor 51"
remarks:  bitwise operator
related:  and, or, xor=, operators
group:    operators
updated:  10/01/2018
.


key:  "and= 51"
same:     &=
remarks:  bitwise assign operator
related:  and, or, xor, operators
group:    operators
updated:  10/01/2018
.


key:  "or= 51"
same:     |=
remarks:  bitwise assign operator
related:  and, or, xor, operators
group:    operators
updated:  10/01/2018
.


key:  "xor= 51"
remarks:  bitwise assign operator
related:  and, or, xor, operators
group:    operators
updated:  10/01/2018
.


key:  "&& 51"
remarks:  logical operator
related:  &&, ||, ^^ operators
group:    operators
updated:  10/01/2018
.


key:  "|| 51"
remarks:  logical operator
related:  &&, ||, ^^ operators
group:    operators
updated:  10/01/2018
.


key:  "^^ 51"
remarks:  logical operator
related:  &&, ||, ^^ operators
group:    operators
updated:  10/01/2018
.


key:  "&&= 51"
remarks:  logical assign operator
related:  &&, ||, ^^ operators
group:    operators
updated:  10/01/2018
.


key:  "||= 51"
remarks:  logical assign operator
related:  &&, ||, ^^ operators
group:    operators
updated:  10/01/2018
.


key:  "^^= 51"
remarks:  logical assign operator
related:  &&, ||, ^^ operators
group:    operators
updated:  10/01/2018
.


key:  "<< 51"
remarks:  logical operator
related:  >>, <<<, >>>, operators
group:    operators
updated:  06/02/2026
.


key:  ">> 51"
remarks:  logical operator
related:  <<, <<<, >>>, operators
group:    operators
updated:  06/02/2026
.


key:  "<<< 51"
remarks:  logical operator
related:  <<, >>, >>>, operators
group:    operators
updated:  06/02/2026
.


key:  ">>> 51"
remarks:  logical operator
related:  <<, >>, <<<, operators
group:    operators
updated:  06/02/2026
.


key:      "operators "
members:  and, or, xor, =, := ,+, -, *, /,
          \, ^, +=, -=, *=, /=, ==, !=,
          <>, <, >, <=,>=, and=, or=, xor=,
          &, |, &=, |=, &&, ||, ^^,
          &&=, ||=, ^^=,
          <<, >>, <<<, >>>
keylinks: yes
action:   changes the state of an accumulator  
use:      formulating expressions, in conjunction with operands
example:  a*b+c/4
remarks:  universal feature of maths and programming languages
group:    operators
related:  types
updated:  06/02/2026
.


'-------------------
'CALLING CONVENTIONS
'===================


key:  "stdcall 55"
action:   determines how parameters are passed on the stack   
use:      declaring external functions
example:  ! Sleep lib "kernel32.dll" stdcall (int msec)
remarks:  this is the default calling convention on 32bit Windows platforms.
group:    calling conventions
related:  calling_conventions, cdecl, ms64, pascal
updated:  17/06/2022
.


key:  "pascal 55"
action:   determines how parameters are passed on the stack   
use:      declaring external functions
example:  ! Sleep lib "kernel32.dll" stdcall (int msec)
remarks:  this is a legacy calling convention on 32bit platforms.
group:    calling conventions
related:  calling_conventions, stdcall, cdecl, ms64
updated:  17/06/2022
.


key:  "cdecl 55"
action:   determines how parameters are passed on the stack   
use:      declaring external functions, and variadic functions
example:  
remarks:  this is a common calling convention on 32bit platforms. The stack is cleaned up
  after the call by the caller.
group:    calling conventions
related:  calling_conventions, cdecl, ms64, pascal, callback
updated:  17/06/2022
.


key:  "ms64 55"
action:   determines how parameters are passed on the stack   
use:      declaring external functions, and variadic functions
example:  
remarks:  this is the default Windows calling convention on 64bit platforms.
  The first four parameters are passed in registers. 
  The stack is cleaned up after the call by the caller.
group:    calling conventions
related:  calling_conventions, stdcall, cdecl, pascal
updated:  17/06/2022
.

'also fastcall thiscall fpucall


key:      "calling_conventions "
members:  stdcall, cdecl, ms64, pascal
keylinks: yes
title:    calling conventions
action:   determines how parameters are passed on the stack, when making a call
group:    calling conventions
related:  extern
updated:  05/02/2026
.


key:      "metakeywords "
members:  #if, #elseif, #else, #endif,
          #ifdef, #ifndef, defined, undefined,
          match, leftmatch, rightmatch, anymatch
keylinks: yes
title:    meta keywords
related:  typeof, typecodeof, def, macro ,$ ,%
remarks:  generally for use inside macros
group:    meta control
updated:  05/02/2026
.


key:      "defined 57"
title:    defined
action:   test whether a symbol exists
use:      to allow blocks of code to be included or omitted at compile time
example:  
  #if defined X
  #else
    dim string X
  #endif
related:  undefined, #ifdef, #ifndef, #if, #elseif, #else, #endif, def, macro
remarks:  generally for use inside macros
group:    meta control
updated:  11/02/2025
.


key:      "undefined 57"
title:    undefined
action:   test whether a symbol exists
use:      to allow blocks of code to be included or omitted at compile time
example:  
  #if undefined X
    dim string X
  #endif
related:  defined, #ifdef, #ifndef, #if, #elseif, #else, #endif, def, macro
remarks:  generally for use inside macros
group:    meta control
updated:  20/06/2022
.


key:      "match 57"
title:    match
action:   match testing of symbol names
use:      to allow blocks of code to be included or omitted at compile time
example:  
  #if leftmatch X, "vector"
    'X must be vector
    #include "mathutil.inc"
  #endif
related:  leftmatch, rightmatch, anymatch, #if, #elseif, #else, #endif, typeof, typecodeof, def, macro
remarks:  generally for use inside macros
group:    meta control
updated:  20/06/2022
.


key:      "leftmatch 57"
title:    leftmatch
action:   match testing of symbol names
use:      to allow blocks of code to be included or omitted at compile time
example:  
  #if leftmatch X, "vector"
    'X could be vector vector2f vector3f
    #include "mathutil.inc"
  #endif
related:  match, rightmatch, anymatch, #if, #elseif, #else, #endif, typeof, typecodeof, def, macro
remarks:  generally for use inside macros
group:    meta control
updated:  20/06/2022
.


key:      "rightmatch 57"
title:    rightmatch
action:   match testing of symbol names
use:      to allow blocks of code to be included or omitted at compile time
example:  
  #if rightmatch X, "Vec"
    'X could be aVec bVec FloatVec
    #include "mathutil.inc"
  #endif
related:  match, leftmatch, anymatch, #if, #elseif, #else, #endif, typeof, typecodeof, def, macro
remarks:  generally for use inside macros
group:    meta control
updated:  20/06/2022
.

key:      "anymatch 57"
title:    anymatch
action:   match testing of symbol names
use:      to allow blocks of code to be included or omitted at compile time
example:  
  #if anymatch X, "Vec"
    'X could be aVec FloatVec2 vector3f
    #include "mathutil.inc"
  #endif
related:  match, leftmatch, rightmatch, #if, #elseif, #else, #endif, typeof, typecodeof, def, macro
remarks:  generally for use inside macros
group:    meta control
updated:  20/06/2022
.



'===========================
'>>REGISTERS
'===========================

key:      "registers "
members:  al, cl, dl, bl,
          ah, ch, dh, bh,
          ax, cx, dx, bx,
          sp, bp, si, di,
          eax, ecx, edx, ebx,
          esp, ebp, esi, edi,
          st0, st1, st2, st3, st4, st5, st6, st7,
          mmx0, mmx1, mmx2, mmx3, mmx4, mmx5, mmx6, mmx7,
          xmm0, xmm1, xmm2, xmm3, xmm4, xmm5, xmx6, xmm7,
          xmm8, xmm9, xmm10, xmm11, xmm12, xmm13, xmm14, xmm15,
          cr0, cr1, cr2, cr3, cr4,
          dr0, dr1, dr2, dr3, dr4, dr5, dr6, dr7,
          es, cs, ss, ds, fs, gs,
          rax, rcx, rdx, rbx, rsp, rbp,, rsi, rdi,
          r8, r9, r10, r11, r12, r13, r14, r15,
          r8l, r9l, r10l, r11l, r12l, r13l, r14l, r15l,
          r8w, r9w, r10w, r11w, r12w, r13w, r14w, r15w,
          r8d, r9d, r10d, r11d, r12d, r13d, r14d, r15d
keylinks: no
action:   
use:      access CPU registers directly using Assembly code
example:
  mov eax,42
  add eax,ecx
result:   eax now contains 42 plus the value in ecx
remarks:  many of these registers are only accessible if the CPU
  is runnig in a particular mode - eg: the R* registers require
  64 bit mode.
group:    X86 CPU
updated:  05/02/2026
.




'===
'END
'===
