Understanding Rust types (coming from Python)¶
When you use Rust interop (rust::... imports), you’ll sometimes see Rust types in signatures and docs. This page explains the common ones and how they map to Incan.
Quick mapping¶
| Rust type | Incan mental model | Notes |
|---|---|---|
Vec[T] |
List[T] |
Growable list |
HashMap[K, V] |
Dict[K, V] |
Key/value map |
HashSet[T] |
Set[T] |
Unordered unique items |
String |
str |
Owned string |
&str |
str |
Borrowed string slice — avoid as an API type in Incan when you can |
Option[T] |
Option[T] |
Some(x) or None |
Result[T, E] |
Result[T, E] |
Ok(x) or Err(e) |
Instant |
“time point” | For measuring elapsed time |
Duration |
“time span” | Length of time |
Note: In Incan type annotations, Vec[T] is accepted as an alias for List[T] to mirror Rust APIs.
Dict vs HashMap¶
In normal Incan code, prefer Dict (and literals like {}).
When interoperating with Rust crates, you may encounter HashMap because that’s what Rust APIs return.
# These are equivalent:
counts: Dict[str, int] = {}
counts: HashMap[str, int] = HashMap.new()
Method naming conventions you may see¶
| Python habit | Incan | Notes |
|---|---|---|
dict.get(key) |
d.get(key) |
Returns Option holding the stored value |
dict[key] |
d[key] |
Panics if missing |
dict.get(key, default) |
d.get(key, default) |
The stored value, or the default when the key is missing |
str(x) |
str(x) |
Convert to string |
len(x) |
len(x) |
Length |
Option and Result: unwrap-like patterns¶
Rust APIs often return Option/Result instead of raising exceptions.
unwrap() is a “this must exist” assertion (it panics if missing), so prefer unwrap_or(...) or match when the value can be absent.
value = my_dict.get("key").unwrap_or(0)
match my_dict.get("key"):
case Some(v): println(v)
case None: println("missing")
str and bytes¶
Method names on str are the familiar ones — upper, lower, strip, split, replace, join — and substring membership is Python's in operator, "x" in s and "x" not in s, with s.contains("x") as its method form. Incan hides the String / &str split: write str and the compiler decides ownership in the generated Rust.
Python's bytes is immutable; Incan's bytes lowers to Vec<u8>, which is not. Choose the type by what the data is, not by where it came from:
| Use case | Type |
|---|---|
| Text, user-facing content | str |
| File contents that are text | str |
| Binary files, network protocols, cryptographic inputs, raw file I/O | bytes |
str.encode() and bytes.decode() convert between them, UTF-8 only; where Python's decode raises UnicodeDecodeError, Incan's returns Result[str, ValidationError], so a malformed input is an Err you match on or pass up with ?.