Coming From Other Languages

If you already program in Python, JavaScript, Java, or Rust, compare the familiar constructs below with Topaz. Use the differences to choose your next lesson without repeating programming basics.

Read a familiar calculation

This function adds the minutes from an array of tasks.

TOPAZ

record Task {
    title: string,
    minutes: int
}

function totalMinutes(tasks: Array<Task>) -> int {
    let mut total = 0
    for task in tasks {
        total = total + task.minutes
    }
    total
}

For tasks lasting 10 and 25 minutes, totalMinutes returns 35. This snippet defines the record and function without calling them. let mut total allows the loop to update the total, and the final total supplies the return value.

Four differences to check

Reassignment uses let mut. A name declared with let cannot be reassigned. Use let mut for a variable whose value you need to replace.

Recoverable errors use Result. Handle the returned error or pass it to the caller with ?. Topaz has no exception-catching syntax. A runtime fault stops execution and cannot be handled as a returned error.

Missing values use a type. Use Option<T> for a result that may be absent. Use T | null for external nullable data. These are distinct types, and you must handle absence before using the contained value.

File access depends on the execution environment. A profile names the supported features and execution rules. Check the imports, package configuration, and selected profile when code uses files or other input and output. A function signature shows its input and result types. Reading a Real File shows how to read these parts together.

Map familiar constructs

Familiar construct	Topaz form
`dict`, `Map`, or `HashMap`	`Map` stores keys and values. See Collections & Comprehensions.
A class used to group data	A `record` groups fields. Functions operate on those records.
An interface for generic code	Explicit function signatures and static protocols describe required operations. Protocols have no runtime dynamic dispatch.
Recoverable `try`/`except` handling	Return a `Result` and handle `Ok` or `Err`.
A lookup that may find nothing	Return `Option<T>` and handle `Some` or `None`.
Nullable external data	Use `T \| null` and handle `null`.

Topaz has no class inheritance or runtime reflection to inspect program structure. It also has no row polymorphism, which lets a generic record type leave some fields unspecified. See Records & Nominal Data for the data model. Numeric types do not convert implicitly, so an int does not automatically become a float in an expression.

Try this

A function searches an in-memory task list by title. What return type represents a search that may find nothing?

Answer

Use Option<Task>. Return Some(task) for a match and None when no task matches. If the operation can also fail, such as when reading a file, represent that error with Result.

Choose your next lesson

Start with First Program to install Topaz and run a file. If you have already done that, choose a topic below.

Values and Functions covers types, return values, and reassignment.
Data and Control covers records, collections, and branches.
Failures and Resources covers Option, Result, ?, and defer.

Once those examples are familiar, combine them in First Application. Keep Syntax at a Glance open to look up syntax while you work.