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 { $subsection v+ }
   7 { $subsection v- }
   8 { $subsection v+- }
   9 { $subsection v* }
  10 { $subsection v/ }
  11 "Vector unary operations:"
  12 { $subsection vneg }
  13 { $subsection vabs }
  14 { $subsection vsqrt }
  15 { $subsection vfloor }
  16 { $subsection vceiling }
  17 { $subsection vtruncate }
  18 "Vector/scalar and scalar/vector binary operations:"
  19 { $subsection vneg }
  20 { $subsection v*n }
  21 { $subsection n*v }
  22 { $subsection v/n }
  23 { $subsection n/v }
  24 { $subsection v+n }
  25 { $subsection n+v }
  26 { $subsection v-n }
  27 { $subsection n-v }
  28 "Saturated arithmetic (only on " { $link "specialized-arrays" } "):"
  29 { $subsection vs+ }
  30 { $subsection vs- }
  31 { $subsection vs* }
  32 "Inner product and norm:"
  33 { $subsection v. }
  34 { $subsection norm }
  35 { $subsection norm-sq }
  36 { $subsection normalize }
  37 "Comparing entire vectors:"
  38 { $subsection distance }
  39 { $subsection v~ } ;
  40
  41 ARTICLE: "math-vectors-shuffle" "Vector shuffling, packing, and unpacking"
  42 { $notes
  43 "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."
  44 }
  45 $nl
  46 { $subsection vshuffle }
  47 { $subsection vbroadcast }
  48 { $subsection hlshift }
  49 { $subsection hrshift } ;
  50
  51 ARTICLE: "math-vectors-logic" "Vector component- and bit-wise logic"
  52 { $notes
  53 "See " { $link "math-vectors-simd-logic" } " for notes about using comparison and logical operations with SIMD vector types."
  54 }
  55 $nl
  56 "Element comparisons:"
  57 { $subsection v< }
  58 { $subsection v<= }
  59 { $subsection v= }
  60 { $subsection v>= }
  61 { $subsection v> }
  62 { $subsection vunordered? }
  63 { $subsection vmax }
  64 { $subsection vmin }
  65 { $subsection vsupremum }
  66 { $subsection vinfimum }
  67 "Bitwise operations:"
  68 { $subsection vbitand }
  69 { $subsection vbitandn }
  70 { $subsection vbitor }
  71 { $subsection vbitxor }
  72 { $subsection vbitnot }
  73 { $subsection vlshift }
  74 { $subsection vrshift }
  75 "Element logical operations:"
  76 { $subsection vand }
  77 { $subsection vandn }
  78 { $subsection vor }
  79 { $subsection vxor }
  80 { $subsection vnot }
  81 { $subsection v? }
  82 "Vector tests:"
  83 { $subsection vall? }
  84 { $subsection vany? }
  85 { $subsection vnone? } ;
  86
  87 ARTICLE: "math-vectors-misc" "Miscellaneous vector functions"
  88 { $subsection trilerp }
  89 { $subsection bilerp }
  90 { $subsection vlerp }
  91 { $subsection vnlerp }
  92 { $subsection vbilerp } ;
  93
  94 ARTICLE: "math-vectors-simd-logic" "Componentwise logic with SIMD vectors"
  95 "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:"
  96 { $example
  97 """USING: math.vectors math.vectors.simd prettyprint ;
  98 FROM: alien.c-types => float ;
  99 SIMD: float
 100
 101 float-4{ 1.0 2.0 3.0 0/0. } float-4{ 1.0 -2.0 3.0 0/0. } v= ."""
 102 """float-4{ NAN: fffffe0000000 0.0 NAN: fffffe0000000 0.0 }"""
 103 }
 104 "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):"
 105 { $example
 106 """USING: math.vectors math.vectors.simd prettyprint alien.c-types ;
 107 SIMD: int
 108 SIMD: uchar
 109
 110 int-4{ 1 2 3 0 } int-4{ 1 -2 3 4 } v=
 111 uchar-16{  0  1  2  3  4  5 6 7 8 9 10 11 12 13 14 15 }
 112 uchar-16{ 15 14 13 12 11 10 9 8 7 6  5  4  3  2  1  0 } v<
 113 [ . ] bi@"""
 114 """int-4{ -1 0 -1 0 }
 115 uchar-16{ 255 255 255 255 255 255 255 255 0 0 0 0 0 0 0 0 }"""
 116 }
 117 "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:"
 118 { $example
 119 """USING: math.vectors math.vectors.simd prettyprint alien.c-types ;
 120 SIMD: int
 121
 122 int-4{ f f t f } ."""
 123 """int-4{ 0 0 -1 0 }""" }
 124 "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."
 125 $nl
 126 "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."
 127 $nl
 128 "This applies to the output of the following element comparison words: "
 129 { $list
 130 { $link v< }
 131 { $link v<= }
 132 { $link v= }
 133 { $link v>= }
 134 { $link v> }
 135 { $link vunordered? }
 136 }
 137 "This likewise applies to the " { $snippet "mask" } " argument of " { $link v? } " and to the inputs and outputs of the following element logic words:"
 138 { $list
 139 { $link vand }
 140 { $link vandn }
 141 { $link vor }
 142 { $link vxor }
 143 { $link vnot }
 144 }
 145 "Finally, this applies to the inputs of these vector test words:"
 146 { $list
 147 { $link vall? }
 148 { $link vany? }
 149 { $link vnone? }
 150 } ;
 151
 152 ARTICLE: "math-vectors" "Vector operations"
 153 "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."
 154 { $subsection "math-vectors-arithmetic" }
 155 { $subsection "math-vectors-logic" }
 156 { $subsection "math-vectors-shuffle" }
 157 { $subsection "math-vectors-misc" } ;
 158
 159 ABOUT: "math-vectors"
 160
 161 HELP: vneg
 162 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
 163 { $description "Negates each element of " { $snippet "u" } "." } ;
 164
 165 HELP: vabs
 166 { $values { "u" "a sequence of numbers" } { "v" "a sequence of non-negative real numbers" } }
 167 { $description "Takes the absolute value of each element of " { $snippet "u" } "." } ;
 168
 169 HELP: vsqrt
 170 { $values { "u" "a sequence of non-negative real numbers" } { "v" "a sequence of non-negative real numbers" } }
 171 { $description "Takes the square root of each element of " { $snippet "u" } "." }
 172 { $warning "For performance reasons, this does not work with negative inputs, unlike " { $link sqrt } "." } ;
 173
 174 HELP: vfloor
 175 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } }
 176 { $description "Takes the " { $link floor } " of each element of " { $snippet "u" } "." } ;
 177
 178 HELP: vceiling
 179 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } }
 180 { $description "Takes the " { $link ceiling } " of each element of " { $snippet "u" } "." } ;
 181
 182 HELP: vtruncate
 183 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } }
 184 { $description "Truncates each element of " { $snippet "u" } "." } ;
 185
 186 HELP: n+v
 187 { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
 188 { $description "Adds " { $snippet "n" } " to each element of " { $snippet "u" } "." } ;
 189
 190 HELP: v+n
 191 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
 192 { $description "Adds " { $snippet "n" } " to each element of " { $snippet "u" } "." } ;
 193
 194 HELP: n-v
 195 { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
 196 { $description "Subtracts each element of " { $snippet "u" } " from " { $snippet "n" } "." } ;
 197
 198 HELP: v-n
 199 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
 200 { $description "Subtracts " { $snippet "n" } " from each element of " { $snippet "u" } "." } ;
 201
 202 HELP: n*v
 203 { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
 204 { $description "Multiplies each element of " { $snippet "u" } " by " { $snippet "n" } "." } ;
 205
 206 HELP: v*n
 207 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
 208 { $description "Multiplies each element of " { $snippet "u" } " by " { $snippet "n" } "." } ;
 209
 210 HELP: n/v
 211 { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
 212 { $description "Divides " { $snippet "n" } " by each element of " { $snippet "u" } "." }
 213 { $errors "May throw an error if a division by zero occurs; see " { $link "division-by-zero" } "." } ;
 214
 215 HELP: v/n
 216 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
 217 { $description "Divides each element of " { $snippet "u" } " by " { $snippet "n" } "." }
 218 { $errors "May throw an error if a division by zero occurs; see " { $link "division-by-zero" } "." } ;
 219
 220 HELP: v+
 221 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 222 { $description "Adds " { $snippet "u" } " and " { $snippet "v" } " component-wise." } ;
 223
 224 HELP: v-
 225 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 226 { $description "Subtracts " { $snippet "v" } " from " { $snippet "u" } " component-wise." } ;
 227
 228 HELP: v+-
 229 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 230 { $description "Adds and subtracts alternate elements of " { $snippet "v" } " and " { $snippet "u" } " component-wise." }
 231 { $examples
 232     { $example
 233         "USING: math.vectors prettyprint ;"
 234         "{ 1 2 3 } { 2 3 2 } v+- ."
 235         "{ -1 5 1 }"
 236     }
 237 } ;
 238
 239 HELP: [v-]
 240 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 241 { $description "Subtracts " { $snippet "v" } " from " { $snippet "u" } " component-wise; any components which become negative are set to zero." } ;
 242
 243 HELP: v*
 244 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 245 { $description "Multiplies " { $snippet "u" } " and " { $snippet "v" } " component-wise." } ;
 246
 247 HELP: v/
 248 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 249 { $description "Divides " { $snippet "u" } " by " { $snippet "v" } " component-wise." }
 250 { $errors "May throw an error if a division by zero occurs; see " { $link "division-by-zero" } "." } ;
 251
 252 HELP: vmax
 253 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 254 { $description "Creates a sequence where each element is the maximum of the corresponding elements from " { $snippet "u" } " and " { $snippet "v" } "." }
 255 { $examples { $example "USING: math.vectors prettyprint ;" "{ 1 2 5 } { -7 6 3 } vmax ." "{ 1 6 5 }" } } ;
 256
 257 HELP: vmin
 258 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 259 { $description "Creates a sequence where each element is the minimum of the corresponding elements from " { $snippet "u" } " and " { $snippet "v" } "." }
 260 { $examples { $example "USING: math.vectors prettyprint ;" "{ 1 2 5 } { -7 6 3 } vmin ." "{ -7 2 3 }" } } ;
 261
 262 HELP: v.
 263 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "x" "a real number" } }
 264 { $description "Computes the dot product of two vectors." } ;
 265
 266 HELP: vs+
 267 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 268 { $description "Adds " { $snippet "u" } " and " { $snippet "v" } " component-wise with saturation." }
 269 { $examples
 270     "With saturation:"
 271     { $example
 272         "USING: alien.c-types math.vectors prettyprint specialized-arrays ;"
 273         "SPECIALIZED-ARRAY: uchar"
 274         "uchar-array{ 100 200 150 } uchar-array{ 70 70 70 } vs+ ."
 275         "uchar-array{ 170 255 220 }"
 276     }
 277     "Without saturation:"
 278     { $example
 279         "USING: alien.c-types math.vectors prettyprint specialized-arrays ;"
 280         "SPECIALIZED-ARRAY: uchar"
 281         "uchar-array{ 100 200 150 } uchar-array{ 70 70 70 } v+ ."
 282         "uchar-array{ 170 14 220 }"
 283     }
 284 } ;
 285
 286 HELP: vs-
 287 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 288 { $description "Subtracts " { $snippet "v" } " from " { $snippet "u" } " component-wise with saturation." } ;
 289
 290 HELP: vs*
 291 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 292 { $description "Multiplies " { $snippet "u" } " and " { $snippet "v" } " component-wise with saturation." } ;
 293
 294 HELP: vbitand
 295 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 296 { $description "Takes the bitwise and of " { $snippet "u" } " and " { $snippet "v" } " component-wise." }
 297 { $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." } ;
 298
 299 HELP: vbitandn
 300 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 301 { $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" } "." }
 302 { $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." } ;
 303
 304 HELP: vbitor
 305 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 306 { $description "Takes the bitwise or of " { $snippet "u" } " and " { $snippet "v" } " component-wise." }
 307 { $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." } ;
 308
 309 HELP: vbitxor
 310 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 311 { $description "Takes the bitwise exclusive or of " { $snippet "u" } " and " { $snippet "v" } " component-wise." }
 312 { $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." } ;
 313
 314 HELP: vlshift
 315 { $values { "u" "a sequence of integers" } { "n" "a non-negative integer" } { "w" "a sequence of integers" } }
 316 { $description "Shifts each element of " { $snippet "u" } " to the left by " { $snippet "n" } " bits." }
 317 { $notes "Undefined behavior will result if " { $snippet "n" } " is negative." } ;
 318
 319 HELP: vrshift
 320 { $values { "u" "a sequence of integers" } { "n" "a non-negative integer" } { "w" "a sequence of integers" } }
 321 { $description "Shifts each element of " { $snippet "u" } " to the right by " { $snippet "n" } " bits." }
 322 { $notes "Undefined behavior will result if " { $snippet "n" } " is negative." } ;
 323
 324 HELP: hlshift
 325 { $values { "u" "a SIMD array" } { "n" "a non-negative integer" } { "w" "a SIMD array" } }
 326 { $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." } ;
 327
 328 HELP: hrshift
 329 { $values { "u" "a SIMD array" } { "n" "a non-negative integer" } { "w" "a SIMD array" } }
 330 { $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." } ;
 331
 332 HELP: vbroadcast
 333 { $values { "u" "a SIMD array" } { "n" "a non-negative integer" } { "v" "a SIMD array" } }
 334 { $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" } "." }
 335 { $examples
 336     { $example
 337         "USING: alien.c-types math.vectors math.vectors.simd" "prettyprint ;"
 338         "SIMD: int"
 339         "int-4{ 69 42 911 13 } 2 vbroadcast ."
 340         "int-4{ 911 911 911 911 }"
 341     }
 342 } ;
 343
 344 HELP: vshuffle
 345 { $values { "u" "a SIMD array" } { "perm" "an array of integers" } { "v" "a SIMD array" } }
 346 { $description "Permutes the elements of a SIMD array. Duplicate entries are allowed in the permutation." }
 347 { $examples
 348     { $example
 349         "USING: alien.c-types math.vectors math.vectors.simd" "prettyprint ;"
 350         "SIMD: int"
 351         "int-4{ 69 42 911 13 } { 1 3 2 3 } vshuffle ."
 352         "int-4{ 42 13 911 13 }"
 353     }
 354 } ;
 355
 356 HELP: norm-sq
 357 { $values { "v" "a sequence of numbers" } { "x" "a non-negative real number" } }
 358 { $description "Computes the squared length of a mathematical vector." } ;
 359
 360 HELP: norm
 361 { $values { "v" "a sequence of numbers" } { "x" "a non-negative real number" } }
 362 { $description "Computes the length of a mathematical vector." } ;
 363
 364 HELP: normalize
 365 { $values { "u" "a sequence of numbers, not all zero" } { "v" "a sequence of numbers" } }
 366 { $description "Outputs a vector with the same direction as " { $snippet "u" } " but length 1." } ;
 367
 368 HELP: distance
 369 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "x" "a non-negative real number" } }
 370 { $description "Outputs the Euclidean distance between two vectors." } ;
 371
 372 HELP: set-axis
 373 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "axis" "a sequence of 0/1" } { "w" "a sequence of numbers" } }
 374 { $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." }
 375 { $examples { $example "USING: math.vectors prettyprint ;" "{ 1 2 3 } { 4 5 6 } { 0 1 0 } set-axis ." "{ 1 5 3 }" } } ;
 376
 377 HELP: v<
 378 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 379 { $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." }
 380 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean results when using SIMD types." } ;
 381
 382 HELP: v<=
 383 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 384 { $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." }
 385 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean results when using SIMD types." } ;
 386
 387 HELP: v=
 388 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 389 { $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." }
 390 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean results when using SIMD types." } ;
 391
 392 HELP: v>
 393 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 394 { $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." }
 395 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean results when using SIMD types." } ;
 396
 397 HELP: v>=
 398 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 399 { $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." }
 400 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean results when using SIMD types." } ;
 401
 402 HELP: vunordered?
 403 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 404 { $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." }
 405 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean results when using SIMD types." } ;
 406
 407 HELP: vand
 408 { $values { "u" "a sequence of booleans" } { "v" "a sequence of booleans" } { "w" "a sequence of booleans" } }
 409 { $description "Takes the logical AND of each corresponding element of " { $snippet "u" } " and " { $snippet "v" } "." }
 410 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types." } ;
 411
 412 HELP: vandn
 413 { $values { "u" "a sequence of booleans" } { "v" "a sequence of booleans" } { "w" "a sequence of booleans" } }
 414 { $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" } "." }
 415 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types." } ;
 416
 417 HELP: vor
 418 { $values { "u" "a sequence of booleans" } { "v" "a sequence of booleans" } { "w" "a sequence of booleans" } }
 419 { $description "Takes the logical OR of each corresponding element of " { $snippet "u" } " and " { $snippet "v" } "." }
 420 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types." } ;
 421
 422 HELP: vxor
 423 { $values { "u" "a sequence of booleans" } { "v" "a sequence of booleans" } { "w" "a sequence of booleans" } }
 424 { $description "Takes the logical XOR of each corresponding element of " { $snippet "u" } " and " { $snippet "v" } "." }
 425 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types." } ;
 426
 427 HELP: vnot
 428 { $values { "u" "a sequence of booleans" } { "w" "a sequence of booleans" } }
 429 { $description "Takes the logical NOT of each element of " { $snippet "u" } "." }
 430 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types." } ;
 431
 432 HELP: v?
 433 { $values { "mask" "a sequence of booleans" } { "true" "a sequence of numbers" } { "false" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 434 { $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." }
 435 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types." } ;
 436
 437 HELP: vany?
 438 { $values { "v" "a sequence of booleans" } { "?" "a boolean" } }
 439 { $description "Returns true if any element of " { $snippet "v" } " is true." }
 440 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs when using SIMD types." } ;
 441
 442 HELP: vall?
 443 { $values { "v" "a sequence of booleans" } { "?" "a boolean" } }
 444 { $description "Returns true if every element of " { $snippet "v" } " is true." }
 445 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs when using SIMD types." } ;
 446
 447 HELP: vnone?
 448 { $values { "v" "a sequence of booleans" } { "?" "a boolean" } }
 449 { $description "Returns true if every element of " { $snippet "v" } " is false." }
 450 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs when using SIMD types." } ;
 451
 452 { 2map v+ v- v* v/ } related-words
 453
 454 { 2reduce v. } related-words
 455
 456 { vs+ vs- vs* } related-words
 457
 458 { v< v<= v= v> v>= vunordered? vand vor vxor vnot vany? vall? vnone? v? } related-words
 459
 460 { vbitand vbitandn vbitor vbitxor vbitnot } related-words