doc/info/bitwise.texi

   1 The package @code{bitwise} provides functions that allow to manipulate
   2 bits of integer constants. As always maxima attempts to simplify the result
   3 of the operation if the actual value of a constant isn't known considering
   4 attributes that might be known for the variables, see the @mref{declare}
   5 mechanism.
   6
   7 @menu
   8 * Functions and Variables for bitwise::
   9 @end menu
  10
  11 @node Functions and Variables for bitwise, , Top, Top
  12 @section Functions and Variables for bitwise
  13
  14 @anchor{bit_not}
  15 @deffn {Function} bit_not (@var{int})
  16
  17 Inverts all bits of a signed integer. The result of this action reads
  18 @code{-int - 1}.
  19
  20 @c ===beg===
  21 @c load("bitwise")$
  22 @c bit_not(i);
  23 @c bit_not(bit_not(i));
  24 @c bit_not(3);
  25 @c bit_not(100);
  26 @c bit_not(-101);
  27 @c ===end===
  28 @example
  29 (%i1) load("bitwise")$
  30 @group
  31 (%i2) bit_not(i);
  32 (%o2)                      bit_not(i)
  33 @end group
  34 @group
  35 (%i3) bit_not(bit_not(i));
  36 (%o3)                           i
  37 @end group
  38 @group
  39 (%i4) bit_not(3);
  40 (%o4)                          - 4
  41 @end group
  42 @group
  43 (%i5) bit_not(100);
  44 (%o5)                         - 101
  45 @end group
  46 @group
  47 (%i6) bit_not(-101);
  48 (%o6)                          100
  49 @end group
  50 @end example
  51
  52 @opencatbox{Categories:}
  53 @category{Number theory}
  54 @category{Binary operations}
  55 @category{Package bitwise}
  56 @closecatbox
  57 @end deffn
  58
  59 @anchor{bit_and}
  60 @deffn {Function} bit_and (@var{int1}, ...)
  61
  62 This function calculates a bitwise @code{and} of two or more signed integers.
  63
  64 @c ===beg===
  65 @c load("bitwise")$
  66 @c bit_and(i,i);
  67 @c bit_and(i,i,i);
  68 @c bit_and(1,3);
  69 @c bit_and(-7,7);
  70 @c ===end===
  71 @example
  72 (%i1) load("bitwise")$
  73 @group
  74 (%i2) bit_and(i,i);
  75 (%o2)                           i
  76 @end group
  77 @group
  78 (%i3) bit_and(i,i,i);
  79 (%o3)                           i
  80 @end group
  81 @group
  82 (%i4) bit_and(1,3);
  83 (%o4)                           1
  84 @end group
  85 @group
  86 (%i5) bit_and(-7,7);
  87 (%o5)                           1
  88 @end group
  89 @end example
  90
  91 If it is known if one of the parameters to @code{bit_and} is even this information
  92 is taken into consideration by the function.
  93 @c ===beg===
  94 @c load("bitwise")$
  95 @c declare(e,even,o,odd);
  96 @c bit_and(1,e);
  97 @c bit_and(1,o);
  98 @c ===end===
  99 @example
 100 (%i1) load("bitwise")$
 101 @group
 102 (%i2) declare(e,even,o,odd);
 103 (%o2)                         done
 104 @end group
 105 @group
 106 (%i3) bit_and(1,e);
 107 (%o3)                           0
 108 @end group
 109 @group
 110 (%i4) bit_and(1,o);
 111 (%o4)                           1
 112 @end group
 113 @end example
 114
 115 @opencatbox{Categories:}
 116 @category{Number theory}
 117 @category{Binary operations}
 118 @category{Package bitwise}
 119 @closecatbox
 120 @end deffn
 121
 122 @anchor{bit_or}
 123 @deffn {Function} bit_or (@var{int1}, ...)
 124
 125 This function calculates a bitwise @code{or} of two or more signed integers.
 126
 127 @c ===beg===
 128 @c load("bitwise")$
 129 @c bit_or(i,i);
 130 @c bit_or(i,i,i);
 131 @c bit_or(1,3);
 132 @c bit_or(-7,7);
 133 @c ===end===
 134 @example
 135 (%i1) load("bitwise")$
 136 @group
 137 (%i2) bit_or(i,i);
 138 (%o2)                           i
 139 @end group
 140 @group
 141 (%i3) bit_or(i,i,i);
 142 (%o3)                           i
 143 @end group
 144 @group
 145 (%i4) bit_or(1,3);
 146 (%o4)                           3
 147 @end group
 148 @group
 149 (%i5) bit_or(-7,7);
 150 (%o5)                          - 1
 151 @end group
 152 @end example
 153
 154 If it is known if one of the parameters to @code{bit_or} is even this information
 155 is taken into consideration by the function.
 156 @c ===beg===
 157 @c load("bitwise")$
 158 @c declare(e,even,o,odd);
 159 @c bit_or(1,e);
 160 @c bit_or(1,o);
 161 @c ===end===
 162 @example
 163 (%i1) load("bitwise")$
 164 @group
 165 (%i2) declare(e,even,o,odd);
 166 (%o2)                         done
 167 @end group
 168 @group
 169 (%i3) bit_or(1,e);
 170 (%o3)                         e + 1
 171 @end group
 172 @group
 173 (%i4) bit_or(1,o);
 174 (%o4)                           o
 175 @end group
 176 @end example
 177
 178 @opencatbox{Categories:}
 179 @category{Number theory}
 180 @category{Binary operations}
 181 @category{Package bitwise}
 182 @closecatbox
 183 @end deffn
 184
 185 @anchor{bit_xor}
 186 @deffn {Function} bit_xor (@var{int1}, ...)
 187
 188 This function calculates a bitwise @code{or} of two or more signed integers.
 189
 190 @c ===beg===
 191 @c load("bitwise")$
 192 @c bit_xor(i,i);
 193 @c bit_xor(i,i,i);
 194 @c bit_xor(1,3);
 195 @c bit_xor(-7,7);
 196 @c ===end===
 197 @example
 198 (%i1) load("bitwise")$
 199 @group
 200 (%i2) bit_xor(i,i);
 201 (%o2)                           0
 202 @end group
 203 @group
 204 (%i3) bit_xor(i,i,i);
 205 (%o3)                           i
 206 @end group
 207 @group
 208 (%i4) bit_xor(1,3);
 209 (%o4)                           2
 210 @end group
 211 @group
 212 (%i5) bit_xor(-7,7);
 213 (%o5)                          - 2
 214 @end group
 215 @end example
 216
 217 If it is known if one of the parameters to @code{bit_xor} is even this information
 218 is taken into consideration by the function.
 219 @c ===beg===
 220 @c load("bitwise")$
 221 @c declare(e,even,o,odd);
 222 @c bit_xor(1,e);
 223 @c bit_xor(1,o);
 224 @c ===end===
 225 @example
 226 (%i1) load("bitwise")$
 227 @group
 228 (%i2) declare(e,even,o,odd);
 229 (%o2)                         done
 230 @end group
 231 @group
 232 (%i3) bit_xor(1,e);
 233 (%o3)                         e + 1
 234 @end group
 235 @group
 236 (%i4) bit_xor(1,o);
 237 (%o4)                         o - 1
 238 @end group
 239 @end example
 240
 241 @opencatbox{Categories:}
 242 @category{Number theory}
 243 @category{Binary operations}
 244 @category{Package bitwise}
 245 @closecatbox
 246 @end deffn
 247
 248
 249 @anchor{bit_lsh}
 250 @deffn {Function} bit_lsh (@var{int}, @var{nBits})
 251
 252 This function shifts all bits of the signed integer @code{int} to the left by
 253 @code{nBits} bits. The width of the integer is extended by @code{nBits} for
 254 this process. The result of @code{bit_lsh} therefore is @code{int * 2}.
 255
 256 @c ===beg===
 257 @c load("bitwise")$
 258 @c bit_lsh(0,1);
 259 @c bit_lsh(1,0);
 260 @c bit_lsh(1,1);
 261 @c bit_lsh(1,i);
 262 @c bit_lsh(-3,1);
 263 @c bit_lsh(-2,1);
 264 @c ===end===
 265 @example
 266 (%i1) load("bitwise")$
 267 @group
 268 (%i2) bit_lsh(0,1);
 269 (%o2)                           0
 270 @end group
 271 @group
 272 (%i3) bit_lsh(1,0);
 273 (%o3)                           1
 274 @end group
 275 @group
 276 (%i4) bit_lsh(1,1);
 277 (%o4)                           2
 278 @end group
 279 @group
 280 (%i5) bit_lsh(1,i);
 281 (%o5)                     bit_lsh(1, i)
 282 @end group
 283 @group
 284 (%i6) bit_lsh(-3,1);
 285 (%o6)                          - 6
 286 @end group
 287 @group
 288 (%i7) bit_lsh(-2,1);
 289 (%o7)                          - 4
 290 @end group
 291 @end example
 292 @opencatbox{Categories:}
 293 @category{Number theory}
 294 @category{Binary operations}
 295 @category{Package bitwise}
 296 @closecatbox
 297 @end deffn
 298
 299
 300 @anchor{bit_rsh}
 301 @deffn {Function} bit_rsh (@var{int}, @var{nBits})
 302
 303 This function shifts all bits of the signed integer @code{int} to the right by
 304 @code{nBits} bits. The width of the integer is reduced by @code{nBits} for
 305 this process.
 306
 307 @c ===beg===
 308 @c load("bitwise")$
 309 @c bit_rsh(0,1);
 310 @c bit_rsh(2,0);
 311 @c bit_rsh(2,1);
 312 @c bit_rsh(2,2);
 313 @c bit_rsh(-3,1);
 314 @c bit_rsh(-2,1);
 315 @c bit_rsh(-2,2);
 316 @c ===end===
 317 @example
 318 (%i1) load("bitwise")$
 319 @group
 320 (%i2) bit_rsh(0,1);
 321 (%o2)                           0
 322 @end group
 323 @group
 324 (%i3) bit_rsh(2,0);
 325 (%o3)                           2
 326 @end group
 327 @group
 328 (%i4) bit_rsh(2,1);
 329 (%o4)                           1
 330 @end group
 331 @group
 332 (%i5) bit_rsh(2,2);
 333 (%o5)                           0
 334 @end group
 335 @group
 336 (%i6) bit_rsh(-3,1);
 337 (%o6)                          - 2
 338 @end group
 339 @group
 340 (%i7) bit_rsh(-2,1);
 341 (%o7)                          - 1
 342 @end group
 343 @group
 344 (%i8) bit_rsh(-2,2);
 345 (%o8)                          - 1
 346 @end group
 347 @end example
 348 @opencatbox{Categories:}
 349 @category{Number theory}
 350 @category{Binary operations}
 351 @category{Package bitwise}
 352 @closecatbox
 353 @end deffn
 354
 355 @anchor{bit_length}
 356 @deffn {Function} bit_length (@var{int})
 357
 358 determines how many bits a variable needs to be long in order to store the
 359 number @code{int}. This function only operates on positive numbers.
 360
 361 @c ===beg===
 362 @c load("bitwise")$
 363 @c bit_length(0);
 364 @c bit_length(1);
 365 @c bit_length(7);
 366 @c bit_length(8);
 367 @c ===end===
 368 @example
 369 (%i1) load("bitwise")$
 370 @group
 371 (%i2) bit_length(0);
 372 (%o2)                           0
 373 @end group
 374 @group
 375 (%i3) bit_length(1);
 376 (%o3)                           1
 377 @end group
 378 @group
 379 (%i4) bit_length(7);
 380 (%o4)                           3
 381 @end group
 382 @group
 383 (%i5) bit_length(8);
 384 (%o5)                           4
 385 @end group
 386 @end example
 387 @opencatbox{Categories:}
 388 @category{Number theory}
 389 @category{Binary operations}
 390 @category{Package bitwise}
 391 @closecatbox
 392 @end deffn
 393
 394 @anchor{bit_onep}
 395 @deffn {Function} bit_onep (@var{int}, @var{nBit})
 396
 397 determines if bits @code{nBit} is set in the signed integer @code{int}.
 398
 399 @c ===beg===
 400 @c load("bitwise")$
 401 @c bit_onep(85,0);
 402 @c bit_onep(85,1);
 403 @c bit_onep(85,2);
 404 @c bit_onep(85,3);
 405 @c bit_onep(85,100);
 406 @c bit_onep(i,100);
 407 @c ===end===
 408 @example
 409 (%i1) load("bitwise")$
 410 @group
 411 (%i2) bit_onep(85,0);
 412 (%o2)                         true
 413 @end group
 414 @group
 415 (%i3) bit_onep(85,1);
 416 (%o3)                         false
 417 @end group
 418 @group
 419 (%i4) bit_onep(85,2);
 420 (%o4)                         true
 421 @end group
 422 @group
 423 (%i5) bit_onep(85,3);
 424 (%o5)                         false
 425 @end group
 426 @group
 427 (%i6) bit_onep(85,100);
 428 (%o6)                         false
 429 @end group
 430 @group
 431 (%i7) bit_onep(i,100);
 432 (%o7)                   bit_onep(i, 100)
 433 @end group
 434 @end example
 435
 436 For signed numbers the sign bit is interpreted to be more than @code{nBit} to the
 437 left of the leftmost bit of @code{int} that reads @code{1}.
 438 @c ===beg===
 439 @c load("bitwise")$
 440 @c bit_onep(-2,0);
 441 @c bit_onep(-2,1);
 442 @c bit_onep(-2,2);
 443 @c bit_onep(-2,3);
 444 @c bit_onep(-2,4);
 445 @c ===end===
 446 @example
 447 (%i1) load("bitwise")$
 448 @group
 449 (%i2) bit_onep(-2,0);
 450 (%o2)                         false
 451 @end group
 452 @group
 453 (%i3) bit_onep(-2,1);
 454 (%o3)                         true
 455 @end group
 456 @group
 457 (%i4) bit_onep(-2,2);
 458 (%o4)                         true
 459 @end group
 460 @group
 461 (%i5) bit_onep(-2,3);
 462 (%o5)                         true
 463 @end group
 464 @group
 465 (%i6) bit_onep(-2,4);
 466 (%o6)                         true
 467 @end group
 468 @end example
 469
 470
 471 If it is known if the number to be tested is even this information
 472 is taken into consideration by the function.
 473 @c ===beg===
 474 @c load("bitwise")$
 475 @c declare(e,even,o,odd);
 476 @c bit_onep(e,0);
 477 @c bit_onep(o,0);
 478 @c ===end===
 479 @example
 480 (%i1) load("bitwise")$
 481 @group
 482 (%i2) declare(e,even,o,odd);
 483 (%o2)                         done
 484 @end group
 485 @group
 486 (%i3) bit_onep(e,0);
 487 (%o3)                         false
 488 @end group
 489 @group
 490 (%i4) bit_onep(o,0);
 491 (%o4)                         true
 492 @end group
 493 @end example
 494
 495 @opencatbox{Categories:}
 496 @category{Number theory}
 497 @category{Binary operations}
 498 @category{Package bitwise}
 499 @closecatbox
 500 @end deffn