core/math/integers/integers-docs.factor

   1 USING: help.markup help.syntax math math.private ;
   2 IN: math.integers
   3
   4 ARTICLE: "integers" "Integers"
   5 { $subsection integer }
   6 "Integers come in two varieties -- fixnums and bignums. Fixnums fit in a machine word and are faster to manipulate; if the result of a fixnum operation is too large to fit in a fixnum, the result is upgraded to a bignum. Here is an example where two fixnums are multiplied yielding a bignum:"
   7 { $example "134217728 class ." "fixnum" }
   8 { $example "128 class ." "fixnum" }
   9 { $example "134217728 128 * ." "17179869184" }
  10 { $example "134217728 128 * class ." "bignum" }
  11 "Integers can be entered using a different base; see " { $link "syntax-numbers" } "."
  12 $nl
  13 "Integers can be tested for, and real numbers can be converted to integers:"
  14 { $subsection fixnum? }
  15 { $subsection bignum? }
  16 { $subsection >fixnum }
  17 { $subsection >integer }
  18 { $subsection >bignum }
  19 { $see-also "prettyprint-numbers" "modular-arithmetic" "bitwise-arithmetic" "integer-functions" "syntax-integers" } ;
  20
  21 ABOUT: "integers"
  22
  23 HELP: fixnum
  24 { $class-description "The class of fixnums, which are fixed-width integers small enough to fit in a machine cell. Because they are not heap-allocated, fixnums do not have object identity. Equality of tagged pointer bit patterns is actually " { $emphasis "value" } " equality for fixnums." } ;
  25
  26 HELP: >fixnum
  27 { $values { "x" real } { "n" fixnum } }
  28 { $description "Converts a real number to a fixnum, with a possible loss of precision and overflow." } ;
  29
  30 HELP: bignum
  31 { $class-description "The class of bignums, which are heap-allocated arbitrary-precision integers." } ;
  32
  33 HELP: >bignum
  34 { $values { "x" real } { "n" bignum } }
  35 { $description "Converts a real number to a bignum, with a possible loss of precision." } ;
  36
  37 HELP: >integer
  38 { $values { "x" real } { "n" bignum } }
  39 { $description "Converts a real number to an integer, with a possible loss of precision." } ;
  40
  41 HELP: integer
  42 { $class-description "The class of integers, which is a disjoint union of fixnums and bignums." } ;
  43
  44 HELP: even?
  45 { $values { "n" integer } { "?" "a boolean" } }
  46 { $description "Tests if an integer is even." } ;
  47
  48 HELP: odd?
  49 { $values { "n" integer } { "?" "a boolean" } }
  50 { $description "Tests if an integer is odd." } ;
  51
  52 ! Unsafe primitives
  53 HELP: fixnum+ ( x y -- z )
  54 { $values { "x" fixnum } { "y" fixnum } { "z" integer } }
  55 { $description "Primitive version of " { $link + } ". The result may overflow to a bignum." }
  56 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link + } " instead." } ;
  57
  58 HELP: fixnum- ( x y -- z )
  59 { $values { "x" fixnum } { "y" fixnum } { "z" integer } }
  60 { $description "Primitive version of " { $link - } ". The result may overflow to a bignum." }
  61 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link - } " instead." } ;
  62
  63 HELP: fixnum* ( x y -- z )
  64 { $values { "x" fixnum } { "y" fixnum } { "z" integer } }
  65 { $description "Primitive version of " { $link * } ". The result may overflow to a bignum." }
  66 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link * } " instead." } ;
  67
  68 HELP: fixnum/i ( x y -- z )
  69 { $values { "x" fixnum } { "y" fixnum } { "z" integer } }
  70 { $description "Primitive version of " { $link /i } ". The result may overflow to a bignum." }
  71 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link /i } " instead." } ;
  72
  73 HELP: fixnum-mod ( x y -- z )
  74 { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
  75 { $description "Primitive version of " { $link mod } ". The result always fits in a fixnum." }
  76 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link mod } " instead." } ;
  77
  78 HELP: fixnum/mod ( x y -- z w )
  79 { $values { "x" fixnum } { "y" fixnum } { "z" integer } { "w" fixnum } }
  80 { $description "Primitive version of " { $link /mod } ". The result may overflow to a bignum." }
  81 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link /mod } " instead." } ;
  82
  83 HELP: fixnum< ( x y -- ? )
  84 { $values { "x" fixnum } { "y" fixnum } { "?" "a boolean" } }
  85 { $description "Primitive version of " { $link < } ". The result may overflow to a bignum." }
  86 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link < } " instead." } ;
  87
  88 HELP: fixnum<= ( x y -- z )
  89 { $values { "x" fixnum } { "y" fixnum } { "z" integer } }
  90 { $description "Primitive version of " { $link <= } ". The result may overflow to a bignum." }
  91 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link <= } " instead." } ;
  92
  93 HELP: fixnum> ( x y -- ? )
  94 { $values { "x" fixnum } { "y" fixnum } { "?" "a boolean" } }
  95 { $description "Primitive version of " { $link > } ". The result may overflow to a bignum." }
  96 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link > } " instead." } ;
  97
  98 HELP: fixnum>= ( x y -- ? )
  99 { $values { "x" fixnum } { "y" fixnum } { "?" "a boolean" } }
 100 { $description "Primitive version of " { $link >= } ". The result may overflow to a bignum." }
 101 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link >= } " instead." } ;
 102
 103 HELP: fixnum-bitand ( x y -- z )
 104 { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
 105 { $description "Primitive version of " { $link bitand } ". The result always fits in a fixnum." }
 106 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitand } " instead." } ;
 107
 108 HELP: fixnum-bitor ( x y -- z )
 109 { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
 110 { $description "Primitive version of " { $link bitor } ". The result always fits in a fixnum." }
 111 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitor } " instead." } ;
 112
 113 HELP: fixnum-bitxor ( x y -- z )
 114 { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
 115 { $description "Primitive version of " { $link bitxor } ". The result always fits in a fixnum." }
 116 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitxor } " instead." } ;
 117
 118 HELP: fixnum-bitnot ( x -- y )
 119 { $values { "x" fixnum } { "y" fixnum } }
 120 { $description "Primitive version of " { $link bitnot } ". The result always fits in a fixnum." }
 121 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitnot } " instead." } ;
 122
 123 HELP: fixnum-shift ( x y -- z )
 124 { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
 125 { $description "Primitive version of " { $link shift } ". The result may overflow to a bignum." }
 126 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link shift } " instead." } ;
 127
 128 HELP: fixnum-shift-fast ( x y -- z )
 129 { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
 130 { $description "Primitive version of " { $link shift } ". Unlike " { $link fixnum-shift } ", does not perform an overflow check, so the result may be incorrect." }
 131 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link shift } " instead." } ;
 132
 133 HELP: fixnum+fast ( x y -- z )
 134 { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
 135 { $description "Primitive version of " { $link + } ". Unlike " { $link fixnum+ } ", does not perform an overflow check, so the result may be incorrect." }
 136 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link + } " instead." } ;
 137
 138 HELP: fixnum-fast ( x y -- z )
 139 { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
 140 { $description "Primitive version of " { $link - } ". Unlike " { $link fixnum- } ", does not perform an overflow check, so the result may be incorrect." }
 141 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link - } " instead." } ;
 142
 143 HELP: fixnum*fast ( x y -- z )
 144 { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
 145 { $description "Primitive version of " { $link * } ". Unlike " { $link fixnum* } ", does not perform an overflow check, so the result may be incorrect." }
 146 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link * } " instead." } ;
 147
 148 HELP: bignum+ ( x y -- z )
 149 { $values { "x" bignum } { "y" bignum } { "z" bignum } }
 150 { $description "Primitive version of " { $link + } "." }
 151 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link + } " instead." } ;
 152
 153 HELP: bignum- ( x y -- z )
 154 { $values { "x" bignum } { "y" bignum } { "z" bignum } }
 155 { $description "Primitive version of " { $link - } "." }
 156 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link - } " instead." } ;
 157
 158 HELP: bignum* ( x y -- z )
 159 { $values { "x" bignum } { "y" bignum } { "z" bignum } }
 160 { $description "Primitive version of " { $link * } "." }
 161 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link * } " instead." } ;
 162
 163 HELP: bignum/i ( x y -- z )
 164 { $values { "x" bignum } { "y" bignum } { "z" bignum } }
 165 { $description "Primitive version of " { $link /i } "." }
 166 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link /i } " instead." } ;
 167
 168 HELP: bignum-mod ( x y -- z )
 169 { $values { "x" bignum } { "y" bignum } { "z" bignum } }
 170 { $description "Primitive version of " { $link mod } "." }
 171 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link mod } " instead." } ;
 172
 173 HELP: bignum/mod ( x y -- z w )
 174 { $values { "x" bignum } { "y" bignum } { "z" bignum } { "w" bignum } }
 175 { $description "Primitive version of " { $link /mod } "." }
 176 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link /mod } " instead." } ;
 177
 178 HELP: bignum< ( x y -- ? )
 179 { $values { "x" bignum } { "y" bignum } { "?" "a boolean" } }
 180 { $description "Primitive version of " { $link < } "." }
 181 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link < } " instead." } ;
 182
 183 HELP: bignum<= ( x y -- ? )
 184 { $values { "x" bignum } { "y" bignum } { "?" "a boolean" } }
 185 { $description "Primitive version of " { $link <= } "." }
 186 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link <= } " instead." } ;
 187
 188 HELP: bignum> ( x y -- ? )
 189 { $values { "x" bignum } { "y" bignum } { "?" "a boolean" } }
 190 { $description "Primitive version of " { $link > } "." }
 191 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link > } " instead." } ;
 192
 193 HELP: bignum>= ( x y -- ? )
 194 { $values { "x" bignum } { "y" bignum } { "?" "a boolean" } }
 195 { $description "Primitive version of " { $link >= } "." }
 196 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link >= } " instead." } ;
 197
 198 HELP: bignum= ( x y -- ? )
 199 { $values { "x" bignum } { "y" bignum } { "?" "a boolean" } }
 200 { $description "Primitive version of " { $link number= } "." }
 201 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link number= } " instead." } ;
 202
 203 HELP: bignum-bitand ( x y -- z )
 204 { $values { "x" bignum } { "y" bignum } { "z" bignum } }
 205 { $description "Primitive version of " { $link bitand } "." }
 206 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitand } " instead." } ;
 207
 208 HELP: bignum-bitor ( x y -- z )
 209 { $values { "x" bignum } { "y" bignum } { "z" bignum } }
 210 { $description "Primitive version of " { $link bitor } "." }
 211 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitor } " instead." } ;
 212
 213 HELP: bignum-bitxor ( x y -- z )
 214 { $values { "x" bignum } { "y" bignum } { "z" bignum } }
 215 { $description "Primitive version of " { $link bitxor } "." }
 216 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitxor } " instead." } ;
 217
 218 HELP: bignum-bitnot ( x -- y )
 219 { $values { "x" bignum } { "y" bignum } }
 220 { $description "Primitive version of " { $link bitnot } "." }
 221 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitnot } " instead." } ;
 222
 223 HELP: bignum-shift ( x y -- z )
 224 { $values { "x" bignum } { "y" bignum } { "z" bignum } }
 225 { $description "Primitive version of " { $link shift } "." }
 226 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link shift } " instead." } ;