basis/math/ratios/ratios-docs.factor

   1 USING: help.markup help.syntax math math.private
   2 math.ratios.private ;
   3 IN: math.ratios
   4
   5 ARTICLE: "rationals" "Rational numbers"
   6 { $subsection ratio }
   7 "When we add, subtract or multiply any two integers, the result is always an integer. However, dividing a numerator by a denominator that is not an integral divisor of the denominator yields a ratio:"
   8 { $example "1210 11 / ." "110" }
   9 { $example "100 330 / ." "10/33" }
  10 { $example "14 10 / ." "1+2/5" }
  11 "Ratios are printed and can be input literally in the form above. Ratios are always reduced to lowest terms by factoring out the greatest common divisor of the numerator and denominator. A ratio with a denominator of 1 becomes an integer. Division with a denominator of 0 throws an error."
  12 $nl
  13 "Ratios behave just like any other number -- all numerical operations work as you would expect."
  14 { $example "1/2 1/3 + ." "5/6" }
  15 { $example "100 6 / 3 * ." "50" }
  16 "Ratios can be taken apart:"
  17 { $subsection numerator }
  18 { $subsection denominator }
  19 { $subsection >fraction }
  20 { $see-also "syntax-ratios" } ;
  21
  22 ABOUT: "rationals"
  23
  24 HELP: ratio
  25 { $class-description "The class of rational numbers with denominator not equal to 1." } ;
  26
  27 HELP: rational
  28 { $class-description "The class of rational numbers, a disjoint union of integers and ratios." } ;
  29
  30 HELP: numerator
  31 { $values { "a/b" rational } { "a" integer } }
  32 { $description "Outputs the numerator of a rational number. Acts as the identity on integers." } ;
  33
  34 HELP: denominator
  35 { $values { "a/b" rational } { "b" "a positive integer" } }
  36 { $description "Outputs the denominator of a rational number. Always outputs 1 with integers." } ;
  37
  38 HELP: fraction>
  39 { $values { "a" integer } { "b" "a positive integer" } { "a/b" rational } }
  40 { $description "Creates a new ratio, or outputs the numerator if the denominator is 1. This word does not reduce the fraction to lowest terms, and should not be called directly; use " { $link / } " instead." } ;
  41
  42 HELP: >fraction
  43 { $values { "a/b" rational } { "a" integer } { "b" "a positive integer" } }
  44 { $description "Extracts the numerator and denominator of a rational number." } ;
  45
  46 HELP: 2>fraction
  47 { $values { "a/b" rational } { "c/d" rational } { "a" integer } { "c" integer } { "b" "a positive integer" } { "d" "a positive integer" } }
  48 { $description "Extracts the numerator and denominator of two rational numbers at once." } ;
  49
  50 HELP: <ratio> ( a b -- a/b )
  51 { $values { "a" integer } { "b" integer } { "a/b" "a ratio" } }
  52 { $description "Primitive ratio constructor. User code should call " { $link / } " to create ratios instead." } ;