basis/math/floats/env/env-docs.factor

   1 ! Copyright (C) 2009 Joe Groff.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax kernel math.floats.env quotations ;
   4 IN: math.floats.env
   5
   6 HELP: fp-exception
   7 { $class-description "Symbols of this type represent floating-point exceptions. They are used to get and set the floating-point unit's exception flags (using " { $link fp-exception-flags } " and " { $link set-fp-exception-flags } ") and to control processor traps (using " { $link with-fp-traps } "). The following symbols are defined:"
   8 { $list
   9 { { $link +fp-invalid-operation+ } " indicates that an invalid floating-point operation occurred, such as taking the square root of a negative number or dividing zero by zero." }
  10 { { $link +fp-overflow+ } " indicates that a floating-point operation gave a result larger than the maximum representable value of the type used to perform the calculation." }
  11 { { $link +fp-underflow+ } " indicates that a floating-point operation gave a result smaller than the minimum representable normalized value of the type used to perform the calculation." }
  12 { { $link +fp-zero-divide+ } " indicates that a floating-point division by zero was attempted." }
  13 { { $link +fp-inexact+ } " indicates that a floating-point operation gave an inexact result that needed to be rounded." }
  14 } } ;
  15
  16 HELP: +fp-invalid-operation+
  17 { $class-description "This symbol represents a invalid operation " { $link fp-exception } "." } ;
  18 HELP: +fp-overflow+
  19 { $class-description "This symbol represents an overflow " { $link fp-exception } "." } ;
  20 HELP: +fp-underflow+
  21 { $class-description "This symbol represents an underflow " { $link fp-exception } "." } ;
  22 HELP: +fp-zero-divide+
  23 { $class-description "This symbol represents a division-by-zero " { $link fp-exception } "." } ;
  24 HELP: +fp-inexact+
  25 { $class-description "This symbol represents an inexact result " { $link fp-exception } "." } ;
  26
  27 HELP: fp-rounding-mode
  28 { $class-description "Symbols of this type represent floating-point rounding modes. They are passed to the " { $link with-rounding-mode } " word to control how inexact values are calculated when exact results cannot fit in a floating-point type. The following symbols are defined:"
  29 { $list
  30 { { $link +round-nearest+ } " rounds the exact result to the nearest representable value, using the even value when the result is halfway between its two nearest values." }
  31 { { $link +round-zero+ } " rounds the exact result toward zero, that is, down for positive values, and up for negative values." }
  32 { { $link +round-down+ } " always rounds the exact result down." }
  33 { { $link +round-up+ } " always rounds the exact result up." }
  34 } } ;
  35
  36 HELP: +round-nearest+
  37 { $class-description "This symbol represents the round-to-nearest " { $link fp-rounding-mode } "." } ;
  38 HELP: +round-zero+
  39 { $class-description "This symbol represents the round-toward-zero " { $link fp-rounding-mode } "." } ;
  40 HELP: +round-down+
  41 { $class-description "This symbol represents the round-down " { $link fp-rounding-mode } "." } ;
  42 HELP: +round-up+
  43 { $class-description "This symbol represents the round-up " { $link fp-rounding-mode } "." } ;
  44
  45 HELP: fp-denormal-mode
  46 { $class-description "Symbols of this type represent floating-point denormal modes. They are passed to the " { $link with-denormal-mode } " word to control whether denormals are generated as outputs of floating-point operations and how they are treated when given as inputs."
  47 { $list
  48 { { $link +denormal-keep+ } " causes denormal results to be generated and accepted as inputs as required by IEEE 754." }
  49 { { $link +denormal-flush+ } " causes denormal results to be flushed to zero and be treated as zero when given as inputs. This mode may allow floating point operations to give results that are not compliant with the IEEE 754 standard." }
  50 } } ;
  51
  52 HELP: +denormal-keep+
  53 { $class-description "This symbol represents the IEEE 754 compliant keep-denormals " { $link fp-denormal-mode } "." } ;
  54 HELP: +denormal-flush+
  55 { $class-description "This symbol represents the non-IEEE-754-compliant flush-denormals-to-zero " { $link fp-denormal-mode } "." } ;
  56
  57 HELP: fp-exception-flags
  58 { $values { "exceptions" { $sequence fp-exception } } }
  59 { $description "Returns the set of floating-point exception flags that have been raised." } ;
  60
  61 HELP: set-fp-exception-flags
  62 { $values { "exceptions" { $sequence fp-exception } } }
  63 { $description "Replaces the set of floating-point exception flags with the set specified in " { $snippet "exceptions" } "." }
  64 { $notes "On Intel platforms, the legacy x87 floating-point unit does not support setting exception flags, so this word only clears the x87 exception flags. However, the SSE unit's flags are set as expected." } ;
  65
  66 HELP: clear-fp-exception-flags
  67 { $description "Clears all of the floating-point exception flags." } ;
  68
  69 HELP: collect-fp-exceptions
  70 { $values { "quot" quotation } { "exceptions" { $sequence fp-exception } } }
  71 { $description "Clears the floating-point exception flags and then calls " { $snippet "quot" } ", returning the set of floating-point exceptions raised during its execution and placing them on the datastack on " { $snippet "quot" } "'s completion." } ;
  72
  73 { fp-exception-flags set-fp-exception-flags clear-fp-exception-flags collect-fp-exceptions } related-words
  74
  75 HELP: denormal-mode
  76 { $values { "mode" fp-denormal-mode } }
  77 { $description "Returns the current floating-point denormal mode." } ;
  78
  79 HELP: with-denormal-mode
  80 { $values { "mode" fp-denormal-mode } { "quot" quotation } }
  81 { $description "Sets the floating-point denormal mode to " { $snippet "mode" } " for the dynamic extent of " { $snippet "quot" } ", restoring the denormal mode to its original value on " { $snippet "quot" } "'s completion." } ;
  82
  83 { denormal-mode with-denormal-mode } related-words
  84
  85 HELP: rounding-mode
  86 { $values { "mode" fp-rounding-mode } }
  87 { $description "Returns the current floating-point rounding mode." } ;
  88
  89 HELP: with-rounding-mode
  90 { $values { "mode" fp-rounding-mode } { "quot" quotation } }
  91 { $description "Sets the floating-point rounding mode to " { $snippet "mode" } " for the dynamic extent of " { $snippet "quot" } ", restoring the rounding mode to its original value on " { $snippet "quot" } "'s completion." } ;
  92
  93 { rounding-mode with-rounding-mode } related-words
  94
  95 HELP: fp-traps
  96 { $values { "exceptions" { $sequence fp-exception } } }
  97 { $description "Returns the set of floating point exceptions with processor traps currently set." } ;
  98
  99 HELP: with-fp-traps
 100 { $values { "exceptions" { $sequence fp-exception } } { "quot" quotation } }
 101 { $description "Clears the floating-point exception flags and replaces the exception mask, enabling processor traps for the set of exception conditions specified in " { $snippet "exceptions" } " for the dynamic extent of " { $snippet "quot" } ". The original exception mask is restored on " { $snippet "quot" } "'s completion." } ;
 102
 103 HELP: without-fp-traps
 104 { $values { "quot" quotation } }
 105 { $description "Disables all floating-pointer processor traps for the dynamic extent of " { $snippet "quot" } ", restoring the original exception mask on " { $snippet "quot" } "'s completion." } ;
 106
 107 { fp-traps with-fp-traps without-fp-traps vm-error>exception-flags vm-error-exception-flag? } related-words
 108
 109 HELP: vm-error>exception-flags
 110 { $values { "error" "a floating-point error object from the Factor VM" } { "exceptions" { $sequence fp-exception } } }
 111 { $description "When a floating-point trap is raised, the Factor VM reports the trap by throwing a Factor exception containing the exception flags at the time the trap was raised. This word extracts the exception flag information from " { $snippet "error" } " and converts it into a sequence of " { $link fp-exception } "s." } ;
 112
 113 HELP: vm-error-exception-flag?
 114 { $values { "error" "a floating-point error object from the Factor VM" } { "flag" fp-exception } { "?" boolean } }
 115 { $description "When a floating-point trap is raised, the Factor VM reports the trap by throwing a Factor exception containing the exception flags at the time the trap was raised. This word returns a boolean indicating whether the exception " { $snippet "flag" } " was raised at the time " { $snippet "error" } " was thrown." } ;
 116
 117 ARTICLE: "math.floats.env" "Controlling the floating-point environment"
 118 "The " { $vocab-link "math.floats.env" } " vocabulary contains words for querying and controlling the floating-point environment."
 119 $nl
 120 "Querying and setting exception flags:"
 121 { $subsections
 122     fp-exception-flags
 123     set-fp-exception-flags
 124     clear-fp-exception-flags
 125     collect-fp-exceptions
 126 }
 127 "Querying and controlling processor traps for floating-point exceptions:"
 128 { $subsections
 129     fp-traps
 130     with-fp-traps
 131     without-fp-traps
 132 }
 133 "Getting the floating-point exception state from errors raised by enabled traps:"
 134 { $subsections
 135     vm-error>exception-flags
 136     vm-error-exception-flag?
 137 }
 138 "Querying and controlling the rounding mode and treatment of denormals:"
 139 { $subsections
 140     rounding-mode
 141     with-rounding-mode
 142     denormal-mode
 143     with-denormal-mode
 144 } ;
 145
 146 ABOUT: "math.floats.env"