Verse Utility Functions: The Built-in Toolbox

Before you write a helper, check whether Verse already wrote it for you. The standard library ships a toolbox of small, sharp utility functions — math (Abs, Min, Max, Clamp, Floor, Mod), array operations (Slice, RemoveElement, Concatenate), conversions (ToString), and the workhorse Print — and most beginner bugs in this area come from not knowing they exist, or from missing a single detail in their signatures: some of these can fail. This lesson maps the toolbox and teaches you to read a utility's effect label so you call it correctly the first time.

This is where the previous three lessons pay off. Some utilities are <computes> (always succeed). Some are <decides> (can fail — call with [], handle in a failure context). Some are <transacts> (change state). The label is not decoration — it dictates how you call the function.

Reading a utility's signature

<!-- section-art:reading-a-utility-s-signature -->

Signature Tools

Every standard function in the digest is written with its full signature. Train yourself to read three things: the parameters, the effect label, and the return type. Here are real signatures from Verse.digest.verse:

# Always succeeds — pure computation. Call with ().
Min<public>(X : int, Y : int)<computes> : int
Max<public>(X : int, Y : int)<computes> : int
Clamp<native><public>(Val : int, A : int, B : int)<computes> : int

# Can FAIL — note <decides>. Call with [] inside a failure context.
Floor<native><public>(Val : float)<reads><decides> : int
Ceil<native><public>(Val : float)<reads><decides> : int
Round<native><public>(Val : float)<reads><decides> : int
Mod<native><public>(X : int, Y : int)<computes><decides> : int

The difference is everything. Min, Max, and Clamp are <computes> — they can't fail, so you call them with parentheses:

# <computes> utilities — ordinary () calls, can't fail.
Health := Clamp(RawHealth, 0, 100)
Bigger := Max(ScoreA, ScoreB)

