KSL Wiki

Abs

Returns the absolute value of a number.

Parameters

Abs[n]

The function requires exactly one argument.

• n: The argument must be of the type Number.

Return Value

Returns a non-negative Number that is the absolute value of n.

No domain-specific errors are thrown by this function.

Examples

(* Returns the absolute value of a positive number *)
Abs[3.0]; (* 3 *)

(* Returns the absolute value of a negative number *)
Abs[-3.2]; (* 3.2 *)

(* The absolute value of zero is zero *)
Abs[0]; (* 0 *)

Add

Computes the sum of one or more numbers.

Parameters

Add[n1, n2, ...]

The function accepts one or more arguments.

• n1, n2, ...: All arguments must be of the type Number.

Return Value

Returns a Number that is the sum of all arguments. If a single argument is provided, the function returns that argument unchanged.

No domain-specific errors are thrown by this function.

Examples

(* Computes the sum of multiple integers *)
Add[1, 2, 3]; (* 6 *)

(* Computes the sum of floating-point numbers *)
Add[1.5, 2.4, -0.2]; (* 3.7 *)

(* Returns the number itself if only one argument is given *)
Add[42]; (* 42 *)

(* Arguments can be expressions that evaluate to numbers *)
Add[1, 2, Add[3, 2], 7]; (* 15 *)

All

A higher-order function that tests whether a predicate function returns #t for every element in a list.

Parameters

All[list, predicate]

The function requires exactly two arguments.

• list: The List to iterate over.

• predicate: A function or a lambda that serves as the condition.

  This function must:

  • Accept a single argument. It must be able to operate on every element type present in the list.
  • Return either the atom #t or #f.

Return Value

Returns an atom:

• #t if the predicate function returns #t for every element in the list. If the list is empty, it also returns #t.

• #f if any element causes the predicate to return #f.

  The function short-circuits and returns immediately upon finding the first such element.

Errors

The evaluation of All will fail and propagate an error if the predicate function fails when applied to any element. This typically occurs due to a type mismatch, where an element in the list is not a valid argument for the operation inside the predicate.

Examples

Let[v, {1, 2, 3, 4}];

