basis/math/vectors/vectors-docs.factor

   1 USING: help.markup help.syntax math math.functions sequences ;
   2 IN: math.vectors
   3
   4 ARTICLE: "math-vectors-arithmetic" "Vector arithmetic"
   5 "Vector/vector binary operations:"
   6 { $subsections
   7     v+
   8     v-
   9     v+-
  10     v*
  11     v/
  12 }
  13 "Vector unary operations:"
  14 { $subsections
  15     vneg
  16     vabs
  17     vsqrt
  18     vfloor
  19     vceiling
  20     vtruncate
  21 }
  22 "Vector/scalar and scalar/vector binary operations:"
  23 { $subsections
  24     vneg
  25     v*n
  26     n*v
  27     v/n
  28     n/v
  29     v+n
  30     n+v
  31     v-n
  32     n-v
  33 }
  34 "Saturated arithmetic (only on " { $link "specialized-arrays" } "):"
  35 { $subsections
  36     vs+
  37     vs-
  38     vs*
  39 }
  40 "Inner product and norm:"
  41 { $subsections
  42     v.
  43     norm
  44     norm-sq
  45     normalize
  46 }
  47 "Comparing entire vectors:"
  48 { $subsections
  49     distance
  50     v~
  51 } ;
  52
  53 ARTICLE: "math-vectors-shuffle" "Vector shuffling, packing, and unpacking"
  54 { $notes
  55 "These operations are primarily meant to be used with " { $vocab-link "math.vectors.simd" } " types. The software fallbacks for types not supported by hardware will not perform well."
  56 }
  57 $nl
  58 { $subsection vshuffle }
  59 { $subsection vbroadcast }
  60 { $subsection hlshift }
  61 { $subsection hrshift }
  62 { $subsection vmerge }
  63 { $subsection (vmerge) } ;
  64
  65 ARTICLE: "math-vectors-logic" "Vector component- and bit-wise logic"
  66 { $notes
  67 "See " { $link "math-vectors-simd-logic" } " for notes about using comparison and logical operations with SIMD vector types."
  68 }
  69 $nl
  70 "Element comparisons:"
  71 { $subsections
  72     v<
  73     v<=
  74     v=
  75     v>=
  76     v>
  77     vunordered?
  78     vmax
  79     vmin
  80     vsupremum
  81     vinfimum
  82 }
  83 "Bitwise operations:"
  84 { $subsections
  85     vbitand
  86     vbitandn
  87     vbitor
  88     vbitxor
  89     vbitnot
  90     vlshift
  91     vrshift
  92 }
  93 "Element logical operations:"
  94 { $subsections
  95     vand
  96     vandn
  97     vor
  98     vxor
  99     vnot
 100     v?
 101 }
 102 "Entire vector tests:"
 103 { $subsections
 104     vall?
 105     vany?
 106     vnone?
 107 }
 108 "Element shuffling:"
 109 { $subsections vshuffle } ;
 110
 111 ARTICLE: "math-vectors-misc" "Miscellaneous vector functions"
 112 { $subsections
 113     trilerp
 114     bilerp
 115     vlerp
 116     vnlerp
 117     vbilerp
 118 } ;
 119
 120 ARTICLE: "math-vectors-simd-logic" "Componentwise logic with SIMD vectors"
 121 "Processor SIMD units supported by the " { $vocab-link "math.vectors.simd" } " vocabulary represent boolean values as bitmasks, where a true result's binary representation is all ones and a false representation is all zeroes. This is the format in which results from comparison words such as " { $link v= } " return their results and in which logic and test words such as " { $link vand } " and " { $link vall? } " take their inputs when working with SIMD types. For a float vector, false will manifest itself as " { $snippet "0.0" } " and true as a " { $link POSTPONE: NAN: } " literal with a string of set bits in its payload:"
 122 { $example
 123 """USING: math.vectors math.vectors.simd prettyprint ;
 124 FROM: alien.c-types => float ;
 125 SIMD: float
 126
 127 float-4{ 1.0 2.0 3.0 0/0. } float-4{ 1.0 -2.0 3.0 0/0. } v= ."""
 128 """float-4{ NAN: fffffe0000000 0.0 NAN: fffffe0000000 0.0 }"""
 129 }
 130 "For an integer vector, false will manifest as " { $snippet "0" } " and true as " { $snippet "-1" } " (for signed vectors) or the largest representable value of the element type (for unsigned vectors):"
 131 { $example
 132 """USING: math.vectors math.vectors.simd prettyprint alien.c-types ;
 133 SIMD: int
 134 SIMD: uchar
 135
 136 int-4{ 1 2 3 0 } int-4{ 1 -2 3 4 } v=
 137 uchar-16{  0  1  2  3  4  5 6 7 8 9 10 11 12 13 14 15 }
 138 uchar-16{ 15 14 13 12 11 10 9 8 7 6  5  4  3  2  1  0 } v<
 139 [ . ] bi@"""
 140 """int-4{ -1 0 -1 0 }
 141 uchar-16{ 255 255 255 255 255 255 255 255 0 0 0 0 0 0 0 0 }"""
 142 }
 143 "This differs from Factor's native representation of boolean values, where " { $link f } " is false and every other value (including " { $snippet "0" } " and " { $snippet "0.0" } ") is true. To make it easy to construct literal SIMD masks, " { $link t } " and " { $link f } " are accepted inside SIMD literal syntax and expand to the proper true or false representation for the underlying type:"
 144 { $example
 145 """USING: math.vectors math.vectors.simd prettyprint alien.c-types ;
 146 SIMD: int
 147
 148 int-4{ f f t f } ."""
 149 """int-4{ 0 0 -1 0 }""" }
 150 "However, extracting an element from a boolean SIMD vector with " { $link nth } " will not yield a valid Factor boolean. This is not generally a problem, since the results of vector comparisons are meant to be consumed by subsequent vector logical and test operations, which will accept SIMD values in the native boolean format."
 151 $nl
 152 "Providing a SIMD boolean vector with element values other than the proper true and false representations as an input to the vector logical or test operations is undefined. Do not count on operations such as " { $link vall? } " or " { $link v? } " using bitwise operations to construct their results."
 153 $nl
 154 "This applies to the output of the following element comparison words: "
 155 { $list
 156 { $link v< }
 157 { $link v<= }
 158 { $link v= }
 159 { $link v>= }
 160 { $link v> }
 161 { $link vunordered? }
 162 }
 163 "This likewise applies to the " { $snippet "mask" } " argument of " { $link v? } " and to the inputs and outputs of the following element logic words:"
 164 { $list
 165 { $link vand }
 166 { $link vandn }
 167 { $link vor }
 168 { $link vxor }
 169 { $link vnot }
 170 }
 171 "Finally, this applies to the inputs of these vector test words:"
 172 { $list
 173 { $link vall? }
 174 { $link vany? }
 175 { $link vnone? }
 176 } ;
 177
 178 ARTICLE: "math-vectors" "Vector operations"
 179 "Any Factor sequence can be used to represent a mathematical vector, however for best performance, the sequences defined by the " { $vocab-link "specialized-arrays" } " and " { $vocab-link "math.vectors.simd" } " vocabularies should be used."
 180 { $subsections
 181     "math-vectors-arithmetic"
 182     "math-vectors-logic"
 183     "math-vectors-shuffle"
 184     "math-vectors-misc"
 185 } ;
 186
 187 ABOUT: "math-vectors"
 188
 189 HELP: vneg
 190 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
 191 { $description "Negates each element of " { $snippet "u" } "." } ;
 192
 193 HELP: vabs
 194 { $values { "u" "a sequence of numbers" } { "v" "a sequence of non-negative real numbers" } }
 195 { $description "Takes the absolute value of each element of " { $snippet "u" } "." } ;
 196
 197 HELP: vsqrt
 198 { $values { "u" "a sequence of non-negative real numbers" } { "v" "a sequence of non-negative real numbers" } }
 199 { $description "Takes the square root of each element of " { $snippet "u" } "." }
 200 { $warning "For performance reasons, this does not work with negative inputs, unlike " { $link sqrt } "." } ;
 201
 202 HELP: vfloor
 203 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } }
 204 { $description "Takes the " { $link floor } " of each element of " { $snippet "u" } "." } ;
 205
 206 HELP: vceiling
 207 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } }
 208 { $description "Takes the " { $link ceiling } " of each element of " { $snippet "u" } "." } ;
 209
 210 HELP: vtruncate
 211 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } }
 212 { $description "Truncates each element of " { $snippet "u" } "." } ;
 213
 214 HELP: n+v
 215 { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
 216 { $description "Adds " { $snippet "n" } " to each element of " { $snippet "u" } "." } ;
 217
 218 HELP: v+n
 219 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
 220 { $description "Adds " { $snippet "n" } " to each element of " { $snippet "u" } "." } ;
 221
 222 HELP: n-v
 223 { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
 224 { $description "Subtracts each element of " { $snippet "u" } " from " { $snippet "n" } "." } ;
 225
 226 HELP: v-n
 227 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
 228 { $description "Subtracts " { $snippet "n" } " from each element of " { $snippet "u" } "." } ;
 229
 230 HELP: n*v
 231 { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
 232 { $description "Multiplies each element of " { $snippet "u" } " by " { $snippet "n" } "." } ;
 233
 234 HELP: v*n
 235 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
 236 { $description "Multiplies each element of " { $snippet "u" } " by " { $snippet "n" } "." } ;
 237
 238 HELP: n/v
 239 { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
 240 { $description "Divides " { $snippet "n" } " by each element of " { $snippet "u" } "." }
 241 { $errors "May throw an error if a division by zero occurs; see " { $link "division-by-zero" } "." } ;
 242
 243 HELP: v/n
 244 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
 245 { $description "Divides each element of " { $snippet "u" } " by " { $snippet "n" } "." }
 246 { $errors "May throw an error if a division by zero occurs; see " { $link "division-by-zero" } "." } ;
 247
 248 HELP: v+
 249 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 250 { $description "Adds " { $snippet "u" } " and " { $snippet "v" } " component-wise." } ;
 251
 252 HELP: v-
 253 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 254 { $description "Subtracts " { $snippet "v" } " from " { $snippet "u" } " component-wise." } ;
 255
 256 HELP: v+-
 257 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 258 { $description "Adds and subtracts alternate elements of " { $snippet "v" } " and " { $snippet "u" } " component-wise." }
 259 { $examples
 260     { $example
 261         "USING: math.vectors prettyprint ;"
 262         "{ 1 2 3 } { 2 3 2 } v+- ."
 263         "{ -1 5 1 }"
 264     }
 265 } ;
 266
 267 HELP: [v-]
 268 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 269 { $description "Subtracts " { $snippet "v" } " from " { $snippet "u" } " component-wise; any components which become negative are set to zero." } ;
 270
 271 HELP: v*
 272 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 273 { $description "Multiplies " { $snippet "u" } " and " { $snippet "v" } " component-wise." } ;
 274
 275 HELP: v/
 276 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 277 { $description "Divides " { $snippet "u" } " by " { $snippet "v" } " component-wise." }
 278 { $errors "May throw an error if a division by zero occurs; see " { $link "division-by-zero" } "." } ;
 279
 280 HELP: vmax
 281 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 282 { $description "Creates a sequence where each element is the maximum of the corresponding elements from " { $snippet "u" } " and " { $snippet "v" } "." }
 283 { $examples { $example "USING: math.vectors prettyprint ;" "{ 1 2 5 } { -7 6 3 } vmax ." "{ 1 6 5 }" } } ;
 284
 285 HELP: vmin
 286 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 287 { $description "Creates a sequence where each element is the minimum of the corresponding elements from " { $snippet "u" } " and " { $snippet "v" } "." }
 288 { $examples { $example "USING: math.vectors prettyprint ;" "{ 1 2 5 } { -7 6 3 } vmin ." "{ -7 2 3 }" } } ;
 289
 290 HELP: v.
 291 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "x" "a real number" } }
 292 { $description "Computes the dot product of two vectors." } ;
 293
 294 HELP: vs+
 295 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 296 { $description "Adds " { $snippet "u" } " and " { $snippet "v" } " component-wise with saturation." }
 297 { $examples
 298     "With saturation:"
 299     { $example
 300         "USING: alien.c-types math.vectors prettyprint specialized-arrays ;"
 301         "SPECIALIZED-ARRAY: uchar"
 302         "uchar-array{ 100 200 150 } uchar-array{ 70 70 70 } vs+ ."
 303         "uchar-array{ 170 255 220 }"
 304     }
 305     "Without saturation:"
 306     { $example
 307         "USING: alien.c-types math.vectors prettyprint specialized-arrays ;"
 308         "SPECIALIZED-ARRAY: uchar"
 309         "uchar-array{ 100 200 150 } uchar-array{ 70 70 70 } v+ ."
 310         "uchar-array{ 170 14 220 }"
 311     }
 312 } ;
 313
 314 HELP: vs-
 315 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 316 { $description "Subtracts " { $snippet "v" } " from " { $snippet "u" } " component-wise with saturation." } ;
 317
 318 HELP: vs*
 319 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 320 { $description "Multiplies " { $snippet "u" } " and " { $snippet "v" } " component-wise with saturation." } ;
 321
 322 HELP: vbitand
 323 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 324 { $description "Takes the bitwise and of " { $snippet "u" } " and " { $snippet "v" } " component-wise." }
 325 { $notes "Unlike " { $link bitand } ", this word may be used on a specialized array of floats or doubles, in which case the bitwise representation of the floating point numbers is operated upon." } ;
 326
 327 HELP: vbitandn
 328 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 329 { $description "Takes the bitwise and-not of " { $snippet "u" } " and " { $snippet "v" } " component-wise, where " { $snippet "x and-not y" } " is defined as " { $snippet "not(x) and y" } "." }
 330 { $notes "This word may be used on a specialized array of floats or doubles, in which case the bitwise representation of the floating point numbers is operated upon." } ;
 331
 332 HELP: vbitor
 333 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 334 { $description "Takes the bitwise or of " { $snippet "u" } " and " { $snippet "v" } " component-wise." }
 335 { $notes "Unlike " { $link bitor } ", this word may be used on a specialized array of floats or doubles, in which case the bitwise representation of the floating point numbers is operated upon." } ;
 336
 337 HELP: vbitxor
 338 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 339 { $description "Takes the bitwise exclusive or of " { $snippet "u" } " and " { $snippet "v" } " component-wise." }
 340 { $notes "Unlike " { $link bitxor } ", this word may be used on a specialized array of floats or doubles, in which case the bitwise representation of the floating point numbers is operated upon." } ;
 341
 342 HELP: vlshift
 343 { $values { "u" "a sequence of integers" } { "n" "a non-negative integer" } { "w" "a sequence of integers" } }
 344 { $description "Shifts each element of " { $snippet "u" } " to the left by " { $snippet "n" } " bits." }
 345 { $notes "Undefined behavior will result if " { $snippet "n" } " is negative." } ;
 346
 347 HELP: vrshift
 348 { $values { "u" "a sequence of integers" } { "n" "a non-negative integer" } { "w" "a sequence of integers" } }
 349 { $description "Shifts each element of " { $snippet "u" } " to the right by " { $snippet "n" } " bits." }
 350 { $notes "Undefined behavior will result if " { $snippet "n" } " is negative." } ;
 351
 352 HELP: hlshift
 353 { $values { "u" "a SIMD array" } { "n" "a non-negative integer" } { "w" "a SIMD array" } }
 354 { $description "Shifts the entire SIMD array to the left by " { $snippet "n" } " bytes, filling the vacated right-hand bits with zeroes. This word may only be used in a context where the compiler can statically infer that the input is a SIMD array." } ;
 355
 356 HELP: hrshift
 357 { $values { "u" "a SIMD array" } { "n" "a non-negative integer" } { "w" "a SIMD array" } }
 358 { $description "Shifts the entire SIMD array to the right by " { $snippet "n" } " bytes, filling the vacated left-hand bits with zeroes. This word may only be used in a context where the compiler can statically infer that the input is a SIMD array." } ;
 359
 360 HELP: vmerge
 361 { $values { "u" "a sequence" } { "v" "a sequence" } { "w" "a sequence" } }
 362 { $description "Creates a new sequence of the same type as and twice the length of " { $snippet "u" } " and " { $snippet "v" } " by interleaving the elements of " { $snippet "u" } " and " { $snippet "v" } "." }
 363 { $examples
 364 { $example """USING: kernel math.vectors prettyprint ;
 365
 366 { "A" "B" "C" "D" } { "1" "2" "3" "4" } vmerge ."""
 367 """{ "A" "1" "B" "2" "C" "3" "D" "4" }"""
 368 } } ;
 369
 370 HELP: (vmerge)
 371 { $values { "u" "a sequence" } { "v" "a sequence" } { "h" "a sequence" } { "t" "a sequence" } }
 372 { $description "Creates two new sequences of the same type and size as " { $snippet "u" } " and " { $snippet "v" } " by interleaving the elements of " { $snippet "u" } " and " { $snippet "v" } "." }
 373 { $notes "For hardware-supported SIMD vector types this word compiles to a single instruction per output value." }
 374 { $examples
 375 { $example """USING: kernel math.vectors prettyprint ;
 376
 377 { "A" "B" "C" "D" } { "1" "2" "3" "4" } (vmerge) [ . ] bi@"""
 378 """{ "A" "1" "B" "2" }
 379 { "C" "3" "D" "4" }"""
 380 } } ;
 381
 382 HELP: (vmerge-head)
 383 { $values { "u" "a sequence" } { "v" "a sequence" } { "h" "a sequence" } }
 384 { $description "Creates a new sequence of the same type and size as " { $snippet "u" } " and " { $snippet "v" } " by interleaving the elements from the first half of " { $snippet "u" } " and " { $snippet "v" } "." }
 385 { $notes "For hardware-supported SIMD vector types this word compiles to a single instruction." }
 386 { $examples
 387 { $example """USING: kernel math.vectors prettyprint ;
 388
 389 { "A" "B" "C" "D" } { "1" "2" "3" "4" } (vmerge-head) ."""
 390 """{ "A" "1" "B" "2" }"""
 391 } } ;
 392
 393 HELP: (vmerge-tail)
 394 { $values { "u" "a sequence" } { "v" "a sequence" } { "t" "a sequence" } }
 395 { $description "Creates a new sequence of the same type and size as " { $snippet "u" } " and " { $snippet "v" } " by interleaving the elements from the tail half of " { $snippet "u" } " and " { $snippet "v" } "." }
 396 { $notes "For hardware-supported SIMD vector types this word compiles to a single instruction." }
 397 { $examples
 398 { $example """USING: kernel math.vectors prettyprint ;
 399
 400 { "A" "B" "C" "D" } { "1" "2" "3" "4" } (vmerge-tail) ."""
 401 """{ "C" "3" "D" "4" }"""
 402 } } ;
 403
 404 { vmerge (vmerge) (vmerge-head) (vmerge-tail) } related-words
 405
 406 HELP: vbroadcast
 407 { $values { "u" "a SIMD array" } { "n" "a non-negative integer" } { "v" "a SIMD array" } }
 408 { $description "Outputs a new SIMD array of the same type as " { $snippet "u" } " where every element is equal to the " { $snippet "n" } "th element of " { $snippet "u" } "." }
 409 { $examples
 410     { $example
 411         "USING: alien.c-types math.vectors math.vectors.simd" "prettyprint ;"
 412         "SIMD: int"
 413         "int-4{ 69 42 911 13 } 2 vbroadcast ."
 414         "int-4{ 911 911 911 911 }"
 415     }
 416 } ;
 417
 418 HELP: vshuffle
 419 { $values { "u" "a SIMD array" } { "perm" "an array of integers" } { "v" "a SIMD array" } }
 420 { $description "Permutes the elements of a SIMD array. Duplicate entries are allowed in the permutation." }
 421 { $examples
 422     { $example
 423         "USING: alien.c-types math.vectors math.vectors.simd" "prettyprint ;"
 424         "SIMD: int"
 425         "int-4{ 69 42 911 13 } { 1 3 2 3 } vshuffle ."
 426         "int-4{ 42 13 911 13 }"
 427     }
 428 } ;
 429
 430 HELP: norm-sq
 431 { $values { "v" "a sequence of numbers" } { "x" "a non-negative real number" } }
 432 { $description "Computes the squared length of a mathematical vector." } ;
 433
 434 HELP: norm
 435 { $values { "v" "a sequence of numbers" } { "x" "a non-negative real number" } }
 436 { $description "Computes the length of a mathematical vector." } ;
 437
 438 HELP: normalize
 439 { $values { "u" "a sequence of numbers, not all zero" } { "v" "a sequence of numbers" } }
 440 { $description "Outputs a vector with the same direction as " { $snippet "u" } " but length 1." } ;
 441
 442 HELP: distance
 443 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "x" "a non-negative real number" } }
 444 { $description "Outputs the Euclidean distance between two vectors." } ;
 445
 446 HELP: set-axis
 447 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "axis" "a sequence of 0/1" } { "w" "a sequence of numbers" } }
 448 { $description "Using " { $snippet "w" } " as a template, creates a new sequence containing corresponding elements from " { $snippet "u" } " in place of 0, and corresponding elements from " { $snippet "v" } " in place of 1." }
 449 { $examples { $example "USING: math.vectors prettyprint ;" "{ 1 2 3 } { 4 5 6 } { 0 1 0 } set-axis ." "{ 1 5 3 }" } } ;
 450
 451 HELP: v<
 452 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 453 { $description "Compares each corresponding element of " { $snippet "u" } " and " { $snippet "v" } ", returning " { $link t } " in the result vector when the former is less than the latter or " { $link f } " otherwise." }
 454 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean results when using SIMD types." } ;
 455
 456 HELP: v<=
 457 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 458 { $description "Compares each corresponding element of " { $snippet "u" } " and " { $snippet "v" } ", returning " { $link t } " in the result vector when the former is less than or equal to the latter or " { $link f } " otherwise." }
 459 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean results when using SIMD types." } ;
 460
 461 HELP: v=
 462 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 463 { $description "Compares each corresponding element of " { $snippet "u" } " and " { $snippet "v" } ", returning " { $link t } " in the result vector when they are equal or " { $link f } " otherwise." }
 464 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean results when using SIMD types." } ;
 465
 466 HELP: v>
 467 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 468 { $description "Compares each corresponding element of " { $snippet "u" } " and " { $snippet "v" } ", returning " { $link t } " in the result vector when the former is greater than the latter or " { $link f } " otherwise." }
 469 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean results when using SIMD types." } ;
 470
 471 HELP: v>=
 472 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 473 { $description "Compares each corresponding element of " { $snippet "u" } " and " { $snippet "v" } ", returning " { $link t } " in the result vector when the former is greater than or equal to the latter or " { $link f } " otherwise." }
 474 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean results when using SIMD types." } ;
 475
 476 HELP: vunordered?
 477 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 478 { $description "Compares each corresponding element of " { $snippet "u" } " and " { $snippet "v" } ", returning " { $link t } " in the result vector when either value is Not-a-Number or " { $link f } " otherwise." }
 479 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean results when using SIMD types." } ;
 480
 481 HELP: vand
 482 { $values { "u" "a sequence of booleans" } { "v" "a sequence of booleans" } { "w" "a sequence of booleans" } }
 483 { $description "Takes the logical AND of each corresponding element of " { $snippet "u" } " and " { $snippet "v" } "." }
 484 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types." } ;
 485
 486 HELP: vandn
 487 { $values { "u" "a sequence of booleans" } { "v" "a sequence of booleans" } { "w" "a sequence of booleans" } }
 488 { $description "Takes the logical AND-NOT of each corresponding element of " { $snippet "u" } " and " { $snippet "v" } ", where " { $snippet "x AND-NOT y" } " is defined as " { $snippet "NOT(x) AND y" } "." }
 489 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types." } ;
 490
 491 HELP: vor
 492 { $values { "u" "a sequence of booleans" } { "v" "a sequence of booleans" } { "w" "a sequence of booleans" } }
 493 { $description "Takes the logical OR of each corresponding element of " { $snippet "u" } " and " { $snippet "v" } "." }
 494 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types." } ;
 495
 496 HELP: vxor
 497 { $values { "u" "a sequence of booleans" } { "v" "a sequence of booleans" } { "w" "a sequence of booleans" } }
 498 { $description "Takes the logical XOR of each corresponding element of " { $snippet "u" } " and " { $snippet "v" } "." }
 499 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types." } ;
 500
 501 HELP: vnot
 502 { $values { "u" "a sequence of booleans" } { "w" "a sequence of booleans" } }
 503 { $description "Takes the logical NOT of each element of " { $snippet "u" } "." }
 504 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types." } ;
 505
 506 HELP: v?
 507 { $values { "mask" "a sequence of booleans" } { "true" "a sequence of numbers" } { "false" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 508 { $description "Creates a new sequence by selecting elements from the " { $snippet "true" } " and " { $snippet "false" } " sequences based on whether the corresponding bits of the " { $snippet "mask" } " sequence are set or not." }
 509 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types." } ;
 510
 511 HELP: vany?
 512 { $values { "v" "a sequence of booleans" } { "?" "a boolean" } }
 513 { $description "Returns true if any element of " { $snippet "v" } " is true." }
 514 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs when using SIMD types." } ;
 515
 516 HELP: vall?
 517 { $values { "v" "a sequence of booleans" } { "?" "a boolean" } }
 518 { $description "Returns true if every element of " { $snippet "v" } " is true." }
 519 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs when using SIMD types." } ;
 520
 521 HELP: vnone?
 522 { $values { "v" "a sequence of booleans" } { "?" "a boolean" } }
 523 { $description "Returns true if every element of " { $snippet "v" } " is false." }
 524 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs when using SIMD types." } ;
 525
 526 { 2map v+ v- v* v/ } related-words
 527
 528 { 2reduce v. } related-words
 529
 530 { vs+ vs- vs* } related-words
 531
 532 { v< v<= v= v> v>= vunordered? vand vor vxor vnot vany? vall? vnone? v? } related-words
 533
 534 { vbitand vbitandn vbitor vbitxor vbitnot } related-words