mirrors/Nim
1
0
Fork 0
mirror of https://github.com/nim-lang/Nim.git synced 2026-01-04 04:02:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

add short overview of the system module (#10883)

Browse Source
This commit is contained in:
Miran
2019-03-23 08:34:59 +01:00
committed by Andreas Rumpf
parent bf592c4e94
commit 714c4f0d67
2 changed files with 223 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
lib/system.nim
View File

@@ -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:

168
lib/system_overview.rst Normal file
View File

@@ -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
============================================= ============================================