Template:Main:Vector/Methods: Difference between revisions

← Older edit

VisualWikitext

Latest revision as of 23:41, 29 October 2024

Math operations

Mathematical operations that apply to all vectors, such as computing their length

length

Mathematical definition

Computes the Euclidean norm of the vector.

Computes the length of a vector.

Arguments	Return Type
`length()`	number

lengthSquared

Computes the length of a vector, squared. Due to the nature of the length calculation, this is a little bit faster than length.

Arguments	Return Type
`lengthSquared()`	number

dot

Computes the dot product between two vectors. The argument must be the same type as the target vector.

Arguments	Return Type
`dot(Vector other)`	number

add

Mathematical definition

Performs vector addition with another vector, storing the result in this vector.

Adds the values from this vector and another vector of the same size, and writes them to this vector. To create a new instance from the sum, see + (operator).

Arguments	Return Type
`add(Vector other)`	self Vector

subtract

Mathematical definition

Performs vector subtraction with another vector (in the order this - other), storing the result in this vector.

Subtracts the passed vector of the same size from this vector, and writes the result to this vector. To create a new instance from the difference, see - (operator).

Arguments	Return Type
`subtract(Vector other)`	self Vector

offset

Adds factor to all components of this vector. To create a new instance from the result, see + (operator) or - (operator).

Arguments	Return Type
`offset(number factor)`	self Vector

multiply

Multiplies vectors of the same size by multiplying their components. The result is written to this vector.

Arguments	Return Type
`multiply(Vector other)`	self Vector

transform

Mathematical definition

Multiplies the provided matrix with this vector, in the order M * V, and writes the resulting vector to this vector.

Applies a matrix transformation to this vector. Equivalent to multiplying the matrix by the vector. The matrix must be the same size as the vector; the following are valid:

Vector2:transform(Matrix2)
Vector3:transform(Matrix3)
Vector4:transform(Matrix4)

Arguments	Return Type
`transform(Matrix mat)`	self Vector

divide

Divides vectors of the same size by dividing their components. The result is written to this vector.

Arguments	Return Type
`divide(Vector other)`	self Vector

reduce

For each component in this vector, perform the positive modulo operation on it and the equivalent component in the other vector.

Arguments	Return Type
`reduce(Vector other)`	self Vector

scale

Multiplies each component in this vector by factor.

Arguments	Return Type
`scale(number factor)`	self Vector

normalize

Normalizes this vector in-place. After this operation, the length of the vector will be 1, unless the length is currently 0. If this vector's length is 0, then no normalization will occur.

Arguments	Return Type
`normalize()`	self Vector

clampLength

Scales this vector such that its length is within the bounds specified by minLength and maxLength. If this vector's length is 0, no scaling will be performed, even if minLength is greater than 0. If this vector's length is already within the specified bounds, no scaling will be performed.

Both minLength and maxLength can be omitted or set to nil, resulting in no lower or upper bound on the length of the vector.

Arguments	Return Type
`clampLength(number \| nil minLength, number \| nil maxLength)`	self Vector

clamped

Copies this vector, then clamps its length. See clampLength for details.

Arguments	Return Type
`clamped(number \| nil minLength, number \| nil maxLength)`	new Vector

normalized

Copies this vector, then normalizes it. See normalize for details.

Arguments	Return Type
`normalized()`	new Vector

toRad

Returns a copy of this vector, scaled by a factor of (pi / 180). If this vector represents a rotation in degrees, the result will be a rotation in radians.

See also toDeg.

Arguments	Return Type
`toRad()`	new Vector

toDeg

Returns a copy of this vector, scaled by a factor of (180 / pi). If this vector represents a rotation in radians, the result will be a rotation in degrees.

See also toRad.

Arguments	Return Type
`toDeg()`	new Vector

floor

Returns a copy of this vector with every component floored.

Arguments	Return Type
`floor()`	new Vector

ceil

Returns a copy of this vector with every component ceiling-ed.

Arguments	Return Type
`ceil()`	new Vector

Utility methods

copy

Creates a copy of this vector. Creating a copy will make a new Vector with the same size and values, but which is disconnected from the original. This means that methods like set or add which modify the vector they are called with will not modify copies.

Arguments	Return Type
`copy()`	new Vector

set

Assigns the values from another vector of the same size to this vector in place. To create a new instance, see copy.

Arguments	Return Type
`set(Vector other)`	self Vector

reset

Sets all the components of this vector to 0.

Arguments	Return Type
`reset()`	self Vector

applyFunc

Calls the provided function f on every component, and sets this vector's components to the return values of the function.

The function receives the following values as arguments: first, the value as a number, then the index (integer, 1 is x, 2 is y, etc.) The function is expected to return a number.

