adoc/p_branch.adoc

   1 // control.asm: WORD p_branch,'BRANCH',fasm
   2
   3 anchor:p_branch[]
   4
   5 === Word: BRANCH
   6
   7 ....
   8 Data stack: ( -- )
   9 ....
  10
  11 "BRANCH" is a function word that implements execution transfer by
  12 means of adding the subsequent branch offset to the point of
  13 execution.
  14
  15 Note that the branch offset is a byte count and each FORTH word of a
  16 definition take up a cell of 8 bytes. The offset is relative to the
  17 cell address immediately subsequent to the offset cell. In other
  18 words, offset 0 is not branching anywhere and an offset of -16 would
  19 make a tight loop back to the branch instruction itself. The latter
  20 would pull data stack values until and including the first zero value.
  21
  22 See also <<p_0branch,0BRANCH>>, <<p_1branch,1BRANCH>>, <<p_if,IF>>,
  23 <<p_else,ELSE>>, <<p_ifbreak,IFBREAK>> and <<p_ifagain,IFAGAIN>>.