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

   1 ! (c)Joe Groff bsd license
   2 USING: help help.markup help.syntax kernel quotations ;
   3 IN: math.floats.env
   4
   5 HELP: fp-exception
   6 { $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:"
   7 { $list
   8 { { $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." }
   9 { { $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." }
  10 { { $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." }
  11 { { $link +fp-zero-divide+ } " indicates that a floating-point division by zero was attempted." }
  12 { { $link +fp-inexact+ } " indicates that a floating-point operation gave an inexact result that needed to be rounded." }
  13 } } ;
  14
  15 HELP: +fp-invalid-operation+
  16 { $class-description "This symbol represents a invalid operation " { $link fp-exception } "." } ;
  17 HELP: +fp-overflow+
  18 { $class-description "This symbol represents an overflow " { $link fp-exception } "." } ;
  19 HELP: +fp-underflow+
  20 { $class-description "This symbol represents an underflow " { $link fp-exception } "." } ;
  21 HELP: +fp-zero-divide+
  22 { $class-description "This symbol represents a division-by-zero " { $link fp-exception } "." } ;
  23 HELP: +fp-inexact+
  24 { $class-description "This symbol represents an inexact result " { $link fp-exception } "." } ;
  25
  26 HELP: fp-rounding-mode
  27 { $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:"
  28 { $list
  29 { { $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." }
  30 { { $link +round-zero+ } " rounds the exact result toward zero, that is, down for positive values, and up for negative values." }
  31 { { $link +round-down+ } " always rounds the exact result down." }
  32 { { $link +round-up+ } " always rounds the exact result up." }
  33 } } ;
  34
  35 HELP: +round-nearest+
  36 { $class-description "This symbol represents the round-to-nearest " { $link fp-rounding-mode } "." } ;
  37 HELP: +round-zero+
  38 { $class-description "This symbol represents the round-toward-zero " { $link fp-rounding-mode } "." } ;
  39 HELP: +round-down+
  40 { $class-description "This symbol represents the round-down " { $link fp-rounding-mode } "." } ;
  41 HELP: +round-up+
  42 { $class-description "This symbol represents the round-up " { $link fp-rounding-mode } "." } ;
  43
  44 HELP: fp-denormal-mode
  45 { $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."
  46 { $list
  47 { { $link +denormal-keep+ } " causes denormal results to be generated and accepted as inputs as required by IEEE 754." }
  48 { { $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." }
  49 } } ;
  50
  51 HELP: +denormal-keep+
  52 { $class-description "This symbol represents the IEEE 754 compliant keep-denormals " { $link fp-denormal-mode } "." } ;
  53 HELP: +denormal-flush+
  54 { $class-description "This symbol represents the non-IEEE-754-compliant flush-denormals-to-zero " { $link fp-denormal-mode } "." } ;
  55
  56 HELP: fp-exception-flags
  57 { $values { "exceptions" "a sequence of " { $link fp-exception } " symbols" } }
  58 { $description "Returns the set of floating-point exception flags that have been raised." } ;
  59
  60 HELP: set-fp-exception-flags
  61 { $values { "exceptions" "a sequence of " { $link fp-exception } " symbols" } }
  62 { $description "Replaces the set of floating-point exception flags with the set specified in " { $snippet "exceptions" } "." }
  63 { $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." } ;
  64
  65 HELP: clear-fp-exception-flags
  66 { $description "Clears all of the floating-point exception flags." } ;
  67
  68 HELP: collect-fp-exceptions
  69 { $values { "quot" quotation } { "exceptions" "a sequence of " { $link fp-exception } " symbols" } }
  70 { $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." } ;
  71
  72 { fp-exception-flags set-fp-exception-flags clear-fp-exception-flags collect-fp-exceptions } related-words
  73
  74 HELP: denormal-mode
  75 { $values { "mode" fp-denormal-mode } }
  76 { $description "Returns the current floating-point denormal mode." } ;
  77
  78 HELP: with-denormal-mode
  79 { $values { "mode" fp-denormal-mode } { "quot" quotation } }
  80 { $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." } ;
  81
  82 { denormal-mode with-denormal-mode } related-words
  83
  84 HELP: rounding-mode
  85 { $values { "mode" fp-rounding-mode } }
  86 { $description "Returns the current floating-point rounding mode." } ;
  87
  88 HELP: with-rounding-mode
  89 { $values { "mode" fp-rounding-mode } { "quot" quotation } }
  90 { $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." } ;
  91
  92 { rounding-mode with-rounding-mode } related-words
  93
  94 HELP: fp-traps
  95 { $values { "exceptions" "a sequence of " { $link fp-exception } " symbols" } }
  96 { $description "Returns the set of floating point exceptions with processor traps currently set." } ;
  97
  98 HELP: with-fp-traps
  99 { $values { "exceptions" "a sequence of " { $link fp-exception } " symbols" } { "quot" quotation } }
 100 { $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." } ;
 101
 102 HELP: without-fp-traps
 103 { $values { "quot" quotation } }
 104 { $description "Disables all floating-pointer processor traps for the dynamic extent of " { $snippet "quot" } ", restoring the original exception mask on " { $snippet "quot" } "'s completion." } ;
 105
 106 { fp-traps with-fp-traps without-fp-traps vm-error>exception-flags vm-error-exception-flag? } related-words
 107
 108 HELP: vm-error>exception-flags
 109 { $values { "error" "a floating-point error object from the Factor VM" } { "exceptions" "a sequence of " { $link fp-exception } " symbols" } }
 110 { $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." } ;
 111
 112 HELP: vm-error-exception-flag?
 113 { $values { "error" "a floating-point error object from the Factor VM" } { "flag" fp-exception } { "?" boolean } }
 114 { $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." } ;
 115
 116 ARTICLE: "math.floats.env" "Controlling the floating-point environment"
 117 "The " { $vocab-link "math.floats.env" } " vocabulary contains words for querying and controlling the floating-point environment."
 118 $nl
 119 "Querying and setting exception flags:"
 120 { $subsections
 121     fp-exception-flags
 122     set-fp-exception-flags
 123     clear-fp-exception-flags
 124     collect-fp-exceptions
 125 }
 126 "Querying and controlling processor traps for floating-point exceptions:"
 127 { $subsections
 128     fp-traps
 129     with-fp-traps
 130     without-fp-traps
 131 }
 132 "Getting the floating-point exception state from errors raised by enabled traps:"
 133 { $subsections
 134     vm-error>exception-flags
 135     vm-error-exception-flag?
 136 }
 137 "Querying and controlling the rounding mode and treatment of denormals:"
 138 { $subsections
 139     rounding-mode
 140     with-rounding-mode
 141     denormal-mode
 142     with-denormal-mode
 143 } ;
 144
 145 ABOUT: "math.floats.env"