jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

various small documentation improvements (#18602)

Browse source
This commit is contained in:
Miran 2021-07-28 14:31:13 +02:00 • committed by GitHub
commit e616675c41
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
13 changed files with 123 additions and 97 deletions
Download patch file Download diff file Expand all files Collapse all files

11
lib/pure/collections/deques.nim
View file

@ -10,8 +10,9 @@
## An implementation of a `deque`:idx: (double-ended queue). ## An implementation of a `deque`:idx: (double-ended queue).
## The underlying implementation uses a `seq`. ## The underlying implementation uses a `seq`.
## ##
## Note that none of the procs that get an individual value from the deque should be used ## .. note:: None of the procs that get an individual value from the deque should be used
## on an empty deque. ## on an empty deque.
##
## If compiled with the `boundChecks` option, those procs will raise an `IndexDefect` ## If compiled with the `boundChecks` option, those procs will raise an `IndexDefect`
## on such access. This should not be relied upon, as `-d:danger` or `--checks:off` will ## on such access. This should not be relied upon, as `-d:danger` or `--checks:off` will
## disable those checks and then the procs may return garbage or crash the program. ## disable those checks and then the procs may return garbage or crash the program.
@ -198,7 +199,7 @@ iterator items*[T](deq: Deque[T]): lent T =
## Yields every element of `deq`. ## Yields every element of `deq`.
## ##
## **See also:** ## **See also:**
## * `mitems iterator <#mitems,Deque[T]>`_ ## * `mitems iterator <#mitems.i,Deque[T]>`_
runnableExamples: runnableExamples:
from std/sequtils import toSeq from std/sequtils import toSeq
@ -214,7 +215,7 @@ iterator mitems*[T](deq: var Deque[T]): var T =
## Yields every element of `deq`, which can be modified. ## Yields every element of `deq`, which can be modified.
## ##
## **See also:** ## **See also:**
## * `items iterator <#items,Deque[T]>`_ ## * `items iterator <#items.i,Deque[T]>`_
runnableExamples: runnableExamples:
var a = [10, 20, 30, 40, 50].toDeque var a = [10, 20, 30, 40, 50].toDeque
assert $a == "[10, 20, 30, 40, 50]" assert $a == "[10, 20, 30, 40, 50]"
@ -274,7 +275,7 @@ proc addFirst*[T](deq: var Deque[T], item: sink T) =
## Adds an `item` to the beginning of `deq`. ## Adds an `item` to the beginning of `deq`.
## ##
## **See also:** ## **See also:**
## * `addLast proc <#addLast,Deque[T],T>`_ ## * `addLast proc <#addLast,Deque[T],sinkT>`_
runnableExamples: runnableExamples:
var a = initDeque[int]() var a = initDeque[int]()
for i in 1 .. 5: for i in 1 .. 5:
@ -290,7 +291,7 @@ proc addLast*[T](deq: var Deque[T], item: sink T) =
## Adds an `item` to the end of `deq`. ## Adds an `item` to the end of `deq`.
## ##
## **See also:** ## **See also:**
## * `addFirst proc <#addFirst,Deque[T],T>`_ ## * `addFirst proc <#addFirst,Deque[T],sinkT>`_
runnableExamples: runnableExamples:
var a = initDeque[int]() var a = initDeque[int]()
for i in 1 .. 5: for i in 1 .. 5:

2
lib/pure/collections/intsets.nim
View file

@ -8,7 +8,7 @@
# #
## Specialization of the generic `packedsets module <packedsets.html>`_ ## Specialization of the generic `packedsets module <packedsets.html>`_
## for ordinal sparse sets. ## (see its documentation for more examples) for ordinal sparse sets.
import std/private/since import std/private/since
import std/packedsets import std/packedsets

2
lib/pure/collections/sharedlist.nim
View file

@ -35,7 +35,7 @@ template withLock(t, x: untyped) =
release(t.lock) release(t.lock)
proc iterAndMutate*[A](x: var SharedList[A]; action: proc(x: A): bool) = proc iterAndMutate*[A](x: var SharedList[A]; action: proc(x: A): bool) =
## Iterates over the list. If 'action' returns true, the ## Iterates over the list. If `action` returns true, the
## current item is removed from the list. ## current item is removed from the list.
## ##
## .. warning:: It may not preserve the element order after some modifications. ## .. warning:: It may not preserve the element order after some modifications.

20
lib/pure/collections/tables.nim
View file

@ -136,6 +136,8 @@ runnableExamples:
## a more complex object as a key you will be greeted by a strange compiler ## a more complex object as a key you will be greeted by a strange compiler
## error: ## error:
## ##
## .. code::
##
## Error: type mismatch: got (Person) ## Error: type mismatch: got (Person)
## but expected one of: ## but expected one of:
## hashes.hash(x: openArray[A]): Hash ## hashes.hash(x: openArray[A]): Hash
@ -324,7 +326,7 @@ proc `[]`*[A, B](t: Table[A, B], key: A): B =
## a default value (e.g. zero for int) if the key doesn't exist ## a default value (e.g. zero for int) if the key doesn't exist
## * `getOrDefault proc<#getOrDefault,Table[A,B],A,B>`_ to return ## * `getOrDefault proc<#getOrDefault,Table[A,B],A,B>`_ to return
## a custom value if the key doesn't exist ## a custom value if the key doesn't exist
## * `[]= proc<#[]=,Table[A,B],A,B>`_ for inserting a new ## * `[]= proc<#[]=,Table[A,B],A,sinkB>`_ for inserting a new
## (key, value) pair in the table ## (key, value) pair in the table
## * `hasKey proc<#hasKey,Table[A,B],A>`_ for checking if a key is in ## * `hasKey proc<#hasKey,Table[A,B],A>`_ for checking if a key is in
## the table ## the table
@ -345,7 +347,7 @@ proc `[]`*[A, B](t: var Table[A, B], key: A): var B =
## a default value (e.g. zero for int) if the key doesn't exist ## a default value (e.g. zero for int) if the key doesn't exist
## * `getOrDefault proc<#getOrDefault,Table[A,B],A,B>`_ to return ## * `getOrDefault proc<#getOrDefault,Table[A,B],A,B>`_ to return
## a custom value if the key doesn't exist ## a custom value if the key doesn't exist
## * `[]= proc<#[]=,Table[A,B],A,B>`_ for inserting a new ## * `[]= proc<#[]=,Table[A,B],A,sinkB>`_ for inserting a new
## (key, value) pair in the table ## (key, value) pair in the table
## * `hasKey proc<#hasKey,Table[A,B],A>`_ for checking if a key is in ## * `hasKey proc<#hasKey,Table[A,B],A>`_ for checking if a key is in
## the table ## the table
@ -488,7 +490,7 @@ proc add*[A, B](t: var Table[A, B], key: A, val: sink B) {.deprecated:
## ##
## **This can introduce duplicate keys into the table!** ## **This can introduce duplicate keys into the table!**
## ##
## Use `[]= proc<#[]=,Table[A,B],A,B>`_ for inserting a new ## Use `[]= proc<#[]=,Table[A,B],A,sinkB>`_ for inserting a new
## (key, value) pair in the table without introducing duplicates. ## (key, value) pair in the table without introducing duplicates.
addImpl(enlarge) addImpl(enlarge)
@ -499,7 +501,8 @@ template tabCellHash(i) = t.data[i].hcode
proc del*[A, B](t: var Table[A, B], key: A) = proc del*[A, B](t: var Table[A, B], key: A) =
## Deletes `key` from hash table `t`. Does nothing if the key does not exist. ## Deletes `key` from hash table `t`. Does nothing if the key does not exist.
## ##
## .. warning:: If duplicate keys were added, this may need to be called multiple times. ## .. warning:: If duplicate keys were added (via the now deprecated `add` proc),
## this may need to be called multiple times.
## ##
## See also: ## See also:
## * `pop proc<#pop,Table[A,B],A,B>`_ ## * `pop proc<#pop,Table[A,B],A,B>`_
@ -519,7 +522,8 @@ proc pop*[A, B](t: var Table[A, B], key: A, val: var B): bool =
## mapping of the key. Otherwise, returns `false`, and the `val` is ## mapping of the key. Otherwise, returns `false`, and the `val` is
## unchanged. ## unchanged.
## ##
## .. warning:: If duplicate keys were added, this may need to be called multiple times. ## .. warning:: If duplicate keys were added (via the now deprecated `add` proc),
## this may need to be called multiple times.
## ##
## See also: ## See also:
## * `del proc<#del,Table[A,B],A>`_ ## * `del proc<#del,Table[A,B],A>`_
@ -1028,7 +1032,8 @@ proc add*[A, B](t: TableRef[A, B], key: A, val: sink B) {.deprecated:
proc del*[A, B](t: TableRef[A, B], key: A) = proc del*[A, B](t: TableRef[A, B], key: A) =
## Deletes `key` from hash table `t`. Does nothing if the key does not exist. ## Deletes `key` from hash table `t`. Does nothing if the key does not exist.
## ##
## **If duplicate keys were added, this may need to be called multiple times.** ## .. warning:: If duplicate keys were added (via the now deprecated `add` proc),
## this may need to be called multiple times.
## ##
## See also: ## See also:
## * `pop proc<#pop,TableRef[A,B],A,B>`_ ## * `pop proc<#pop,TableRef[A,B],A,B>`_
@ -1048,7 +1053,8 @@ proc pop*[A, B](t: TableRef[A, B], key: A, val: var B): bool =
## mapping of the key. Otherwise, returns `false`, and the `val` is ## mapping of the key. Otherwise, returns `false`, and the `val` is
## unchanged. ## unchanged.
## ##
## **If duplicate keys were added, this may need to be called multiple times.** ## .. warning:: If duplicate keys were added (via the now deprecated `add` proc),
## this may need to be called multiple times.
## ##
## See also: ## See also:
## * `del proc<#del,TableRef[A,B],A>`_ ## * `del proc<#del,TableRef[A,B],A>`_

46
lib/pure/strformat.nim
View file

@ -142,12 +142,12 @@ An expression like `&"{key} is {value:arg} {{z}}"` is transformed into:
temp temp
Parts of the string that are enclosed in the curly braces are interpreted Parts of the string that are enclosed in the curly braces are interpreted
as Nim code, to escape a `{` or `}`, double it. as Nim code. To escape a `{` or `}`, double it.
Within a curly expression,however, '{','}', must be escaped with a backslash. Within a curly expression, however, `{`, `}`, must be escaped with a backslash.
To enable evaluating Nim expressions within curlies, inside parentheses To enable evaluating Nim expressions within curlies, colons inside parentheses
colons do not need to be escaped. do not need to be escaped.
]## ]##
runnableExamples: runnableExamples:
@ -177,28 +177,28 @@ The general form of a standard format specifier is::
The square brackets `[]` indicate an optional element. The square brackets `[]` indicate an optional element.
The optional 'align' flag can be one of the following: The optional `align` flag can be one of the following:
'<' `<`
Forces the field to be left-aligned within the available Forces the field to be left-aligned within the available
space. (This is the default for strings.) space. (This is the default for strings.)
'>' `>`
Forces the field to be right-aligned within the available space. Forces the field to be right-aligned within the available space.
(This is the default for numbers.) (This is the default for numbers.)
'^' `^`
Forces the field to be centered within the available space. Forces the field to be centered within the available space.
Note that unless a minimum field width is defined, the field width Note that unless a minimum field width is defined, the field width
will always be the same size as the data to fill it, so that the alignment will always be the same size as the data to fill it, so that the alignment
option has no meaning in this case. option has no meaning in this case.
The optional 'fill' character defines the character to be used to pad The optional `fill` character defines the character to be used to pad
the field to the minimum width. The fill character, if present, must be the field to the minimum width. The fill character, if present, must be
followed by an alignment flag. followed by an alignment flag.
The 'sign' option is only valid for numeric types, and can be one of the following: The `sign` option is only valid for numeric types, and can be one of the following:
================= ==================================================== ================= ====================================================
Sign Meaning Sign Meaning
@ -211,22 +211,22 @@ The 'sign' option is only valid for numeric types, and can be one of the followi
positive numbers. positive numbers.
================= ==================================================== ================= ====================================================
If the '#' character is present, integers use the 'alternate form' for formatting. If the `#` character is present, integers use the 'alternate form' for formatting.
This means that binary, octal and hexadecimal output will be prefixed This means that binary, octal and hexadecimal output will be prefixed
with '0b', '0o' and '0x', respectively. with `0b`, `0o` and `0x`, respectively.
'width' is a decimal integer defining the minimum field width. If not specified, `width` is a decimal integer defining the minimum field width. If not specified,
then the field width will be determined by the content. then the field width will be determined by the content.
If the width field is preceded by a zero ('0') character, this enables If the width field is preceded by a zero (`0`) character, this enables
zero-padding. zero-padding.
The 'precision' is a decimal number indicating how many digits should be displayed The `precision` is a decimal number indicating how many digits should be displayed
after the decimal point in a floating point conversion. For non-numeric types the after the decimal point in a floating point conversion. For non-numeric types the
field indicates the maximum field size - in other words, how many characters will field indicates the maximum field size - in other words, how many characters will
be used from the field content. The precision is ignored for integer conversions. be used from the field content. The precision is ignored for integer conversions.
Finally, the 'type' determines how the data should be presented. Finally, the `type` determines how the data should be presented.
The available integer presentation types are: The available integer presentation types are:
@ -240,7 +240,7 @@ The available integer presentation types are:
lower-case letters for the digits above 9. lower-case letters for the digits above 9.
`X` Hex format. Outputs the number in base 16, using `X` Hex format. Outputs the number in base 16, using
uppercase letters for the digits above 9. uppercase letters for the digits above 9.
(None) The same as 'd'. (None) The same as `d`.
================= ==================================================== ================= ====================================================
The available floating point presentation types are: The available floating point presentation types are:
@ -249,21 +249,21 @@ The available floating point presentation types are:
Type Result Type Result
================= ==================================================== ================= ====================================================
`e` Exponent notation. Prints the number in scientific `e` Exponent notation. Prints the number in scientific
notation using the letter 'e' to indicate the notation using the letter `e` to indicate the
exponent. exponent.
`E` Exponent notation. Same as 'e' except it converts `E` Exponent notation. Same as `e` except it converts
the number to uppercase. the number to uppercase.
`f` Fixed point. Displays the number as a fixed-point `f` Fixed point. Displays the number as a fixed-point
number. number.
`F` Fixed point. Same as 'f' except it converts the `F` Fixed point. Same as `f` except it converts the
number to uppercase. number to uppercase.
`g` General format. This prints the number as a `g` General format. This prints the number as a
fixed-point number, unless the number is too fixed-point number, unless the number is too
large, in which case it switches to 'e' large, in which case it switches to `e`
exponent notation. exponent notation.
`G` General format. Same as 'g' except it switches to 'E' `G` General format. Same as `g` except it switches to `E`
if the number gets to large. if the number gets to large.
(None) Similar to 'g', except that it prints at least one (None) Similar to `g`, except that it prints at least one
digit after the decimal point. digit after the decimal point.
================= ==================================================== ================= ====================================================

2
lib/pure/strscans.nim
View file

@ -52,7 +52,7 @@ substrings starting with ``$``. These constructions are available:
================= ======================================================== ================= ========================================================
Even though ``$*`` and ``$+`` look similar to the regular expressions ``.*`` Even though ``$*`` and ``$+`` look similar to the regular expressions ``.*``
and ``.+`` they work quite differently, there is no non-deterministic and ``.+``, they work quite differently. There is no non-deterministic
state machine involved and the matches are non-greedy. ``[$*]`` state machine involved and the matches are non-greedy. ``[$*]``
matches ``[xyz]`` via ``parseutils.parseUntil``. matches ``[xyz]`` via ``parseutils.parseUntil``.

31
lib/std/enumutils.nim
View file

@ -79,8 +79,14 @@ macro enumNames(a: typed): untyped =
iterator items*[T: HoleyEnum](E: typedesc[T]): T = iterator items*[T: HoleyEnum](E: typedesc[T]): T =
## Iterates over an enum with holes. ## Iterates over an enum with holes.
runnableExamples: runnableExamples:
type A = enum a0 = 2, a1 = 4, a2 type
type B[T] = enum b0 = 2, b1 = 4 A = enum
a0 = 2
a1 = 4
a2
B[T] = enum
b0 = 2
b1 = 4
from std/sequtils import toSeq from std/sequtils import toSeq
assert A.toSeq == [a0, a1, a2] assert A.toSeq == [a0, a1, a2]
assert B[float].toSeq == [B[float].b0, B[float].b1] assert B[float].toSeq == [B[float].b0, B[float].b1]
@ -130,9 +136,19 @@ template symbolRank*[T: enum](a: T): int =
## for small enums, otherwise is `O(T.enumLen)`. ## for small enums, otherwise is `O(T.enumLen)`.
runnableExamples: runnableExamples:
type type
A = enum a0 = -3, a1 = 10, a2, a3 = (20, "f3Alt") # HoleyEnum A = enum # HoleyEnum
B = enum b0, b1, b2 # OrdinalEnum a0 = -3
C = enum c0 = 10, c1, c2 # OrdinalEnum a1 = 10
a2
a3 = (20, "f3Alt")
B = enum # OrdinalEnum
b0
b1
b2
C = enum # OrdinalEnum
c0 = 10
c1
c2
assert a2.symbolRank == 2 assert a2.symbolRank == 2
assert b2.symbolRank == 2 assert b2.symbolRank == 2
assert c2.symbolRank == 2 assert c2.symbolRank == 2
@ -156,7 +172,10 @@ func symbolName*[T: enum](a: T): string =
assert b.symbolName == "b0" assert b.symbolName == "b0"
assert $b == "kb0" assert $b == "kb0"
static: assert B.high.symbolName == "b2" static: assert B.high.symbolName == "b2"
type C = enum c0 = -3, c1 = 4, c2 = 20 # HoleyEnum type C = enum # HoleyEnum
c0 = -3
c1 = 4
c2 = 20
assert c1.symbolName == "c1" assert c1.symbolName == "c1"
const names = enumNames(T) const names = enumNames(T)
names[a.symbolRank] names[a.symbolRank]

2
lib/std/packedsets.nim
View file

@ -12,7 +12,7 @@
## ##
## Supports any Ordinal type. ## Supports any Ordinal type.
## ##
## **Note**: Currently the assignment operator `=` for `PackedSet[A]` ## .. note:: Currently the assignment operator `=` for `PackedSet[A]`
## performs some rather meaningless shallow copy. Since Nim currently does ## performs some rather meaningless shallow copy. Since Nim currently does
## not allow the assignment operator to be overloaded, use the `assign proc ## not allow the assignment operator to be overloaded, use the `assign proc
## <#assign,PackedSet[A],PackedSet[A]>`_ to get a deep copy. ## <#assign,PackedSet[A],PackedSet[A]>`_ to get a deep copy.

2
lib/system/threads.nim
View file

@ -11,7 +11,7 @@
## ##
## **Note**: This is part of the system module. Do not import it directly. ## **Note**: This is part of the system module. Do not import it directly.
## To activate thread support you need to compile ## To activate thread support you need to compile
## with the `--threads:on` command line switch. ## with the `--threads:on`:option: command line switch.
## ##
## Nim's memory model for threads is quite different from other common ## Nim's memory model for threads is quite different from other common
## programming languages (C, Pascal): Each thread has its own ## programming languages (C, Pascal): Each thread has its own

12
lib/system_overview.rst
View file

@ -48,9 +48,9 @@ Proc Usage
Seqs Seqs
---- ----
============================================== ========================================== ============================================================= ==========================================
Proc Usage Proc Usage
============================================== ========================================== ============================================================= ==========================================
`newSeq<#newSeq>`_ Create a new sequence of a given length `newSeq<#newSeq>`_ Create a new sequence of a given length
`newSeqOfCap<#newSeqOfCap,Natural>`_ Create a new sequence with zero length `newSeqOfCap<#newSeqOfCap,Natural>`_ Create a new sequence with zero length
and a given capacity and a given capacity
@ -64,11 +64,11 @@ Proc Usage
`del<#del,seq[T],Natural>`_ `O(1)` removal, doesn't preserve the order `del<#del,seq[T],Natural>`_ `O(1)` removal, doesn't preserve the order
`pop<#pop,seq[T]>`_ Remove and return last item of a sequence `pop<#pop,seq[T]>`_ Remove and return last item of a sequence
`x & y<#&,seq[T],seq[T]>`_ Concatenate two sequences `x & y<#&,seq[T],seq[T]>`_ Concatenate two sequences
`x[a .. b]<#[],openArray[T],HSlice[U,V]>`_ Slice of a sequence (both ends included) `x[a .. b]<#[],openArray[T],HSlice[U: Ordinal,V: Ordinal]>`_ Slice of a sequence (both ends included)
`x[a .. ^b]<#[],openArray[T],HSlice[U,V]>`_ Slice of a sequence but `b` is a `x[a .. ^b]<#[],openArray[T],HSlice[U: Ordinal,V: Ordinal]>`_ Slice of a sequence but `b` is a
reversed index (both ends included) reversed index (both ends included)
`x[a ..\< b]<#[],openArray[T],HSlice[U,V]>`_ Slice of a sequence (excluded upper bound) `x[a ..< b]<#[],openArray[T],HSlice[U: Ordinal,V: Ordinal]>`_ Slice of a sequence (excluded upper bound)
============================================== ========================================== ============================================================= ==========================================
**See also:** **See also:**
* `sequtils module <sequtils.html>`_ for operations on container * `sequtils module <sequtils.html>`_ for operations on container