278 lines
13 KiB
Factor
278 lines
13 KiB
Factor
USING: help.markup help.syntax math math.order ;
|
|
IN: math.intervals
|
|
|
|
ARTICLE: "math-intervals-new" "Creating intervals"
|
|
"Standard constructors:"
|
|
{ $subsection [a,b] }
|
|
{ $subsection (a,b) }
|
|
{ $subsection [a,b) }
|
|
{ $subsection (a,b] }
|
|
"One-point interval constructor:"
|
|
{ $subsection [a,a] }
|
|
"Open-ended interval constructors:"
|
|
{ $subsection [-inf,a] }
|
|
{ $subsection [-inf,a) }
|
|
{ $subsection [a,inf] }
|
|
{ $subsection (a,inf] }
|
|
"Another constructor:"
|
|
{ $subsection points>interval } ;
|
|
|
|
ARTICLE: "math-intervals-arithmetic" "Interval arithmetic"
|
|
"Binary operations on intervals:"
|
|
{ $subsection interval+ }
|
|
{ $subsection interval- }
|
|
{ $subsection interval* }
|
|
{ $subsection interval/ }
|
|
{ $subsection interval/i }
|
|
{ $subsection interval-shift }
|
|
{ $subsection interval-min }
|
|
{ $subsection interval-max }
|
|
"Unary operations on intervals:"
|
|
{ $subsection interval-1+ }
|
|
{ $subsection interval-1- }
|
|
{ $subsection interval-neg }
|
|
{ $subsection interval-bitnot }
|
|
{ $subsection interval-recip }
|
|
{ $subsection interval-2/ } ;
|
|
|
|
ARTICLE: "math-intervals-sets" "Set-theoretic operations on intervals"
|
|
{ $subsection interval-contains? }
|
|
{ $subsection interval-subset? }
|
|
{ $subsection interval-intersect }
|
|
{ $subsection interval-union }
|
|
{ $subsection interval-closure }
|
|
{ $subsection integral-closure } ;
|
|
|
|
ARTICLE: "math-intervals-compare" "Comparing intervals"
|
|
{ $subsection interval< }
|
|
{ $subsection interval<= }
|
|
{ $subsection interval> }
|
|
{ $subsection interval>= }
|
|
{ $subsection assume< }
|
|
{ $subsection assume<= }
|
|
{ $subsection assume> }
|
|
{ $subsection assume>= } ;
|
|
|
|
ARTICLE: "math-intervals" "Intervals"
|
|
"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."
|
|
$nl
|
|
"The class of intervals:"
|
|
{ $subsection interval }
|
|
{ $subsection interval? }
|
|
{ $subsection "math-intervals-new" }
|
|
{ $subsection "math-intervals-arithmetic" }
|
|
{ $subsection "math-intervals-sets" }
|
|
{ $subsection "math-intervals-compare" } ;
|
|
|
|
ABOUT: "math-intervals"
|
|
|
|
HELP: interval
|
|
{ $class-description "An interval represents a set of real numbers between two endpoints; the endpoints can either be included or excluded from the interval."
|
|
$nl
|
|
"The " { $link interval-from } " and " { $link interval-to } " slots store endpoints, represented as arrays of the shape " { $snippet "{ number included? }" } "."
|
|
$nl
|
|
"Intervals are created by calling " { $link [a,b] } ", " { $link (a,b) } ", " { $link [a,b) } ", " { $link (a,b] } " or " { $link [a,a] } "." } ;
|
|
|
|
HELP: <interval> ( from to -- interval )
|
|
{ $values { "from" "a " { $snippet "{ point included? }" } " pair" } { "to" "a " { $snippet "{ point included? }" } " pair" } { "interval" interval } }
|
|
{ $description "Creates a new interval. Usually it is more convenient to create intervals using one of the following words instead:"
|
|
{ $list
|
|
{ $link [a,b] }
|
|
{ $link (a,b) }
|
|
{ $link [a,b) }
|
|
{ $link (a,b] }
|
|
{ $link [a,inf] }
|
|
{ $link (a,inf] }
|
|
{ $link [-inf,a) }
|
|
{ $link [-inf,a] }
|
|
}
|
|
} ;
|
|
|
|
HELP: [a,b]
|
|
{ $values { "a" real } { "b" real } { "interval" interval } }
|
|
{ $description "Creates a new interval that includes both endpoints." } ;
|
|
|
|
HELP: (a,b)
|
|
{ $values { "a" real } { "b" real } { "interval" interval } }
|
|
{ $description "Creates a new interval that excludes both endpoints." } ;
|
|
|
|
HELP: [a,b)
|
|
{ $values { "a" real } { "b" real } { "interval" interval } }
|
|
{ $description "Creates a new interval that includes the lower endpoint and excludes the upper endpoint." } ;
|
|
|
|
HELP: (a,b]
|
|
{ $values { "a" real } { "b" real } { "interval" interval } }
|
|
{ $description "Creates a new interval that excludes the lower endpoint and includes the upper endpoint." } ;
|
|
|
|
HELP: [a,a]
|
|
{ $values { "a" real } { "interval" interval } }
|
|
{ $description "Creates a new interval consisting of a single point." } ;
|
|
|
|
HELP: [-inf,a]
|
|
{ $values { "a" real } { "interval" interval } }
|
|
{ $description "Creates a new interval containing all real numbers less than or equal to " { $snippet "a" } ", together with negative infinity." } ;
|
|
|
|
HELP: [-inf,a)
|
|
{ $values { "a" real } { "interval" interval } }
|
|
{ $description "Creates a new interval containing all real numbers less than " { $snippet "a" } ", together with negative infinity." } ;
|
|
|
|
HELP: [a,inf]
|
|
{ $values { "a" real } { "interval" interval } }
|
|
{ $description "Creates a new interval containing all real numbers greater than or equal to " { $snippet "a" } ", together with positive infinity." } ;
|
|
|
|
HELP: (a,inf]
|
|
{ $values { "a" real } { "interval" interval } }
|
|
{ $description "Creates a new interval containing all real numbers greater than " { $snippet "a" } ", together with positive infinity." } ;
|
|
|
|
HELP: interval+
|
|
{ $values { "i1" interval } { "i2" interval } { "i3" interval } }
|
|
{ $description "Adds two intervals." } ;
|
|
|
|
HELP: interval-
|
|
{ $values { "i1" interval } { "i2" interval } { "i3" interval } }
|
|
{ $description "Subtracts " { $snippet "i2" } " from " { $snippet "i1" } "." } ;
|
|
|
|
HELP: interval*
|
|
{ $values { "i1" interval } { "i2" interval } { "i3" interval } }
|
|
{ $description "Multiplies two intervals." } ;
|
|
|
|
HELP: interval-shift
|
|
{ $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
|
|
{ $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." } ;
|
|
|
|
HELP: interval-max
|
|
{ $values { "i1" interval } { "i2" interval } { "i3" interval } }
|
|
{ $description "Outputs the interval values obtained by lifting the " { $link max } " word to " { $snippet "i1" } " and " { $snippet "i2" } "." } ;
|
|
|
|
HELP: interval-min
|
|
{ $values { "i1" interval } { "i2" interval } { "i3" interval } }
|
|
{ $description "Outputs the interval values obtained by lifting the " { $link min } " word to " { $snippet "i1" } " and " { $snippet "i2" } "." } ;
|
|
|
|
HELP: interval-1+
|
|
{ $values { "i1" interval } { "i2" interval } }
|
|
{ $description "Adds 1 to an interval." } ;
|
|
|
|
HELP: interval-1-
|
|
{ $values { "i1" interval } { "i2" interval } }
|
|
{ $description "Subtracts 1 from an interval." } ;
|
|
|
|
HELP: interval-neg
|
|
{ $values { "i1" interval } { "i2" interval } }
|
|
{ $description "Negates an interval." } ;
|
|
|
|
HELP: interval-intersect
|
|
{ $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
|
|
{ $description "Outputs the set-theoretic intersection of " { $snippet "i1" } " and " { $snippet "i2" } ". If " { $snippet "i1" } " and " { $snippet "i2" } " do not intersect, outputs " { $link f } "." } ;
|
|
|
|
HELP: interval-union
|
|
{ $values { "i1" interval } { "i2" interval } { "i3" interval } }
|
|
{ $description "Outputs the smallest interval containing the set-theoretic union of " { $snippet "i1" } " and " { $snippet "i2" } " (the union itself may not be an interval)." } ;
|
|
|
|
HELP: interval-subset?
|
|
{ $values { "i1" interval } { "i2" interval } { "?" "a boolean" } }
|
|
{ $description "Tests if every point of " { $snippet "i1" } " is contained in " { $snippet "i2" } "." } ;
|
|
|
|
HELP: interval-contains?
|
|
{ $values { "x" real } { "int" interval } { "?" "a boolean" } }
|
|
{ $description "Tests if " { $snippet "x" } " is contained in " { $snippet "int" } "." } ;
|
|
|
|
HELP: interval-closure
|
|
{ $values { "i1" interval } { "i2" interval } }
|
|
{ $description "Outputs the smallest closed interval containing the endpoints of " { $snippet "i1" } "." } ;
|
|
|
|
HELP: interval/
|
|
{ $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
|
|
{ $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." } ;
|
|
|
|
HELP: interval/i
|
|
{ $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
|
|
{ $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." } ;
|
|
|
|
HELP: interval-recip
|
|
{ $values { "i1" interval } { "i2" interval } }
|
|
{ $description "Outputs the reciprocal of an interval. Outputs " { $link f } " if " { $snippet "i1" } " contains points arbitrarily close to zero." } ;
|
|
|
|
HELP: interval-2/
|
|
{ $values { "i1" interval } { "i2" interval } }
|
|
{ $description "Shifts an interval to the right by one bit." } ;
|
|
|
|
HELP: interval-bitnot
|
|
{ $values { "i1" interval } { "i2" interval } }
|
|
{ $description "Computes the bitwise complement of the interval." } ;
|
|
|
|
HELP: points>interval
|
|
{ $values { "seq" "a sequence of " { $snippet "{ point included? }" } " pairs" } { "interval" interval } }
|
|
{ $description "Outputs the smallest interval containing all of the endpoints." }
|
|
;
|
|
|
|
HELP: interval-shift-safe
|
|
{ $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
|
|
{ $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." } ;
|
|
|
|
HELP: incomparable
|
|
{ $description "Output value from " { $link interval<= } ", " { $link interval< } ", " { $link interval>= } " and " { $link interval> } " in the case where the result of the comparison is ambiguous." } ;
|
|
|
|
HELP: interval<=
|
|
{ $values { "i1" interval } { "i2" interval } { "?" "a boolean or " { $link incomparable } } }
|
|
{ $description "Compares " { $snippet "i1" } " with " { $snippet "i2" } ", and outputs one of the following:"
|
|
{ $list
|
|
{ { $link t } " if every point in " { $snippet "i1" } " is less than or equal to every point in " { $snippet "i2" } }
|
|
{ { $link f } " if every point in " { $snippet "i1" } " is greater than every point in " { $snippet "i2" } }
|
|
{ { $link incomparable } " if neither of the above conditions hold" }
|
|
}
|
|
} ;
|
|
|
|
HELP: interval<
|
|
{ $values { "i1" interval } { "i2" interval } { "?" "a boolean or " { $link incomparable } } }
|
|
{ $description "Compares " { $snippet "i1" } " with " { $snippet "i2" } ", and outputs one of the following:"
|
|
{ $list
|
|
{ { $link t } " if every point in " { $snippet "i1" } " is less than every point in " { $snippet "i2" } }
|
|
{ { $link f } " if every point in " { $snippet "i1" } " is greater than or equal to every point in " { $snippet "i2" } }
|
|
{ { $link incomparable } " if neither of the above conditions hold" }
|
|
}
|
|
} ;
|
|
|
|
HELP: interval>=
|
|
{ $values { "i1" interval } { "i2" interval } { "?" "a boolean or " { $link incomparable } } }
|
|
{ $description "Compares " { $snippet "i1" } " with " { $snippet "i2" } ", and outputs one of the following:"
|
|
{ $list
|
|
{ { $link t } " if every point in " { $snippet "i1" } " is greater than or equal to every point in " { $snippet "i2" } }
|
|
{ { $link f } " if every point in " { $snippet "i1" } " is less than every point in " { $snippet "i2" } }
|
|
{ { $link incomparable } " if neither of the above conditions hold" }
|
|
}
|
|
} ;
|
|
|
|
HELP: interval>
|
|
{ $values { "i1" interval } { "i2" interval } { "?" "a boolean or " { $link incomparable } } }
|
|
{ $description "Compares " { $snippet "i1" } " with " { $snippet "i2" } ", and outputs one of the following:"
|
|
{ $list
|
|
{ { $link t } " if every point in " { $snippet "i1" } " is greater than every point in " { $snippet "i2" } }
|
|
{ { $link f } " if every point in " { $snippet "i1" } " is less than or equal to every point in " { $snippet "i2" } }
|
|
{ { $link incomparable } " if neither of the above conditions hold" }
|
|
}
|
|
} ;
|
|
|
|
HELP: interval>points
|
|
{ $values { "int" interval } { "from" "a " { $snippet "{ point included? }" } " pair" } { "to" "a " { $snippet "{ point included? }" } " pair" } }
|
|
{ $description "Outputs both endpoints of the interval." } ;
|
|
|
|
HELP: assume<
|
|
{ $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
|
|
{ $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 } "." } ;
|
|
|
|
HELP: assume<=
|
|
{ $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
|
|
{ $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 } "." } ;
|
|
|
|
HELP: assume>
|
|
{ $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
|
|
{ $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 } "." } ;
|
|
|
|
HELP: assume>=
|
|
{ $values { "i1" interval } { "i2" interval } { "i3" "an " { $link interval } " or " { $link f } } }
|
|
{ $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 } "." } ;
|
|
|
|
HELP: integral-closure
|
|
{ $values { "i1" "an " { $link interval } " with integer end-points" } { "i2" "a closed " { $link interval } " with integer end-points" } }
|
|
{ $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)." } ;
|