Most primitives are specified by the BQN-based implementation in reference.bqn. This document specifies the basic functionality required by those definitions. Descriptions of other primitives are for informational purposes only.
Functions in this section are defined for atoms only; the reference implementations extend them to arrays.
BQN uses five arithmetic functions that are standard in mathematics. The precision of these operations should be specified by the number type.
+- invert addition, with -๐ฉ equivalent to 0-๐ฉ.ร generalizes repeated addition.รท invert multiplication, with รท๐ฉ equivalent to 1รท๐ฉ.โ generalizes repeated multiplication, and Exponential โ is Power with Euler's number e as the base.The three higher functions ร, รท, and โ apply to numbers and no other atomic types. + and - apply to numbers, and possibly also to characters, according to the rules of the affine character type:
+ is the character with code point c and the other is a number n (in either order), then the result is the character with code point c+n.- is the character with code point c and the right is a number n, the result is the character with code point c-n.- are characters, the result is the difference of their respective code points.In the first two cases, if the result would not be a valid Unicode code point, then an error results. The remaining cases of + and - (adding two characters; negating a character or subtracting it from a number) are not allowed.
Additionally, the Floor function โ returns the largest integer smaller than the argument, or the argument itself if it is ยฏโ or โ. It's needed because the arithmetic operations give no fixed-time way to determine if a value is an integer. Floor gives an error if the argument is an atom other than a number.
Two kinds of comparison are needed to define BQN's primitives: equality comparison and ordered comparison.
Ordered comparison is simpler and is provided by the dyadic Less than or Equal to (โค) function. This function gives an error if either argument is an operation, so it needs to be defined only for numbers and characters. For numbers it is defined by the number system, and for characters it returns 1 if the left argument's code point is less than that of the right argument. Characters are considered greater than numbers, so that nโคc is 1 and cโคn is 0 if c is a character and n is a number.
The dyadic function =, representing equality comparison, can be applied to any two atoms without an error. Roughly speaking, it returns 1 if they are indistinguishable within the language and 0 otherwise. If the two arguments have different types, the result is 0; if they have the same type, the comparison depends on type:
Operations are split into subtypes depending on how they were created.
This means that block instance equality indicates identity in the context of mutability: two block instances are equal if any change of state in one would be reflected in the other as well. The concept of identity holds even if the blocks in question have no way of changing or accessing state. For example, =โ{๐ฉโ{๐ฉ}}ห@ is 0 while =หโ{๐ฉโ{๐ฉ}}@ is 1.
Several subsets of primitives, or dedicated operations, are used to manipulate arrays in the reference implementation.
IsArray returns 1 if the argument is an array and 0 if it's an atom.The following functions translate between arrays and the two lists that define them: the shape and ravel.
โข) returns the shape of array ๐ฉ, as a list of natural numbers.โฅ) returns the ravel of array ๐ฉ, that is, the list of its elements.โฅ) returns an array with the same ravel as ๐ฉ with shape ๐จ. It can be assumed that โข๐ฉ and ๐จ have the same product.The following functions manipulate lists. In these functions, a valid index for list l is a natural number less than the length of l.
๐ฉ (a natural number) with value i at any index i.โ) selects the element at index ๐จ from list ๐ฉ._amend returns an array identical to list ๐ฉ except that the element at index ๐ is changed to ๐จ.Inferred properties are specified in their own document, not in the reference implementation.
Identity gives the identity value for reduction by function ๐.โผ) gives a partial right inverse for function ๐ฝ.Fill gives the enclose of the fill value for array ๐ฉ.!) causes an error if the argument is not 1. If ๐จ is provided, it gives a message to be associated with this error (which can be any value, not necessarily a string).As noted above, see reference.bqn for the authoritative definitions. Commentary here gives an overall description and highlights implementation subtleties and edge cases.
There's little to say about BQN's true combinators, since each is simply a pattern of function application. All primitive combinators use their operands as functions, and thus treat a data operand as a constant function.
โถ) is later redefined to use the complete โ rather than the simple version assumed (using this primitive means it's not a true combinator).ห)โ) uses a trick with ambivalent - to find out whether there's a left argument, described below.โข)โฃ)ห)โ)โ)โธ)โ)The somewhat complicated definition of Valences could be replaced with {๐ฝ๐ฉ;๐จ๐พ๐ฉ} using headers. However, reference.bqn uses a simple subset of BQN's syntax that doesn't include headers. Instead, the definition relies on the fact that ๐จ works like ยท if no left argument is given: (1ห๐จ)-0 is 1-0 or 1 if ๐จ is present and (1หยท)-0 otherwise: this reduces to ยท-0 or 0.
The reference implementations extend Shape (โข) to atoms as well as arrays, in addition to implementing other properties. In all cases, an atom behaves as if it has shape โจโฉ. The functions in this section never cause an error.
โข) gives the shape of an array or atom.=) gives the length of the shape.โ ) gives the number of major cells, or 1 for an argument of rank 0.โก) gives the nesting depth. It ignores the shapes of arrays, and considering only the depths of their elements.