---
title: Nim
date: 2025-11-23 1:04:20
background: bg-[#eed547]
tags:
categories:
  - Programming
intro: |
  The Nim quick reference cheat sheet that aims at providing help on writing basic syntax and methods.
plugins:
  - copyCode
---

## Getting Started

### helloworld.nim {.row-span-2}

```nim
echo "Hello World!"

# This is a comment
echo "What's your name? "
var name: string = readLine(stdin)
# readLine(stdin) asks you to type in a string.

echo "Hi, ", name, "!"
```

Compile `helloworld.nim` with `nim compile`

```bash
$ nim compile helloworld.nim
```

Run the compiled binary `helloworld` (or `helloworld.exe` if you're on Windows)

```
./helloworld
Hello, World!
What's your name?
Hi, <name>!
```

There is also a possibility
to both compile and run the
program with just one command.
We need to type:
`$ nim c -r helloworld.nim`

#### Common compile commands (terminal)

```sh
nim c -r main.nim          # debug build, run after compile
nim c -d:release main.nim  # optimized release build
nim c --mm:arc main.nim    # ARC memory management (Nim 2 default)
```

### Useful Resources {.col-span-2}

- [Nim](https://www.nim-lang.org/) _(nim-lang.org)_
- [The Nim Manual](https://nim-lang.org/docs/manual.html) _(../docs/manual.html)_
- [Nim Basics](https://narimiran.github.io/nim-basics/) _(narimiran.github.io)_
- [Learn X in Y minutes](https://learnxinyminutes.com/docs/nim/) _(learnxinyminutes.com)_

### Variables {.row-span-1}

```nim
# 'var' declares mutable variables.

var number: int = 100 # Single line declaration

# A 'var' block can declare multiple variables at once.

var
  letter: char = 'n'
  lang = "N" & "im"
  length = len(lang)
  counter: int = 7
  boat: float
  truth = true
```

### Immutable Variables (let)

```nim
# 'let' declares immutable variables.
let
  salute: string = "Hello!"
  x: int = 10
  y = x + 5

let z = 20
z = 500   # Error: 'z' is immutable
```

### Comments

```nim
# This is a comment

#[
  This is a multiline comment.
  In Nim, multiline comments can be nested, beginning with #[
  ... and ending with ]#
]#
```

### Constants {.row-span-1}

```nim
const
  debug = true
  compileBadCode = false

# Constants are declared at compile time and cannot be changed.
```

### "For" Loops

```nim
for item in (1 ..< 6):
  if item == 3: break
  echo item

echo "All done!"
```

See: [Loops](#loops)

### If Statements

```nim
import std/strutils
let number = parseInt(readLine(stdin))

if number <= 5:
  echo "Small sized number."
elif number > 5 and number <= 25:
  echo "Medium sized number."
else:
  echo "Big number."
```

See: [Flow Control](#flow-control)

### Procedures / Functions

```nim
proc myFunction() =
  echo "Hello, this is my function"

myFunction()

# prints "Hello, this is my function"
```

See: [Procedures](#procedures)

### Formatted Strings

```nim
import std/strformat

let
  a = "Hello there."
  b = "How's it going?"
  c = "These are variables."

echo fmt"{a} {b} {c}" # "Hello there. How's it going? These are variables."
```

See: [Imports](#imports-and-modules)

## Data Types

### Integers

```nim
let
  a = 11
  b = 4

echo "a + b = ", a + b # 15
echo "a - b = ", a - b # 7
echo "a * b = ", a * b # 44
echo "a / b = ", a / b # 2.75
echo "a div b = ", a div b # 2
echo "a mod b = ", a mod b # 3
```

### Floats

```nim
let
  c = 6.75
  d = 2.25

echo "c + d = ", c + d # 9.0
echo "c - d = ", c - d # 4.5
echo "c * d = ", c * d # 15.1875
echo "c / d = ", c / d # 3.0
```

### Strings {.row-span-3}

```nim
let
  m = "word"
  n = "A sentence with punctuation."
  o = ""
  p = "32"
  q = "!"

echo m
# prints "word"
echo p, " is a string."
# prints "32 is a string."
```

#### String Concatenation

```nim
var
  p = "abc"
  q = "xy"
  r = 'z'

p.add("def")   # modifies p
q.add(r)       # chars can be added to strings

echo p         # "abcdef"
echo q         # "xyz"

# `&` creates a new string:
echo p & q     # "abcdefxyz"
```

#### Special Escape Sequences

```nim
echo "line1\nline2"     # newline
echo "col1\tcol2"       # tab
echo "A\\B\\C"          # backslash

# Raw strings ignore escapes:
echo r"line1\nline2"
```

See also: [Escape Sequences](https://nim-lang.org/docs/manual.html#lexical-analysis-string-literals)

### Characters

```nim
let
  h = 'z'
  i = '+'
  j = '2'
  k = '35'   # error: too many characters
  l = 'xy'   # error: too many characters
```

### Booleans

```nim
let x = true
let y = false

# Boolean literals are lowercase.
```

### Type Conversion {.col-span-2}

```nim

let e = 5
let f = 23.987

# Converting between ints and floats:
echo float(e)    # 5.0
echo int(f)      # 23

# Mixed operations require explicit conversion:
echo float(e) + f    # 28.987
echo e + int(f)      # 28
```

## Compound Types

### Arrays

```nim
type IntArray = array[0..3, int]

let a: IntArray = [10, 20, 30, 40]

echo a[0]      # 10
echo a.len     # 4
```

### Sequences

```nim
var s: seq[int] = @[1, 2, 3]
s.add(4)

echo s         # @[1, 2, 3, 4]
echo s.len     # 4
```

### Objects

```nim
type Person = object
  name: string
  age: int

let p = Person(name: "Ana", age: 20)
echo p.name
```

### Tuples

```nim
var person = (name: "Sophie", age: 18)

echo person.name # Sophie
echo person.age  # 18

# swapping values:
var (x, y) = (1, 2)
(x, y) = (y, x)
echo x, " ", y     # 2 1
```

### Sets

```nim
type CharSet = set[char]

let letters: CharSet = {'a'..'z'}

echo 'a' in letters    # true
echo 'Z' in letters    # false
```

### Reference Objects

```nim
type Node = ref object
  value: int
  next: Node     # linked list style

var n = Node(value: 10)
echo n.value
```

Needed for Object Oriented Programming within Nim.

### Slicing Sequences and Strings {.col-span-2}

```nim
let xs = @[10, 20, 30, 40]

echo xs[1..2]    # @[20, 30]
echo xs[^2..^1]  # @[30, 40]
```

---

```nim
let s = "abcdef"

echo s[0..2]     # "abc"
echo s[3..^1]    # "def" (^1 = last char)
echo s[1..<4]    # "bcd"
```

### Tables/Dictionaries

```nim
import std/tables

var ages = initTable[string, int]()
ages["Ana"] = 20
ages["Sophie"] = 18

echo ages["Ana"]                 # 20
echo ages.getOrDefault("X", -1)  # -1

for name, age in ages:
  echo name, ": ", age
```

## Operators

### Arithmetic Operators {.row-span-1}

```nim
var
  a = 10
  b = 3

echo a + b      # 13
echo a - b      # 7
echo a * b      # 30
echo a / b      # 3.333333
echo a div b    # 3
echo a mod b    # 1
echo a ^ b      # 1000
```

---

| Operator | Name           | Example   |
| -------- | -------------- | --------- |
| `+`      | Add            | `x + y`   |
| `-`      | Subtract       | `x - y`   |
| `*`      | Multiply       | `x * y`   |
| `/`      | Float Divide   | `x / y`   |
| `div`    | Integer Divide | `x div y` |
| `mod`    | Modulo         | `x mod y` |
| `^`      | Power          | `x ^ y`   |

{.show-header}

### Assignment

These only work on mutable (`var`) variables, not on `let` or `const`.

```nim
var value = 1990
echo value # 1990

value = 2
echo value # 2
```

---

| Operator | Description  | Example |
| -------- | ------------ | ------- |
| `=`      | Assign value | `x = y` |

{.show-header}

#### Update operations

| Syntax   | Expands to  | Meaning          |
| -------- | ----------- | ---------------- |
| `x += y` | `x = x + y` | add, assign      |
| `x -= y` | `x = x - y` | subtract, assign |
| `x *= y` | `x = x * y` | multiply, assign |

{.show-header}

Other variants like `/=` or `mod=` are not available,  
so just write them out explicitly, e.g. `x = x / y`.

### Comparison Operators {.row-span-2}

```nim
let
  x = 5
  y = 3

echo x > y
# prints "true" because 5 is greater than 3
```

---

| Symbol | Meaning                  | Example        |
| ------ | ------------------------ | -------------- |
| `==`   | equals                   | `if x == y`... |
| `!=`   | not equal to             | `if x != y`... |
| `>`    | greater than             | `if x > y`...  |
| `<`    | less than                | `if x < y`...  |
| `>=`   | greater than or equal to | `if x >= y`... |
| `<=`   | less than or equal to    | `if x <= y`... |

{.show-header}

Comparison operators are used to compare two values.

#### Lexicographical Comparison

They also work on `char` and `string` values via lexicographic order.

```nim
echo "apple" < "banana"  # true
echo "axyz" < "axyb"     # true
echo "ooooo" > "o"       # true
echo "abc" < "ab"        # false

echo 'a' < 'd'           # true
echo 'a' < 'Z'           # false
```

### Logical Operators {.row-span-2} {.col-span-2}

| Operator | Example                | Meaning                  |
| -------- | ---------------------- | ------------------------ |
| `and`    | `if a > 0 and a < 10:` | From 1 to 9              |
| `or`     | `if x == 0 or y == 0:` | Either one of them is 0  |
| `not`    | `if not isValid:`      | If `isValid` is not true |
| `xor`    | `if flagA xor flagB:`  | Only one of them is true |

{.show-header}

Logical operators work on `bool`.

#### Extra Bitwise Operators

| Operator | Example   | Result (with a = 60, b = 13) |
| -------- | --------- | ---------------------------- |
| `and`    | `a and b` | `12`                         |
| `or`     | `a or b`  | `61`                         |
| `xor`    | `a xor b` | `49`                         |
| `not`    | `not a`   | `-61`                        |
| `shl`    | `a shl 2` | `240`                        |
| `shr`    | `a shr 2` | `15`                         |

{.show-header}

These work on integers bit-by-bit; use them for flags, masks, low-level code, etc.

## Flow Control

### Match Case {.row-span-3}

```nim
let x = 5
case x:
of 0, 1:
  echo "small"
of 2, 3, 4:
  echo "medium"
else:
  echo "large"
```

---

`case of` can look for ranges too.

```nim
let age = 17

case age:
of 0..12:
  echo "child"
of 13..19:
  echo "teen"
else:
  echo "adult"
```

---

...and `strings` and `chars`, too

```nim
let cmd = "quit"

case cmd:
of "help":
  echo "show help"
of "quit", "exit":
  echo "bye!"
else:
  echo "unknown command"
```

---

```nim
let ch = 'g'
case ch:
of {'a', 'e', 'i', 'o', 'u'}:
  echo "vowel"
else:
  echo "consonant or symbol"
```

### Basic If-Else {.col-span-2}

```nim
let num = 5

if num > 10:
  echo "num is bigger than 10"
elif num < 10:
  echo "num is smaller than 10"
else:
  echo "num is exactly 10"
```

### One Liners {.col-span-2}

```nim
let
  a = 330
  b = 200

let r = if a > b: a else: b

echo r # 330
```

### Compile-Time Conditions {.col-span-2}

```nim
when defined(linux):
  echo "Compiled on Linux"
elif defined(windows):
  echo "Compiled on Windows"
else:
  echo "Unknown OS"
```

## Loops

### For Loops {.row-span-2}

```nim
for i in 1..5:
  echo i
# 1 2 3 4 5
```

---

```nim
for i in 0..<3:
  echo i
# 0 1 2
```

---

```nim
# i = index, v = value in sequence
for i, v in @[10, 20, 30]:
  echo i, ": ", v
# 0: 10
# 1: 20
# 2: 30
```

**Keep in mind**: \
1..5 = Inclusive (1 2 3 4 5) \
1..<5 = Exclusive (1 2 3 4)

### While Loops

```nim
var counter = 0

while counter <= 10:
  counter = counter + 1
  echo counter # prints 1..10
```

### Infinite Loops

```nim
while true:
  echo "ay! "
```

---

```nim
while 1 > 0:
  echo "echo... "
```

### Break Statements

```nim
var query = ""
while true:
  echo "Do you want out?"
  query = readLine(stdin)
  if query == "yes":
    echo "Well then."
    break
  else:
    echo "I'll ask again."

```

### Continue Statements

```nim
for i in 1..5:
  if i mod 2 == 0: continue
  echo i
# prints only odd numbers: 1 3 5
```

## Procedures

### Simple Procedure

```nim
proc salute() =
  echo "Hello!"

salute() # prints "Hello!"
```

### Procedures with Parameters

```nim
proc addition(a: int, b: int): int =
  a + b

echo addition(20, 30) # returns 50
```

### Using result {.row-span-2}

```nim
proc double(x: int): int =
  result = x * 2

echo double(5) # returns 10
```

---

Useful when building results step-by-step:

```nim
proc sumAll(xs: seq[int]): int =
  for n in xs:
    result += n

echo sumAll(@[1,1,1,1,1]) # returns 5
```

### Default Parameters {.col-span-2}

```nim
proc welcome(name = "stranger") =
  echo "Hi, ", name

welcome("Sophie") # prints "Hi, Sophie"
welcome()         # uses default, prints "Hi, stranger"
```

### Procedures returning multiple values

```nim
proc divmod(a, b: int): (int, int) =
  (a div b, a mod b)

let (q, r) = divmod(10, 3)
echo q, " ", r   # 3 1
```

### Anonymous Procedures (Lambdas)

```nim
let square = proc(x: int): int = x * x
echo square(5) # 25
```

### Procedures within Procedures {.row-span-2}

```nim
proc outer() =
  var count = 0

  proc inner() =
    inc(count)
    echo count

  inner()
  inner()

outer()   # prints 1 then 2
```

### Overloading

```nim
proc show(x: int) = echo "int: ", x
proc show(x: string) = echo "string: ", x

show(10)
show("hi")
```

### Discardable Procedure Returns

```nim
proc doSomething(): int {.discardable.} =
  123

doSomething()      # allowed now
```

## Object-Oriented Programming

### Ref Objects and Inheritance {.row-span-2}

```nim
type
  Animal = ref object of RootObj
    name: string

  Dog = ref object of Animal
    breed: string

method speak(a: Animal) {.base.} =
  echo a.name, " makes a sound."

method speak(d: Dog) =
  echo d.name, " barks!"

var
  a: Animal = Animal(name: "Creature")
  d: Animal = Dog(name: "Fido", breed: "Mutt")  # Dog upcasted to Animal

speak(a)  # Creature makes a sound.
speak(d)  # Fido barks!
```

Use `ref object of RootObj` + `method` when you need runtime polymorphism.

### Procs as Methods

```nim
type
  Counter = ref object
    value: int

proc inc(c: var Counter) =
  inc c.value

var c = Counter(value: 0)
inc(c)
echo c.value  # 1
```

### Constructor Procs

```nim
type
  Dog = ref object
    name: string
    age: int

proc newDog(name: string; age: int): Dog =
  Dog(name: name, age: age)

let d = newDog("Fido", 3)
echo d.name, " is ", d.age, " years old"
```

### Type tests and Downcasting {.col-span-2}

```nim
type
  Animal = ref object of RootObj
    name: string

  Dog = ref object of Animal
    breed: string

proc newDog(name, breed: string): Dog =
  Dog(name: name, breed: breed)

var a: Animal = newDog("Fido", "mutt")

if a of Dog:                       # runtime type check
  let d = Dog(a)                   # downcast
  echo d.name, " is a ", d.breed

```

`x of Type` checks the dynamic type; `Type(x)` downcasts (unsafe if you lie).

## Imports and Modules

### Basic Imports

```nim
import std/math

echo sqrt(9.0) # 3.0
```

See also: [Standard Library](https://nim-lang.org/docs/lib.html)

### Importing Multiple Modules

```nim
import std/[strutils, sequtils]

echo "hi".toUpperAscii()    # "HI"
echo @[1,2,3].mapIt(it * 2) # @[2, 4, 6]
```

### Importing Specific Modules

```nim
from std/strutils import toLowerAscii

echo toLowerAscii("ABC")  # "abc"
```

### Renaming Modules

```nim
import std/random as rng

rng.randomize()

echo rng.rand(1..10) # anywhere from 1 to 10
```

_Don't forget to use randomize() if you're using the std/random library, or else you won't have randomness._

### Creating Modules {.col-span-2}

```nim
# utils.nim
proc greet*(name: string) =
  echo "Hello, ", name
```

(The asterisk means "export this procedure from the module".)

---

```nim
# main.nim
import utils

greet("John") # prints "Hello, John"
```

### `when isMainModule`

```nim
proc run() =
  echo "Running..."

when isMainModule:
  run()  # Only runs when this file is the program entry point
```

_Code inside when isMainModule: is skipped when the file is imported._

### Re-exporting {.col-span-2}

```nim
# utils.nim
import std/strutils
export strutils    # re-export everything from strutils
```

---

Now main.nim can use toUpperAscii directly, through utils.

```nim
# main.nim
import utils

echo "hi".toUpperAscii()
```

### Prelude Module {.col-span-3}

```nim
import std/prelude
include std/prelude
  # same as:
  # import std/[os, strutils, times, parseutils, hashes, tables, sets, sequtils, parseopt, strformat]
let x = 1
assert "foo $# $#" % [$x, "bar"] == "foo 1 bar"
assert toSeq(1..3) == @[1, 2, 3]
when not defined(js) or defined(nodejs):
  assert getCurrentDir().len > 0
  assert ($now()).startsWith "20"
```

## Error Handling

### Try - Except - Finally {.row-span-2}

```nim
import std/strutils

try:
  let x = parseInt("42a")         # invalid integer
  echo x
except ValueError as e:
  echo "Value error: ", e.msg     # catch conversion error
except IOError:
  echo "I/O error!"
finally:
  echo "This always runs"
```

### Raising Exceptions

```nim
type
  MyError* = object of Exception

proc loadData(name: string) =
  if name == "":
    raise newException(MyError, "No name provided")
  # ... else proceed

loadData("")  # raises MyError
```

### `defer` for Cleanup

```nim
proc processFile(path: string) =
  var f = open(path, fmRead)
  defer:
    close(f)
  # work with f …
```

### Try as Exception

```nim
import std/strutils

let result = try: parseInt("bad")
             except ValueError: -1

echo result  # prints -1
```

### Exception Tracking with raises

```nim
proc riskyOperation() {.raises: [IOError].} =
  # this proc may raise IOError
  raise newException(IOError, "fail")

# A proc with {.raises: []} must not raise any catchable exception.
```

## Enums

### Basic Usage

```nim
type
  Direction = enum
    north, east, south, west

var d = north

if d == north:
  echo "Going up!"
```

### Enums and `case`

```nim
# with the same Direction enum:

var d = north

case d:
  of north: echo "N"
  of south: echo "S"
  of east:  echo "E"
  of west:  echo "W"
```

### Enum as an Ordinal

```nim
# with the same Direction enum:
echo ord(north)   # 0
echo succ(north)  # east
echo pred(south)  # east
```

## Iterators

### Basic Iterator {.row-span-2}

```nim
iterator countUp(a, b: int): int =
  var i = a
  while i <= b:
    yield i      # `yield` produces a value for the `for` loop
    inc i

for n in countUp(1, 5):
  echo n
# 1 2 3 4 5
```

### Common Built-In Iterators

```nim
for i in countup(1, 3):
  echo i               # 1 2 3

for i in countdown(3, 1):
  echo i               # 3 2 1
```

### Defining your own Iterator {.row-span-2}

```nim
iterator evensUpTo(n: int): int =
  var x = 0
  while x <= n:
    yield x
    x += 2

for e in evensUpTo(10):
  echo e        # 0 2 4 6 8 10
```

## Files & IO

### Check Paths and Existence {.row-span-2}

```nim
import std/os

if fileExists("data.txt"):
  echo "File exists!"

if dirExists("configs"):
  echo "Directory exists!"

echo getCurrentDir()
echo absolutePath("data.txt")
```

### Read / Write Whole File {.row-span-1}

```nim
# Write whole file
writeFile("out.txt", "Hello Nim!\n")

# Read whole file
let text = readFile("out.txt")
echo text
```

### Manual Open/Close with `defer` {.row-span-2}

```nim
import std/syncio

proc writeLog() =
  var f = open("log.txt", fmWrite)
  defer: f.close()
  f.writeLine("entry 1")
  f.writeLine("entry 2")

when isMainModule:
  writeLog()
```

### Read a File Line-By-Line

```nim
for line in lines("data.txt"):
  echo line
```

## Generics

### Generic Types and Procedures {.col-span-3}

```nim
type
  Box[T] = object
    value: T

proc wrap[T](x: T): Box[T] =
  Box[T](value: x)

let a = wrap(10)        # Box[int]
let b = wrap("hello")   # Box[string]

echo a.value            # 10
echo b.value            # hello
```

## Templates and Macros

### Templates

```nim
# Template = macro-like, expanded at compile time
template times2(x: untyped): untyped = (x) * 2
echo times2(21)  # 42
```

### Macros {.row-span-2} {.col-span-2}

```nim
import std/macros

macro dbg(expr: untyped): untyped =
  # prints both the expression and its value
  result = quote do:
    echo astToStr(`expr`), " = ", `expr`

let x = 10
dbg(x * 2)
# prints: x * 2 = 20
```