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