(* Returns #t because all elements are less than 5 *)
All[v, Fun[{ x }, Less[x, 5]]]; (* #t *)

(* Returns #f because 1 and 2 are not greater than 2 *)
All[v, Fun[{ x }, Greater[x, 2]]]; (* #f *)

(* Returns #t for an empty list *)
All[{ }, Fun[{ x }, Less[x, 0]]]; (* #t *)

(* This will cause an error *)
Let[mixed_list, { 1, 2, "three", 4 }];
(* The call to Less will fail for the element "three",
  causing All to propagate the error. *)
All[mixed_list, Fun[{ x }, Less[x, 5]]];
(* ?
Error[ksl::builtin::Less]: Unexpected value: `"three"`.
*)

And

Acts as a short-circuiting logical AND operator. It evaluates the second argument only if the first argument evaluates to #t.

Parameters

And[condition, expression]

The function requires exactly two arguments.

• condition: The first argument must be #t or #f.
• expression: The second argument can be any expression. It is only evaluated if condition is #t.

Return Value

• If condition is #f, the function immediately returns #f.
• If condition is #t, the function returns the result of expression. The return type will be the type of the evaluated expression.

No domain-specific errors are thrown by this function.

Examples

(* Returns #f because the first argument is false;
  #any is not evaluated *)
And[Greater[1, 2], #any]; (* #f *)

(* Returns #f because the second argument evaluates to false *)
And[Less[3, 5], Greater[9, 11]]; (* #f *)

(* Returns #val because the first argument is true *)
And[Less[3, 5], #val]; (* #val *)

(* The return type is determined by the second argument *)
And[Less[3, 5], "test"]; (* "test" *)

Any

A higher-order function that tests whether a predicate function returns #t for at least one element in a list.

Parameters

Any[list, predicate]

The function requires exactly two arguments.

• list: The List to iterate over.

• predicate: A function or a lambda that serves as the condition.

  This function must:

  • Accept a single argument. It must be able to operate on the element types present in the list.
  • Return either the atom #t or #f.

Return Value

Returns an atom:

• #t if the predicate function returns #t for any element in the list.

  The function short-circuits and returns immediately upon finding the first such element.

• #f if the predicate function returns #f for all elements in the list, or if the list is empty.

Errors

The evaluation of Any will fail and propagate an error if the predicate function fails when applied to any element. This typically occurs due to a type mismatch, where an element in the list is not a valid argument for the operation inside the predicate.

Examples

Let[v, {1, 2, 3, 4}];

(* Returns #t because at least one element (4) is greater than 3 *)
Any[v, Fun[{ x }, Greater[x, 3]]]; (* #t *)

(* Returns #f because no element is less than 0 *)
Any[v, Fun[{ x }, Less[x, 0]]]; (* #f *)

(* Returns #f for an empty list *)
Any[{ }, Fun[{ x }, Greater[x, 0]]]; (* #f *)

(* This will cause an error *)
Let[mixed_list, { 1, "two", 3, 4 }];
(* The call to Greater will fail for the element "two",
  causing Any to propagate the error. *)
Any[mixed_list, Fun[{ x }, Greater[x, 1]]];
(* ?
Error[ksl::builtin::Greater]: Unexpected value: `"two"`.
*)

Append

Returns a new list with a given element added to the end.

Parameters

Append[list, element]

The function requires exactly two arguments.

• list: The List to which the element will be appended.
• element: The element to add to the end of the list. This can be of any type.

Return Value

Returns a new List containing all the elements of the original list followed by the new element.

Crucially, Append does not modify the original list. To update a variable, the result must be reassigned using Let.

No domain-specific errors are thrown by this function.

Examples

(* Appends an atom to the end of a list *)
Append[{ 1, 2, 3, 4 }, #five]; (* {1, 2, 3, 4, #five} *)

(* Demonstrates the immutability of the original list *)
Let[v, { 1, 2, 3, 4 }];

(* Append returns a new list but does not change v *)
Append[v, 5]; (* {1, 2, 3, 4, 5} *)

(* The original variable v remains unmodified *)
Print[v]; (* => {1, 2, 3, 4} *)

(* To update the variable, use Let to rebind it *)
Let[v, Append[v, 5]];
Print[v]; (* => {1, 2, 3, 4, 5} *)

ArcCos

Computes the arc-cosine (inverse cosine) of a number in radians.

Parameters

ArcCos[n]

The function requires exactly one argument.

• n: A Number. Its value must be within the range $\left[-1, 1\right]$.

Return Value

Returns a Number in radians, in the range $\left[0, \pi\right]$.

Out-of-domain inputs produce nan instead of an error.

Examples

ArcCos[1]; (* 0 *)

ArcCos[-1]; (* 3.14159265358979 *)

ArcCos[0.5]; (* 1.0471975511966 *)

(* Returns nan because the input is outside the domain *)
ArcCos[2]; (* nan *)

ArcSin

Computes the arc-sine (inverse sine) of a number in radians.

Parameters

ArcSin[n]

The function requires exactly one argument.

• n: A Number. Its value must be within the range $\left[-1, 1\right]$.

Return Value

Returns a Number in radians, in the range $\left[-\dfrac{\pi}{2}, \dfrac{\pi}{2}\right]$.

Out-of-domain inputs produce nan instead of an error.

Examples

ArcSin[1]; (* 1.5707963267949 *)

ArcSin[-1]; (* -1.5707963267949 *)

ArcSin[0]; (* 0 *)

(* Returns nan because the input is outside the domain *)
ArcSin[2]; (* nan *)

ArcTan

Computes the arc-tangent (inverse tangent) of a number in radians.

Parameters

ArcTan[n]

The function requires exactly one argument.

• n: A Number.

Return Value

Returns a Number in radians, in the range $\left(-\dfrac{\pi}{2}, \dfrac{\pi}{2}\right)$.

No domain-specific errors are thrown by this function.

Examples

ArcTan[1]; (* 0.785398163397448 *)

ArcTan[0]; (* 0 *)

ArcTan[-100]; (* -1.56079666010823 *)

ArcTan2

Computes the arc-tangent of y / x in radians, using the signs of both arguments to determine the correct quadrant of the resulting angle.

Parameters

ArcTan2[x, y]

The function requires exactly two arguments.

• x: A Number representing the x-coordinate.
• y: A Number representing the y-coordinate.

Note on parameter order: The signature is ArcTan2[x, y], which corresponds to the mathematical angle for the point (x, y). This is in contrast to the atan2(y, x) convention found in many other programming languages.

Return Value

Returns a Number in radians, in the range $\left(-\pi, \pi\right]$.

No domain-specific errors are thrown by this function.

Examples

(* Quadrant 1: (1, 1) *)
ArcTan2[1, 1]; (* 0.785398163397448 *)

(* Quadrant 2: (-1, 1) *)
ArcTan2[-1, 1]; (* 2.35619449019234 *)

(* Quadrant 3: (-1, -1) *)
ArcTan2[-1, -1]; (* -2.35619449019234 *)

(* On the positive y-axis *)
ArcTan2[0, 1]; (* 1.5707963267949 *)

(* On the positive x-axis *)
ArcTan2[1, 0]; (* 0 *)