W3cubDocs

/Nim

system

The compiler depends on the System module to work properly and the System module depends on the compiler. Most of the routines listed here use special compiler magic.

Each module implicitly imports the System module; it must not be listed explicitly. Because of this there cannot be a user-defined module named system.

System module

The System module imports several separate modules, and their documentation is in separate files:

Here is a short overview of the most commonly used functions from the system module. Function names in the tables below are clickable and will take you to the full documentation of the function.

There are many more functions available than the ones listed in this overview. Use the table of contents on the left-hand side and/or Ctrl+F to navigate through this module.

Strings and characters

Proc	Usage
len(s)	Return the length of a string
chr(i)	Convert an `int` in the range `0..255` to a character
ord(c)	Return `int` value of a character
a & b	Concatenate two strings
s.add(c)	Add character to the string
$	Convert various types to string

See also:

strutils module for common string functions
strformat module for string interpolation and formatting
unicode module for Unicode UTF-8 handling
strscans for scanf and scanp macros, which offer easier substring extraction than regular expressions
strtabs module for efficient hash tables (dictionaries, in some programming languages) mapping from strings to strings

Seqs

Proc	Usage
newSeq	Create a new sequence of a given length
newSeqOfCap	Create a new sequence with zero length and a given capacity
setLen	Set the length of a sequence
len	Return the length of a sequence
@	Turn an array into a sequence
add	Add an item to the sequence
insert	Insert an item at a specific position
delete	Delete an item while preserving the order of elements (`O(n)` operation)
del	`O(1)` removal, doesn't preserve the order
pop	Remove and return last item of a sequence
x & y	Concatenate two sequences
x[a .. b]	Slice of a sequence (both ends included)
x[a .. ^b]	Slice of a sequence but `b` is a reversed index (both ends included)
x[a ..< b]	Slice of a sequence (excluded upper bound)

See also:

sequtils module for operations on container types (including strings)
json module for a structure which allows heterogeneous members
lists module for linked lists

Sets

Built-in bit sets.

Proc	Usage
incl	Include element `y` in the set `x`
excl	Exclude element `y` from the set `x`
card	Return the cardinality of the set, i.e. the number of elements
a * b	Intersection
a + b	Union
a - b	Difference
contains	Check if an element is in the set
a < b	Check if `a` is a subset of `b`

See also:

setutils module for bit set convenience functions
sets module for hash sets
intsets module for efficient int sets

Numbers

Proc	Usage	Also known as (in other languages)
div	Integer division	`//`
mod	Integer modulo (remainder)	`%`
shl	Shift left	`<<`
shr	Shift right	`>>`
ashr	Arithmetic shift right
and	Bitwise `and`	`&`
or	Bitwise `or`	`\|`
xor	Bitwise `xor`	`^`
not	Bitwise `not` (complement)	`~`
toInt	Convert floating-point number into an `int`
toFloat	Convert an integer into a `float`

See also:

math module for mathematical operations like trigonometric functions, logarithms, square and cubic roots, etc.
complex module for operations on complex numbers
rationals module for rational numbers

Ordinals

Ordinal type includes integer, bool, character, and enumeration types, as well as their subtypes.

Proc	Usage
succ	Successor of the value
pred	Predecessor of the value
inc	Increment the ordinal
dec	Decrement the ordinal
high	Return the highest possible value
low	Return the lowest possible value
ord	Return `int` value of an ordinal value

Misc

Proc	Usage
is	Check if two arguments are of the same type
isnot	Negated version of `is`
!=	Not equals
addr	Take the address of a memory location
T and F	Boolean `and`
T or F	Boolean `or`
T xor F	Boolean `xor` (exclusive or)
not T	Boolean `not`
a[^x]	Take the element at the reversed index `x`
a .. b	Binary slice that constructs an interval `[a, b]`
a ..^ b	Interval `[a, b]` but `b` as reversed index
a ..< b	Interval `[a, b)` (excluded upper bound)
runnableExamples	Create testable documentation

Default new string implementation used by Nim's core.Default seq implementation used by Nim's core.

Channel support for threads.

