diff options
| -rw-r--r-- | lib/system.nim | 79 | ||||
| -rw-r--r-- | lib/system_overview.rst | 168 |
2 files changed, 223 insertions, 24 deletions
diff --git a/lib/system.nim b/lib/system.nim index 88521a026..3641271cf 100644 --- a/lib/system.nim +++ b/lib/system.nim @@ -7,6 +7,7 @@ # distribution, for details about the copyright. # + ## 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. @@ -15,12 +16,11 @@ ## explicitly. Because of this there cannot be a user-defined module named ## ``system``. ## -## Module system +## System module ## ============= ## +## .. include:: ./system_overview.rst -# That lonesome header above is to prevent :idx: entries from being mentioned -# in the global index as part of the previous header (Exception hierarchy). type int* {.magic: Int.} ## Default integer type; bitwidth depends on @@ -904,7 +904,7 @@ proc `<`*[T](x: Ordinal[T]): T {.magic: "UnaryLt", noSideEffect, deprecated.} proc succ*[T: Ordinal](x: T, y = 1): T {.magic: "Succ", noSideEffect.} ## Returns the ``y``-th successor (default: 1) of the value ``x``. - ## ``T`` has to be an ordinal type. + ## ``T`` has to be an `ordinal type <#Ordinal>`_. ## ## If such a value does not exist, ``OverflowError`` is raised ## or a compile time error occurs. @@ -916,7 +916,7 @@ proc succ*[T: Ordinal](x: T, y = 1): T {.magic: "Succ", noSideEffect.} proc pred*[T: Ordinal](x: T, y = 1): T {.magic: "Pred", noSideEffect.} ## Returns the ``y``-th predecessor (default: 1) of the value ``x``. - ## ``T`` has to be an ordinal type. + ## ``T`` has to be an `ordinal type <#Ordinal>`_. ## ## If such a value does not exist, ``OverflowError`` is raised ## or a compile time error occurs. @@ -950,6 +950,7 @@ proc dec*[T: Ordinal|uint|uint64](x: var T, y = 1) {.magic: "Dec", noSideEffect. proc newSeq*[T](s: var seq[T], len: Natural) {.magic: "NewSeq", noSideEffect.} ## Creates a new sequence of type ``seq[T]`` with length ``len``. + ## ## This is equivalent to ``s = @[]; setlen(s, len)``, but more ## efficient since no reallocation is needed. ## @@ -1056,8 +1057,9 @@ proc len*[T](x: seq[T]): int {.magic: "LengthSeq", noSideEffect.} # set routines: proc incl*[T](x: var set[T], y: T) {.magic: "Incl", noSideEffect.} - ## Includes element ``y`` in the set ``x``. This is the same as - ## ``x = x + {y}``, but it might be more efficient. + ## Includes element ``y`` in the set ``x``. + ## + ## This is the same as ``x = x + {y}``, but it might be more efficient. ## ## .. code-block:: Nim ## var a = {1, 3, 5} @@ -1074,8 +1076,9 @@ template incl*[T](x: var set[T], y: set[T]) = x = x + y proc excl*[T](x: var set[T], y: T) {.magic: "Excl", noSideEffect.} - ## Excludes element ``y`` from the set ``x``. This is the same as - ## ``x = x - {y}``, but it might be more efficient. + ## Excludes element ``y`` from the set ``x``. + ## + ## This is the same as ``x = x - {y}``, but it might be more efficient. ## ## .. code-block:: Nim ## var b = {2, 3, 5, 6, 12, 545} @@ -1099,14 +1102,14 @@ proc card*[T](x: set[T]): int {.magic: "Card", noSideEffect.} ## echo card(a) # => 4 proc ord*[T: Ordinal|enum](x: T): int {.magic: "Ord", noSideEffect.} - ## Returns the internal int value of an ordinal value ``x``. + ## Returns the internal `int` value of an ordinal value ``x``. ## ## .. code-block:: Nim ## echo ord('A') # => 65 ## echo ord('a') # => 97 proc chr*(u: range[0..255]): char {.magic: "Chr", noSideEffect.} - ## Converts an int in the range 0..255 to a character. + ## Converts an `int` in the range `0..255` to a character. ## ## .. code-block:: Nim ## echo chr(65) # => A @@ -1230,8 +1233,9 @@ else: proc `*`*(x, y: int64): int64 {.magic: "MulI64", noSideEffect.} proc `div`*(x, y: int): int {.magic: "DivI", noSideEffect.} - ## Computes the integer division. This is roughly the same as - ## ``trunc(x/y)``. + ## Computes the integer division. + ## + ## This is roughly the same as ``trunc(x/y)``. ## ## .. code-block:: Nim ## ( 1 div 2) == 0 @@ -1251,8 +1255,8 @@ else: 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``. + ## + ## This is the same as ``x - (x div y) * y``. ## ## .. code-block:: Nim ## ( 7 mod 5) == 2 @@ -1272,8 +1276,11 @@ when defined(nimNewShiftOps): ## Computes the `shift right` operation of `x` and `y`, filling ## vacant bit positions with zeros. ## + ## **Note**: `Operator precedence <manual.html#syntax-precedence>`_ + ## is different than in *C*. + ## ## See also: - ## * `ashr proc <#ashr,int,SomeInteger>`_ + ## * `ashr proc <#ashr,int,SomeInteger>`_ for arithmetic shift right ## ## .. code-block:: Nim ## 0b0001_0000'i8 shr 2 == 0b0000_0100'i8 @@ -1287,6 +1294,9 @@ when defined(nimNewShiftOps): proc `shl`*(x: int, y: SomeInteger): int {.magic: "ShlI", noSideEffect.} ## Computes the `shift left` operation of `x` and `y`. ## + ## **Note**: `Operator precedence <manual.html#syntax-precedence>`_ + ## is different than in *C*. + ## ## .. code-block:: Nim ## 1'i32 shl 4 == 0x0000_0010 ## 1'i64 shl 4 == 0x0000_0000_0000_0010 @@ -1502,7 +1512,6 @@ proc `+`*(x, y: float): float {.magic: "AddF64", noSideEffect.} proc `-`*(x, y: float): float {.magic: "SubF64", noSideEffect.} proc `*`*(x, y: float): float {.magic: "MulF64", noSideEffect.} proc `/`*(x, y: float): float {.magic: "DivF64", noSideEffect.} - ## Computes the floating point division. proc `==`*(x, y: float32): bool {.magic: "EqF64", noSideEffect.} proc `<=`*(x, y: float32): bool {.magic: "LeF64", noSideEffect.} @@ -1550,7 +1559,8 @@ proc contains*[T](x: set[T], y: T): bool {.magic: "InSet", noSideEffect.} ## ## .. code-block:: Nim ## var s: set[range['a'..'z']] = {'a'..'c'} - ## writeLine(stdout, 'b' in s) + ## assert s.contains('c') + ## assert 'b' in s ## ## If ``in`` had been declared as ``[T](elem: T, s: set[T])`` then ``T`` would ## have been bound to ``char``. But ``s`` is not compatible to type @@ -1742,13 +1752,13 @@ proc `&`*(x: string, y: char): string {. ## assert("ab" & 'c' == "abc") proc `&`*(x, y: char): string {. magic: "ConStrStr", noSideEffect, merge.} - ## Concatenates `x` and `y` into a string. + ## Concatenates characters `x` and `y` into a string. ## ## .. code-block:: Nim ## assert('a' & 'b' == "ab") proc `&`*(x, y: string): string {. magic: "ConStrStr", noSideEffect, merge.} - ## Concatenates `x` and `y`. + ## Concatenates strings `x` and `y`. ## ## .. code-block:: Nim ## assert("ab" & "cd" == "abcd") @@ -2005,7 +2015,8 @@ proc add*[T](x: var seq[T], y: openArray[T]) {.noSideEffect.} = proc del*[T](x: var seq[T], i: Natural) {.noSideEffect.} = ## Deletes the item at index `i` by putting ``x[high(x)]`` into position `i`. - ## This is an O(1) operation. + ## + ## This is an `O(1)` operation. ## ## See also: ## * `delete <#delete,seq[T][T],Natural>`_ for preserving the order @@ -2018,8 +2029,9 @@ proc del*[T](x: var seq[T], i: Natural) {.noSideEffect.} = setLen(x, xl) proc delete*[T](x: var seq[T], i: Natural) {.noSideEffect.} = - ## Deletes the item at index `i` by moving ``x[i+1..]`` by one position. - ## This is an O(n) operation. + ## Deletes the item at index `i` by moving all ``x[i+1..]`` items by one position. + ## + ## This is an `O(n)` operation. ## ## See also: ## * `del <#delete,seq[T][T],Natural>`_ for O(1) operation @@ -2971,6 +2983,15 @@ proc find*[T, S](a: T, item: S): int {.inline.}= proc contains*[T](a: openArray[T], item: T): bool {.inline.}= ## Returns true if `item` is in `a` or false if not found. This is a shortcut ## for ``find(a, item) >= 0``. + ## + ## This allows the `in` operator: `a.contains(item)` is the same as + ## `item in a`. + ## + ## .. code-block:: Nim + ## var a = @[1, 3, 5] + ## assert a.contains(5) + ## assert 3 in a + ## assert 99 notin a return find(a, item) >= 0 proc pop*[T](s: var seq[T]): T {.inline, noSideEffect.} = @@ -2980,6 +3001,7 @@ proc pop*[T](s: var seq[T]): T {.inline, noSideEffect.} = var a = @[1, 3, 5, 7] let b = pop(a) assert b == 7 + assert a == @[1, 3, 5] var L = s.len-1 result = s[L] @@ -3704,7 +3726,11 @@ proc quit*(errormsg: string, errorcode = QuitFailure) {.noReturn.} = {.pop.} # hints proc `/`*(x, y: int): float {.inline, noSideEffect.} = - ## Integer division that results in a float. + ## Division of intergers that results in a float. + ## + ## See also: + ## * `div <#div,int,int>`_ + ## * `mod <#mod,int,int>`_ ## ## .. code-block:: Nim ## echo 7 / 5 # => 1.4 @@ -3806,6 +3832,11 @@ proc `[]`*[Idx, T, U, V](a: array[Idx, T], x: HSlice[U, V]): seq[T] = proc `[]=`*[Idx, T, U, V](a: var array[Idx, T], x: HSlice[U, V], b: openArray[T]) = ## Slice assignment for arrays. + ## + ## .. code-block:: Nim + ## var a = [10, 20, 30, 40, 50] + ## a[1..2] = @[99, 88] + ## assert a == [10, 99, 88, 40, 50] let xa = a ^^ x.a let L = (a ^^ x.b) - xa + 1 if L == b.len: diff --git a/lib/system_overview.rst b/lib/system_overview.rst new file mode 100644 index 000000000..e7622339f --- /dev/null +++ b/lib/system_overview.rst @@ -0,0 +1,168 @@ +System module imports several separate modules, and their documentation +is in separate files: +* `iterators <iterators.html>`_ +* `assertions <assertions.html>`_ +* `dollars <dollars.html>`_ +* `io <io.html>`_ +* `widestr <widestr.html>`_ + + +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)<#len,string>`_ Return the length of a string +`chr(i)<#chr,range[]>`_ Convert an `int` in the range `0..255` + to a character +`ord(c)<#ord,T>`_ Return `int` value of a character +`a & b<#&,string,string>`_ Concatenate two strings +`s.add(c)<#add,string,char>`_ Add character to the string +`$<dollars.html>`_ Convert various types to string +============================= ======================================= + +**See also:** +* `strutils module<strutils.html>`_ for common string functions +* `strformat module<strformat.html>`_ for string interpolation and formatting +* `unicode module<unicode.html>`_ for Unicode UTF-8 handling +* `strscans<strscans.html>`_ for ``scanf`` and ``scanp`` macros, which offer + easier substring extraction than regular expressions +* `strtabs module<strtabs.html>`_ for efficient hash tables + (dictionaries, in some programming languages) mapping from strings to strings +* `ropes module<ropes.html>`_ for rope data type, which can represent very + long strings efficiently + + + +Seqs +---- + +======================================== ========================================== +Proc Usage +======================================== ========================================== +`newSeq<#newSeq>`_ Create a new sequence of a given length +`newSeqOfCap<#newSeqOfCap,Natural>`_ Create a new sequence with zero length + and a given capacity +`setLen<#setLen,seq[T][T],Natural>`_ Set the length of a sequence +`len<#len,seq[T][T]>`_ Return the length of a sequence +`@<#@,array[IDX,T]>`_ Turn an array into a sequence +`add<#add,seq[T][T],T>`_ Add an item to the sequence +`insert<#insert,seq[T][T],T>`_ Insert an item at a specific position +`delete<#delete,seq[T][T],Natural>`_ Delete an item while preserving the + order of elements (`O(n)` operation) +`del<#del,seq[T][T],Natural>`_ `O(1)` removal, doesn't preserve the order +`pop<#pop,seq[T][T]>`_ Remove and return last item of a sequence +`x & y<#&,seq[T][T],seq[T][T]>`_ Concatenate two sequences +`x[a..b]<#[],openArray[T],HSlice[U,V]>`_ Slice of a seqence (both ends included) +======================================== ========================================== + +**See also:** +* `sequtils module<collections/sequtils.html>`_ for operations on container + types (including strings) +* `json module<json.html>`_ for a structure which allows heterogeneous members +* `lists module<lists.html>`_ for linked lists + + + +Sets +---- + +Built-in bit sets. + +=============================== ====================================== +Proc Usage +=============================== ====================================== +`incl<#incl,set[T],T>`_ Include element `y` in the set `x` +`excl<#excl,set[T],T>`_ Exclude element `y` from the set `x` +`card<#card,set[T]>`_ Return the cardinality of the set, + i.e. the number of elements +`a * b<#*,set[T],set[T]>`_ Intersection +`a + b<#+,set[T],set[T]>`_ Union +`a - b<#-,set[T],set[T]>`_ Difference +`contains<#contains,set[T],T>`_ Check if an element is in the set +[a < b](#<,set[T],set[T]) Check if `a` is a subset of `b` +=============================== ====================================== + +**See also:** +* `sets module <sets.html>`_ for hash sets +* `intsets module <intsets.html>`_ for efficient int sets + + + +Numbers +------- + +============================== ================================== ===================== +Proc Usage Also known as + (in other languages) +============================== ================================== ===================== +`div<#div,int,int>`_ Integer division `//` +`mod<#mod,int,int>`_ Integer modulo (remainder) `%` +`shl<#shl,int,SomeInteger>`_ Shift left `<<` +`shr<#shr,int,SomeInteger>`_ Shift right `>>` +`ashr<#ashr,int,SomeInteger>`_ Arithmetic shift right +`and<#and,int,int>`_ Bitwise `and` `&` +`or<#or,int,int>`_ Bitwise `or` `|` +`xor<#xor,int,int>`_ Bitwise `xor` `^` +`not<#not,int>`_ Bitwise `not` (complement) `~` +`toInt<#toInt,float>`_ Convert floating-point number + into an `int` +`toFloat<#toFloat,int>`_ Convert an integer into a `float` +============================== ================================== ===================== + +**See also:** +* `math module<math.html>`_ for mathematical operations like trigonometric + functions, logarithms, square and cubic roots, etc. +* `complex module<complex.html>`_ for operations on complex numbers +* `rationals module<rationals.html>`_ for rational numbers + + + +Ordinals +-------- + +`Ordinal type <#Ordinal>`_ includes integer, bool, character, and enumeration +types, as well as their subtypes. + +===================== ======================================= +Proc Usage +===================== ======================================= +`succ<#succ,T,int>`_ Successor of the value +`pred<#pred,T,int>`_ Predecessor of the value +`inc<#inc,T,int>`_ Increment the ordinal +`dec<#dec,T,int>`_ Decrement the ordinal +`high<#high,T>`_ Return the highest possible value +`low<#low,T>`_ Return the lowest possible value +`ord<#ord,T>`_ Return `int` value of an ordinal value +===================== ======================================= + + + +Misc +---- + +============================================= ============================================ +Proc Usage +============================================= ============================================ +`is<#is,T,S>`_ Check if two arguments are of the same type +`isnot<#isnot.t,untyped,untyped>`_ Negated version of `is` +`!=<#!%3D.t,untyped,untyped>`_ Not equals +`addr<#addr,T>`_ Take the address of a memory location +`T and F<#and,bool,bool>`_ Boolean `and` +`T or F<#or,bool,bool>`_ Boolean `or` +`T xor F<#xor,bool,bool>`_ Boolean `xor` (exclusive or) +`not T<#not,bool>`_ Boolean `not` +`a .. b<#..,T,U>`_ Binary slice that constructs an interval + `[a, b]` +[a ..< b](#..<.t,untyped,untyped) Interval `[a, b>` (excluded upper bound) +[runnableExamples](#runnableExamples,untyped) Create testable documentation +============================================= ============================================ |