Arguments	Return Type
`applyFunc(function f)`	self Vector

local A = vec(1, 2, 3)
-- cube the values
A:applyFunc(function(value, index) return value*value*value end)
print(A) -- {1, 8, 27}

@@ Line 101: / Line 101: @@
 ----
 {{sidebox
-  |[[wikipedia:Matrix multiplication#Matrix times vector|Multiplies]] the provided matrix with this vector, in the order ''M * V'', and writes the resulting vector to this vector.
+  |[[wikipedia:Matrix multiplication#Matrix times vector|Multiplies]] the provided matrix with this vector, in the order ''M&nbsp;*&nbsp;V'', and writes the resulting vector to this vector.
   |Mathematical definition
 }}
@@ Line 234: / Line 234: @@
 |}
-=== Utility methods ===
+==== floor ====
-==== copy ====
 ----
-Creates a copy of this vector. Creating a copy will make a new Vector with the same size and values, but which is disconnected from the original. This means that methods like [[#set|set]] or [[#add|add]] which modify the vector they are called with will not modify copies.
+Returns a [[#copy|copy]] of this vector with every component floored.
 {| class="wikitable"
 ! Arguments !! Return Type
 |-
-| <code>copy()</code>
+| <code>floor()</code>
 | new {{type|{{{T|Vector}}}}}
 |}
-==== set ====
+==== ceil ====
 ----
-Assigns the values from another vector of the same size to this vector in place. To create a new instance, see [[#copy|copy]].
+Returns a [[#copy|copy]] of this vector with every component ceiling-ed.
 {| class="wikitable"
 ! Arguments !! Return Type
 |-
-| <code>set({{type|{{{T|Vector}}}}} other)</code>
+| <code>ceil()</code>
-| self {{type|{{{T|Vector}}}}}
-|}
-=== Operators ===
-Lua operators, such as <code>+</code>, <code>-</code>, and <code>*</code>, apply to vectors and have different results.
-==== + (operator) ====
-===== With two vectors <span id="meta_add_vv"></span> =====
-----
-Adds the values from this vector and another vector of the same size. The result is a ''new'' vector of the same size which holds the sum.
-{| class="wikitable"
-! Left !! Right !! Result
-|-
-| {{type|{{{T|Vector}}}}}
-| {{type|{{{T|Vector}}}}}
 | new {{type|{{{T|Vector}}}}}
 |}
-<syntaxhighlight lang="lua">
+=== Utility methods ===
-local a = vec(1, 2, 3)
-local b = vec(4, 4, 6)
-print(a + b, a, b) -- {5, 6, 9}  {1, 2, 3}  {4, 4, 6}
-</syntaxhighlight>
-===== With a vector and number <span id="meta_add_vn"></span><span id="meta_add_nv"></span> =====
+==== copy ====
-{{Hatnote|Operator is commutative and has the same result regardless of order.}}
 ----
-The result is a new vector of the same size which holds the result of adding the number to all components of this vector.
+Creates a copy of this vector. Creating a copy will make a new Vector with the same size and values, but which is disconnected from the original. This means that methods like [[#set|set]] or [[#add|add]] which modify the vector they are called with will not modify copies.
 {| class="wikitable"
-! Left !! Right !! Result
+! Arguments !! Return Type
 |-
-| {{type|{{{T|Vector}}}}}
+| <code>copy()</code>
-| {{type|number}}
-| new {{type|{{{T|Vector}}}}}
-|-
-| {{type|number}}
-| {{type|{{{T|Vector}}}}}
 | new {{type|{{{T|Vector}}}}}
 |}
-==== - (operator) ====
+==== set ====
-===== With two vectors <span id="meta_sub_vv"></span> =====
 ----
-{{Sidebox
- |Performs [[wikipedia:Euclidean vector#Addition and subtraction|vector subtraction]] with another vector, and creates a new vector from the result.
- |Mathematical definition
-}}
-Subtracts the right vector from the left vector. The result is a ''new'' vector of the same size which holds the difference.
+Assigns the values from another vector of the same size to this vector in place. To create a new instance, see [[#copy|copy]].
 {| class="wikitable"
-! Left !! Right !! Result
+! Arguments !! Return Type
 |-
-| {{type|{{{T|Vector}}}}}
+| <code>set({{type|{{{T|Vector}}}}} other)</code>
-| {{type|{{{T|Vector}}}}}
+| self {{type|{{{T|Vector}}}}}
-| new {{type|{{{T|Vector}}}}}
 |}
-<syntaxhighlight lang="lua">
+==== reset ====
-local a = vec(1, 2, 3)
-local b = vec(4, 4, 6)
-print(b - a, a, b) -- {3, 2, 3}  {1, 2, 3}  {4, 4, 6}
-</syntaxhighlight>
-===== With a vector and a number <span id="meta_sub_vn"></span> =====
-{{Hatnote|Only applies when the number is on the '''right''' side of the operator.}}
 ----
-Returns a new vector of the same size containing the result of subtracting the number from all components of the vector.
+Sets all the components of this vector to 0.
 {| class="wikitable"
-! Left !! Right !! Result
+! Arguments !! Return Type
 |-
-| {{type|{{{T|Vector}}}}}
+| <code>reset()</code>
-| {{type|number}}
+| self {{type|{{{T|Vector}}}}}
-| new {{type|{{{T|Vector}}}}}
-|}
-===== With a number and a vector <span id="meta_sub_nv"></span> =====
-{{Hatnote|Only applies when the number is on the '''left''' side of the operator.}}
-----
-Returns a new vector of the same size containing the result of negating all of the components of the vector, then [[#meta_add_vn|adding]] the number. In effect, <code>number - vector == (-vector) + number</code>.
-{| class="wikitable"
-! Left !! Right !! Result
-|-
-| {{type|number}}
-| {{type|{{{T|Vector}}}}}
-| new {{type|{{{T|Vector}}}}}
 |}
-==== * (operator) ====
+==== applyFunc ====
-===== With two vectors <span id="meta_mul_vv"></span> =====
 ----
-Returns a new vector of the same size containing the result of [[#multiply|multiplying]] the vectors together (component multiplication.)
+Calls the provided function ''f'' on every component, and sets this vector's components to the return values of the function.
-{| class="wikitable"
-! Left !! Right !! Result
-|-
-| {{type|{{{T|Vector}}}}}
-| {{type|{{{T|Vector}}}}}
-| new {{type|{{{T|Vector}}}}}
-|}
-===== With a vector and a number <span id="meta_mul_vn"></span><span id="meta_mul_nv"></span> =====
-{{Hatnote|Operator is commutative and has the same result regardless of order.}}
-----
-Returns a new vector of the same size containing the result of [[#scale|scaling]] the vector by the number (scalar multiplication.)
+The function receives the following values as arguments: first, the value as a {{type|number}}, then the index ({{type|integer}}, 1 is x, 2 is y, etc.) The function is expected to return a {{type|number}}.
 {| class="wikitable"
-! Left !! Right !! Result
+! Arguments !! Return Type
 |-
-| {{type|{{{T|Vector}}}}}
+| <code>applyFunc({{type|function}} f)</code>
-| {{type|number}}
+| self {{type|{{{T|Vector}}}}}
-| new {{type|{{{T|Vector}}}}}
-|-
-| {{type|number}}
-| {{type|{{{T|Vector}}}}}
-| new {{type|{{{T|Vector}}}}}
 |}
-===== With a vector and a matrix <span id="meta_mul_vm"> =====
+<syntaxhighlight lang="lua">
-{{Hatnote|This definition only applies if the vector is on the left side. If the vector is on the right side, see [[{{{M|Matrix}}}#meta_mul_mv|the associated operator on the matrix]].}}
+local A = vec(1, 2, 3)
-----
+-- cube the values
+A:applyFunc(function(value, index) return value*value*value end)
-Returns a new vector of the same size containing the result of [[#transform|transforming]] the vector with the matrix.
+print(A) -- {1, 8, 27}
+</syntaxhighlight>
-{| class="wikitable"
-! Left !! Right !! Result
-|-
-| {{type|{{{T|Vector}}}}}
-| {{type|{{{M|Matrix}}}}}
-| new {{type|{{{T|Vector}}}}}
-|}
-==== / (operator) ====
-===== With two vectors <span id="meta_div_vv"></span> =====
-----
-Returns a new vector of the same size containing the result of [[#divide|dividing]] the left vector by the right vector (component division.)
-{| class="wikitable"
-! Left !! Right !! Result
-|-
-| {{type|{{{T|Vector}}}}}
-| {{type|{{{T|Vector}}}}}
-| new {{type|{{{T|Vector}}}}}
-|}
-===== With a vector and a number <span id="meta_div_vn"></span> =====
-{{Hatnote|Only applies when the number is on the '''right''' side of the operator. There is no definition with the number on the left side of the operator.}}
-----
-Returns a new vector of the same size containing the result of [[#scale|scaling]] the vector by the [[wikipedia:Multiplicative inverse|reciprocal]] of the number.
-{| class="wikitable"
-! Left !! Right !! Result
-|-
-| {{type|{{{T|Vector}}}}}
-| {{type|number}}
-| new {{type|{{{T|Vector}}}}}
-|}