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.
The amount of available functions is much larger. 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
andscanp
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:
- 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 |
Imports
- since, ansi_c, memory, assertions, iterators, dollars, miscdollars, stacktraces, formatfloat, widestrs, io
Types
float {...}{.magic: Float.}
- Default floating point type. Source Edit
float32 {...}{.magic: Float32.}
- 32 bit floating point type. Source Edit
float64 {...}{.magic: Float.}
- 64 bit floating point type. Source Edit
char {...}{.magic: Char.}
- Built-in 8 bit character type (unsigned). Source Edit
string {...}{.magic: String.}
- Built-in string type. Source Edit
cstring {...}{.magic: Cstring.}
- Built-in cstring (compatible string) type. Source Edit
pointer {...}{.magic: Pointer.}
- Built-in pointer type, use the
addr
operator to get a pointer to a variable. Source Edit typedesc {...}{.magic: TypeDesc.}
- Meta type to denote a type description. Source Edit
ptr[T] {...}{.magic: Pointer.}
- Built-in generic untraced pointer type. Source Edit
ref[T] {...}{.magic: Pointer.}
- Built-in generic traced pointer type. Source Edit
void {...}{.magic: "VoidType".}
- Meta type to denote the absence of any type. Source Edit
auto {...}{.magic: Expr.}
- Meta type for automatic type determination. Source Edit
any = distinct auto
- Meta type for any supported type. Source Edit
untyped {...}{.magic: Expr.}
- Meta type to denote an expression that is not resolved (for templates). Source Edit
typed {...}{.magic: Stmt.}
- Meta type to denote an expression that is resolved (for templates). Source Edit
int {...}{.magic: "Int".}
- Default integer type; bitwidth depends on architecture, but is always the same as a pointer. Source Edit
int8 {...}{.magic: "Int8".}
- Signed 8 bit integer type. Source Edit
int16 {...}{.magic: "Int16".}
- Signed 16 bit integer type. Source Edit
int32 {...}{.magic: "Int32".}
- Signed 32 bit integer type. Source Edit
int64 {...}{.magic: "Int64".}
- Signed 64 bit integer type. Source Edit
uint {...}{.magic: "UInt".}
- Unsigned default integer type. Source Edit
uint8 {...}{.magic: "UInt8".}
- Unsigned 8 bit integer type. Source Edit
uint16 {...}{.magic: "UInt16".}
- Unsigned 16 bit integer type. Source Edit
uint32 {...}{.magic: "UInt32".}
- Unsigned 32 bit integer type. Source Edit
uint64 {...}{.magic: "UInt64".}
- Unsigned 64 bit integer type. Source Edit
bool {...}{.magic: "Bool".} = enum false = 0, true = 1
- Built-in boolean type. Source Edit
SomeSignedInt = int | int8 | int16 | int32 | int64
- Type class matching all signed integer types. Source Edit
SomeUnsignedInt = uint | uint8 | uint16 | uint32 | uint64
- Type class matching all unsigned integer types. Source Edit
SomeInteger = SomeSignedInt | SomeUnsignedInt
- Type class matching all integer types. Source Edit
SomeOrdinal = int | int8 | int16 | int32 | int64 | bool | enum | uint | uint8 | uint16 | uint32 | uint64
- Type class matching all ordinal types; however this includes enums with holes. See also
Ordinal
Source Edit BiggestInt = int64
- is an alias for the biggest signed integer type the Nim compiler supports. Currently this is
int64
, but it is platform-dependent in general. Source Edit SomeFloat = float | float32 | float64
- Type class matching all floating point number types. Source Edit
SomeNumber = SomeInteger | SomeFloat
- Type class matching all number types. Source Edit
Ordinal[T] {...}{.magic: Ordinal.}
- Generic ordinal type. Includes integer, bool, character, and enumeration types as well as their subtypes. See also
SomeOrdinal
. Source Edit static[T] {...}{.magic: "Static".}
-
Meta type representing all values that can be evaluated at compile-time.
The type coercion
Source Editstatic(x)
can be used to force the compile-time evaluation of the given expressionx
. type[T] {...}{.magic: "Type".}
-
Meta type representing the type of all type values.
The coercion
Source Edittype(x)
can be used to obtain the type of the given expressionx
. TypeOfMode = enum typeOfProc, ## Prefer the interpretation that means `x` is a proc call. typeOfIter ## Prefer the interpretation that means `x` is an iterator call.
- Possible modes of
typeof
. Source Edit range[T] {...}{.magic: "Range".}
- Generic type to construct range types. Source Edit
array[I; T] {...}{.magic: "Array".}
- Generic type to construct fixed-length arrays. Source Edit
openArray[T] {...}{.magic: "OpenArray".}
- Generic type to construct open arrays. Open arrays are implemented as a pointer to the array data and a length field. Source Edit
varargs[T] {...}{.magic: "Varargs".}
- Generic type to construct a varargs type. Source Edit
seq[T] {...}{.magic: "Seq".}
- Generic type to construct sequences. Source Edit
set[T] {...}{.magic: "Set".}
- Generic type to construct bit sets. Source Edit
UncheckedArray[T] {...}{.magic: "UncheckedArray".}
- Source Edit
sink[T] {...}{.magic: "BuiltinType".}
- Source Edit
lent[T] {...}{.magic: "BuiltinType".}
- Source Edit
HSlice[T; U] = object a*: T ## The lower bound (inclusive). b*: U ## The upper bound (inclusive).
- "Heterogeneous" slice type. Source Edit
Slice[T] = HSlice[T, T]
- An alias for
HSlice[T, T]
. Source Edit byte = uint8
- This is an alias for
uint8
, that is an unsigned integer, 8 bits wide. Source Edit Natural = range[0 .. high(int)]
- is an
int
type ranging from zero to the maximum value of anint
. This type is often useful for documentation and debugging. Source Edit Positive = range[1 .. high(int)]
- is an
int
type ranging from one to the maximum value of anint
. This type is often useful for documentation and debugging. Source Edit RootObj {...}{.compilerproc, inheritable.} = object
-
The root of Nim's object hierarchy.
Objects should inherit from
Source EditRootObj
or one of its descendants. However, objects that have no ancestor are also allowed. RootRef = ref RootObj
- Reference to
RootObj
. Source Edit RootEffect {...}{.compilerproc.} = object of RootObj
-
Base effect class.
Each effect should inherit from
Source EditRootEffect
unless you know what you're doing. TimeEffect = object of RootEffect
- Time effect. Source Edit
IOEffect = object of RootEffect
- IO effect. Source Edit
ReadIOEffect = object of IOEffect
- Effect describing a read IO operation. Source Edit
WriteIOEffect = object of IOEffect
- Effect describing a write IO operation. Source Edit
ExecIOEffect = object of IOEffect
- Effect describing an executing IO operation. Source Edit
StackTraceEntry = object procname*: cstring ## Name of the proc that is currently executing. line*: int ## Line number of the proc that is currently executing. filename*: cstring ## Filename of the proc that is currently executing. when NimStackTraceMsgs: frameMsg*: string ## When a stacktrace is generated in a given frame and ## rendered at a later time, we should ensure the stacktrace ## data isn't invalidated; any pointer into PFrame is ## subject to being invalidated so shouldn't be stored. when defined(nimStackTraceOverride): programCounter*: uint ## Program counter - will be used to get the rest of the info, ## when `$` is called on this type. We can't use ## "cuintptr_t" in here. procnameStr*, filenameStr*: string ## GC-ed alternatives to "procname" and "filename"
- In debug mode exceptions store the stack trace that led to them. A
StackTraceEntry
is a single entry of the stack trace. Source Edit Exception {...}{.compilerproc, magic: "Exception".} = object of RootObj parent*: ref Exception ## Parent exception (can be used as a stack). name*: cstring ## The exception's name is its Nim identifier. ## This field is filled automatically in the ## ``raise`` statement. msg* {...}{.exportc: "message".}: string ## The exception's message. Not ## providing an exception message ## is bad style. when defined(js): trace: string else: trace: seq[StackTraceEntry] up: ref Exception
-
Base exception class.
Each exception has to inherit from
Source EditException
. See the full exception hierarchy. Defect = object of Exception
- Abstract base class for all exceptions that Nim's runtime raises but that are strictly uncatchable as they can also be mapped to a
quit
/trap
/exit
operation. Source Edit CatchableError = object of Exception
- Abstract class for all exceptions that are catchable. Source Edit
IOError = object of CatchableError
- Raised if an IO error occurred. Source Edit
EOFError = object of IOError
- Raised if an IO "end of file" error occurred. Source Edit
OSError = object of CatchableError errorCode*: int32 ## OS-defined error code describing this error.
- Raised if an operating system service failed. Source Edit
LibraryError = object of OSError
- Raised if a dynamic library could not be loaded. Source Edit
ResourceExhaustedError = object of CatchableError
- Raised if a resource request could not be fulfilled. Source Edit
ArithmeticDefect = object of Defect
- Raised if any kind of arithmetic error occurred. Source Edit
DivByZeroDefect = object of ArithmeticDefect
- Raised for runtime integer divide-by-zero errors. Source Edit
OverflowDefect = object of ArithmeticDefect
-
Raised for runtime integer overflows.
This happens for calculations whose results are too large to fit in the provided bits.
Source Edit AccessViolationDefect = object of Defect
- Raised for invalid memory access errors Source Edit
AssertionDefect = object of Defect
-
Raised when assertion is proved wrong.
Usually the result of using the assert() template.
Source Edit ValueError = object of CatchableError
- Raised for string and object conversion errors. Source Edit
KeyError = object of ValueError
-
Raised if a key cannot be found in a table.
Mostly used by the tables module, it can also be raised by other collection modules like sets or strtabs.
Source Edit OutOfMemDefect = object of Defect
- Raised for unsuccessful attempts to allocate memory. Source Edit
IndexDefect = object of Defect
- Raised if an array index is out of bounds. Source Edit
FieldDefect = object of Defect
- Raised if a record field is not accessible because its discriminant's value does not fit. Source Edit
RangeDefect = object of Defect
- Raised if a range check error occurred. Source Edit
StackOverflowDefect = object of Defect
- Raised if the hardware stack used for subroutine calls overflowed. Source Edit
ReraiseDefect = object of Defect
- Raised if there is no exception to reraise. Source Edit
ObjectAssignmentDefect = object of Defect
- Raised if an object gets assigned to its parent's object. Source Edit
ObjectConversionDefect = object of Defect
- Raised if an object is converted to an incompatible object type. You can use
of
operator to check if conversion will succeed. Source Edit FloatingPointDefect = object of Defect
- Base class for floating point exceptions. Source Edit
FloatInvalidOpDefect = object of FloatingPointDefect
-
Raised by invalid operations according to IEEE.
Raised by
Source Edit0.0/0.0
, for example. FloatDivByZeroDefect = object of FloatingPointDefect
-
Raised by division by zero.
Divisor is zero and dividend is a finite nonzero number.
Source Edit FloatOverflowDefect = object of FloatingPointDefect
-
Raised for overflows.
The operation produced a result that exceeds the range of the exponent.
Source Edit FloatUnderflowDefect = object of FloatingPointDefect
-
Raised for underflows.
The operation produced a result that is too small to be represented as a normal number.
Source Edit FloatInexactDefect = object of FloatingPointDefect
-
Raised for inexact results.
The operation produced a result that cannot be represented with infinite precision -- for example:
2.0 / 3.0, log(1.1)
Note: Nim currently does not detect these!
Source Edit DeadThreadDefect = object of Defect
- Raised if it is attempted to send a message to a dead thread. Source Edit
NilAccessDefect = object of Defect
-
Raised on dereferences of
nil
pointers.This is only raised if the segfaults module was imported!
Source Edit ArithmeticError {...}{.deprecated: "See corresponding Defect".} = ArithmeticDefect
- Source Edit
DivByZeroError {...}{.deprecated: "See corresponding Defect".} = DivByZeroDefect
- Source Edit
OverflowError {...}{.deprecated: "See corresponding Defect".} = OverflowDefect
- Source Edit
AccessViolationError {...}{.deprecated: "See corresponding Defect".} = AccessViolationDefect
- Source Edit
AssertionError {...}{.deprecated: "See corresponding Defect".} = AssertionDefect
- Source Edit
OutOfMemError {...}{.deprecated: "See corresponding Defect".} = OutOfMemDefect
- Source Edit
IndexError {...}{.deprecated: "See corresponding Defect".} = IndexDefect
- Source Edit
FieldError {...}{.deprecated: "See corresponding Defect".} = FieldDefect
- Source Edit
RangeError {...}{.deprecated: "See corresponding Defect".} = RangeDefect
- Source Edit
StackOverflowError {...}{.deprecated: "See corresponding Defect".} = StackOverflowDefect
- Source Edit
ReraiseError {...}{.deprecated: "See corresponding Defect".} = ReraiseDefect
- Source Edit
ObjectAssignmentError {...}{.deprecated: "See corresponding Defect".} = ObjectAssignmentDefect
- Source Edit
ObjectConversionError {...}{.deprecated: "See corresponding Defect".} = ObjectConversionDefect
- Source Edit
FloatingPointError {...}{.deprecated: "See corresponding Defect".} = FloatingPointDefect
- Source Edit
FloatInvalidOpError {...}{.deprecated: "See corresponding Defect".} = FloatInvalidOpDefect
- Source Edit
FloatDivByZeroError {...}{.deprecated: "See corresponding Defect".} = FloatDivByZeroDefect
- Source Edit
FloatOverflowError {...}{.deprecated: "See corresponding Defect".} = FloatOverflowDefect
- Source Edit
FloatUnderflowError {...}{.deprecated: "See corresponding Defect".} = FloatUnderflowDefect
- Source Edit
FloatInexactError {...}{.deprecated: "See corresponding Defect".} = FloatInexactDefect
- Source Edit
DeadThreadError {...}{.deprecated: "See corresponding Defect".} = DeadThreadDefect
- Source Edit
NilAccessError {...}{.deprecated: "See corresponding Defect".} = NilAccessDefect
- Source Edit
JsRoot = ref object of RootObj
- Root type of the JavaScript object hierarchy Source Edit
owned[T] {...}{.magic: "BuiltinType".}
- type constructor to mark a ref/ptr or a closure as
owned
. Source Edit Endianness = enum littleEndian, bigEndian
- Type describing the endianness of a processor. Source Edit
TaintedString = string
- A distinct string type that is tainted, see taint mode for details. It is an alias for
string
if the taint mode is not turned on. Source Edit ByteAddress = int
- is the signed integer type that should be used for converting pointers to integer addresses for readability. Source Edit
BiggestFloat = float64
- is an alias for the biggest floating point type the Nim compiler supports. Currently this is
float64
, but it is platform-dependent in general. Source Edit BiggestUInt = uint64
- is an alias for the biggest unsigned integer type the Nim compiler supports. Currently this is
uint32
for JS anduint64
for other targets. Source Edit clong {...}{.importc: "long", nodecl.} = int
- This is the same as the type
long
in C. Source Edit culong {...}{.importc: "unsigned long", nodecl.} = uint
- This is the same as the type
unsigned long
in C. Source Edit cchar {...}{.importc: "char", nodecl.} = char
- This is the same as the type
char
in C. Source Edit cschar {...}{.importc: "signed char", nodecl.} = int8
- This is the same as the type
signed char
in C. Source Edit cshort {...}{.importc: "short", nodecl.} = int16
- This is the same as the type
short
in C. Source Edit cint {...}{.importc: "int", nodecl.} = int32
- This is the same as the type
int
in C. Source Edit csize {...}{.importc: "size_t", nodecl, deprecated: "use `csize_t` instead".} = int
- This isn't the same as
size_t
in C. Don't use it. Source Edit csize_t {...}{.importc: "size_t", nodecl.} = uint
- This is the same as the type
size_t
in C. Source Edit clonglong {...}{.importc: "long long", nodecl.} = int64
- This is the same as the type
long long
in C. Source Edit cfloat {...}{.importc: "float", nodecl.} = float32
- This is the same as the type
float
in C. Source Edit cdouble {...}{.importc: "double", nodecl.} = float64
- This is the same as the type
double
in C. Source Edit clongdouble {...}{.importc: "long double", nodecl.} = BiggestFloat
- This is the same as the type
long double
in C. This C type is not supported by Nim's code generator. Source Edit cuchar {...}{.importc: "unsigned char", nodecl.} = char
- This is the same as the type
unsigned char
in C. Source Edit cushort {...}{.importc: "unsigned short", nodecl.} = uint16
- This is the same as the type
unsigned short
in C. Source Edit cuint {...}{.importc: "unsigned int", nodecl.} = uint32
- This is the same as the type
unsigned int
in C. Source Edit culonglong {...}{.importc: "unsigned long long", nodecl.} = uint64
- This is the same as the type
unsigned long long
in C. Source Edit cstringArray {...}{.importc: "char**", nodecl.} = ptr UncheckedArray[cstring]
- This is binary compatible to the type
char**
in C. The array's high value is large enough to disable bounds checking in practice. Use cstringArrayToSeq proc to convert it into aseq[string]
. Source Edit PFloat32 = ptr float32
- An alias for
ptr float32
. Source Edit PFloat64 = ptr float64
- An alias for
ptr float64
. Source Edit PInt64 = ptr int64
- An alias for
ptr int64
. Source Edit PInt32 = ptr int32
- An alias for
ptr int32
. Source Edit AllocStats = object allocCount: int deallocCount: int
- Source Edit
AtomType = SomeNumber | pointer | ptr | char | bool
- Type Class representing valid types for use with atomic procs Source Edit
GC_Strategy = enum gcThroughput, ## optimize for throughput gcResponsiveness, ## optimize for responsiveness (default) gcOptimizeTime, ## optimize for speed gcOptimizeSpace ## optimize for memory footprint
- The strategy the GC should use for the application. Source Edit
PFrame = ptr TFrame
- Represents a runtime frame of the call stack; part of the debugger API. Source Edit
TFrame {...}{.importc, nodecl, final.} = object prev*: PFrame ## Previous frame; used for chaining the call stack. procname*: cstring ## Name of the proc that is currently executing. line*: int ## Line number of the proc that is currently executing. filename*: cstring ## Filename of the proc that is currently executing. len*: int16 ## Length of the inspectable slots. calldepth*: int16 ## Used for max call depth checking. when NimStackTraceMsgs: frameMsgLen*: int ## end position in frameMsgBuf for this frame.
- The frame itself. Source Edit
FileSeekPos = enum fspSet, ## Seek to absolute value fspCur, ## Seek relative to current position fspEnd ## Seek relative to end
- Position relative to which seek should happen. Source Edit
ForeignCell = object data*: pointer owner: ptr GcHeap
- Source Edit
BackwardsIndex = distinct int
- Type that is constructed by
^
for reversed array accesses. (See ^ template) Source Edit NimNode {...}{.magic: "PNimrodNode".} = ref NimNodeObj
- Represents a Nim AST node. Macros operate on this type. Source Edit
ForLoopStmt {...}{.compilerproc.} = object
- A special type that marks a macro as a for-loop macro. See "For Loop Macro". Source Edit
Vars
programResult: int
- deprecated, prefer
quit
orexitprocs.getProgramResult
,exitprocs.setProgramResult
. Source Edit globalRaiseHook: proc (e: ref Exception): bool {...}{.nimcall, gcsafe, locks: 0.}
-
With this hook you can influence exception handling on a global level. If not nil, every 'raise' statement ends up calling this hook.
Warning: Ordinary application code should never set this hook! You better know what you do when setting this.
If
Source EditglobalRaiseHook
returns false, the exception is caught and does not propagate further through the call stack. localRaiseHook: proc (e: ref Exception): bool {...}{.nimcall, gcsafe, locks: 0.}
-
With this hook you can influence exception handling on a thread local level. If not nil, every 'raise' statement ends up calling this hook.
Warning: Ordinary application code should never set this hook! You better know what you do when setting this.
If
Source EditlocalRaiseHook
returns false, the exception is caught and does not propagate further through the call stack. outOfMemHook: proc () {...}{.nimcall, tags: [], gcsafe, locks: 0, raises: [].}
-
Set this variable to provide a procedure that should be called in case of an out of memory event. The standard handler writes an error message and terminates the program.
outOfMemHook
can be used to raise an exception in case of OOM like so:var gOutOfMem: ref EOutOfMemory new(gOutOfMem) # need to be allocated *before* OOM really happened! gOutOfMem.msg = "out of memory" proc handleOOM() = raise gOutOfMem system.outOfMemHook = handleOOM
If the handler does not raise an exception, ordinary control flow continues and the program is terminated.
Source Edit unhandledExceptionHook: proc (e: ref Exception) {...}{.nimcall, tags: [], gcsafe, locks: 0, raises: [].}
- Set this variable to provide a procedure that should be called in case of an
unhandle exception
event. The standard handler writes an error message and terminates the program, except when using--os:any
Source Edit errorMessageWriter: (proc (msg: string) {...}{.tags: [WriteIOEffect], gcsafe, locks: 0, nimcall.})
- Function that will be called instead of
stdmsg.write
when printing stacktrace. Unstable API. Source Edit onUnhandledException: (proc (errorMsg: string) {...}{.nimcall, gcsafe.})
-
Set this error handler to override the existing behaviour on an unhandled exception.
The default is to write a stacktrace to
Source Editstderr
and then callquit(1)
. Unstable API.
Lets
nimvm: bool = false
- May be used only in
when
expression. It is true in Nim VM context and false otherwise. Source Edit
Consts
on = true
- Alias for
true
. Source Edit off = false
- Alias for
false
. Source Edit appType: string = ""
- A string that describes the application type. Possible values:
"console"
,"gui"
,"lib"
. Source Edit NoFakeVars = false
-
true
if the backend doesn't support "fake variables" likevar EBADF {.importc.}: cint
. Source Edit isMainModule: bool = false
- True only when accessed in the main module. This works thanks to compiler magic. It is useful to embed testing code in a module. Source Edit
CompileDate: string = "0000-00-00"
- The date (in UTC) of compilation as a string of the form
YYYY-MM-DD
. This works thanks to compiler magic. Source Edit CompileTime: string = "00:00:00"
- The time (in UTC) of compilation as a string of the form
HH:MM:SS
. This works thanks to compiler magic. Source Edit cpuEndian: Endianness = littleEndian
- The endianness of the target CPU. This is a valuable piece of information for low-level code only. This works thanks to compiler magic. Source Edit
hostOS: string = ""
-
A string that describes the host operating system.
Possible values:
Source Edit"windows"
,"macosx"
,"linux"
,"netbsd"
,"freebsd"
,"openbsd"
,"solaris"
,"aix"
,"haiku"
,"standalone"
. hostCPU: string = ""
-
A string that describes the host CPU.
Possible values:
Source Edit"i386"
,"alpha"
,"powerpc"
,"powerpc64"
,"powerpc64el"
,"sparc"
,"amd64"
,"mips"
,"mipsel"
,"arm"
,"arm64"
,"mips64"
,"mips64el"
,"riscv64"
. nimEnableCovariance = false
- Source Edit
QuitSuccess = 0
- is the value that should be passed to quit to indicate success. Source Edit
QuitFailure = 1
- is the value that should be passed to quit to indicate failure. Source Edit
Inf = 0x7FF0000000000000'f64
- Contains the IEEE floating point value of positive infinity. Source Edit
NegInf = 0xFFF0000000000000'f64
- Contains the IEEE floating point value of negative infinity. Source Edit
NaN = 0x7FF7FFFFFFFFFFFF'f64
-
Contains an IEEE floating point value of Not A Number.
Note that you cannot compare a floating point value to this value and expect a reasonable result - use the
Source Editclassify
procedure in the math module for checking for NaN. nimCoroutines = false
- Source Edit
NimMajor: int = 1
- is the major number of Nim's version. Example:
when (NimMajor, NimMinor, NimPatch) >= (1, 3, 1): discard
Source Edit NimMinor: int = 4
- is the minor number of Nim's version. Odd for devel, even for releases. Source Edit
NimPatch: int = 8
- is the patch number of Nim's version. Odd for devel, even for releases. Source Edit
NimVersion: string = "1.4.8"
- is the version of Nim as a string. Source Edit
nativeStackTraceSupported = false
- Source Edit
Procs
proc `not`(x: bool): bool {...}{.magic: "Not", noSideEffect.}
- Boolean not; returns true if
x == false
. Source Edit proc `and`(x, y: bool): bool {...}{.magic: "And", noSideEffect.}
-
Boolean
and
; returns true ifx == y == true
(if both arguments are true).Evaluation is lazy: if
Source Editx
is false,y
will not even be evaluated. proc `or`(x, y: bool): bool {...}{.magic: "Or", noSideEffect.}
-
Boolean
or
; returns true ifnot (not x and not y)
(if any of the arguments is true).Evaluation is lazy: if
Source Editx
is true,y
will not even be evaluated. proc `xor`(x, y: bool): bool {...}{.magic: "Xor", noSideEffect.}
- Boolean
exclusive or
; returns true ifx != y
(if either argument is true while the other is false). Source Edit proc compileOption(option: string): bool {...}{.magic: "CompileOption", noSideEffect.}
- Can be used to determine an
on|off
compile-time option. Example:when compileOption("floatchecks"): echo "compiled with floating point NaN and Inf checks"
Source Edit proc compileOption(option, arg: string): bool {...}{.magic: "CompileOptionArg", noSideEffect.}
- Can be used to determine an enum compile-time option. Example:
when compileOption("opt", "size") and compileOption("gc", "boehm"): echo "compiled with optimization for size and uses Boehm's GC"
Source Edit proc `or`(a, b: typedesc): typedesc {...}{.magic: "TypeTrait", noSideEffect.}
- Constructs an
or
meta class. Source Edit proc `and`(a, b: typedesc): typedesc {...}{.magic: "TypeTrait", noSideEffect.}
- Constructs an
and
meta class. Source Edit proc `not`(a: typedesc): typedesc {...}{.magic: "TypeTrait", noSideEffect.}
- Constructs an
not
meta class. Source Edit proc defined(x: untyped): bool {...}{.magic: "Defined", noSideEffect, compileTime.}
-
Special compile-time procedure that checks whether
x
is defined.x
is an external symbol introduced through the compiler's -d:x switch to enable build time conditionals:when not defined(release): # Do here programmer friendly expensive sanity checks. # Put here the normal code
Source Edit proc runnableExamples(rdoccmd = ""; body: untyped) {...}{.magic: "RunnableExamples".}
- A section you should use to mark runnable example code with.
- In normal debug and release builds code within a
runnableExamples
section is ignored. - The documentation generator is aware of these examples and considers them part of the
##
doc comment. As the last step of documentation generation each runnableExample is put in its own file$file_examples$i.nim
, compiled and tested. The collected examples are put into their own module to ensure the examples do not refer to non-exported symbols.
Usage:
proc double*(x: int): int = ## This proc doubles a number. runnableExamples: ## at module scope assert double(5) == 10 block: ## at block scope defer: echo "done" result = 2 * x runnableExamples "-d:foo -b:cpp": import std/compilesettings doAssert querySetting(backend) == "cpp" runnableExamples "-r:off": ## this one is only compiled import std/browsers openDefaultBrowser "https://forum.nim-lang.org/"
Source Edit - In normal debug and release builds code within a
proc declared(x: untyped): bool {...}{.magic: "Declared", noSideEffect, compileTime.}
-
Special compile-time procedure that checks whether
x
is declared.x
has to be an identifier or a qualified identifier.See also:
This can be used to check whether a library provides a certain feature or not:
when not declared(strutils.toUpper): # provide our own toUpper proc here, because strutils is # missing it.
Source Edit proc declaredInScope(x: untyped): bool {...}{.magic: "DeclaredInScope", noSideEffect, compileTime.}
- Special compile-time procedure that checks whether
x
is declared in the current scope.x
has to be an identifier. Source Edit proc `addr`[T](x: var T): ptr T {...}{.magic: "Addr", noSideEffect.}
-
Builtin
addr
operator for taking the address of a memory location. Cannot be overloaded.See also:
var buf: seq[char] = @['a','b','c'] p = buf[1].addr echo p.repr # ref 0x7faa35c40059 --> 'b' echo p[] # b
Source Edit proc unsafeAddr[T](x: T): ptr T {...}{.magic: "Addr", noSideEffect.}
-
Builtin
addr
operator for taking the address of a memory location. This works even forlet
variables or parameters for better interop with C and so it is considered even more unsafe than the ordinary addr.Note: When you use it to write a wrapper for a C library, you should always check that the original library does never write to data behind the pointer that is returned from this procedure.
Cannot be overloaded.
Source Edit proc typeof(x: untyped; mode = typeOfIter): typedesc {...}{.magic: "TypeOf", noSideEffect, compileTime.}
- Builtin
typeof
operation for accessing the type of an expression. Since version 0.20.0. Source Edit proc internalNew[T](a: var ref T) {...}{.magic: "New", noSideEffect.}
- Leaked implementation detail. Do not use. Source Edit
proc new[T](a: var ref T; finalizer: proc (x: ref T) {...}{.nimcall.}) {...}{. magic: "NewFinalize", noSideEffect.}
-
Creates a new object of type
T
and returns a safe (traced) reference to it ina
.When the garbage collector frees the object,
finalizer
is called. Thefinalizer
may not keep a reference to the object pointed to byx
. Thefinalizer
cannot prevent the GC from freeing the object.Note: The
Source Editfinalizer
refers to the typeT
, not to the object! This means that for each object of typeT
the finalizer will be called! proc wasMoved[T](obj: var T) {...}{.magic: "WasMoved", noSideEffect.}
- Resets an object
obj
to its initial (binary zero) value to signify it was "moved" and to signify its destructor should do nothing and ideally be optimized away. Source Edit proc move[T](x: var T): T {...}{.magic: "Move", noSideEffect.}
- Source Edit
proc high[T: Ordinal | enum | range](x: T): T {...}{.magic: "High", noSideEffect, deprecated: "Deprecated since v1.4; there should not be `high(value)`. Use `high(type)`.".}
-
Returns the highest possible value of an ordinal value
x
.As a special semantic rule,
x
may also be a type identifier.This proc is deprecated, use this one instead:
high(2) # => 9223372036854775807
Source Edit proc high[T: Ordinal | enum | range](x: typedesc[T]): T {...}{.magic: "High", noSideEffect.}
-
Returns the highest possible value of an ordinal or enum type.
high(int)
is Nim's way of writing INT_MAX or MAX_INT.See also:
high(int) # => 9223372036854775807
Source Edit proc high[T](x: openArray[T]): int {...}{.magic: "High", noSideEffect.}
-
Returns the highest possible index of a sequence
x
.See also:
var s = @[1, 2, 3, 4, 5, 6, 7] high(s) # => 6 for i in low(s)..high(s): echo s[i]
Source Edit proc high[I, T](x: array[I, T]): I {...}{.magic: "High", noSideEffect.}
-
Returns the highest possible index of an array
x
.See also:
var arr = [1, 2, 3, 4, 5, 6, 7] high(arr) # => 6 for i in low(arr)..high(arr): echo arr[i]
Source Edit proc high[I, T](x: typedesc[array[I, T]]): I {...}{.magic: "High", noSideEffect.}
-
Returns the highest possible index of an array type.
See also:
high(array[7, int]) # => 6
Source Edit proc high(x: cstring): int {...}{.magic: "High", noSideEffect.}
-
Returns the highest possible index of a compatible string
x
. This is sometimes an O(n) operation.See also:
Source Edit proc high(x: string): int {...}{.magic: "High", noSideEffect.}
-
Returns the highest possible index of a string
x
.See also:
var str = "Hello world!" high(str) # => 11
Source Edit proc low[T: Ordinal | enum | range](x: T): T {...}{.magic: "Low", noSideEffect, deprecated: "Deprecated since v1.4; there should not be `low(value)`. Use `low(type)`.".}
-
Returns the lowest possible value of an ordinal value
x
. As a special semantic rule,x
may also be a type identifier.This proc is deprecated, use this one instead:
low(2) # => -9223372036854775808
Source Edit proc low[T: Ordinal | enum | range](x: typedesc[T]): T {...}{.magic: "Low", noSideEffect.}
-
Returns the lowest possible value of an ordinal or enum type.
low(int)
is Nim's way of writing INT_MIN or MIN_INT.See also:
low(int) # => -9223372036854775808
Source Edit proc low[T](x: openArray[T]): int {...}{.magic: "Low", noSideEffect.}
-
Returns the lowest possible index of a sequence
x
.See also:
var s = @[1, 2, 3, 4, 5, 6, 7] low(s) # => 0 for i in low(s)..high(s): echo s[i]
Source Edit proc low[I, T](x: array[I, T]): I {...}{.magic: "Low", noSideEffect.}
-
Returns the lowest possible index of an array
x
.See also:
var arr = [1, 2, 3, 4, 5, 6, 7] low(arr) # => 0 for i in low(arr)..high(arr): echo arr[i]
Source Edit proc low[I, T](x: typedesc[array[I, T]]): I {...}{.magic: "Low", noSideEffect.}
-
Returns the lowest possible index of an array type.
See also:
low(array[7, int]) # => 0
Source Edit proc low(x: cstring): int {...}{.magic: "Low", noSideEffect.}
-
Returns the lowest possible index of a compatible string
x
.See also:
Source Edit proc low(x: string): int {...}{.magic: "Low", noSideEffect.}
-
Returns the lowest possible index of a string
x
.See also:
var str = "Hello world!" low(str) # => 0
Source Edit proc shallowCopy[T](x: var T; y: T) {...}{.noSideEffect, magic: "ShallowCopy".}
-
Use this instead of
=
for a shallow copy.The shallow copy only changes the semantics for sequences and strings (and types which contain those).
Be careful with the changed semantics though! There is a reason why the default assignment does a deep copy of sequences and strings.
Source Edit proc `[]`[I: Ordinal; T](a: T; i: I): T {...}{.noSideEffect, magic: "ArrGet".}
- Source Edit
proc `[]=`[I: Ordinal; T, S](a: T; i: I; x: sink S) {...}{.noSideEffect, magic: "ArrPut".}
- Source Edit
proc `=`[T](dest: var T; src: T) {...}{.noSideEffect, magic: "Asgn".}
- Source Edit
proc `=destroy`[T](x: var T) {...}{.inline, magic: "Destroy".}
- Generic destructor implementation that can be overridden. Source Edit
proc `=sink`[T](x: var T; y: T) {...}{.inline, magic: "Asgn".}
- Generic sink implementation that can be overridden. Source Edit
proc `..`[T, U](a: sink T; b: sink U): HSlice[T, U] {...}{.noSideEffect, inline, magic: "DotDot".}
-
Binary slice operator that constructs an interval
[a, b]
, botha
andb
are inclusive.Slices can also be used in the set constructor and in ordinal case statements, but then they are special-cased by the compiler.
let a = [10, 20, 30, 40, 50] echo a[2 .. 3] # @[30, 40]
Source Edit proc `..`[T](b: sink T): HSlice[int, T] {...}{.noSideEffect, inline, magic: "DotDot".}
- Unary slice operator that constructs an interval
[default(int), b]
.let a = [10, 20, 30, 40, 50] echo a[.. 2] # @[10, 20, 30]
Source Edit proc succ[T: Ordinal](x: T; y = 1): T {...}{.magic: "Succ", noSideEffect.}
-
Returns the
y
-th successor (default: 1) of the valuex
.T
has to be an ordinal type.If such a value does not exist,
OverflowDefect
is raised or a compile time error occurs.let x = 5 echo succ(5) # => 6 echo succ(5, 3) # => 8
Source Edit proc pred[T: Ordinal](x: T; y = 1): T {...}{.magic: "Pred", noSideEffect.}
-
Returns the
y
-th predecessor (default: 1) of the valuex
.T
has to be an ordinal type.If such a value does not exist,
OverflowDefect
is raised or a compile time error occurs.let x = 5 echo pred(5) # => 4 echo pred(5, 3) # => 2
Source Edit proc inc[T: Ordinal](x: var T; y = 1) {...}{.magic: "Inc", noSideEffect.}
-
Increments the ordinal
x
byy
.If such a value does not exist,
OverflowDefect
is raised or a compile time error occurs. This is a short notation for:x = succ(x, y)
.var i = 2 inc(i) # i <- 3 inc(i, 3) # i <- 6
Source Edit proc dec[T: Ordinal](x: var T; y = 1) {...}{.magic: "Dec", noSideEffect.}
-
Decrements the ordinal
x
byy
.If such a value does not exist,
OverflowDefect
is raised or a compile time error occurs. This is a short notation for:x = pred(x, y)
.var i = 2 dec(i) # i <- 1 dec(i, 3) # i <- -2
Source Edit proc ze(x: int8): int {...}{.deprecated, raises: [], tags: [].}
-
int
. This treatsx
as unsigned. Deprecated since version 0.19.9: Use unsigned integers instead. Source Edit zero extends a smaller integer type to proc ze(x: int16): int {...}{.deprecated, raises: [], tags: [].}
-
int
. This treatsx
as unsigned. Deprecated since version 0.19.9: Use unsigned integers instead. Source Edit zero extends a smaller integer type to proc ze64(x: int8): int64 {...}{.deprecated, raises: [], tags: [].}
-
int64
. This treatsx
as unsigned. Deprecated since version 0.19.9: Use unsigned integers instead. Source Edit zero extends a smaller integer type to proc ze64(x: int16): int64 {...}{.deprecated, raises: [], tags: [].}
-
int64
. This treatsx
as unsigned. Deprecated since version 0.19.9: Use unsigned integers instead. Source Edit zero extends a smaller integer type to proc ze64(x: int32): int64 {...}{.deprecated, raises: [], tags: [].}
-
int64
. This treatsx
as unsigned. Deprecated since version 0.19.9: Use unsigned integers instead. Source Edit zero extends a smaller integer type to proc ze64(x: int): int64 {...}{.deprecated, raises: [], tags: [].}
-
int64
. This treatsx
as unsigned. Does nothing if the size of anint
is the same asint64
. (This is the case on 64 bit processors.) Deprecated since version 0.19.9: Use unsigned integers instead. Source Edit zero extends a smaller integer type to proc toU8(x: int): int8 {...}{.deprecated, raises: [], tags: [].}
-
x
as unsigned and converts it to a byte by taking the last 8 bits fromx
. Deprecated since version 0.19.9: Use unsigned integers instead. Source Edit treats proc toU16(x: int): int16 {...}{.deprecated, raises: [], tags: [].}
-
x
as unsigned and converts it to anint16
by taking the last 16 bits fromx
. Deprecated since version 0.19.9: Use unsigned integers instead. Source Edit treats proc toU32(x: int64): int32 {...}{.deprecated, raises: [], tags: [].}
-
x
as unsigned and converts it to anint32
by taking the last 32 bits fromx
. Deprecated since version 0.19.9: Use unsigned integers instead. Source Edit treats proc `+`(x: int): int {...}{.magic: "UnaryPlusI", noSideEffect.}
- Unary
+
operator for an integer. Has no effect. Source Edit proc `+`(x: int8): int8 {...}{.magic: "UnaryPlusI", noSideEffect.}
- Source Edit
proc `+`(x: int16): int16 {...}{.magic: "UnaryPlusI", noSideEffect.}
- Source Edit
proc `+`(x: int32): int32 {...}{.magic: "UnaryPlusI", noSideEffect.}
- Source Edit
proc `+`(x: int64): int64 {...}{.magic: "UnaryPlusI", noSideEffect.}
- Source Edit
proc `-`(x: int): int {...}{.magic: "UnaryMinusI", noSideEffect.}
- Unary
-
operator for an integer. Negatesx
. Source Edit proc `-`(x: int8): int8 {...}{.magic: "UnaryMinusI", noSideEffect.}
- Source Edit
proc `-`(x: int16): int16 {...}{.magic: "UnaryMinusI", noSideEffect.}
- Source Edit
proc `-`(x: int32): int32 {...}{.magic: "UnaryMinusI", noSideEffect.}
- Source Edit
proc `-`(x: int64): int64 {...}{.magic: "UnaryMinusI64", noSideEffect.}
- Source Edit
proc `not`(x: int): int {...}{.magic: "BitnotI", noSideEffect.}
- Computes the
bitwise complement
of the integerx
.var a = 0'u8 b = 0'i8 c = 1000'u16 d = 1000'i16 echo not a # => 255 echo not b # => -1 echo not c # => 64535 echo not d # => -1001
Source Edit proc `not`(x: int8): int8 {...}{.magic: "BitnotI", noSideEffect.}
- Source Edit
proc `not`(x: int16): int16 {...}{.magic: "BitnotI", noSideEffect.}
- Source Edit
proc `not`(x: int32): int32 {...}{.magic: "BitnotI", noSideEffect.}
- Source Edit
proc `not`(x: int64): int64 {...}{.magic: "BitnotI", noSideEffect.}
- Source Edit
proc `+`(x, y: int): int {...}{.magic: "AddI", noSideEffect.}
- Binary
+
operator for an integer. Source Edit proc `+`(x, y: int8): int8 {...}{.magic: "AddI", noSideEffect.}
- Source Edit
proc `+`(x, y: int16): int16 {...}{.magic: "AddI", noSideEffect.}
- Source Edit
proc `+`(x, y: int32): int32 {...}{.magic: "AddI", noSideEffect.}
- Source Edit
proc `+`(x, y: int64): int64 {...}{.magic: "AddI", noSideEffect.}
- Source Edit
proc `-`(x, y: int): int {...}{.magic: "SubI", noSideEffect.}
- Binary
-
operator for an integer. Source Edit proc `-`(x, y: int8): int8 {...}{.magic: "SubI", noSideEffect.}
- Source Edit
proc `-`(x, y: int16): int16 {...}{.magic: "SubI", noSideEffect.}
- Source Edit
proc `-`(x, y: int32): int32 {...}{.magic: "SubI", noSideEffect.}
- Source Edit
proc `-`(x, y: int64): int64 {...}{.magic: "SubI", noSideEffect.}
- Source Edit
proc `*`(x, y: int): int {...}{.magic: "MulI", noSideEffect.}
- Binary
*
operator for an integer. Source Edit proc `*`(x, y: int8): int8 {...}{.magic: "MulI", noSideEffect.}
- Source Edit
proc `*`(x, y: int16): int16 {...}{.magic: "MulI", noSideEffect.}
- Source Edit
proc `*`(x, y: int32): int32 {...}{.magic: "MulI", noSideEffect.}
- Source Edit
proc `*`(x, y: int64): int64 {...}{.magic: "MulI", noSideEffect.}
- Source Edit
proc `div`(x, y: int): int {...}{.magic: "DivI", noSideEffect.}
-
Computes the integer division.
This is roughly the same as
trunc(x/y)
.( 1 div 2) == 0 ( 2 div 2) == 1 ( 3 div 2) == 1 ( 7 div 3) == 2 (-7 div 3) == -2 ( 7 div -3) == -2 (-7 div -3) == 2
Source Edit proc `div`(x, y: int8): int8 {...}{.magic: "DivI", noSideEffect.}
- Source Edit
proc `div`(x, y: int16): int16 {...}{.magic: "DivI", noSideEffect.}
- Source Edit
proc `div`(x, y: int32): int32 {...}{.magic: "DivI", noSideEffect.}
- Source Edit
proc `div`(x, y: int64): int64 {...}{.magic: "DivI", noSideEffect.}
- Source Edit
proc `mod`(x, y: int): int {...}{.magic: "ModI", noSideEffect.}
-
Computes the integer modulo operation (remainder).
This is the same as
x - (x div y) * y
.( 7 mod 5) == 2 (-7 mod 5) == -2 ( 7 mod -5) == 2 (-7 mod -5) == -2
Source Edit proc `mod`(x, y: int8): int8 {...}{.magic: "ModI", noSideEffect.}
- Source Edit
proc `mod`(x, y: int16): int16 {...}{.magic: "ModI", noSideEffect.}
- Source Edit
proc `mod`(x, y: int32): int32 {...}{.magic: "ModI", noSideEffect.}
- Source Edit
proc `mod`(x, y: int64): int64 {...}{.magic: "ModI", noSideEffect.}
- Source Edit
proc `shr`(x: int; y: SomeInteger): int {...}{.magic: "AshrI", noSideEffect.}
-
Computes the
shift right
operation ofx
andy
, filling vacant bit positions with the sign bit.Note: Operator precedence is different than in C.
See also:
- ashr proc for arithmetic shift right
0b0001_0000'i8 shr 2 == 0b0000_0100'i8 0b0000_0001'i8 shr 1 == 0b0000_0000'i8 0b1000_0000'i8 shr 4 == 0b1111_1000'i8 -1 shr 5 == -1 1 shr 5 == 0 16 shr 2 == 4 -16 shr 2 == -4
Source Edit proc `shr`(x: int8; y: SomeInteger): int8 {...}{.magic: "AshrI", noSideEffect.}
- Source Edit
proc `shr`(x: int16; y: SomeInteger): int16 {...}{.magic: "AshrI", noSideEffect.}
- Source Edit
proc `shr`(x: int32; y: SomeInteger): int32 {...}{.magic: "AshrI", noSideEffect.}
- Source Edit
proc `shr`(x: int64; y: SomeInteger): int64 {...}{.magic: "AshrI", noSideEffect.}
- Source Edit
proc `shl`(x: int; y: SomeInteger): int {...}{.magic: "ShlI", noSideEffect.}
-
Computes the
shift left
operation ofx
andy
.Note: Operator precedence is different than in C.
1'i32 shl 4 == 0x0000_0010 1'i64 shl 4 == 0x0000_0000_0000_0010
Source Edit proc `shl`(x: int8; y: SomeInteger): int8 {...}{.magic: "ShlI", noSideEffect.}
- Source Edit
proc `shl`(x: int16; y: SomeInteger): int16 {...}{.magic: "ShlI", noSideEffect.}
- Source Edit
proc `shl`(x: int32; y: SomeInteger): int32 {...}{.magic: "ShlI", noSideEffect.}
- Source Edit
proc `shl`(x: int64; y: SomeInteger): int64 {...}{.magic: "ShlI", noSideEffect.}
- Source Edit
proc ashr(x: int; y: SomeInteger): int {...}{.magic: "AshrI", noSideEffect.}
-
Shifts right by pushing copies of the leftmost bit in from the left, and let the rightmost bits fall off.
Note that
ashr
is not an operator so use the normal function call syntax for it.See also:
ashr(0b0001_0000'i8, 2) == 0b0000_0100'i8 ashr(0b1000_0000'i8, 8) == 0b1111_1111'i8 ashr(0b1000_0000'i8, 1) == 0b1100_0000'i8
Source Edit proc ashr(x: int8; y: SomeInteger): int8 {...}{.magic: "AshrI", noSideEffect.}
- Source Edit
proc ashr(x: int16; y: SomeInteger): int16 {...}{.magic: "AshrI", noSideEffect.}
- Source Edit
proc ashr(x: int32; y: SomeInteger): int32 {...}{.magic: "AshrI", noSideEffect.}
- Source Edit
proc ashr(x: int64; y: SomeInteger): int64 {...}{.magic: "AshrI", noSideEffect.}
- Source Edit
proc `and`(x, y: int): int {...}{.magic: "BitandI", noSideEffect.}
- Computes the
bitwise and
of numbersx
andy
.(0b0011 and 0b0101) == 0b0001 (0b0111 and 0b1100) == 0b0100
Source Edit proc `and`(x, y: int8): int8 {...}{.magic: "BitandI", noSideEffect.}
- Source Edit
proc `and`(x, y: int16): int16 {...}{.magic: "BitandI", noSideEffect.}
- Source Edit
proc `and`(x, y: int32): int32 {...}{.magic: "BitandI", noSideEffect.}
- Source Edit
proc `and`(x, y: int64): int64 {...}{.magic: "BitandI", noSideEffect.}
- Source Edit
proc `or`(x, y: int): int {...}{.magic: "BitorI", noSideEffect.}
- Computes the
bitwise or
of numbersx
andy
.(0b0011 or 0b0101) == 0b0111 (0b0111 or 0b1100) == 0b1111
Source Edit proc `or`(x, y: int8): int8 {...}{.magic: "BitorI", noSideEffect.}
- Source Edit
proc `or`(x, y: int16): int16 {...}{.magic: "BitorI", noSideEffect.}
- Source Edit
proc `or`(x, y: int32): int32 {...}{.magic: "BitorI", noSideEffect.}
- Source Edit
proc `or`(x, y: int64): int64 {...}{.magic: "BitorI", noSideEffect.}
- Source Edit
proc `xor`(x, y: int): int {...}{.magic: "BitxorI", noSideEffect.}
- Computes the
bitwise xor
of numbersx
andy
.(0b0011 xor 0b0101) == 0b0110 (0b0111 xor 0b1100) == 0b1011
Source Edit proc `xor`(x, y: int8): int8 {...}{.magic: "BitxorI", noSideEffect.}
- Source Edit
proc `xor`(x, y: int16): int16 {...}{.magic: "BitxorI", noSideEffect.}
- Source Edit
proc `xor`(x, y: int32): int32 {...}{.magic: "BitxorI", noSideEffect.}
- Source Edit
proc `xor`(x, y: int64): int64 {...}{.magic: "BitxorI", noSideEffect.}
- Source Edit
proc `not`(x: uint): uint {...}{.magic: "BitnotI", noSideEffect.}
- Computes the
bitwise complement
of the integerx
. Source Edit proc `not`(x: uint8): uint8 {...}{.magic: "BitnotI", noSideEffect.}
- Source Edit
proc `not`(x: uint16): uint16 {...}{.magic: "BitnotI", noSideEffect.}
- Source Edit
proc `not`(x: uint32): uint32 {...}{.magic: "BitnotI", noSideEffect.}
- Source Edit
proc `not`(x: uint64): uint64 {...}{.magic: "BitnotI", noSideEffect.}
- Source Edit
proc `shr`(x: uint; y: SomeInteger): uint {...}{.magic: "ShrI", noSideEffect.}
- Computes the
shift right
operation ofx
andy
. Source Edit proc `shr`(x: uint8; y: SomeInteger): uint8 {...}{.magic: "ShrI", noSideEffect.}
- Source Edit
proc `shr`(x: uint16; y: SomeInteger): uint16 {...}{.magic: "ShrI", noSideEffect.}
- Source Edit
proc `shr`(x: uint32; y: SomeInteger): uint32 {...}{.magic: "ShrI", noSideEffect.}
- Source Edit
proc `shr`(x: uint64; y: SomeInteger): uint64 {...}{.magic: "ShrI", noSideEffect.}
- Source Edit
proc `shl`(x: uint; y: SomeInteger): uint {...}{.magic: "ShlI", noSideEffect.}
- Computes the
shift left
operation ofx
andy
. Source Edit proc `shl`(x: uint8; y: SomeInteger): uint8 {...}{.magic: "ShlI", noSideEffect.}
- Source Edit
proc `shl`(x: uint16; y: SomeInteger): uint16 {...}{.magic: "ShlI", noSideEffect.}
- Source Edit
proc `shl`(x: uint32; y: SomeInteger): uint32 {...}{.magic: "ShlI", noSideEffect.}
- Source Edit
proc `shl`(x: uint64; y: SomeInteger): uint64 {...}{.magic: "ShlI", noSideEffect.}
- Source Edit
proc `and`(x, y: uint): uint {...}{.magic: "BitandI", noSideEffect.}
- Computes the
bitwise and
of numbersx
andy
. Source Edit proc `and`(x, y: uint8): uint8 {...}{.magic: "BitandI", noSideEffect.}
- Source Edit
proc `and`(x, y: uint16): uint16 {...}{.magic: "BitandI", noSideEffect.}
- Source Edit
proc `and`(x, y: uint32): uint32 {...}{.magic: "BitandI", noSideEffect.}
- Source Edit
proc `and`(x, y: uint64): uint64 {...}{.magic: "BitandI", noSideEffect.}
- Source Edit
proc `or`(x, y: uint): uint {...}{.magic: "BitorI", noSideEffect.}
- Computes the
bitwise or
of numbersx
andy
. Source Edit proc `or`(x, y: uint8): uint8 {...}{.magic: "BitorI", noSideEffect.}
- Source Edit
proc `or`(x, y: uint16): uint16 {...}{.magic: "BitorI", noSideEffect.}
- Source Edit
proc `or`(x, y: uint32): uint32 {...}{.magic: "BitorI", noSideEffect.}
- Source Edit
proc `or`(x, y: uint64): uint64 {...}{.magic: "BitorI", noSideEffect.}
- Source Edit
proc `xor`(x, y: uint): uint {...}{.magic: "BitxorI", noSideEffect.}
- Computes the
bitwise xor
of numbersx
andy
. Source Edit proc `xor`(x, y: uint8): uint8 {...}{.magic: "BitxorI", noSideEffect.}
- Source Edit
proc `xor`(x, y: uint16): uint16 {...}{.magic: "BitxorI", noSideEffect.}
- Source Edit
proc `xor`(x, y: uint32): uint32 {...}{.magic: "BitxorI", noSideEffect.}
- Source Edit
proc `xor`(x, y: uint64): uint64 {...}{.magic: "BitxorI", noSideEffect.}
- Source Edit
proc `+`(x, y: uint): uint {...}{.magic: "AddU", noSideEffect.}
- Binary
+
operator for unsigned integers. Source Edit proc `+`(x, y: uint8): uint8 {...}{.magic: "AddU", noSideEffect.}
- Source Edit
proc `+`(x, y: uint16): uint16 {...}{.magic: "AddU", noSideEffect.}
- Source Edit
proc `+`(x, y: uint32): uint32 {...}{.magic: "AddU", noSideEffect.}
- Source Edit
proc `+`(x, y: uint64): uint64 {...}{.magic: "AddU", noSideEffect.}
- Source Edit
proc `-`(x, y: uint): uint {...}{.magic: "SubU", noSideEffect.}
- Binary
-
operator for unsigned integers. Source Edit proc `-`(x, y: uint8): uint8 {...}{.magic: "SubU", noSideEffect.}
- Source Edit
proc `-`(x, y: uint16): uint16 {...}{.magic: "SubU", noSideEffect.}
- Source Edit
proc `-`(x, y: uint32): uint32 {...}{.magic: "SubU", noSideEffect.}
- Source Edit
proc `-`(x, y: uint64): uint64 {...}{.magic: "SubU", noSideEffect.}
- Source Edit
proc `*`(x, y: uint): uint {...}{.magic: "MulU", noSideEffect.}
- Binary
*
operator for unsigned integers. Source Edit proc `*`(x, y: uint8): uint8 {...}{.magic: "MulU", noSideEffect.}
- Source Edit
proc `*`(x, y: uint16): uint16 {...}{.magic: "MulU", noSideEffect.}
- Source Edit
proc `*`(x, y: uint32): uint32 {...}{.magic: "MulU", noSideEffect.}
- Source Edit
proc `*`(x, y: uint64): uint64 {...}{.magic: "MulU", noSideEffect.}
- Source Edit
proc `div`(x, y: uint): uint {...}{.magic: "DivU", noSideEffect.}
- Computes the integer division for unsigned integers. This is roughly the same as
trunc(x/y)
. Source Edit proc `div`(x, y: uint8): uint8 {...}{.magic: "DivU", noSideEffect.}
- Source Edit
proc `div`(x, y: uint16): uint16 {...}{.magic: "DivU", noSideEffect.}
- Source Edit
proc `div`(x, y: uint32): uint32 {...}{.magic: "DivU", noSideEffect.}
- Source Edit
proc `div`(x, y: uint64): uint64 {...}{.magic: "DivU", noSideEffect.}
- Source Edit
proc `mod`(x, y: uint): uint {...}{.magic: "ModU", noSideEffect.}
- Computes the integer modulo operation (remainder) for unsigned integers. This is the same as
x - (x div y) * y
. Source Edit proc `mod`(x, y: uint8): uint8 {...}{.magic: "ModU", noSideEffect.}
- Source Edit
proc `mod`(x, y: uint16): uint16 {...}{.magic: "ModU", noSideEffect.}
- Source Edit
proc `mod`(x, y: uint32): uint32 {...}{.magic: "ModU", noSideEffect.}
- Source Edit
proc `mod`(x, y: uint64): uint64 {...}{.magic: "ModU", noSideEffect.}
- Source Edit
proc `+%`(x, y: int): int {...}{.inline, raises: [], tags: [].}
-
Treats
x
andy
as unsigned and adds them.The result is truncated to fit into the result. This implements modulo arithmetic. No overflow errors are possible.
Source Edit proc `+%`(x, y: int8): int8 {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `+%`(x, y: int16): int16 {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `+%`(x, y: int32): int32 {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `+%`(x, y: int64): int64 {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `-%`(x, y: int): int {...}{.inline, raises: [], tags: [].}
-
Treats
x
andy
as unsigned and subtracts them.The result is truncated to fit into the result. This implements modulo arithmetic. No overflow errors are possible.
Source Edit proc `-%`(x, y: int8): int8 {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `-%`(x, y: int16): int16 {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `-%`(x, y: int32): int32 {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `-%`(x, y: int64): int64 {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `*%`(x, y: int): int {...}{.inline, raises: [], tags: [].}
-
Treats
x
andy
as unsigned and multiplies them.The result is truncated to fit into the result. This implements modulo arithmetic. No overflow errors are possible.
Source Edit proc `*%`(x, y: int8): int8 {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `*%`(x, y: int16): int16 {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `*%`(x, y: int32): int32 {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `*%`(x, y: int64): int64 {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `/%`(x, y: int): int {...}{.inline, raises: [], tags: [].}
-
Treats
x
andy
as unsigned and divides them.The result is truncated to fit into the result. This implements modulo arithmetic. No overflow errors are possible.
Source Edit proc `/%`(x, y: int8): int8 {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `/%`(x, y: int16): int16 {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `/%`(x, y: int32): int32 {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `/%`(x, y: int64): int64 {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `%%`(x, y: int): int {...}{.inline, raises: [], tags: [].}
-
Treats
x
andy
as unsigned and compute the modulo ofx
andy
.The result is truncated to fit into the result. This implements modulo arithmetic. No overflow errors are possible.
Source Edit proc `%%`(x, y: int8): int8 {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `%%`(x, y: int16): int16 {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `%%`(x, y: int32): int32 {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `%%`(x, y: int64): int64 {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `+=`[T: SomeInteger](x: var T; y: T) {...}{.magic: "Inc", noSideEffect.}
- Increments an integer. Source Edit
proc `-=`[T: SomeInteger](x: var T; y: T) {...}{.magic: "Dec", noSideEffect.}
- Decrements an integer. Source Edit
proc `*=`[T: SomeInteger](x: var T; y: T) {...}{.inline, noSideEffect.}
- Binary
*=
operator for integers. Source Edit proc `==`[Enum: enum](x, y: Enum): bool {...}{.magic: "EqEnum", noSideEffect.}
- Checks whether values within the same enum have the same underlying value.
type Enum1 = enum Field1 = 3, Field2 Enum2 = enum Place1, Place2 = 3 var e1 = Field1 e2 = Enum1(Place2) echo (e1 == e2) # true echo (e1 == Place2) # raises error
Source Edit proc `==`(x, y: pointer): bool {...}{.magic: "EqRef", noSideEffect.}
-
var # this is a wildly dangerous example a = cast[pointer](0) b = cast[pointer](nil) echo (a == b) # true due to the special meaning of `nil`/0 as a pointer
Source Edit proc `==`(x, y: string): bool {...}{.magic: "EqStr", noSideEffect.}
- Checks for equality between two
string
variables. Source Edit proc `==`(x, y: char): bool {...}{.magic: "EqCh", noSideEffect.}
- Checks for equality between two
char
variables. Source Edit proc `==`(x, y: bool): bool {...}{.magic: "EqB", noSideEffect.}
- Checks for equality between two
bool
variables. Source Edit proc `==`[T](x, y: set[T]): bool {...}{.magic: "EqSet", noSideEffect.}
- Checks for equality between two variables of type
set
.var a = {1, 2, 2, 3} # duplication in sets is ignored var b = {1, 2, 3} echo (a == b) # true
Source Edit proc `==`[T](x, y: ref T): bool {...}{.magic: "EqRef", noSideEffect.}
- Checks that two
ref
variables refer to the same item. Source Edit proc `==`[T](x, y: ptr T): bool {...}{.magic: "EqRef", noSideEffect.}
- Checks that two
ptr
variables refer to the same item. Source Edit proc `==`[T: proc](x, y: T): bool {...}{.magic: "EqProc", noSideEffect.}
- Checks that two
proc
variables refer to the same procedure. Source Edit proc `<=`[Enum: enum](x, y: Enum): bool {...}{.magic: "LeEnum", noSideEffect.}
- Source Edit
proc `<=`(x, y: string): bool {...}{.magic: "LeStr", noSideEffect.}
- Compares two strings and returns true if
x
is lexicographically beforey
(uppercase letters come before lowercase letters).let a = "abc" b = "abd" c = "ZZZ" assert a <= b assert a <= a assert (a <= c) == false
Source Edit proc `<=`(x, y: char): bool {...}{.magic: "LeCh", noSideEffect.}
- Compares two chars and returns true if
x
is lexicographically beforey
(uppercase letters come before lowercase letters).let a = 'a' b = 'b' c = 'Z' assert a <= b assert a <= a assert (a <= c) == false
Source Edit proc `<=`[T](x, y: set[T]): bool {...}{.magic: "LeSet", noSideEffect.}
-
Returns true if
x
is a subset ofy
.A subset
x
has all of its members iny
andy
doesn't necessarily have more members thanx
. That is,x
can be equal toy
.let a = {3, 5} b = {1, 3, 5, 7} c = {2} assert a <= b assert a <= a assert (a <= c) == false
Source Edit proc `<=`(x, y: bool): bool {...}{.magic: "LeB", noSideEffect.}
- Source Edit
proc `<=`[T](x, y: ref T): bool {...}{.magic: "LePtr", noSideEffect.}
- Source Edit
proc `<=`(x, y: pointer): bool {...}{.magic: "LePtr", noSideEffect.}
- Source Edit
proc `<`[Enum: enum](x, y: Enum): bool {...}{.magic: "LtEnum", noSideEffect.}
- Source Edit
proc `<`(x, y: string): bool {...}{.magic: "LtStr", noSideEffect.}
- Compares two strings and returns true if
x
is lexicographically beforey
(uppercase letters come before lowercase letters).let a = "abc" b = "abd" c = "ZZZ" assert a < b assert (a < a) == false assert (a < c) == false
Source Edit proc `<`(x, y: char): bool {...}{.magic: "LtCh", noSideEffect.}
- Compares two chars and returns true if
x
is lexicographically beforey
(uppercase letters come before lowercase letters).let a = 'a' b = 'b' c = 'Z' assert a < b assert (a < a) == false assert (a < c) == false
Source Edit proc `<`[T](x, y: set[T]): bool {...}{.magic: "LtSet", noSideEffect.}
-
Returns true if
x
is a strict or proper subset ofy
.A strict or proper subset
x
has all of its members iny
buty
has more elements thany
.let a = {3, 5} b = {1, 3, 5, 7} c = {2} assert a < b assert (a < a) == false assert (a < c) == false
Source Edit proc `<`(x, y: bool): bool {...}{.magic: "LtB", noSideEffect.}
- Source Edit
proc `<`[T](x, y: ref T): bool {...}{.magic: "LtPtr", noSideEffect.}
- Source Edit
proc `<`[T](x, y: ptr T): bool {...}{.magic: "LtPtr", noSideEffect.}
- Source Edit
proc `<`(x, y: pointer): bool {...}{.magic: "LtPtr", noSideEffect.}
- Source Edit
proc `==`(x, y: int): bool {...}{.magic: "EqI", noSideEffect.}
- Compares two integers for equality. Source Edit
proc `==`(x, y: int8): bool {...}{.magic: "EqI", noSideEffect.}
- Source Edit
proc `==`(x, y: int16): bool {...}{.magic: "EqI", noSideEffect.}
- Source Edit
proc `==`(x, y: int32): bool {...}{.magic: "EqI", noSideEffect.}
- Source Edit
proc `==`(x, y: int64): bool {...}{.magic: "EqI", noSideEffect.}
- Source Edit
proc `<=`(x, y: int): bool {...}{.magic: "LeI", noSideEffect.}
- Returns true if
x
is less than or equal toy
. Source Edit proc `<=`(x, y: int8): bool {...}{.magic: "LeI", noSideEffect.}
- Source Edit
proc `<=`(x, y: int16): bool {...}{.magic: "LeI", noSideEffect.}
- Source Edit
proc `<=`(x, y: int32): bool {...}{.magic: "LeI", noSideEffect.}
- Source Edit
proc `<=`(x, y: int64): bool {...}{.magic: "LeI", noSideEffect.}
- Source Edit
proc `<`(x, y: int): bool {...}{.magic: "LtI", noSideEffect.}
- Returns true if
x
is less thany
. Source Edit proc `<`(x, y: int8): bool {...}{.magic: "LtI", noSideEffect.}
- Source Edit
proc `<`(x, y: int16): bool {...}{.magic: "LtI", noSideEffect.}
- Source Edit
proc `<`(x, y: int32): bool {...}{.magic: "LtI", noSideEffect.}
- Source Edit
proc `<`(x, y: int64): bool {...}{.magic: "LtI", noSideEffect.}
- Source Edit
proc `<=`(x, y: uint): bool {...}{.magic: "LeU", noSideEffect.}
- Returns true if
x <= y
. Source Edit proc `<=`(x, y: uint8): bool {...}{.magic: "LeU", noSideEffect.}
- Source Edit
proc `<=`(x, y: uint16): bool {...}{.magic: "LeU", noSideEffect.}
- Source Edit
proc `<=`(x, y: uint32): bool {...}{.magic: "LeU", noSideEffect.}
- Source Edit
proc `<=`(x, y: uint64): bool {...}{.magic: "LeU", noSideEffect.}
- Source Edit
proc `<`(x, y: uint): bool {...}{.magic: "LtU", noSideEffect.}
- Returns true if
x < y
. Source Edit proc `<`(x, y: uint8): bool {...}{.magic: "LtU", noSideEffect.}
- Source Edit
proc `<`(x, y: uint16): bool {...}{.magic: "LtU", noSideEffect.}
- Source Edit
proc `<`(x, y: uint32): bool {...}{.magic: "LtU", noSideEffect.}
- Source Edit
proc `<`(x, y: uint64): bool {...}{.magic: "LtU", noSideEffect.}
- Source Edit
proc `<=%`(x, y: int): bool {...}{.inline, raises: [], tags: [].}
- Treats
x
andy
as unsigned and compares them. Returns true ifunsigned(x) <= unsigned(y)
. Source Edit proc `<=%`(x, y: int8): bool {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `<=%`(x, y: int16): bool {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `<=%`(x, y: int32): bool {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `<=%`(x, y: int64): bool {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `<%`(x, y: int): bool {...}{.inline, raises: [], tags: [].}
- Treats
x
andy
as unsigned and compares them. Returns true ifunsigned(x) < unsigned(y)
. Source Edit proc `<%`(x, y: int8): bool {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `<%`(x, y: int16): bool {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `<%`(x, y: int32): bool {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `<%`(x, y: int64): bool {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `==`(x, y: uint): bool {...}{.magic: "EqI", noSideEffect.}
- Compares two unsigned integers for equality. Source Edit
proc `==`(x, y: uint8): bool {...}{.magic: "EqI", noSideEffect.}
- Source Edit
proc `==`(x, y: uint16): bool {...}{.magic: "EqI", noSideEffect.}
- Source Edit
proc `==`(x, y: uint32): bool {...}{.magic: "EqI", noSideEffect.}
- Source Edit
proc `==`(x, y: uint64): bool {...}{.magic: "EqI", noSideEffect.}
- Source Edit
proc min(x, y: int): int {...}{.magic: "MinI", noSideEffect, raises: [], tags: [].}
- Source Edit
proc min(x, y: int8): int8 {...}{.magic: "MinI", noSideEffect, raises: [], tags: [].}
- Source Edit
proc min(x, y: int16): int16 {...}{.magic: "MinI", noSideEffect, raises: [], tags: [].}
- Source Edit
proc min(x, y: int32): int32 {...}{.magic: "MinI", noSideEffect, raises: [], tags: [].}
- Source Edit
proc min(x, y: int64): int64 {...}{.magic: "MinI", noSideEffect, raises: [], tags: [].}
- The minimum value of two integers. Source Edit
proc max(x, y: int): int {...}{.magic: "MaxI", noSideEffect, raises: [], tags: [].}
- Source Edit
proc max(x, y: int8): int8 {...}{.magic: "MaxI", noSideEffect, raises: [], tags: [].}
- Source Edit
proc max(x, y: int16): int16 {...}{.magic: "MaxI", noSideEffect, raises: [], tags: [].}
- Source Edit
proc max(x, y: int32): int32 {...}{.magic: "MaxI", noSideEffect, raises: [], tags: [].}
- Source Edit
proc max(x, y: int64): int64 {...}{.magic: "MaxI", noSideEffect, raises: [], tags: [].}
- The maximum value of two integers. Source Edit
proc min[T](x: openArray[T]): T
- The minimum value of
x
.T
needs to have a<
operator. Source Edit proc max[T](x: openArray[T]): T
- The maximum value of
x
.T
needs to have a<
operator. Source Edit proc clamp[T](x, a, b: T): T
- Limits the value
x
within the interval [a, b].assert((1.4).clamp(0.0, 1.0) == 1.0) assert((0.5).clamp(0.0, 1.0) == 0.5)
Source Edit proc `==`[I, T](x, y: array[I, T]): bool
- Source Edit
proc `==`[T](x, y: openArray[T]): bool
- Source Edit
proc `==`[T](x, y: seq[T]): bool {...}{.noSideEffect.}
- Generic equals operator for sequences: relies on a equals operator for the element type
T
. Source Edit proc unsafeNew[T](a: var ref T; size: Natural) {...}{.magic: "New", noSideEffect.}
-
Creates a new object of type
T
and returns a safe (traced) reference to it ina
.This is unsafe as it allocates an object of the passed
size
. This should only be used for optimization purposes when you know what you're doing!See also:
Source Edit proc sizeof[T](x: T): int {...}{.magic: "SizeOf", noSideEffect.}
-
Returns the size of
x
in bytes.Since this is a low-level proc, its usage is discouraged - using new for the most cases suffices that one never needs to know
x
's size.As a special semantic rule,
x
may also be a type identifier (sizeof(int)
is valid).Limitations: If used for types that are imported from C or C++, sizeof should fallback to the
sizeof
in the C compiler. The result isn't available for the Nim compiler and therefore can't be used inside of macros.sizeof('A') # => 1 sizeof(2) # => 8
Source Edit proc alignof[T](x: T): int {...}{.magic: "AlignOf", noSideEffect.}
- Source Edit
proc alignof(x: typedesc): int {...}{.magic: "AlignOf", noSideEffect.}
- Source Edit
proc sizeof(x: typedesc): int {...}{.magic: "SizeOf", noSideEffect.}
- Source Edit
proc newSeq[T](s: var seq[T]; len: Natural) {...}{.magic: "NewSeq", noSideEffect.}
-
Creates a new sequence of type
seq[T]
with lengthlen
.This is equivalent to
s = @[]; setlen(s, len)
, but more efficient since no reallocation is needed.Note that the sequence will be filled with zeroed entries. After the creation of the sequence you should assign entries to the sequence instead of adding them. Example:
var inputStrings : seq[string] newSeq(inputStrings, 3) assert len(inputStrings) == 3 inputStrings[0] = "The fourth" inputStrings[1] = "assignment" inputStrings[2] = "would crash" #inputStrings[3] = "out of bounds"
Source Edit proc newSeq[T](len = 0.Natural): seq[T]
-
Creates a new sequence of type
seq[T]
with lengthlen
.Note that the sequence will be filled with zeroed entries. After the creation of the sequence you should assign entries to the sequence instead of adding them.
See also:
var inputStrings = newSeq[string](3) assert len(inputStrings) == 3 inputStrings[0] = "The fourth" inputStrings[1] = "assignment" inputStrings[2] = "would crash" #inputStrings[3] = "out of bounds"
Source Edit proc newSeqOfCap[T](cap: Natural): seq[T] {...}{.magic: "NewSeqOfCap", noSideEffect.}
- Creates a new sequence of type
seq[T]
with length zero and capacitycap
.var x = newSeqOfCap[int](5) assert len(x) == 0 x.add(10) assert len(x) == 1
Source Edit proc newSeqUninitialized[T: SomeNumber](len: Natural): seq[T]
-
Creates a new sequence of type
seq[T]
with lengthlen
.Only available for numbers types. Note that the sequence will be uninitialized. After the creation of the sequence you should assign entries to the sequence instead of adding them.
var x = newSeqUninitialized[int](3) assert len(x) == 3 x[0] = 10
Source Edit proc len[TOpenArray: openArray | varargs](x: TOpenArray): int {...}{. magic: "LengthOpenArray", noSideEffect.}
- Returns the length of an openArray.
var s = [1, 1, 1, 1, 1] echo len(s) # => 5
Source Edit proc len(x: string): int {...}{.magic: "LengthStr", noSideEffect.}
- Returns the length of a string.
var str = "Hello world!" echo len(str) # => 12
Source Edit proc len(x: cstring): int {...}{.magic: "LengthStr", noSideEffect.}
-
Returns the length of a compatible string. This is sometimes an O(n) operation.
Note: On the JS backend this currently counts UTF-16 code points instead of bytes at runtime (not at compile time). For now, if you need the byte length of the UTF-8 encoding, convert to string with
$
first then calllen
.var str: cstring = "Hello world!" len(str) # => 12
Source Edit proc len(x: (type array) | array): int {...}{.magic: "LengthArray", noSideEffect.}
- Returns the length of an array or an array type. This is roughly the same as
high(T)-low(T)+1
.var arr = [1, 1, 1, 1, 1] echo len(arr) # => 5 echo len(array[3..8, int]) # => 6
Source Edit proc len[T](x: seq[T]): int {...}{.magic: "LengthSeq", noSideEffect.}
- Returns the length of a sequence.
var s = @[1, 1, 1, 1, 1] echo len(s) # => 5
Source Edit proc ord[T: Ordinal | enum](x: T): int {...}{.magic: "Ord", noSideEffect.}
- Returns the internal
int
value of an ordinal valuex
.echo ord('A') # => 65 echo ord('a') # => 97
Source Edit proc chr(u: range[0 .. 255]): char {...}{.magic: "Chr", noSideEffect.}
- Converts an
int
in the range0..255
to a character.echo chr(65) # => A echo chr(97) # => a
Source Edit proc `+`(x: float32): float32 {...}{.magic: "UnaryPlusF64", noSideEffect.}
- Source Edit
proc `-`(x: float32): float32 {...}{.magic: "UnaryMinusF64", noSideEffect.}
- Source Edit
proc `+`(x, y: float32): float32 {...}{.magic: "AddF64", noSideEffect.}
- Source Edit
proc `-`(x, y: float32): float32 {...}{.magic: "SubF64", noSideEffect.}
- Source Edit
proc `*`(x, y: float32): float32 {...}{.magic: "MulF64", noSideEffect.}
- Source Edit
proc `/`(x, y: float32): float32 {...}{.magic: "DivF64", noSideEffect.}
- Source Edit
proc `+`(x: float): float {...}{.magic: "UnaryPlusF64", noSideEffect.}
- Source Edit
proc `-`(x: float): float {...}{.magic: "UnaryMinusF64", noSideEffect.}
- Source Edit
proc `+`(x, y: float): float {...}{.magic: "AddF64", noSideEffect.}
- Source Edit
proc `-`(x, y: float): float {...}{.magic: "SubF64", noSideEffect.}
- Source Edit
proc `*`(x, y: float): float {...}{.magic: "MulF64", noSideEffect.}
- Source Edit
proc `/`(x, y: float): float {...}{.magic: "DivF64", noSideEffect.}
- Source Edit
proc `==`(x, y: float32): bool {...}{.magic: "EqF64", noSideEffect.}
- Source Edit
proc `<=`(x, y: float32): bool {...}{.magic: "LeF64", noSideEffect.}
- Source Edit
proc `<`(x, y: float32): bool {...}{.magic: "LtF64", noSideEffect.}
- Source Edit
proc `==`(x, y: float): bool {...}{.magic: "EqF64", noSideEffect.}
- Source Edit
proc `<=`(x, y: float): bool {...}{.magic: "LeF64", noSideEffect.}
- Source Edit
proc `<`(x, y: float): bool {...}{.magic: "LtF64", noSideEffect.}
- Source Edit
proc incl[T](x: var set[T]; y: T) {...}{.magic: "Incl", noSideEffect.}
-
Includes element
y
in the setx
.This is the same as
x = x + {y}
, but it might be more efficient.var a = {1, 3, 5} a.incl(2) # a <- {1, 2, 3, 5} a.incl(4) # a <- {1, 2, 3, 4, 5}
Source Edit proc excl[T](x: var set[T]; y: T) {...}{.magic: "Excl", noSideEffect.}
-
Excludes element
y
from the setx
.This is the same as
x = x - {y}
, but it might be more efficient.var b = {2, 3, 5, 6, 12, 545} b.excl(5) # b <- {2, 3, 6, 12, 545}
Source Edit proc card[T](x: set[T]): int {...}{.magic: "Card", noSideEffect.}
- Returns the cardinality of the set
x
, i.e. the number of elements in the set.var a = {1, 3, 5, 7} echo card(a) # => 4
Source Edit proc len[T](x: set[T]): int {...}{.magic: "Card", noSideEffect.}
- An alias for
card(x)
. Source Edit proc `*`[T](x, y: set[T]): set[T] {...}{.magic: "MulSet", noSideEffect.}
- This operator computes the intersection of two sets.
let a = {1, 2, 3} b = {2, 3, 4} echo a * b # => {2, 3}
Source Edit proc `+`[T](x, y: set[T]): set[T] {...}{.magic: "PlusSet", noSideEffect.}
- This operator computes the union of two sets.
let a = {1, 2, 3} b = {2, 3, 4} echo a + b # => {1, 2, 3, 4}
Source Edit proc `-`[T](x, y: set[T]): set[T] {...}{.magic: "MinusSet", noSideEffect.}
- This operator computes the difference of two sets.
let a = {1, 2, 3} b = {2, 3, 4} echo a - b # => {1}
Source Edit proc contains[T](x: set[T]; y: T): bool {...}{.magic: "InSet", noSideEffect.}
-
One should overload this proc if one wants to overload the
in
operator.The parameters are in reverse order!
a in b
is a template forcontains(b, a)
. This is because the unification algorithm that Nim uses for overload resolution works from left to right. But for thein
operator that would be the wrong direction for this piece of code:var s: set[range['a'..'z']] = {'a'..'c'} assert s.contains('c') assert 'b' in s
If
Source Editin
had been declared as[T](elem: T, s: set[T])
thenT
would have been bound tochar
. Buts
is not compatible to typeset[char]
! The solution is to bindT
torange['a'..'z']
. This is achieved by reversing the parameters forcontains
;in
then passes its arguments in reverse order. proc contains[U, V, W](s: HSlice[U, V]; value: W): bool {...}{.noSideEffect, inline.}
- Checks if
value
is within the range ofs
; returns true ifvalue >= s.a and value <= s.b
assert((1..3).contains(1) == true) assert((1..3).contains(2) == true) assert((1..3).contains(4) == false)
Source Edit proc `is`[T, S](x: T; y: S): bool {...}{.magic: "Is", noSideEffect.}
-
Checks if
T
is of the same type asS
.For a negated version, use isnot.
assert 42 is int assert @[1, 2] is seq proc test[T](a: T): int = when (T is int): return a else: return 0 assert(test[int](3) == 3) assert(test[string]("xyz") == 0)
Source Edit proc new[T](a: var ref T) {...}{.magic: "New", noSideEffect.}
- Creates a new object of type
T
and returns a safe (traced) reference to it ina
. Source Edit proc new(t: typedesc): auto
-
Creates a new object of type
T
and returns a safe (traced) reference to it as result value.When
Source EditT
is a ref type then the resulting type will beT
, otherwise it will beref T
. proc `of`[T, S](x: typedesc[T]; y: typedesc[S]): bool {...}{.magic: "Of", noSideEffect.}
- Source Edit
proc `of`[T, S](x: T; y: typedesc[S]): bool {...}{.magic: "Of", noSideEffect.}
- Source Edit
proc `of`[T, S](x: T; y: S): bool {...}{.magic: "Of", noSideEffect.}
- Checks if
x
has a type ofy
.assert(FloatingPointDefect of Exception) assert(DivByZeroDefect of Exception)
Source Edit proc cmp[T](x, y: T): int
-
Generic compare proc.
Returns:
- a value less than zero, if
x < y
- a value greater than zero, if
x > y
- zero, if
x == y
This is useful for writing generic algorithms without performance loss. This generic implementation uses the
==
and<
operators.import algorithm echo sorted(@[4, 2, 6, 5, 8, 7], cmp[int])
Source Edit - a value less than zero, if
proc `@`[IDX, T](a: sink array[IDX, T]): seq[T] {...}{.magic: "ArrToSeq", noSideEffect.}
-
Turns an array into a sequence.
This most often useful for constructing sequences with the array constructor:
@[1, 2, 3]
has the typeseq[int]
, while[1, 2, 3]
has the typearray[0..2, int]
.let a = [1, 3, 5] b = "foo" echo @a # => @[1, 3, 5] echo @b # => @['f', 'o', 'o']
Source Edit proc default(T: typedesc): T:type {...}{.magic: "Default", noSideEffect.}
- returns the default value of the type
T
. Source Edit proc reset[T](obj: var T) {...}{.noSideEffect.}
- Resets an object
obj
to its default value. Source Edit proc setLen[T](s: var seq[T]; newlen: Natural) {...}{.magic: "SetLengthSeq", noSideEffect.}
-
Sets the length of seq
s
tonewlen
.T
may be any sequence type.If the current length is greater than the new length,
s
will be truncated.var x = @[10, 20] x.setLen(5) x[4] = 50 assert x == @[10, 20, 0, 0, 50] x.setLen(1) assert x == @[10]
Source Edit proc setLen(s: var string; newlen: Natural) {...}{.magic: "SetLengthStr", noSideEffect.}
-
Sets the length of string
s
tonewlen
.If the current length is greater than the new length,
s
will be truncated.var myS = "Nim is great!!" myS.setLen(3) # myS <- "Nim" echo myS, " is fantastic!!"
Source Edit proc newString(len: Natural): string {...}{.magic: "NewString", importc: "mnewString", noSideEffect.}
-
Returns a new string of length
len
but with uninitialized content. One needs to fill the string character after character with the index operators[i]
.This procedure exists only for optimization purposes; the same effect can be achieved with the
Source Edit&
operator or withadd
. proc newStringOfCap(cap: Natural): string {...}{.magic: "NewStringOfCap", importc: "rawNewString", noSideEffect.}
-
Returns a new string of length
0
but with capacitycap
.This procedure exists only for optimization purposes; the same effect can be achieved with the
Source Edit&
operator or withadd
. proc `&`(x: string; y: char): string {...}{.magic: "ConStrStr", noSideEffect, merge.}
- Concatenates
x
withy
.assert("ab" & 'c' == "abc")
Source Edit proc `&`(x, y: char): string {...}{.magic: "ConStrStr", noSideEffect, merge.}
- Concatenates characters
x
andy
into a string.assert('a' & 'b' == "ab")
Source Edit proc `&`(x, y: string): string {...}{.magic: "ConStrStr", noSideEffect, merge.}
- Concatenates strings
x
andy
.assert("ab" & "cd" == "abcd")
Source Edit proc `&`(x: char; y: string): string {...}{.magic: "ConStrStr", noSideEffect, merge.}
- Concatenates
x
withy
.assert('a' & "bc" == "abc")
Source Edit proc add(x: var string; y: char) {...}{.magic: "AppendStrCh", noSideEffect.}
- Appends
y
tox
in place.var tmp = "" tmp.add('a') tmp.add('b') assert(tmp == "ab")
Source Edit proc add(x: var string; y: string) {...}{.magic: "AppendStrStr", noSideEffect.}
- Concatenates
x
andy
in place.var tmp = "" tmp.add("ab") tmp.add("cd") assert(tmp == "abcd")
Source Edit proc quit(errorcode: int = QuitSuccess) {...}{.magic: "Exit", noreturn.}
-
Stops the program immediately with an exit code.
Before stopping the program the "exit procedures" are called in the opposite order they were added with addExitProc.
quit
never returns and ignores any exception that may have been raised by the quit procedures. It does not call the garbage collector to free all the memory, unless a quit procedure calls GC_fullCollect.The proc
quit(QuitSuccess)
is called implicitly when your nim program finishes without incident for platforms where this is the expected behavior. A raised unhandled exception is equivalent to callingquit(QuitFailure)
.Note that this is a runtime call and using
Source Editquit
inside a macro won't have any compile time effect. If you need to stop the compiler inside a macro, use the error or fatal pragmas. proc add[T](x: var seq[T]; y: sink T) {...}{.magic: "AppendSeqElem", noSideEffect.}
-
Generic proc for adding a data item
y
to a containerx
.For containers that have an order,
Source Editadd
means append. New generic containers should also call their adding procadd
for consistency. Generic code becomes much easier to write if the Nim naming scheme is respected. proc add[T](x: var seq[T]; y: openArray[T]) {...}{.noSideEffect.}
-
Generic proc for adding a container
y
to a containerx
.For containers that have an order,
add
means append. New generic containers should also call their adding procadd
for consistency. Generic code becomes much easier to write if the Nim naming scheme is respected.See also:
var s: seq[string] = @["test2","test2"] s.add("test") # s <- @[test2, test2, test]
Source Edit proc del[T](x: var seq[T]; i: Natural) {...}{.noSideEffect.}
-
Deletes the item at index
i
by puttingx[high(x)]
into positioni
.This is an
O(1)
operation.See also:
- delete for preserving the order
var i = @[1, 2, 3, 4, 5] i.del(2) # => @[1, 2, 5, 4]
Source Edit proc delete[T](x: var seq[T]; i: Natural) {...}{.noSideEffect.}
-
Deletes the item at index
i
by moving allx[i+1..]
items by one position.This is an
O(n)
operation.See also:
- del for O(1) operation
var i = @[1, 2, 3, 4, 5] i.delete(2) # => @[1, 2, 4, 5]
Source Edit proc insert[T](x: var seq[T]; item: sink T; i = 0.Natural) {...}{.noSideEffect.}
- Inserts
item
intox
at positioni
.var i = @[1, 3, 5] i.insert(99, 0) # i <- @[99, 1, 3, 5]
Source Edit proc repr[T](x: T): string {...}{.magic: "Repr", noSideEffect.}
-
Takes any Nim variable and returns its string representation.
It works even for complex data graphs with cycles. This is a great debugging tool.
var s: seq[string] = @["test2", "test2"] var i = @[1, 2, 3, 4, 5] echo repr(s) # => 0x1055eb050[0x1055ec050"test2", 0x1055ec078"test2"] echo repr(i) # => 0x1055ed050[1, 2, 3, 4, 5]
Source Edit proc toFloat(i: int): float {...}{.noSideEffect, inline, raises: [], tags: [].}
-
Converts an integer
i
into afloat
.If the conversion fails,
ValueError
is raised. However, on most platforms the conversion cannot fail.let a = 2 b = 3.7 echo a.toFloat + b # => 5.7
Source Edit proc toBiggestFloat(i: BiggestInt): BiggestFloat {...}{.noSideEffect, inline, raises: [], tags: [].}
- Same as toFloat but for
BiggestInt
toBiggestFloat
. Source Edit proc toInt(f: float): int {...}{.noSideEffect, raises: [], tags: [].}
-
Converts a floating point number
f
into anint
.Conversion rounds
f
half away from 0, see Round half away from zero.Note that some floating point numbers (e.g. infinity or even 1e19) cannot be accurately converted.
doAssert toInt(0.49) == 0 doAssert toInt(0.5) == 1 doAssert toInt(-0.5) == -1 # rounding is symmetrical
Source Edit proc toBiggestInt(f: BiggestFloat): BiggestInt {...}{.noSideEffect, raises: [], tags: [].}
- Same as toInt but for
BiggestFloat
toBiggestInt
. Source Edit proc addQuitProc(quitProc: proc () {...}{.noconv.}) {...}{.importc: "atexit", header: "<stdlib.h>", deprecated: "use exitprocs.addExitProc".}
-
Adds/registers a quit procedure.
Each call to
Source EditaddQuitProc
registers another quit procedure. Up to 30 procedures can be registered. They are executed on a last-in, first-out basis (that is, the last function registered is the first to be executed).addQuitProc
raises an EOutOfIndex exception ifquitProc
cannot be registered. proc swap[T](a, b: var T) {...}{.magic: "Swap", noSideEffect.}
-
Swaps the values
a
andb
.This is often more efficient than
tmp = a; a = b; b = tmp
. Particularly useful for sorting algorithms.var a = 5 b = 9 swap(a, b) assert a == 9 assert b == 5
Source Edit proc `-`(a, b: AllocStats): AllocStats {...}{.raises: [], tags: [].}
- Source Edit
proc getAllocStats(): AllocStats {...}{.raises: [], tags: [].}
- Source Edit
proc createU(T: typedesc; size = 1.Positive): ptr T:type {...}{.inline, gcsafe, locks: 0, raises: [].}
-
Allocates a new memory block with at least
T.sizeof * size
bytes.The block has to be freed with resize(block, 0) or dealloc(block). The block is not initialized, so reading from it before writing to it is undefined behaviour!
The allocated memory belongs to its allocating thread! Use createSharedU to allocate from a shared heap.
See also:
Source Edit proc create(T: typedesc; size = 1.Positive): ptr T:type {...}{.inline, gcsafe, locks: 0, raises: [].}
-
Allocates a new memory block with at least
T.sizeof * size
bytes.The block has to be freed with resize(block, 0) or dealloc(block). The block is initialized with all bytes containing zero, so it is somewhat safer than createU.
The allocated memory belongs to its allocating thread! Use createShared to allocate from a shared heap.
Source Edit proc resize[T](p: ptr T; newSize: Natural): ptr T {...}{.inline, gcsafe, locks: 0, raises: [].}
-
Grows or shrinks a given memory block.
If
p
is nil then a new memory block is returned. In either way the block has at leastT.sizeof * newSize
bytes. IfnewSize == 0
andp
is not nilresize
callsdealloc(p)
. In other cases the block has to be freed withfree
.The allocated memory belongs to its allocating thread! Use resizeShared to reallocate from a shared heap.
Source Edit proc dealloc(p: pointer) {...}{.noconv, compilerproc, gcsafe, gcsafe, locks: 0, raises: [], tags: [].}
-
Frees the memory allocated with
alloc
,alloc0
orrealloc
.This procedure is dangerous! If one forgets to free the memory a leak occurs; if one tries to access freed memory (or just freeing it twice!) a core dump may happen or other memory may be corrupted.
The freed memory must belong to its allocating thread! Use deallocShared to deallocate from a shared heap.
Source Edit proc createSharedU(T: typedesc; size = 1.Positive): ptr T:type {...}{.inline, tags: [], gcsafe, locks: 0, raises: [].}
-
Allocates a new memory block on the shared heap with at least
T.sizeof * size
bytes.The block has to be freed with resizeShared(block, 0) or freeShared(block).
The block is not initialized, so reading from it before writing to it is undefined behaviour!
See also:
Source Edit proc createShared(T: typedesc; size = 1.Positive): ptr T:type {...}{.inline.}
-
Allocates a new memory block on the shared heap with at least
T.sizeof * size
bytes.The block has to be freed with resizeShared(block, 0) or freeShared(block).
The block is initialized with all bytes containing zero, so it is somewhat safer than createSharedU.
Source Edit proc resizeShared[T](p: ptr T; newSize: Natural): ptr T {...}{.inline, raises: [].}
-
Grows or shrinks a given memory block on the heap.
If
Source Editp
is nil then a new memory block is returned. In either way the block has at leastT.sizeof * newSize
bytes. IfnewSize == 0
andp
is not nilresizeShared
callsfreeShared(p)
. In other cases the block has to be freed with freeShared. proc deallocShared(p: pointer) {...}{.noconv, compilerproc, gcsafe, gcsafe, locks: 0, raises: [], tags: [].}
-
Frees the memory allocated with
allocShared
,allocShared0
orreallocShared
.This procedure is dangerous! If one forgets to free the memory a leak occurs; if one tries to access freed memory (or just freeing it twice!) a core dump may happen or other memory may be corrupted.
Source Edit proc freeShared[T](p: ptr T) {...}{.inline, gcsafe, locks: 0, raises: [].}
-
Frees the memory allocated with
createShared
,createSharedU
orresizeShared
.This procedure is dangerous! If one forgets to free the memory a leak occurs; if one tries to access freed memory (or just freeing it twice!) a core dump may happen or other memory may be corrupted.
Source Edit proc `|`(a, b: typedesc): typedesc
- Source Edit
proc abs(x: float64): float64 {...}{.noSideEffect, inline, raises: [], tags: [].}
- Source Edit
proc abs(x: float32): float32 {...}{.noSideEffect, inline, raises: [], tags: [].}
- Source Edit
proc min(x, y: float32): float32 {...}{.noSideEffect, inline, raises: [], tags: [].}
- Source Edit
proc min(x, y: float64): float64 {...}{.noSideEffect, inline, raises: [], tags: [].}
- Source Edit
proc max(x, y: float32): float32 {...}{.noSideEffect, inline, raises: [], tags: [].}
- Source Edit
proc max(x, y: float64): float64 {...}{.noSideEffect, inline, raises: [], tags: [].}
- Source Edit
proc min[T: not SomeFloat](x, y: T): T {...}{.inline.}
- Source Edit
proc max[T: not SomeFloat](x, y: T): T {...}{.inline.}
- Source Edit
proc high(T: typedesc[SomeFloat]): T:type
- Source Edit
proc low(T: typedesc[SomeFloat]): T:type
- Source Edit
proc len[U: Ordinal; V: Ordinal](x: HSlice[U, V]): int {...}{.noSideEffect, inline.}
- Length of ordinal slice. When x.b < x.a returns zero length.
assert((0..5).len == 6) assert((5..2).len == 0)
Source Edit proc isNil[T](x: seq[T]): bool {...}{.noSideEffect, magic: "IsNil", error.}
-
Requires
--nilseqs:on
since 0.19.Seqs are no longer nil by default, but set and empty. Check for zero length instead.
See also:
Source Edit proc isNil[T](x: ref T): bool {...}{.noSideEffect, magic: "IsNil".}
- Source Edit
proc isNil(x: string): bool {...}{.noSideEffect, magic: "IsNil", error.}
-
Requires
--nilseqs:on
.See also:
Source Edit proc isNil[T](x: ptr T): bool {...}{.noSideEffect, magic: "IsNil".}
- Source Edit
proc isNil(x: pointer): bool {...}{.noSideEffect, magic: "IsNil".}
- Source Edit
proc isNil(x: cstring): bool {...}{.noSideEffect, magic: "IsNil".}
- Source Edit
proc isNil[T: proc](x: T): bool {...}{.noSideEffect, magic: "IsNil".}
- Fast check whether
x
is nil. This is sometimes more efficient than== nil
. Source Edit proc `@`[T](a: openArray[T]): seq[T]
-
Turns an openArray into a sequence.
This is not as efficient as turning a fixed length array into a sequence as it always copies every element of
Source Edita
. proc `&`[T](x, y: seq[T]): seq[T] {...}{.noSideEffect.}
-
Concatenates two sequences.
Requires copying of the sequences.
See also:
assert(@[1, 2, 3, 4] & @[5, 6] == @[1, 2, 3, 4, 5, 6])
Source Edit proc `&`[T](x: seq[T]; y: T): seq[T] {...}{.noSideEffect.}
-
Appends element y to the end of the sequence.
Requires copying of the sequence.
See also:
assert(@[1, 2, 3] & 4 == @[1, 2, 3, 4])
Source Edit proc `&`[T](x: T; y: seq[T]): seq[T] {...}{.noSideEffect.}
-
Prepends the element x to the beginning of the sequence.
Requires copying of the sequence.
assert(1 & @[2, 3, 4] == @[1, 2, 3, 4])
Source Edit proc astToStr[T](x: T): string {...}{.magic: "AstToStr", noSideEffect.}
- Converts the AST of
x
into a string representation. This is very useful for debugging. Source Edit proc instantiationInfo(index = -1; fullPaths = false): tuple[filename: string, line: int, column: int] {...}{.magic: "InstantiationInfo", noSideEffect.}
-
Provides access to the compiler's instantiation stack line information of a template.
While similar to the caller info of other languages, it is determined at compile time.
This proc is mostly useful for meta programming (eg.
assert
template) to retrieve information about the current filename and line number. Example:import strutils template testException(exception, code: untyped): typed = try: let pos = instantiationInfo() discard(code) echo "Test failure at $1:$2 with '$3'" % [pos.filename, $pos.line, astToStr(code)] assert false, "A test expecting failure succeeded?" except exception: discard proc tester(pos: int): int = let a = @[1, 2, 3] result = a[pos] when isMainModule: testException(IndexDefect, tester(30)) testException(IndexDefect, tester(1)) # --> Test failure at example.nim:20 with 'tester(1)'
Source Edit proc compiles(x: untyped): bool {...}{.magic: "Compiles", noSideEffect, compileTime, raises: [], tags: [].}
- Special compile-time procedure that checks whether
x
can be compiled without any semantic error. This can be used to check whether a type supports some operation:when compiles(3 + 4): echo "'+' for integers is available"
Source Edit proc atomicInc(memLoc: var int; x: int = 1): int {...}{.inline, discardable, gcsafe, locks: 0, raises: [], tags: [].}
- Atomic increment of
memLoc
. Returns the value after the operation. Source Edit proc atomicDec(memLoc: var int; x: int = 1): int {...}{.inline, discardable, gcsafe, locks: 0, raises: [], tags: [].}
- Atomic decrement of
memLoc
. Returns the value after the operation. Source Edit proc addAndFetch(p: ptr int; val: int): int {...}{.inline, raises: [], tags: [].}
- Source Edit
proc cas[T: bool | int | ptr](p: ptr T; oldValue, newValue: T): bool {...}{. importc: "__sync_bool_compare_and_swap", nodecl.}
- Source Edit
proc cpuRelax() {...}{.inline, raises: [], tags: [].}
- Source Edit
proc find[T, S](a: T; item: S): int {...}{.inline.}
- Returns the first index of
item
ina
or -1 if not found. This requires appropriateitems
and==
operations to work. Source Edit proc contains[T](a: openArray[T]; item: T): bool {...}{.inline.}
-
Returns true if
item
is ina
or false if not found. This is a shortcut forfind(a, item) >= 0
.This allows the
in
operator:a.contains(item)
is the same asitem in a
.var a = @[1, 3, 5] assert a.contains(5) assert 3 in a assert 99 notin a
Source Edit proc pop[T](s: var seq[T]): T {...}{.inline, noSideEffect.}
- Returns the last item of
s
and decreasess.len
by one. This treatss
as a stack and implements the common pop operation.Example:
var a = @[1, 3, 5, 7] let b = pop(a) assert b == 7 assert a == @[1, 3, 5]
Source Edit proc `==`[T: tuple | object](x, y: T): bool
- Generic
==
operator for tuples that is lifted from the components. ofx
andy
. Source Edit proc `<=`[T: tuple](x, y: T): bool
- Generic lexicographic
<=
operator for tuples that is lifted from the components ofx
andy
. This implementation usescmp
. Source Edit proc `<`[T: tuple](x, y: T): bool
- Generic lexicographic
<
operator for tuples that is lifted from the components ofx
andy
. This implementation usescmp
. Source Edit proc GC_ref[T](x: ref T) {...}{.magic: "GCref", gcsafe, locks: 0.}
- Source Edit
proc GC_ref[T](x: seq[T]) {...}{.magic: "GCref", gcsafe, locks: 0.}
- Source Edit
proc GC_ref(x: string) {...}{.magic: "GCref", gcsafe, locks: 0.}
- Marks the object
x
as referenced, so that it will not be freed until it is unmarked viaGC_unref
. If called n-times for the same objectx
, n calls toGC_unref
are needed to unmarkx
. Source Edit proc GC_unref[T](x: ref T) {...}{.magic: "GCunref", gcsafe, locks: 0.}
- Source Edit
proc GC_unref[T](x: seq[T]) {...}{.magic: "GCunref", gcsafe, locks: 0.}
- Source Edit
proc GC_unref(x: string) {...}{.magic: "GCunref", gcsafe, locks: 0.}
- See the documentation of GC_ref. Source Edit
proc add(x: var string; y: cstring) {...}{.asmNoStackFrame, raises: [], tags: [].}
- Appends
y
tox
in place.Example:
var tmp = "" tmp.add(cstring("ab")) tmp.add(cstring("cd")) doAssert tmp == "abcd"
Source Edit proc add(x: var cstring; y: cstring) {...}{.magic: "AppendStrStr", raises: [], tags: [].}
- Appends
y
tox
in place. Only implemented for JS backend.Example:
when defined(js): var tmp: cstring = "" tmp.add(cstring("ab")) tmp.add(cstring("cd")) doAssert tmp == cstring("abcd")
Source Edit proc echo(x: varargs[typed, `$`]) {...}{.magic: "Echo", tags: [WriteIOEffect], gcsafe, locks: 0, sideEffect.}
-
Writes and flushes the parameters to the standard output.
Special built-in that takes a variable number of arguments. Each argument is converted to a string via
$
, so it works for user-defined types that have an overloaded$
operator. It is roughly equivalent towriteLine(stdout, x); flushFile(stdout)
, but available for the JavaScript target too.Unlike other IO operations this is guaranteed to be thread-safe as
Source Editecho
is very often used for debugging convenience. If you want to useecho
inside a proc without side effects you can use debugEcho instead. proc debugEcho(x: varargs[typed, `$`]) {...}{.magic: "Echo", noSideEffect, tags: [], raises: [].}
- Same as echo, but as a special semantic rule,
debugEcho
pretends to be free of side effects, so that it can be used for debugging routines marked as noSideEffect. Source Edit proc getTypeInfo[T](x: T): pointer {...}{.magic: "GetTypeInfo", gcsafe, locks: 0.}
-
Get type information for
x
.Ordinary code should not use this, but the typeinfo module instead.
Source Edit proc abs(x: int): int {...}{.magic: "AbsI", noSideEffect, raises: [], tags: [].}
- Source Edit
proc abs(x: int8): int8 {...}{.magic: "AbsI", noSideEffect, raises: [], tags: [].}
- Source Edit
proc abs(x: int16): int16 {...}{.magic: "AbsI", noSideEffect, raises: [], tags: [].}
- Source Edit
proc abs(x: int32): int32 {...}{.magic: "AbsI", noSideEffect, raises: [], tags: [].}
- Source Edit
proc abs(x: int64): int64 {...}{.magic: "AbsI", noSideEffect, raises: [], tags: [].}
-
Returns the absolute value of
x
.If
Source Editx
islow(x)
(that is -MININT for its type), an overflow exception is thrown (if overflow checking is turned on). proc zeroMem(p: pointer; size: Natural) {...}{.inline, noSideEffect, tags: [], locks: 0, raises: [].}
-
Overwrites the contents of the memory at
p
with the value 0.Exactly
Source Editsize
bytes will be overwritten. Like any procedure dealing with raw memory this is unsafe. proc copyMem(dest, source: pointer; size: Natural) {...}{.inline, gcsafe, locks: 0, tags: [], locks: 0, raises: [].}
- Copies the contents from the memory at
source
to the memory atdest
. Exactlysize
bytes will be copied. The memory regions may not overlap. Like any procedure dealing with raw memory this is unsafe. Source Edit proc moveMem(dest, source: pointer; size: Natural) {...}{.inline, gcsafe, locks: 0, tags: [], locks: 0, raises: [].}
-
Copies the contents from the memory at
source
to the memory atdest
.Exactly
Source Editsize
bytes will be copied. The memory regions may overlap,moveMem
handles this case appropriately and is thus somewhat more safe thancopyMem
. Like any procedure dealing with raw memory this is still unsafe, though. proc equalMem(a, b: pointer; size: Natural): bool {...}{.inline, noSideEffect, tags: [], locks: 0, raises: [].}
-
Compares the memory blocks
a
andb
.size
bytes will be compared.If the blocks are equal,
Source Edittrue
is returned,false
otherwise. Like any procedure dealing with raw memory this is unsafe. proc cmp(x, y: string): int {...}{.noSideEffect, raises: [], tags: [].}
-
Compare proc for strings. More efficient than the generic version.
Note: The precise result values depend on the used C runtime library and can differ between operating systems!
Source Edit proc cstringArrayToSeq(a: cstringArray; len: Natural): seq[string] {...}{.raises: [], tags: [].}
- Converts a
cstringArray
to aseq[string]
.a
is supposed to be of lengthlen
. Source Edit proc cstringArrayToSeq(a: cstringArray): seq[string] {...}{.raises: [], tags: [].}
- Converts a
cstringArray
to aseq[string]
.a
is supposed to be terminated bynil
. Source Edit proc allocCStringArray(a: openArray[string]): cstringArray {...}{.raises: [], tags: [].}
- Creates a NULL terminated cstringArray from
a
. The result has to be freed withdeallocCStringArray
after it's not needed anymore. Source Edit proc deallocCStringArray(a: cstringArray) {...}{.raises: [], tags: [].}
- Frees a NULL terminated cstringArray. Source Edit
proc setControlCHook(hook: proc () {...}{.noconv.}) {...}{.raises: [], tags: [].}
- Allows you to override the behaviour of your application when CTRL+C is pressed. Only one such hook is supported. Source Edit
proc unsetControlCHook() {...}{.raises: [], tags: [RootEffect, WriteIOEffect].}
- Reverts a call to setControlCHook. Source Edit
proc getStackTrace(): string {...}{.gcsafe, raises: [], tags: [].}
- Gets the current stack trace. This only works for debug builds. Source Edit
proc getStackTrace(e: ref Exception): string {...}{.gcsafe, raises: [], tags: [].}
- Gets the stack trace associated with
e
, which is the stack that lead to theraise
statement. This only works for debug builds. Source Edit proc getFrameState(): FrameState {...}{.compilerproc, inline, raises: [], tags: [].}
- Source Edit
proc setFrameState(state: FrameState) {...}{.compilerproc, inline, raises: [], tags: [].}
- Source Edit
proc getFrame(): PFrame {...}{.compilerproc, inline, raises: [], tags: [].}
- Source Edit
proc setFrame(s: PFrame) {...}{.compilerproc, inline, raises: [], tags: [].}
- Source Edit
proc getGcFrame(): GcFrame {...}{.compilerproc, inline, raises: [], tags: [].}
- Source Edit
proc popGcFrame() {...}{.compilerproc, inline, raises: [], tags: [].}
- Source Edit
proc setGcFrame(s: GcFrame) {...}{.compilerproc, inline, raises: [], tags: [].}
- Source Edit
proc pushGcFrame(s: GcFrame) {...}{.compilerproc, inline, raises: [], tags: [].}
- Source Edit
proc stackTraceAvailable(): bool {...}{.raises: [], tags: [].}
- Source Edit
proc writeStackTrace() {...}{.tags: [], gcsafe, raises: [].}
- Writes the current stack trace to
stderr
. This is only works for debug builds. Since it's usually used for debugging, this is proclaimed to have no IO effect! Source Edit proc getStackTraceEntries(e: ref Exception): seq[StackTraceEntry] {...}{.raises: [], tags: [].}
- Returns the attached stack trace to the exception
e
as aseq
. This is not yet available for the JS backend. Source Edit proc getStackTraceEntries(): seq[StackTraceEntry] {...}{.raises: [], tags: [].}
- Returns the stack trace entries for the current stack trace. This is not yet available for the JS backend. Source Edit
proc iterToProc(iter: typed; envType: typedesc; procName: untyped) {...}{. magic: "Plugin", compileTime.}
- Source Edit
proc allocImpl(size: Natural): pointer {...}{.noconv, gcsafe, tags: [], gcsafe, locks: 0, raises: [].}
- Source Edit
proc alloc0Impl(size: Natural): pointer {...}{.noconv, gcsafe, tags: [], gcsafe, locks: 0, raises: [].}
- Source Edit
proc deallocImpl(p: pointer) {...}{.noconv, gcsafe, tags: [], gcsafe, locks: 0, raises: [].}
- Source Edit
proc reallocImpl(p: pointer; newSize: Natural): pointer {...}{.noconv, gcsafe, tags: [], gcsafe, locks: 0, raises: [].}
- Source Edit
proc realloc0Impl(p: pointer; oldSize, newSize: Natural): pointer {...}{.noconv, gcsafe, tags: [], gcsafe, locks: 0, raises: [].}
- Source Edit
proc getFreeMem(): int {...}{.gcsafe, raises: [], tags: [].}
- Returns the number of bytes that are owned by the process, but do not hold any meaningful data. Source Edit
proc getTotalMem(): int {...}{.gcsafe, raises: [], tags: [].}
- Returns the number of bytes that are owned by the process. Source Edit
proc getOccupiedMem(): int {...}{.gcsafe, raises: [], tags: [].}
- Returns the number of bytes that are owned by the process and hold data. Source Edit
proc getMaxMem(): int {...}{.raises: [], tags: [].}
- Source Edit
proc allocSharedImpl(size: Natural): pointer {...}{.noconv, compilerproc, gcsafe, gcsafe, locks: 0, raises: [], tags: [].}
- Source Edit
proc allocShared0Impl(size: Natural): pointer {...}{.noconv, gcsafe, gcsafe, locks: 0, raises: [], tags: [].}
- Source Edit
proc deallocSharedImpl(p: pointer) {...}{.noconv, gcsafe, gcsafe, locks: 0, raises: [], tags: [].}
- Source Edit
proc reallocSharedImpl(p: pointer; newSize: Natural): pointer {...}{.noconv, gcsafe, tags: [], gcsafe, locks: 0, raises: [].}
- Source Edit
proc reallocShared0Impl(p: pointer; oldSize, newSize: Natural): pointer {...}{. noconv, gcsafe, tags: [], gcsafe, locks: 0, raises: [].}
- Source Edit
proc protect(x: pointer): ForeignCell {...}{.raises: [], tags: [].}
- Source Edit
proc dispose(x: ForeignCell) {...}{.raises: [], tags: [].}
- Source Edit
proc isNotForeign(x: ForeignCell): bool {...}{.raises: [], tags: [].}
- returns true if 'x' belongs to the calling thread. No deep copy has to be performed then. Source Edit
proc setupForeignThreadGc() {...}{.gcsafe, raises: [], tags: [].}
-
Call this if you registered a callback that will be run from a thread not under your control. This has a cheap thread-local guard, so the GC for this thread will only be initialized once per thread, no matter how often it is called.
This function is available only when
Source Edit--threads:on
and--tlsEmulation:off
switches are used proc tearDownForeignThreadGc() {...}{.gcsafe, raises: [], tags: [].}
-
Call this to tear down the GC, previously initialized by
setupForeignThreadGc
. If GC has not been previously initialized, or has already been torn down, the call does nothing.This function is available only when
Source Edit--threads:on
and--tlsEmulation:off
switches are used proc nimGC_setStackBottom(theStackBottom: pointer) {...}{.compilerproc, noinline, gcsafe, locks: 0, raises: [], tags: [].}
- Expands operating GC stack range to
theStackBottom
. Does nothing if current stack bottom is already lower thantheStackBottom
. Source Edit proc deallocHeap(runFinalizers = true; allowGcAfterwards = true) {...}{. raises: [Exception], tags: [RootEffect].}
- Frees the thread local heap. Runs every finalizer if
runFinalizers
is true. IfallowGcAfterwards
is true, a minimal amount of allocation happens to ensure the GC can continue to work after the call todeallocHeap
. Source Edit proc gcInvariant() {...}{.raises: [], tags: [].}
- Source Edit
proc GC_collectZct() {...}{.raises: [Exception], tags: [RootEffect].}
- Collect the ZCT (zero count table). Unstable, experimental API for testing purposes. DO NOT USE! Source Edit
proc GC_disable() {...}{.gcsafe, inline, gcsafe, locks: 0, raises: [], tags: [].}
-
Disables the GC. If called
n
times,n
calls toGC_enable
are needed to reactivate the GC.Note that in most circumstances one should only disable the mark and sweep phase with GC_disableMarkAndSweep.
Source Edit proc GC_enable() {...}{.gcsafe, inline, gcsafe, locks: 0, raises: [], tags: [].}
- Enables the GC again. Source Edit
proc GC_enableMarkAndSweep() {...}{.gcsafe, gcsafe, locks: 0, raises: [], tags: [].}
- Source Edit
proc GC_disableMarkAndSweep() {...}{.gcsafe, gcsafe, locks: 0, raises: [], tags: [].}
- The current implementation uses a reference counting garbage collector with a seldomly run mark and sweep phase to free cycles. The mark and sweep phase may take a long time and is not needed if the application does not create cycles. Thus the mark and sweep phase can be deactivated and activated separately from the rest of the GC. Source Edit
proc GC_fullCollect() {...}{.gcsafe, gcsafe, locks: 0, raises: [Exception], tags: [RootEffect].}
- Forces a full garbage collection pass. Ordinary code does not need to call this (and should not). Source Edit
proc GC_getStatistics(): string {...}{.gcsafe, gcsafe, locks: 0, raises: [], tags: [].}
- Returns an informative string about the GC's activity. This may be useful for tweaking. Source Edit
proc addInt(result: var string; x: int64) {...}{.raises: [], tags: [].}
- Converts integer to its string representation and appends it to
result
.var a = "123" b = 45 a.addInt(b) # a <- "12345"
Source Edit proc addFloat(result: var string; x: float) {...}{.raises: [], tags: [].}
- Converts float to its string representation and appends it to
result
.var a = "123" b = 45.67 a.addFloat(b) # a <- "12345.67"
Source Edit proc getCurrentException(): ref Exception {...}{.compilerproc, inline, gcsafe, locks: 0, raises: [], tags: [].}
- Retrieves the current exception; if there is none,
nil
is returned. Source Edit proc getCurrentExceptionMsg(): string {...}{.inline, gcsafe, locks: 0, raises: [], tags: [].}
- Retrieves the error message that was attached to the current exception; if there is none,
""
is returned. Source Edit proc setCurrentException(exc: ref Exception) {...}{.inline, gcsafe, locks: 0, raises: [], tags: [].}
-
Sets the current exception.
Warning: Only use this if you know what you are doing.
Source Edit proc rawProc[T: proc](x: T): pointer {...}{.noSideEffect, inline.}
- Retrieves the raw proc pointer of the closure
x
. This is useful for interfacing closures with C. Source Edit proc rawEnv[T: proc](x: T): pointer {...}{.noSideEffect, inline.}
- Retrieves the raw environment pointer of the closure
x
. This is useful for interfacing closures with C. Source Edit proc finished[T: proc](x: T): bool {...}{.noSideEffect, inline.}
- can be used to determine if a first class iterator has finished. Source Edit
proc quit(errormsg: string; errorcode = QuitFailure) {...}{.noreturn, raises: [], tags: [].}
- A shorthand for
echo(errormsg); quit(errorcode)
. Source Edit proc `/`(x, y: int): float {...}{.inline, noSideEffect, raises: [], tags: [].}
-
Division of integers that results in a float.
See also:
echo 7 / 5 # => 1.4
Source Edit proc `[]`[T, U](s: string; x: HSlice[T, U]): string {...}{.inline.}
- Slice operation for strings. Returns the inclusive range
[s[x.a], s[x.b]]
:var s = "abcdef" assert s[1..3] == "bcd"
Source Edit proc `[]=`[T, U](s: var string; x: HSlice[T, U]; b: string)
-
Slice assignment for strings.
If
b.len
is not exactly the number of elements that are referred to byx
, a splice is performed:Example:
var s = "abcdefgh" s[1 .. ^2] = "xyz" assert s == "axyzh"
Source Edit proc `[]`[Idx, T, U, V](a: array[Idx, T]; x: HSlice[U, V]): seq[T]
- Slice operation for arrays. Returns the inclusive range
[a[x.a], a[x.b]]
:var a = [1, 2, 3, 4] assert a[0..2] == @[1, 2, 3]
Source Edit proc `[]=`[Idx, T, U, V](a: var array[Idx, T]; x: HSlice[U, V]; b: openArray[T])
- Slice assignment for arrays.
var a = [10, 20, 30, 40, 50] a[1..2] = @[99, 88] assert a == [10, 99, 88, 40, 50]
Source Edit proc `[]`[T, U, V](s: openArray[T]; x: HSlice[U, V]): seq[T]
- Slice operation for sequences. Returns the inclusive range
[s[x.a], s[x.b]]
:var s = @[1, 2, 3, 4] assert s[0..2] == @[1, 2, 3]
Source Edit proc `[]=`[T, U, V](s: var seq[T]; x: HSlice[U, V]; b: openArray[T])
-
Slice assignment for sequences.
If
b.len
is not exactly the number of elements that are referred to byx
, a splice is performed.Example:
var s = @"abcdefgh" s[1 .. ^2] = @"xyz" assert s == @"axyzh"
Source Edit proc `[]`[T](s: openArray[T]; i: BackwardsIndex): T {...}{.inline.}
- Source Edit
proc `[]`[Idx, T](a: array[Idx, T]; i: BackwardsIndex): T {...}{.inline.}
- Source Edit
proc `[]`(s: string; i: BackwardsIndex): char {...}{.inline, raises: [], tags: [].}
- Source Edit
proc `[]`[T](s: var openArray[T]; i: BackwardsIndex): var T {...}{.inline.}
- Source Edit
proc `[]`[Idx, T](a: var array[Idx, T]; i: BackwardsIndex): var T {...}{.inline.}
- Source Edit
proc `[]=`[T](s: var openArray[T]; i: BackwardsIndex; x: T) {...}{.inline.}
- Source Edit
proc `[]=`[Idx, T](a: var array[Idx, T]; i: BackwardsIndex; x: T) {...}{.inline.}
- Source Edit
proc `[]=`(s: var string; i: BackwardsIndex; x: char) {...}{.inline, raises: [], tags: [].}
- Source Edit
proc slurp(filename: string): string {...}{.magic: "Slurp".}
- This is an alias for staticRead. Source Edit
proc staticRead(filename: string): string {...}{.magic: "Slurp".}
-
Compile-time readFile proc for easy resource embedding:
The maximum file size limit that
staticRead
andslurp
can read is near or equal to the free memory of the device you are using to compile.const myResource = staticRead"mydatafile.bin"
slurp is an alias for
Source EditstaticRead
. proc gorge(command: string; input = ""; cache = ""): string {...}{. magic: "StaticExec", raises: [], tags: [].}
- This is an alias for staticExec. Source Edit
proc staticExec(command: string; input = ""; cache = ""): string {...}{. magic: "StaticExec", raises: [], tags: [].}
-
Executes an external process at compile-time and returns its text output (stdout + stderr).
If
input
is not an empty string, it will be passed as a standard input to the executed program.const buildInfo = "Revision " & staticExec("git rev-parse HEAD") & "\nCompiled on " & staticExec("uname -v")
gorge is an alias for
staticExec
.Note that you can use this proc inside a pragma like passc or passl.
If
cache
is not empty, the results ofstaticExec
are cached within thenimcache
directory. Use--forceBuild
to get rid of this caching behaviour then.command & input & cache
(the concatenated string) is used to determine whether the entry in the cache is still valid. You can use versioning information forcache
:const stateMachine = staticExec("dfaoptimizer", "input", "0.8.0")
Source Edit proc gorgeEx(command: string; input = ""; cache = ""): tuple[output: string, exitCode: int] {...}{.raises: [], tags: [].}
- Similar to gorge but also returns the precious exit code. Source Edit
proc `+=`[T: float | float32 | float64](x: var T; y: T) {...}{.inline, noSideEffect.}
- Increments in place a floating point number. Source Edit
proc `-=`[T: float | float32 | float64](x: var T; y: T) {...}{.inline, noSideEffect.}
- Decrements in place a floating point number. Source Edit
proc `*=`[T: float | float32 | float64](x: var T; y: T) {...}{.inline, noSideEffect.}
- Multiplies in place a floating point number. Source Edit
proc `/=`(x: var float64; y: float64) {...}{.inline, noSideEffect, raises: [], tags: [].}
- Divides in place a floating point number. Source Edit
proc `/=`[T: float | float32](x: var T; y: T) {...}{.inline, noSideEffect.}
- Divides in place a floating point number. Source Edit
proc `&=`(x: var string; y: string) {...}{.magic: "AppendStrStr", noSideEffect.}
- Appends in place to a string.
var a = "abc" a &= "de" # a <- "abcde"
Source Edit proc shallow[T](s: var seq[T]) {...}{.noSideEffect, inline.}
-
Marks a sequence
s
as shallow. Subsequent assignments will not perform deep copies ofs
.This is only useful for optimization purposes.
Source Edit proc shallow(s: var string) {...}{.noSideEffect, inline, raises: [], tags: [].}
-
Marks a string
s
as shallow. Subsequent assignments will not perform deep copies ofs
.This is only useful for optimization purposes.
Source Edit proc insert(x: var string; item: string; i = 0.Natural) {...}{.noSideEffect, raises: [], tags: [].}
- Inserts
item
intox
at positioni
.var a = "abc" a.insert("zz", 0) # a <- "zzabc"
Source Edit proc addEscapedChar(s: var string; c: char) {...}{.noSideEffect, inline, raises: [], tags: [].}
- Adds a char to string
s
and applies the following escaping:- replaces any
\
by\\
- replaces any
'
by\'
- replaces any
"
by\"
- replaces any
\a
by\\a
- replaces any
\b
by\\b
- replaces any
\t
by\\t
- replaces any
\n
by\\n
- replaces any
\v
by\\v
- replaces any
\f
by\\f
- replaces any
\c
by\\c
- replaces any
\e
by\\e
- replaces any other character not in the set
{'\21..'\126'} by ``\xHH
whereHH
is its hexadecimal value.
The procedure has been designed so that its output is usable for many different common syntaxes.
Note: This is not correct for producing Ansi C code!
Source Edit - replaces any
proc addQuoted[T](s: var string; x: T)
-
Appends
x
to strings
in place, applying quoting and escaping ifx
is a string or char.See addEscapedChar for the escaping scheme. When
x
is a string, characters in the range{\128..\255}
are never escaped so that multibyte UTF-8 characters are untouched (note that this behavior is different fromaddEscapedChar
).The Nim standard library uses this function on the elements of collections when producing a string representation of a collection. It is recommended to use this function as well for user-side collections. Users may overload
addQuoted
for custom (string-like) types if they want to implement a customized element representation.var tmp = "" tmp.addQuoted(1) tmp.add(", ") tmp.addQuoted("string") tmp.add(", ") tmp.addQuoted('c') assert(tmp == """1, "string", 'c'""")
Source Edit proc locals(): RootObj {...}{.magic: "Plugin", noSideEffect, raises: [], tags: [].}
-
Generates a tuple constructor expression listing all the local variables in the current scope.
This is quite fast as it does not rely on any debug or runtime information. Note that in contrast to what the official signature says, the return type is not
RootObj
but a tuple of a structure that depends on the current scope. Example:proc testLocals() = var a = "something" b = 4 c = locals() d = "super!" b = 1 for name, value in fieldPairs(c): echo "name ", name, " with value ", value echo "B is ", b # -> name a with value something # -> name b with value 4 # -> B is 1
Source Edit proc deepCopy[T](x: var T; y: T) {...}{.noSideEffect, magic: "DeepCopy".}
-
Performs a deep copy of
y
and copies it intox
.This is also used by the code generator for the implementation of
spawn
.For
Source Edit--gc:arc
or--gc:orc
deepcopy support has to be enabled via--deepcopy:on
. proc deepCopy[T](y: T): T
- Convenience wrapper around
deepCopy
overload. Source Edit proc procCall(x: untyped) {...}{.magic: "ProcCall", compileTime, raises: [], tags: [].}
- Special magic to prohibit dynamic binding for method calls. This is similar to super in ordinary OO languages.
# 'someMethod' will be resolved fully statically: procCall someMethod(a, b)
Source Edit proc `==`(x, y: cstring): bool {...}{.magic: "EqCString", noSideEffect, inline, raises: [], tags: [].}
- Checks for equality between two
cstring
variables. Source Edit proc `==`(x: string; y: type(nil) | type(nil)): bool {...}{.error: "\'nil\' is now invalid for \'string\'; compile with --nilseqs:on for a migration period".}
- Source Edit
proc `==`(x: type(nil) | type(nil); y: string): bool {...}{.error: "\'nil\' is now invalid for \'string\'; compile with --nilseqs:on for a migration period".}
- Source Edit
proc substr(s: string; first, last: int): string {...}{.raises: [], tags: [].}
-
Copies a slice of
s
into a new string and returns this new string.The bounds
first
andlast
denote the indices of the first and last characters that shall be copied. Iflast
is omitted, it is treated ashigh(s)
. Iflast >= s.len
,s.len
is used instead: This meanssubstr
can also be used to cut or limit a string's length.Example:
let a = "abcdefgh" assert a.substr(2, 5) == "cdef" assert a.substr(2) == "cdefgh" assert a.substr(5, 99) == "fgh"
Source Edit proc substr(s: string; first = 0): string {...}{.raises: [], tags: [].}
- Source Edit
proc toOpenArray[T](x: ptr UncheckedArray[T]; first, last: int): openArray[T] {...}{. magic: "Slice".}
- Source Edit
proc toOpenArray(x: cstring; first, last: int): openArray[char] {...}{.magic: "Slice".}
- Source Edit
proc toOpenArrayByte(x: cstring; first, last: int): openArray[byte] {...}{. magic: "Slice".}
- Source Edit
proc toOpenArray[T](x: seq[T]; first, last: int): openArray[T] {...}{.magic: "Slice".}
- Source Edit
proc toOpenArray[T](x: openArray[T]; first, last: int): openArray[T] {...}{. magic: "Slice".}
- Source Edit
proc toOpenArray[I, T](x: array[I, T]; first, last: I): openArray[T] {...}{. magic: "Slice".}
- Source Edit
proc toOpenArray(x: string; first, last: int): openArray[char] {...}{.magic: "Slice".}
- Source Edit
proc toOpenArrayByte(x: string; first, last: int): openArray[byte] {...}{. magic: "Slice".}
- Source Edit
proc toOpenArrayByte(x: openArray[char]; first, last: int): openArray[byte] {...}{. magic: "Slice".}
- Source Edit
proc toOpenArrayByte(x: seq[char]; first, last: int): openArray[byte] {...}{. magic: "Slice".}
- Source Edit
Iterators
iterator countdown[T](a, b: T; step: Positive = 1): T {...}{.inline.}
-
Counts from ordinal value
a
down tob
(inclusive) with the given step count.T
may be any ordinal type,step
may only be positive.Note: This fails to count to
low(int)
if T = int for efficiency reasons.for i in countdown(7, 3): echo i # => 7; 6; 5; 4; 3 for i in countdown(9, 2, 3): echo i # => 9; 6; 3
Source Edit iterator countup[T](a, b: T; step: Positive = 1): T {...}{.inline.}
-
Counts from ordinal value
a
tob
(inclusive) with the given step count.T
may be any ordinal type,step
may only be positive.Note: This fails to count to
high(int)
if T = int for efficiency reasons.for i in countup(3, 7): echo i # => 3; 4; 5; 6; 7 for i in countup(2, 9, 3): echo i # => 2; 5; 8
Source Edit iterator `..`[T](a, b: T): T {...}{.inline.}
-
An alias for
countup(a, b, 1)
.See also:
for i in 3 .. 7: echo i # => 3; 4; 5; 6; 7
Source Edit iterator `..`(a, b: int64): int64 {...}{.inline, raises: [], tags: [].}
-
A type specialized version of
..
for convenience so that mixing integer types works better.See also:
Source Edit iterator `..`(a, b: int32): int32 {...}{.inline, raises: [], tags: [].}
-
A type specialized version of
..
for convenience so that mixing integer types works better.See also:
Source Edit iterator `..`(a, b: uint64): uint64 {...}{.inline, raises: [], tags: [].}
-
A type specialized version of
..
for convenience so that mixing integer types works better.See also:
Source Edit iterator `..`(a, b: uint32): uint32 {...}{.inline, raises: [], tags: [].}
-
A type specialized version of
..
for convenience so that mixing integer types works better.See also:
Source Edit iterator `..<`[T](a, b: T): T {...}{.inline.}
- Source Edit
iterator `..<`(a, b: int64): int64 {...}{.inline, raises: [], tags: [].}
- A type specialized version of
..<
for convenience so that mixing integer types works better. Source Edit iterator `..<`(a, b: int32): int32 {...}{.inline, raises: [], tags: [].}
- A type specialized version of
..<
for convenience so that mixing integer types works better. Source Edit iterator `..<`(a, b: uint64): uint64 {...}{.inline, raises: [], tags: [].}
- A type specialized version of
..<
for convenience so that mixing integer types works better. Source Edit iterator `..<`(a, b: uint32): uint32 {...}{.inline, raises: [], tags: [].}
- A type specialized version of
..<
for convenience so that mixing integer types works better. Source Edit iterator `||`[S, T](a: S; b: T; annotation: static string = "parallel for"): T {...}{. inline, magic: "OmpParFor", sideEffect.}
-
OpenMP parallel loop iterator. Same as
..
but the loop may run in parallel.annotation
is an additional annotation for the code generator to use. The default annotation isparallel for
. Please refer to the OpenMP Syntax Reference for further information.Note that the compiler maps that to the
Source Edit#pragma omp parallel for
construct of OpenMP and as such isn't aware of the parallelism in your code! Be careful! Later versions of||
will get proper support by Nim's code generator and GC. iterator `||`[S, T](a: S; b: T; step: Positive; annotation: static string = "parallel for"): T {...}{.inline, magic: "OmpParFor", sideEffect.}
-
OpenMP parallel loop iterator with stepping. Same as
countup
but the loop may run in parallel.annotation
is an additional annotation for the code generator to use. The default annotation isparallel for
. Please refer to the OpenMP Syntax Reference for further information.Note that the compiler maps that to the
Source Edit#pragma omp parallel for
construct of OpenMP and as such isn't aware of the parallelism in your code! Be careful! Later versions of||
will get proper support by Nim's code generator and GC.
Macros
Templates
template `!=`(x, y: untyped): untyped
- Unequals operator. This is a shorthand for
not (x == y)
. Source Edit template `>=`(x, y: untyped): untyped
- "is greater or equals" operator. This is the same as
y <= x
. Source Edit template `>`(x, y: untyped): untyped
- "is greater" operator. This is the same as
y < x
. Source Edit template `>=%`(x, y: untyped): untyped
- Treats
x
andy
as unsigned and compares them. Returns true ifunsigned(x) >= unsigned(y)
. Source Edit template `>%`(x, y: untyped): untyped
- Treats
x
andy
as unsigned and compares them. Returns true ifunsigned(x) > unsigned(y)
. Source Edit template offsetOf[T; ](t: typedesc[T]; member: untyped): int
- Source Edit
template offsetOf[T](value: T; member: untyped): int
- Source Edit
template incl[T](x: var set[T]; y: set[T])
- Includes the set
y
in the setx
.var a = {1, 3, 5, 7} var b = {4, 5, 6} a.incl(b) # a <- {1, 3, 4, 5, 6, 7}
Source Edit template excl[T](x: var set[T]; y: set[T])
- Excludes the set
y
from the setx
.var a = {1, 3, 5, 7} var b = {3, 4, 5} a.excl(b) # a <- {1, 7}
Source Edit template `in`(x, y: untyped): untyped {...}{.dirty.}
- Sugar for
contains
.assert(1 in (1..3) == true) assert(5 in (1..3) == false)
Source Edit template `notin`(x, y: untyped): untyped {...}{.dirty.}
- Sugar for
not contains
.assert(1 notin (1..3) == false) assert(5 notin (1..3) == true)
Source Edit template `isnot`(x, y: untyped): untyped
- Negated version of is. Equivalent to
not(x is y)
.assert 42 isnot float assert @[1, 2] isnot enum
Source Edit template unown(x: typed): untyped
- Source Edit
template `<//>`(t: untyped): untyped
- Source Edit
template disarm(x: typed)
- Useful for
disarming
dangling pointers explicitly for the--newruntime. Regardless of whether --newruntime is used or not this sets the pointer or callback
Source Editx
tonil
. This is an experimental API! template dumpAllocstats(code: untyped)
- Source Edit
template alloc(size: Natural): pointer
-
Allocates a new memory block with at least
size
bytes.The block has to be freed with realloc(block, 0) or dealloc(block). The block is not initialized, so reading from it before writing to it is undefined behaviour!
The allocated memory belongs to its allocating thread! Use allocShared to allocate from a shared heap.
See also:
Source Edit template alloc0(size: Natural): pointer
-
Allocates a new memory block with at least
size
bytes.The block has to be freed with realloc(block, 0) or dealloc(block). The block is initialized with all bytes containing zero, so it is somewhat safer than alloc.
The allocated memory belongs to its allocating thread! Use allocShared0 to allocate from a shared heap.
Source Edit template realloc(p: pointer; newSize: Natural): pointer
-
Grows or shrinks a given memory block.
If
p
is nil then a new memory block is returned. In either way the block has at leastnewSize
bytes. IfnewSize == 0
andp
is not nilrealloc
callsdealloc(p)
. In other cases the block has to be freed with dealloc(block).The allocated memory belongs to its allocating thread! Use reallocShared to reallocate from a shared heap.
Source Edit template realloc0(p: pointer; oldSize, newSize: Natural): pointer
-
Grows or shrinks a given memory block.
If
p
is nil then a new memory block is returned. In either way the block has at leastnewSize
bytes. IfnewSize == 0
andp
is not nilrealloc
callsdealloc(p)
. In other cases the block has to be freed with dealloc(block).The block is initialized with all bytes containing zero, so it is somewhat safer then realloc
The allocated memory belongs to its allocating thread! Use reallocShared to reallocate from a shared heap.
Source Edit template allocShared(size: Natural): pointer
-
Allocates a new memory block on the shared heap with at least
size
bytes.The block has to be freed with reallocShared(block, 0) or deallocShared(block).
The block is not initialized, so reading from it before writing to it is undefined behaviour!
See also: allocShared0.
Source Edit template allocShared0(size: Natural): pointer
-
Allocates a new memory block on the shared heap with at least
size
bytes.The block has to be freed with reallocShared(block, 0) or deallocShared(block).
The block is initialized with all bytes containing zero, so it is somewhat safer than allocShared.
Source Edit template reallocShared(p: pointer; newSize: Natural): pointer
-
Grows or shrinks a given memory block on the heap.
If
Source Editp
is nil then a new memory block is returned. In either way the block has at leastnewSize
bytes. IfnewSize == 0
andp
is not nilreallocShared
callsdeallocShared(p)
. In other cases the block has to be freed with deallocShared. template reallocShared0(p: pointer; oldSize, newSize: Natural): pointer
-
Grows or shrinks a given memory block on the heap.
When growing, the new bytes of the block is initialized with all bytes containing zero, so it is somewhat safer then reallocShared
If
Source Editp
is nil then a new memory block is returned. In either way the block has at leastnewSize
bytes. IfnewSize == 0
andp
is not nilreallocShared
callsdeallocShared(p)
. In other cases the block has to be freed with deallocShared. template newException(exceptn: typedesc; message: string; parentException: ref Exception = nil): untyped
- Creates an exception object of type
exceptn
and sets itsmsg
field tomessage
. Returns the new exception object. Source Edit template likely(val: bool): bool
-
Hints the optimizer that
val
is likely going to be true.You can use this template to decorate a branch condition. On certain platforms this can help the processor predict better which branch is going to be run. Example:
for value in inputValues: if likely(value <= 100): process(value) else: echo "Value too big!"
On backends without branch prediction (JS and the nimscript VM), this template will not affect code execution.
Source Edit template unlikely(val: bool): bool
-
Hints the optimizer that
val
is likely going to be false.You can use this proc to decorate a branch condition. On certain platforms this can help the processor predict better which branch is going to be run. Example:
for value in inputValues: if unlikely(value > 100): echo "Value too big!" else: process(value)
On backends without branch prediction (JS and the nimscript VM), this template will not affect code execution.
Source Edit template formatErrorIndexBound[T](i, a, b: T): string
- Source Edit
template formatErrorIndexBound[T](i, n: T): string
- Source Edit
template `^`(x: int): BackwardsIndex
- Builtin roof operator that can be used for convenient array access.
a[^x]
is a shortcut fora[a.len-x]
.let a = [1, 3, 5, 7, 9] b = "abcdefgh" echo a[^1] # => 9 echo b[^2] # => g
Source Edit template `..^`(a, b: untyped): untyped
- A shortcut for
.. ^
to avoid the common gotcha that a space between '..' and '^' is required. Source Edit template `..<`(a, b: untyped): untyped
- A shortcut for
a .. pred(b)
.for i in 5 ..< 9: echo i # => 5; 6; 7; 8
Source Edit template `[]`(s: string; i: int): char
- Source Edit
template `[]=`(s: string; i: int; val: char)
- Source Edit
template `&=`(x, y: typed)
-
Generic 'sink' operator for Nim.
For files an alias for
Source Editwrite
. If not specialized further, an alias foradd
. template currentSourcePath(): string
-
Returns the full file-system path of the current source.
To get the directory containing the current source, use it with os.parentDir() as
currentSourcePath.parentDir()
.The path returned by this template is set at compile time.
See the docstring of macros.getProjectPath() for an example to see the distinction between the
currentSourcePath
andgetProjectPath
.See also:
Source Edit template rangeCheck(cond)
- Helper for performing user-defined range checks. Such checks will be performed only when the
rangechecks
compile-time option is enabled. Source Edit template closureScope(body: untyped): untyped
-
Useful when creating a closure in a loop to capture local loop variables by their current iteration values.
Note: This template may not work in some cases, use capture instead.
Example:
var myClosure : proc() # without closureScope: for i in 0 .. 5: let j = i if j == 3: myClosure = proc() = echo j myClosure() # outputs 5. `j` is changed after closure creation # with closureScope: for i in 0 .. 5: closureScope: # Everything in this scope is locked after closure creation let j = i if j == 3: myClosure = proc() = echo j myClosure() # outputs 3
Source Edit template once(body: untyped): untyped
- Executes a block of code only once (the first time the block is reached).
proc draw(t: Triangle) = once: graphicsInit() line(t.p1, t.p2) line(t.p2, t.p3) line(t.p3, t.p1)
Source Edit
Exports
- doAssertRaises, raiseAssert, failedAssertImpl, doAssert, assert, onFailedAssert, items, mpairs, items, fieldPairs, items, pairs, fieldPairs, mitems, fields, mpairs, pairs, mitems, items, items, fields, mitems, items, mpairs, mpairs, items, mpairs, pairs, pairs, items, mitems, items, pairs, mitems, $, $, $, $, $, $, $, $, $, $, $, $, $, $, $, $, len, $, newWideCString, Utf16Char, WideCStringObj, $, newWideCString, WideCString, newWideCString, writeFile, write, File, write, writeChars, endOfFile, getFilePos, readChars, readLines, write, readLine, open, reopen, readChar, writeBuffer, stdmsg, getFileHandle, close, write, getOsFileHandle, readFile, setFilePos, write, setStdIoUnbuffered, writeFile, lines, stdout, readLines, getFileSize, FileHandle, write, write, readBytes, writeLine, write, setInheritable, readLine, open, flushFile, readAll, FileMode, write, readBuffer, stderr, stdin, open, writeBytes, lines
© 2006–2021 Andreas Rumpf
Licensed under the MIT License.
https://nim-lang.org/docs/system.html