But Floor, Ceil, Round, and Mod are <decides> — they can fail (e.g. Mod by zero, or a float that can't be represented as an int) — so they need [] and a failure context:

# <decides> utilities — call with [], handle the failure.
if (Whole := Floor[3.7]):
    Print("Floor is {Whole}")        # 3

if (Remainder := Mod[Count, GroupSize]):
    Print("Leftover: {Remainder}")
else:
    Print("GroupSize was zero — can't take a remainder")

Calling Floor(3.7) with parentheses is a compile error, because the <decides> effect demands []. This is the same () vs [] rule from the failure-contexts lesson, applied to the standard library.

The math utilities

The common ones, with their effects:

# Clamp keeps a value in range — the idiomatic way to cap health.
SafeHealth := Clamp(Damaged, 0, MaxHealth)

# Pythagorean distance using Sqrt and Pow (both <reads>, plain ()).
Distance := Sqrt(Pow(Dx, 2.0) + Pow(Dy, 2.0))

Array utilities

Arrays come with extension methods — written (Input : []t).Name(...) in the digest, called as MyArray.Name(...). Several are <decides> because an index might be out of range:

# Real digest signatures — note <decides> on the ones that take an index.
(Input : []t where t : type).Slice<public>(StartIndex : int)<computes><decides> : []t
(Input : []t where t : type).RemoveElement<public>(IndexToRemove : int)<computes><decides> : []t
Concatenate<public>(Arrays : [][]t where t : type)<computes> : []t

So Slice and RemoveElement need [] and a failure context (the index could be invalid), while .Length is a plain property and Concatenate always succeeds:

Names : []string = array{"Ana", "Bo", "Cy", "Di"}

# .Length never fails — it's just the count.
Print("There are {Names.Length} names")

# Slice CAN fail (bad index), so [] + if.
if (Tail := Names.Slice[2]):
    Print("Tail has {Tail.Length} names")   # ["Cy","Di"]

# RemoveElement can fail too.
if (Fewer := Names.RemoveElement[0]):
    set Names = Fewer

A subtle point: indexing an array directly, Names[Index], is itself failable — out-of-range fails — which is exactly why array access uses []. It's the same machinery as option/map access.

Conversions and output

ToString turns values into strings; Print writes to the log. The most-used utility of all is Print:

# Real signature — Print is <computes>, takes a string (or diagnostic).
Print<public>(Message : string, ?Level : log_level = external {})<computes> : void

Most of the time you don't call ToString at all — you use string interpolation with { }, which converts values inline:

# Interpolation calls the right conversion for you — cleaner than ToString.
Print("Player {PlayerName} scored {Points} at {Location}")

For types without automatic interpolation (like vectors), the SpatialMath ToString overloads exist:

# Real overloads from the digest for spatial types.
Print("Position: {ToString(MyVector3)}")

Writing your own utility functions

When the toolbox doesn't have it, write your own — and label it honestly with the effect it actually has. A pure helper is <computes>; one that reads state is <reads>; one that can fail is <decides>; one that changes state is <transacts> (from the previous lesson).

# Pure helper — no state, no failure — so <computes>.
Percent(Part : float, Whole : float)<computes> : float =
    if (Whole > 0.0):
        (Part / Whole) * 100.0
    else:
        0.0

# A helper that can fail belongs in <decides>, called with [].
SafeDivide(Numerator : int, Denominator : int)<decides> : int =
    Denominator <> 0      # fails here if denominator is zero
    Numerator / Denominator

Keep utilities small and single-purpose — one job each. That's the project convention (single-responsibility, DRY): a utility you can describe in one sentence is one you can reuse everywhere and test in your head. Group related helpers into a module (the next lesson) so they're easy to find and using.

The pitfalls — what trips people up

<!-- section-art:the-pitfalls-what-trips-people-up -->

Toolbox Pitfalls

1. Reinventing built-ins. Writing your own clamp/min/max loop when Clamp, Min, Max already exist. Search the digest first — search_api_docs in Verse Cortex is built for exactly this.

2. Calling a <decides> utility with (). Floor(3.7), Mod(X, Y), Slice(2) are all compile errors — those are <decides>, so they need [] and a failure context. This is the #1 utility-function error.

3. Ignoring the failure case of Mod/Floor/index access. Mod[X, 0] fails; MyArray[BadIndex] fails; Slice[OutOfRange] fails. Handle the else, or you silently skip work.

4. Reaching for ToString when interpolation is cleaner. Print("Score: {Score}") beats Print("Score: " + ToString(Score)) for most types — and many types interpolate without any ToString overload at all.

5. Mislabeling your own helpers. A helper that can fail must be <decides>; one that changes state must be <transacts>. Under-labeling won't compile (effects are contagious); over-labeling hides which functions are dangerous.

6. Forgetting Float/Int are distinct. Min(1, 2) (ints) and Min(1.0, 2.0) (floats) hit different overloads. Mixing Min(1, 2.0) is a type error — convert first.

Recap

• Verse ships a toolbox: math (Min, Max, Clamp, Abs, Pow, Sqrt, Floor, Ceil, Round, Mod), arrays (Slice, RemoveElement, Concatenate, .Length), conversions (ToString), and Print.
• Read the effect label to know how to call it: <computes>/<reads> → (), can't fail; <decides> (Floor, Mod, Slice, index access) → [] in a failure context.
• Prefer string interpolation { } over manual ToString.
• When you write your own, label it with its true effect and keep it small and single-purpose.
• Search the digest before reinventing — the toolbox is bigger than you think.

Read a utility's effect label first — it decides whether you call it with ( ) or [ ].

References

• Verse Language Reference (Epic)
• Verse API Reference (Epic)
• Strings and string interpolation in Verse (Epic)
• Grounded in the Verse Cortex knowledge base: Verse.digest.verse (Min/Max/Clamp/Mod/Floor/Ceil/Round/Pow/Sqrt signatures, Slice/RemoveElement/Concatenate array methods, Print/ToString), and project .cursor/rules (single-responsibility, DRY).