adoc/p_1branch.adoc

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