Keyword unsafe

Definition

unsafe marks an advanced surface where low-level or unsafe behavior must remain explicit.

The keyword unsafe marks a zone where the language deliberately exposes a riskier or more machine-facing surface. Its value is precision, not convenience.

Grammatical role

Marks a zone where the language's usual safety must be assumed explicitly by the author.

This grammatical role is essential: if a reader understands the structural place of unsafe, they already understand much of the diagnostics that will appear when it is moved or truncated.

Canonical syntax

Canonical form: `unsafe ...` around an explicit unsafe boundary.

The canonical form matters because it gives the compiler and the reader the same reference structure. A large share of diagnostics related to unsafe come from an abbreviated, displaced, or incomplete form.

Detailed semantics

Semantically, unsafe opens a strongly explicit zone. It signals that a safety, low-level, or interoperability assumption is no longer implicit and must be owned openly.

In an encyclopedic reading, unsafe should not be reduced to a dictionary definition. Its effect on scope, block shape, value visibility, control progression, and the diagnostic family it activates when misused must also be considered.

Effect on execution

unsafe opens a zone where the real effect may touch memory, the ABI, or machine instructions. It should be read as a boundary of strong responsibility.

In other words, the presence of unsafe is not merely syntactic: it helps the reader predict what will be executed, produced, exposed, or forbidden from this point in the program.

Valid variants

• `unsafe ...` around an explicit unsafe boundary.

These variants are not free synonyms. They indicate the legitimate forms from which one can reason about diagnostics, scope differences, or contract readability.

Vitte example

unsafe proc raw_copy(dst: ptr[int], src: ptr[int]) -> int {
  give 0
}

This example shows unsafe in a nominal context. It should be read globally: where the contract begins, which values are constrained, which output becomes observable, and why the presence of the keyword is justified.

Guided reading of the example

1. First locate the full construction that contains unsafe, not the isolated word.
2. Then identify which contract becomes visible because of unsafe: type, branch, binding, module, exit, or advanced boundary.
3. Finish by checking the observable effect produced by the construction that contains unsafe.
4. For an advanced surface, explicitly verify the safety or interoperability boundary it opens.

This guided reading is intentionally closer to a reference page than to a tutorial: it helps reconstruct the exact role of unsafe in a complete block.

Comparison with C

/* C comparison: this role usually appears through inline assembly or unsafe pointer manipulation. */

For this keyword, the parallel with C remains approximate. The comparison mainly indicates that in C the same idea is often spread across file conventions, operators, or less explicit control structures.

The source of truth remains Vitte grammar and semantics. The comparison with C should be read as a cultural marker, not as a parallel specification.

Recommended uses

unsafe deserves to appear when it simplifies the reading of the block's global contract, not when it merely adds one more surface form.

When to use it

• When unsafe makes the block contract more explicit at first reading.
• When it reduces the number of implicit assumptions the reader must reconstruct mentally.
• When a low-level boundary must be marked explicitly instead of being hidden.

When to avoid it

• Avoid unsafe when another, more precise keyword already carries the block's intent.
• Avoid unsafe when it adds only surface noise without clarifying the contract.
• Avoid reading or teaching it as an isolated token with no relation to the full structure.

Common pitfalls

• Using unsafe in a grammatical layer where it does not belong.
• Confusing the role of the keyword with the role of the full surrounding block.
• Showing only the nominal form and never how the contract fails.

Invalid example and diagnostic

proc bad_unsafe() -> int {
  unsafe
  give 0
}

The advanced surface is malformed because it lacks the enclosing contract required by the language.

The counter-example is not merely wrong: it is wrong in an instructive way. It shows which grammar or execution-contract assumption is no longer accepted when unsafe is moved, truncated, or combined with the wrong context. Concretely, the unsafe boundary is badly opened or does not enclose the expected surface.

A good encyclopedic counter-example does not show arbitrarily broken code: it isolates the precise reason why unsafe can no longer support the expected contract. Its teaching value is diagnostic before it is syntactic.

Common compilation errors

This table does not replace the compiler's exact diagnostics. It serves as a mental map: when unsafe fails, the problem usually comes from an invalid grammatical form, an incoherent type contract, or an incomplete construction.

Neighbor keywords

Comparison with neighboring keywords is essential on a wiki-style page: unsafe is better understood when one knows precisely what it does not do.

Common misreadings

• Reducing unsafe to a local token instead of reading it as part of a full construction.
• Explaining only the syntax and forgetting the reading or diagnostic contract it imposes.

Implementation and diagnostic notes

• Diagnostics must stay precise, because a poorly documented advanced surface quickly creates expensive-to-debug errors.
• In a compiler, these keywords often act as guard rails around unsafe transformations or calls.

Presence in the book

• docs/book/chapters/16-interop.html
• docs/book/chapters/27-grammar.html
• docs/book/chapters/65-abi-and-vitte-interop-contracts.html

See also

• docs/book/chapters/keywords/erreurs-compilateur.html
• docs/book/chapters/keywords/asm.html
• docs/book/glossary.html