Note: This is part of the system module. Do not import it directly. To activate thread support compile with the --threads:on command line switch.

Note: Channels are designed for the Thread type. They are unstable when used with spawn

Note: The current implementation of message passing does not work with cyclic data structures.

Note: Channels cannot be passed between threads. Use globals or pass them by ptr.

Example

The following is a simple example of two different ways to use channels: blocking and non-blocking.

# Be sure to compile with --threads:on.
# The channels and threads modules are part of system and should not be
# imported.
import std/os

# Channels can either be:
#  - declared at the module level, or
#  - passed to procedures by ptr (raw pointer) -- see note on safety.
#
# For simplicity, in this example a channel is declared at module scope.
# Channels are generic, and they include support for passing objects between
# threads.
# Note that objects passed through channels will be deeply copied.
var chan: Channel[string]

# This proc will be run in another thread using the threads module.
proc firstWorker() =
  chan.send("Hello World!")

# This is another proc to run in a background thread. This proc takes a while
# to send the message since it sleeps for 2 seconds (or 2000 milliseconds).
proc secondWorker() =
  sleep(2000)
  chan.send("Another message")

# Initialize the channel.
chan.open()

# Launch the worker.
var worker1: Thread[void]
createThread(worker1, firstWorker)

# Block until the message arrives, then print it out.
echo chan.recv() # "Hello World!"

# Wait for the thread to exit before moving on to the next example.
worker1.joinThread()

# Launch the other worker.
var worker2: Thread[void]
createThread(worker2, secondWorker)
# This time, use a non-blocking approach with tryRecv.
# Since the main thread is not blocked, it could be used to perform other
# useful work while it waits for data to arrive on the channel.
while true:
  let tried = chan.tryRecv()
  if tried.dataAvailable:
    echo tried.msg # "Another message"
    break
  
  echo "Pretend I'm doing useful work..."
  # For this example, sleep in order not to flood stdout with the above
  # message.
  sleep(400)

# Wait for the second thread to exit before cleaning up the channel.
worker2.joinThread()

# Clean up the channel.
chan.close()

Sample output

The program should output something similar to this, but keep in mind that exact results may vary in the real world:

Hello World!
Pretend I'm doing useful work...
Pretend I'm doing useful work...
Pretend I'm doing useful work...
Pretend I'm doing useful work...
Pretend I'm doing useful work...
Another message

Passing Channels Safely

Note that when passing objects to procedures on another thread by pointer (for example through a thread's argument), objects created using the default allocator will use thread-local, GC-managed memory. Thus it is generally safer to store channel objects in global variables (as in the above example), in which case they will use a process-wide (thread-safe) shared heap.

However, it is possible to manually allocate shared memory for channels using e.g. system.allocShared0 and pass these pointers through thread arguments:

proc worker(channel: ptr Channel[string]) =
  let greeting = channel[].recv()
  echo greeting

proc localChannelExample() =
  # Use allocShared0 to allocate some shared-heap memory and zero it.
  # The usual warnings about dealing with raw pointers apply. Exercise caution.
  var channel = cast[ptr Channel[string]](
    allocShared0(sizeof(Channel[string]))
  )
  channel[].open()
  # Create a thread which will receive the channel as an argument.
  var thread: Thread[ptr Channel[string]]
  createThread(thread, worker, channel)
  channel[].send("Hello from the main thread!")
  # Clean up resources.
  thread.joinThread()
  channel[].close()
  deallocShared(channel)

localChannelExample() # "Hello from the main thread!"

Imports

exceptions, since, ctypes, ctypes, sysatomics, ansi_c, memory, syslocks, threadtypes, assertions, iterators, coro_detection, dollars, typedthreads, miscdollars, stacktraces, countbits_impl, syslocks, sysatomics, digitsutils, syslocks, digitsutils, repr_v2, widestrs, syncio

Types

AllocStats = object

system

System module

Strings and characters

Seqs

Sets

Numbers

Ordinals

Misc

Example

Sample output

Passing Channels Safely

Imports

Types

Vars

Lets

Consts

Procs

Iterators

Macros

Templates