primitive.md

View this file with results and syntax highlighting here.

BQN primitives

Primitives are the basic functions and modifiers built into the language, written with individual glyphs (more about the concept here). The role of a primitive when written always matches its type (but you can use its value in other roles by assigning it, or other methods).

Primitives have no side effects other than errors, and can't perform infinite computations, except when a primitive modifier calls an operand function that does one of these things (and this can only happen when arguments are passed, as primitive modifiers are always deferred). Side effects here include both writing state such as variables or printed output, and reading any outside state, so that a function without them always returns the same result if passed the same arguments. Since trains and list notation have the same nice properties, tacit code written entirely with primitives, trains, and lists always describes finite, self-contained computations.

Recursion is the primary way to perform potentially infinite computations in BQN, and it can be packaged into control structures like While for ease of use. A given BQN implementation might also provide system values for "impure" tasks like file access or other I/O.

Functions

A function call with one argument (prefix) is called "monadic" and one with two arguments (infix) is "dyadic".

Glyph	Monadic	Dyadic
+	Conjugate	Add
-	Negate	Subtract
×	Sign	Multiply
÷	Reciprocal	Divide
⋆	Exponential	Power
√	Square Root	Root
⌊	Floor	Minimum
⌈	Ceiling	Maximum
∧	Sort Up	And
∨	Sort Down	Or
¬	Not	Span
|	Absolute Value	Modulus
≤		Less Than or Equal to
<	Enclose	Less Than
>	Merge	Greater Than
≥		Greater Than or Equal to
=	Rank	Equals
≠	Length	Not Equals
≡	Depth	Match
≢	Shape	Not Match
⊣	Identity	Left
⊢	Identity	Right
⥊	Deshape	Reshape
∾	Join	Join to
≍	Solo	Couple
⋈	Enlist	Pair
↑	Prefixes	Take
↓	Suffixes	Drop
↕	Range	Windows
»	Nudge	Shift Before
«	Nudge Back	Shift After
⌽	Reverse	Rotate
⍉	Transpose	Reorder Axes
/	Indices	Replicate
⍋	Grade Up	Bins Up
⍒	Grade Down	Bins Down
⊏	First Cell	Select
⊑	First	Pick
⊐	Classify	Index of
⊒	Occurrence Count	Progressive Index of
∊	Mark Firsts	Member of
⍷	Deduplicate	Find
⊔	Group Indices	Group
!	Assert	Assert with Message

Modifiers

Combinators only control the application of functions, which are passed as operands. A data value such as a number or array can also be an operand and, as always, applies as a constant function.

Glyph	Name(s)	Definition	Description
˙	Constant	{𝕩⋄𝕗}	Return a function that returns the operand
˜	Self/Swap	{𝕩𝔽𝕨⊣𝕩}	Duplicate one argument or exchange two
∘	Atop	{𝔽𝕨𝔾𝕩}	Apply 𝔾 to both arguments and 𝔽 to the result
○	Over	{(𝔾𝕨)𝔽𝔾𝕩}	Apply 𝔾 to each argument and 𝔽 to the results
⊸	Before/Bind	{(𝔽𝕨⊣𝕩)𝔾𝕩}	𝔾's left argument comes from 𝔽
⟜	After/Bind	{(𝕨⊣𝕩)𝔽𝔾𝕩}	𝔽's right argument comes from 𝔾
⊘	Valences	{𝔽𝕩;𝕨𝔾𝕩}	Apply 𝔽 if there's one argument but 𝔾 if there are two
◶	Choose	{f←(𝕨𝔽𝕩)⊑𝕘 ⋄ 𝕨F𝕩}	Select one of the functions in list 𝕘 based on 𝔽
⌾	Under	{𝔾⁼∘𝔽○𝔾} OR {(𝔾𝕩)↩𝕨𝔽○𝔾𝕩⋄𝕩}	Apply 𝔽 over 𝔾, then undo 𝔾
⎊	Catch	{𝕨𝔽𝕩… 𝕨𝔾𝕩}	Apply 𝔽, but if it fails catch the error and apply 𝔾

The last three are combinators in spirit but go beyond the actual strict definition: Choose calls the function ⊑, Under has an "undo" step at the end, and Catch traps an error. The second definition for Under and the one for Catch are written in pseudo-BQN because they can't be expressed otherwise.

Other modifiers control array traversal and iteration. In three cases a simpler 1-modifier is paired with a generalized 2-modifier: for each of these the 1-modifier happens to be the same as the 2-modifier with a right operand of ¯1.

1-Modifier	Name	2-Modifier	Name
˘	Cells	⎉	Rank
¨	Each	⚇	Depth
⌜	Table
⁼	Undo	⍟	Repeat
´	Fold
˝	Insert
`	Scan