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 { $subsections 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 "USE: classes" "67108864 class-of ." "fixnum" }
   8 { $example "USE: classes" "128 class-of ." "fixnum" }
   9 { $example "134217728 128 * ." "17179869184" }
  10 { $example "USE: classes" "1 128 shift class-of ." "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 { $subsections
  15     fixnum?
  16     bignum?
  17     >fixnum
  18     >integer
  19     >bignum
  20 }
  21 { $see-also "prettyprint-numbers" "modular-arithmetic" "bitwise-arithmetic" "integer-functions" "syntax-integers" } ;
  22
  23 ABOUT: "integers"
  24
  25 HELP: fixnum
  26 { $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." } ;
  27
  28 HELP: >fixnum
  29 { $values { "x" real } { "n" fixnum } }
  30 { $description "Converts a real number to a fixnum, with a possible loss of precision and overflow." } ;
  31
  32 HELP: bignum
  33 { $class-description "The class of bignums, which are heap-allocated arbitrary-precision integers." } ;
  34
  35 HELP: >bignum
  36 { $values { "x" real } { "n" bignum } }
  37 { $description "Converts a real number to a bignum, with a possible loss of precision." } ;
  38
  39 HELP: >integer
  40 { $values { "x" real } { "n" bignum } }
  41 { $description "Converts a real number to an integer, with a possible loss of precision." } ;
  42
  43 HELP: integer
  44 { $class-description "The class of integers, which is a disjoint union of fixnums and bignums." } ;
  45
  46 HELP: even?
  47 { $values { "n" integer } { "?" "a boolean" } }
  48 { $description "Tests if an integer is even." } ;
  49
  50 HELP: odd?
  51 { $values { "n" integer } { "?" "a boolean" } }
  52 { $description "Tests if an integer is odd." } ;
  53
  54 ! Unsafe primitives
  55 HELP: fixnum+
  56 { $values { "x" fixnum } { "y" fixnum } { "z" integer } }
  57 { $description "Primitive version of " { $link + } ". The result may overflow to a bignum." }
  58 { $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." } ;
  59
  60 HELP: fixnum-
  61 { $values { "x" fixnum } { "y" fixnum } { "z" integer } }
  62 { $description "Primitive version of " { $link - } ". The result may overflow to a bignum." }
  63 { $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." } ;
  64
  65 HELP: fixnum*
  66 { $values { "x" fixnum } { "y" fixnum } { "z" integer } }
  67 { $description "Primitive version of " { $link * } ". The result may overflow to a bignum." }
  68 { $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." } ;
  69
  70 HELP: fixnum/i
  71 { $values { "x" fixnum } { "y" fixnum } { "z" integer } }
  72 { $description "Primitive version of " { $link /i } ". The result may overflow to a bignum." }
  73 { $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." } ;
  74
  75 HELP: fixnum-mod
  76 { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
  77 { $description "Primitive version of " { $link mod } ". The result always fits in a fixnum." }
  78 { $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." } ;
  79
  80 HELP: fixnum/mod
  81 { $values { "x" fixnum } { "y" fixnum } { "z" integer } { "w" fixnum } }
  82 { $description "Primitive version of " { $link /mod } ". The result may overflow to a bignum." }
  83 { $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." } ;
  84
  85 HELP: fixnum<
  86 { $values { "x" fixnum } { "y" fixnum } { "?" "a boolean" } }
  87 { $description "Primitive version of " { $link < } ". The result may overflow to a bignum." }
  88 { $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." } ;
  89
  90 HELP: fixnum<=
  91 { $values { "x" fixnum } { "y" fixnum } { "z" integer } }
  92 { $description "Primitive version of " { $link <= } ". The result may overflow to a bignum." }
  93 { $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." } ;
  94
  95 HELP: fixnum>
  96 { $values { "x" fixnum } { "y" fixnum } { "?" "a boolean" } }
  97 { $description "Primitive version of " { $link > } ". The result may overflow to a bignum." }
  98 { $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." } ;
  99
 100 HELP: fixnum>=
 101 { $values { "x" fixnum } { "y" fixnum } { "?" "a boolean" } }
 102 { $description "Primitive version of " { $link >= } ". The result may overflow to a bignum." }
 103 { $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." } ;
 104
 105 HELP: fixnum-bitand
 106 { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
 107 { $description "Primitive version of " { $link bitand } ". The result always fits in a fixnum." }
 108 { $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." } ;
 109
 110 HELP: fixnum-bitor
 111 { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
 112 { $description "Primitive version of " { $link bitor } ". The result always fits in a fixnum." }
 113 { $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." } ;
 114
 115 HELP: fixnum-bitxor
 116 { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
 117 { $description "Primitive version of " { $link bitxor } ". The result always fits in a fixnum." }
 118 { $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." } ;
 119
 120 HELP: fixnum-bitnot
 121 { $values { "x" fixnum } { "y" fixnum } }
 122 { $description "Primitive version of " { $link bitnot } ". The result always fits in a fixnum." }
 123 { $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." } ;
 124
 125 HELP: fixnum-shift
 126 { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
 127 { $description "Primitive version of " { $link shift } ". The result may overflow to a bignum." }
 128 { $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." } ;
 129
 130 HELP: fixnum-shift-fast
 131 { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
 132 { $description "Primitive version of " { $link shift } ". Unlike " { $link fixnum-shift } ", does not perform an overflow check, so the result may be incorrect." }
 133 { $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." } ;
 134
 135 HELP: fixnum+fast
 136 { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
 137 { $description "Primitive version of " { $link + } ". Unlike " { $link fixnum+ } ", does not perform an overflow check, so the result may be incorrect." }
 138 { $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." } ;
 139
 140 HELP: fixnum-fast
 141 { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
 142 { $description "Primitive version of " { $link - } ". Unlike " { $link fixnum- } ", does not perform an overflow check, so the result may be incorrect." }
 143 { $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." } ;
 144
 145 HELP: fixnum*fast
 146 { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
 147 { $description "Primitive version of " { $link * } ". Unlike " { $link fixnum* } ", does not perform an overflow check, so the result may be incorrect." }
 148 { $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." } ;
 149
 150 HELP: bignum+
 151 { $values { "x" bignum } { "y" bignum } { "z" bignum } }
 152 { $description "Primitive version of " { $link + } "." }
 153 { $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." } ;
 154
 155 HELP: bignum-
 156 { $values { "x" bignum } { "y" bignum } { "z" bignum } }
 157 { $description "Primitive version of " { $link - } "." }
 158 { $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." } ;
 159
 160 HELP: bignum*
 161 { $values { "x" bignum } { "y" bignum } { "z" bignum } }
 162 { $description "Primitive version of " { $link * } "." }
 163 { $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." } ;
 164
 165 HELP: bignum/i
 166 { $values { "x" bignum } { "y" bignum } { "z" bignum } }
 167 { $description "Primitive version of " { $link /i } "." }
 168 { $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." } ;
 169
 170 HELP: bignum-mod
 171 { $values { "x" bignum } { "y" bignum } { "z" bignum } }
 172 { $description "Primitive version of " { $link mod } "." }
 173 { $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." } ;
 174
 175 HELP: bignum/mod
 176 { $values { "x" bignum } { "y" bignum } { "z" bignum } { "w" bignum } }
 177 { $description "Primitive version of " { $link /mod } "." }
 178 { $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." } ;
 179
 180 HELP: bignum<
 181 { $values { "x" bignum } { "y" bignum } { "?" "a boolean" } }
 182 { $description "Primitive version of " { $link < } "." }
 183 { $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." } ;
 184
 185 HELP: bignum<=
 186 { $values { "x" bignum } { "y" bignum } { "?" "a boolean" } }
 187 { $description "Primitive version of " { $link <= } "." }
 188 { $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." } ;
 189
 190 HELP: bignum>
 191 { $values { "x" bignum } { "y" bignum } { "?" "a boolean" } }
 192 { $description "Primitive version of " { $link > } "." }
 193 { $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." } ;
 194
 195 HELP: bignum>=
 196 { $values { "x" bignum } { "y" bignum } { "?" "a boolean" } }
 197 { $description "Primitive version of " { $link >= } "." }
 198 { $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." } ;
 199
 200 HELP: bignum=
 201 { $values { "x" bignum } { "y" bignum } { "?" "a boolean" } }
 202 { $description "Primitive version of " { $link number= } "." }
 203 { $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." } ;
 204
 205 HELP: bignum-bitand
 206 { $values { "x" bignum } { "y" bignum } { "z" bignum } }
 207 { $description "Primitive version of " { $link bitand } "." }
 208 { $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." } ;
 209
 210 HELP: bignum-bitor
 211 { $values { "x" bignum } { "y" bignum } { "z" bignum } }
 212 { $description "Primitive version of " { $link bitor } "." }
 213 { $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." } ;
 214
 215 HELP: bignum-bitxor
 216 { $values { "x" bignum } { "y" bignum } { "z" bignum } }
 217 { $description "Primitive version of " { $link bitxor } "." }
 218 { $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." } ;
 219
 220 HELP: bignum-bitnot
 221 { $values { "x" bignum } { "y" bignum } }
 222 { $description "Primitive version of " { $link bitnot } "." }
 223 { $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." } ;
 224
 225 HELP: bignum-shift
 226 { $values { "x" bignum } { "y" bignum } { "z" bignum } }
 227 { $description "Primitive version of " { $link shift } "." }
 228 { $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." } ;