core/math/intervals/intervals-docs.factor

   1 USING: help.markup help.syntax math ;
   2 IN: math.intervals
   3
   4 ARTICLE: "math-intervals-new" "Creating intervals"
   5 "Standard constructors:"
   6 { $subsection [a,b] }
   7 { $subsection (a,b) }
   8 { $subsection [a,b) }
   9 { $subsection (a,b] }
  10 "One-point interval constructor:"
  11 { $subsection [a,a] }
  12 "Open-ended interval constructors:"
  13 { $subsection [-inf,a] }
  14 { $subsection [-inf,a) }
  15 { $subsection [a,inf] }
  16 { $subsection (a,inf] }
  17 "Another constructor:"
  18 { $subsection points>interval } ;
  19
  20 ARTICLE: "math-intervals-arithmetic" "Interval arithmetic"
  21 "Binary operations on intervals:"
  22 { $subsection interval+ }
  23 { $subsection interval- }
  24 { $subsection interval* }
  25 { $subsection interval/ }
  26 { $subsection interval/i }
  27 { $subsection interval-shift }
  28 { $subsection interval-min }
  29 { $subsection interval-max }
  30 "Unary operations on intervals:"
  31 { $subsection interval-1+ }
  32 { $subsection interval-1- }
  33 { $subsection interval-neg }
  34 { $subsection interval-bitnot }
  35 { $subsection interval-recip }
  36 { $subsection interval-2/ } ;
  37
  38 ARTICLE: "math-intervals-sets" "Set-theoretic operations on intervals"
  39 { $subsection interval-contains? }
  40 { $subsection interval-subset? }
  41 { $subsection interval-intersect }
  42 { $subsection interval-union }
  43 { $subsection interval-closure }
  44 { $subsection integral-closure } ;
  45
  46 ARTICLE: "math-intervals-compare" "Comparing intervals"
  47 { $subsection interval< }
  48 { $subsection interval<= }
  49 { $subsection interval> }
  50 { $subsection interval>= }
  51 { $subsection assume< }
  52 { $subsection assume<= }
  53 { $subsection assume> }
  54 { $subsection assume>= } ;
  55
  56 ARTICLE: "math-intervals" "Intervals"
  57 "Interval arithmetic is performed on ranges of real numbers, rather than exact values. It is used by the Factor compiler to convert arbitrary-precision arithmetic to machine arithmetic, by inferring bounds for integer calculations."
  58 $nl
  59 "The class of intervals:"
  60 { $subsection interval }
  61 { $subsection interval? }
  62 { $subsection "math-intervals-new" }
  63 { $subsection "math-intervals-arithmetic" }
  64 { $subsection "math-intervals-sets" }
  65 { $subsection "math-intervals-compare" } ;
  66
  67 ABOUT: "math-intervals"
  68
  69 HELP: interval
  70 { $class-description "An interval represents a set of real numbers between two endpoints; the endpoints can either be included or excluded from the interval."
  71 $nl
  72 "The " { $link interval-from } " and " { $link interval-to } " slots store endpoints, represented as arrays of the shape " { $snippet "{ number included? }" } "."
  73 $nl
  74 "Intervals are created by calling " { $link [a,b] } ", " { $link (a,b) } ", " { $link [a,b) } ", " { $link (a,b] } " or " { $link [a,a] } "." } ;
  75
  76 HELP: <interval> ( from to -- interval )
  77 { $values { "from" "a " { $snippet "{ point included? }" } " pair" } { "to" "a " { $snippet "{ point included? }" } " pair" } { "interval" interval } }
  78 { $description "Creates a new interval. Usually it is more convenient to create intervals using one of the following words instead:"
  79     { $list
  80         { $link [a,b] }
  81         { $link (a,b) }
  82         { $link [a,b) }
  83         { $link (a,b] }
  84         { $link [a,inf] }
  85         { $link (a,inf] }
  86         { $link [-inf,a) }
  87         { $link [-inf,a] }
  88     }
  89 } ;
  90
  91 HELP: [a,b]
  92 { $values { "a" real } { "b" real } { "interval" interval } }
  93 { $description "Creates a new interval that includes both endpoints." } ;
  94
  95 HELP: (a,b)
  96 { $values { "a" real } { "b" real } { "interval" interval } }
  97 { $description "Creates a new interval that excludes both endpoints." } ;
  98
  99 HELP: [a,b)
 100 { $values { "a" real } { "b" real } { "interval" interval } }
 101 { $description "Creates a new interval that includes the lower endpoint and excludes the upper endpoint." } ;
 102
 103 HELP: (a,b]
 104 { $values { "a" real } { "b" real } { "interval" interval } }
 105 { $description "Creates a new interval that excludes the lower endpoint and includes the upper endpoint." } ;
 106
 107 HELP: [a,a]
 108 { $values { "a" real } { "interval" interval } }
 109 { $description "Creates a new interval consisting of a single point." } ;
 110
 111 HELP: [-inf,a]
 112 { $values { "a" real } { "interval" interval } }
 113 { $description "Creates a new interval containing all real numbers less than or equal to " { $snippet "a" } ", together with negative infinity." } ;
 114
 115 HELP: [-inf,a)
 116 { $values { "a" real } { "interval" interval } }
 117 { $description "Creates a new interval containing all real numbers less than " { $snippet "a" } ", together with negative infinity." } ;
 118
 119 HELP: [a,inf]
 120 { $values { "a" real } { "interval" interval } }
 121 { $description "Creates a new interval containing all real numbers greater than or equal to " { $snippet "a" } ", together with positive infinity." } ;
 122
 123 HELP: (a,inf]
 124 { $values { "a" real } { "interval" interval } }
 125 { $description "Creates a new interval containing all real numbers greater than " { $snippet "a" } ", together with positive infinity." } ;
 126
 127 HELP: interval+
 128 { $values { "i1" interval } { "i2" interval } { "i3" interval } }
 129 { $description "Adds two intervals." } ;
 130
 131 HELP: interval-
 132 { $values { "i1" interval } { "i2" interval } { "i3" interval } }
 133 { $description "Subtracts " { $snippet "i2" } " from " { $snippet "i1" } "." } ;
 134
 135 HELP: interval*
 136 { $values { "i1" interval } { "i2" interval } { "i3" interval } }
 137 { $description "Multiplies two intervals." } ;
 138
 139 HELP: interval-shift
 140 { $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
 141 { $description "Shifts " { $snippet "i1" } " to the left by " { $snippet "i2" } " bits. Outputs " { $link f } " if the endpoints of either " { $snippet "i1" } " or " { $snippet "i2" } " are not integers." } ;
 142
 143 HELP: interval-max
 144 { $values { "i1" interval } { "i2" interval } { "i3" interval } }
 145 { $description "Outputs the interval values obtained by lifting the " { $link max } " word to " { $snippet "i1" } " and " { $snippet "i2" } "." } ;
 146
 147 HELP: interval-min
 148 { $values { "i1" interval } { "i2" interval } { "i3" interval } }
 149 { $description "Outputs the interval values obtained by lifting the " { $link min } " word to " { $snippet "i1" } " and " { $snippet "i2" } "." } ;
 150
 151 HELP: interval-1+
 152 { $values { "i1" interval } { "i2" interval } }
 153 { $description "Adds 1 to an interval." } ;
 154
 155 HELP: interval-1-
 156 { $values { "i1" interval } { "i2" interval } }
 157 { $description "Subtracts 1 from an interval." } ;
 158
 159 HELP: interval-neg
 160 { $values { "i1" interval } { "i2" interval } }
 161 { $description "Negates an interval." } ;
 162
 163 HELP: interval-intersect
 164 { $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval  } " or " { $link f } } }
 165 { $description "Outputs the set-theoretic intersection of " { $snippet "i1" } " and " { $snippet "i2" } ". If " { $snippet "i1" } " and " { $snippet "i2" } " do not intersect, outputs " { $link f } "." } ;
 166
 167 HELP: interval-union
 168 { $values { "i1" interval } { "i2" interval } { "i3" interval } }
 169 { $description "Outputs the smallest interval containing the set-theoretic union of " { $snippet "i1" } " and " { $snippet "i2" } " (the union itself may not be an interval)." } ;
 170
 171 HELP: interval-subset?
 172 { $values { "i1" interval } { "i2" interval } { "?" "a boolean" } }
 173 { $description "Tests if every point of " { $snippet "i1" } " is contained in " { $snippet "i2" } "." } ;
 174
 175 HELP: interval-contains?
 176 { $values { "x" real } { "int" interval } { "?" "a boolean" } }
 177 { $description "Tests if " { $snippet "x" } " is contained in " { $snippet "int" } "." } ;
 178
 179 HELP: interval-closure
 180 { $values { "i1" interval } { "i2" interval } }
 181 { $description "Outputs the smallest closed interval containing the endpoints of " { $snippet "i1" } "." } ;
 182
 183 HELP: interval/
 184 { $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
 185 { $description "Divides " { $snippet "i1" } " by " { $snippet "i2" } ", using " { $link / } " to perform the division. Outputs " { $link f } " if " { $snippet "i2" } " contains points arbitrarily close to zero." } ;
 186
 187 HELP: interval/i
 188 { $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
 189 { $description "Divides " { $snippet "i1" } " by " { $snippet "i2" } ", using " { $link /i } " to perform the division. Outputs " { $link f } " if " { $snippet "i2" } " contains points arbitrarily close to zero." } ;
 190
 191 HELP: interval-recip
 192 { $values { "i1" interval } { "i2" interval } }
 193 { $description "Outputs the reciprocal of an interval. Outputs " { $link f } " if " { $snippet "i1" } " contains points arbitrarily close to zero." } ;
 194
 195 HELP: interval-2/
 196 { $values { "i1" interval } { "i2" interval } }
 197 { $description "Shifts an interval to the right by one bit." } ;
 198
 199 HELP: interval-bitnot
 200 { $values { "i1" interval } { "i2" interval } }
 201 { $description "Computes the bitwise complement of the interval." } ;
 202
 203 HELP: points>interval
 204 { $values { "seq" "a sequence of " { $snippet "{ point included? }" } " pairs" } { "interval" interval } }
 205 { $description "Outputs the smallest interval containing all of the endpoints." }
 206 ;
 207
 208 HELP: interval-shift-safe
 209 { $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
 210 { $description "Shifts " { $snippet "i1" } " to the left by " { $snippet "i2" } " bits. Outputs " { $link f } " if the endpoints of either " { $snippet "i1" } " or " { $snippet "i2" } " are not integers, or if the endpoints of " { $snippet "i2" } " are so large that the resulting interval will consume too much memory." } ;
 211
 212 HELP: incomparable
 213 { $description "Output value from " { $link interval<= } ", " { $link interval< } ", " { $link interval>= } " and " { $link interval> } " in the case where the result of the comparison is ambiguous." } ;
 214
 215 HELP: interval<=
 216 { $values { "int" interval } { "n" real } { "?" "a boolean or " { $link incomparable } } }
 217 { $description "Compares " { $snippet "int" } " with " { $snippet "n" } ", and outputs one of the following:"
 218     { $list
 219         { { $link t } " if every point in " { $snippet "int" } " is less than or equal to " { $snippet "n" } }
 220         { { $link f } " if every point in " { $snippet "int" } " is greater than " { $snippet "n" } }
 221         { { $link incomparable } " if neither of the above conditions hold" }
 222     }
 223 } ;
 224
 225 HELP: interval<
 226 { $values { "int" interval } { "n" real } { "?" "a boolean or " { $link incomparable } } }
 227 { $description "Compares " { $snippet "int" } " with " { $snippet "n" } ", and outputs one of the following:"
 228     { $list
 229         { { $link t } " if every point in " { $snippet "int" } " is less than " { $snippet "n" } }
 230         { { $link f } " if every point in " { $snippet "int" } " is greater than or equal to " { $snippet "n" } }
 231         { { $link incomparable } " if neither of the above conditions hold" }
 232     }
 233 } ;
 234
 235 HELP: interval>=
 236 { $values { "int" interval } { "n" real } { "?" "a boolean or " { $link incomparable } } }
 237 { $description "Compares " { $snippet "int" } " with " { $snippet "n" } ", and outputs one of the following:"
 238     { $list
 239         { { $link t } " if every point in " { $snippet "int" } " is greater than or equal to " { $snippet "n" } }
 240         { { $link f } " if every point in " { $snippet "int" } " is less than " { $snippet "n" } }
 241         { { $link incomparable } " if neither of the above conditions hold" }
 242     }
 243 } ;
 244
 245 HELP: interval>
 246 { $values { "int" interval } { "n" real } { "?" "a boolean or " { $link incomparable } } }
 247 { $description "Compares " { $snippet "int" } " with " { $snippet "n" } ", and outputs one of the following:"
 248     { $list
 249         { { $link t } " if every point in " { $snippet "int" } " is greater than " { $snippet "n" } }
 250         { { $link f } " if every point in " { $snippet "int" } " is less than or equal to " { $snippet "n" } }
 251         { { $link incomparable } " if neither of the above conditions hold" }
 252     }
 253 } ;
 254
 255 HELP: interval>points
 256 { $values { "int" interval } { "from" "a " { $snippet "{ point included? }" } " pair" } { "to" "a " { $snippet "{ point included? }" } " pair" } }
 257 { $description "Outputs both endpoints of the interval." } ;
 258
 259 HELP: assume<
 260 { $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
 261 { $description "Outputs the interval consisting of points from " { $snippet "i1" } " which are less than all points in " { $snippet "i2" } ". If the resulting interval is empty, outputs " { $link f } "." } ;
 262
 263 HELP: assume<=
 264 { $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
 265 { $description "Outputs the interval consisting of points from " { $snippet "i1" } " which are less or equal to all points in " { $snippet "i2" } ". If the resulting interval is empty, outputs " { $link f } "." } ;
 266
 267 HELP: assume>
 268 { $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
 269 { $description "Outputs the interval consisting of points from " { $snippet "i1" } " which are greater than all points in " { $snippet "i2" } ". If the resulting interval is empty, outputs " { $link f } "." } ;
 270
 271 HELP: assume>=
 272 { $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
 273 { $description "Outputs the interval consisting of points from " { $snippet "i1" } " which are greater than or equal to all points in " { $snippet "i2" } ". If the resulting interval is empty, outputs " { $link f } "." } ;
 274
 275 HELP: integral-closure
 276 { $values { "i1" "an " { $link interval } " with integer end-points" } { "i2" "a closed " { $link interval } " with integer end-points" } }
 277 { $description "Outputs a closed interval which is equal as a set to " { $snippet "i1" } ", when " { $snippet "i1" } " is viewed as an interval over in integers (that is, a discrete set)." } ;