add short overview of the system module (#10883)

1 files changed, 168 insertions, 0 deletions

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