mirrors/Nim
1
0
Fork 0
mirror of https://github.com/nim-lang/Nim.git synced 2026-07-19 15:31:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

system: some documentation improvements (#10809)

Browse Source
This commit is contained in:
Miran
2019-03-11 11:04:08 +01:00
committed by GitHub
parent 44d47134f9
commit 06f23572d0
5 changed files with 1412 additions and 820 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2140
lib/system.nim
View File

File diff suppressed because it is too large Load Diff

2
lib/system/assertions.nim
View File

@@ -38,7 +38,7 @@ template assert*(cond: untyped, msg = "") =
assertImpl(cond, msg, expr, compileOption("assertions"))
template doAssert*(cond: untyped, msg = "") =
## same as ``assert`` but is always turned on regardless of ``--assertions``
## Similar to ``assert`` but is always turned on regardless of ``--assertions``.
const expr = astToStr(cond)
assertImpl(cond, msg, expr, true)

5
lib/system/excpt.nim
View File

@@ -14,7 +14,7 @@ var
errorMessageWriter*: (proc(msg: string) {.tags: [WriteIOEffect], benign,
nimcall.})
## Function that will be called
## instead of stdmsg.write when printing stacktrace.
## instead of `stdmsg.write` when printing stacktrace.
## Unstable API.
proc c_fwrite(buf: pointer, size, n: csize, f: CFilePtr): cint {.
@@ -331,8 +331,9 @@ else:
proc stackTraceAvailable*(): bool = result = false
var onUnhandledException*: (proc (errorMsg: string) {.
nimcall.}) ## set this error \
nimcall.}) ## Set this error \
## handler to override the existing behaviour on an unhandled exception.
##
## The default is to write a stacktrace to ``stderr`` and then call ``quit(1)``.
## Unstable API.

71
lib/system/iterators.nim
View File

@@ -1,19 +1,19 @@
iterator items*[T](a: openArray[T]): T {.inline.} =
## iterates over each item of `a`.
## Iterates over each item of `a`.
var i = 0
while i < len(a):
yield a[i]
inc(i)
iterator mitems*[T](a: var openArray[T]): var T {.inline.} =
## iterates over each item of `a` so that you can modify the yielded value.
## Iterates over each item of `a` so that you can modify the yielded value.
var i = 0
while i < len(a):
yield a[i]
inc(i)
iterator items*[IX, T](a: array[IX, T]): T {.inline.} =
## iterates over each item of `a`.
## Iterates over each item of `a`.
var i = low(IX)
if i <= high(IX):
while true:
@@ -22,7 +22,7 @@ iterator items*[IX, T](a: array[IX, T]): T {.inline.} =
inc(i)
iterator mitems*[IX, T](a: var array[IX, T]): var T {.inline.} =
## iterates over each item of `a` so that you can modify the yielded value.
## Iterates over each item of `a` so that you can modify the yielded value.
var i = low(IX)
if i <= high(IX):
while true:
@@ -31,7 +31,7 @@ iterator mitems*[IX, T](a: var array[IX, T]): var T {.inline.} =
inc(i)
iterator items*[T](a: set[T]): T {.inline.} =
## iterates over each element of `a`. `items` iterates only over the
## Iterates over each element of `a`. `items` iterates only over the
## elements that are really in the set (and not over the ones the set is
## able to hold).
var i = low(T).int
@@ -40,7 +40,7 @@ iterator items*[T](a: set[T]): T {.inline.} =
inc(i)
iterator items*(a: cstring): char {.inline.} =
## iterates over each item of `a`.
## Iterates over each item of `a`.
when defined(js):
var i = 0
var L = len(a)
@@ -54,32 +54,32 @@ iterator items*(a: cstring): char {.inline.} =
inc(i)
iterator mitems*(a: var cstring): var char {.inline.} =
## iterates over each item of `a` so that you can modify the yielded value.
## Iterates over each item of `a` so that you can modify the yielded value.
var i = 0
while a[i] != '\0':
yield a[i]
inc(i)
iterator items*(E: typedesc[enum]): E =
## iterates over the values of the enum ``E``.
## Iterates over the values of the enum ``E``.
for v in low(E)..high(E):
yield v
iterator items*[T](s: HSlice[T, T]): T =
## iterates over the slice `s`, yielding each value between `s.a` and `s.b`
## Iterates over the slice `s`, yielding each value between `s.a` and `s.b`
## (inclusively).
for x in s.a..s.b:
yield x
iterator pairs*[T](a: openArray[T]): tuple[key: int, val: T] {.inline.} =
## iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
var i = 0
while i < len(a):
yield (i, a[i])
inc(i)
iterator mpairs*[T](a: var openArray[T]): tuple[key:int, val:var T]{.inline.} =
## iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
## ``a[index]`` can be modified.
var i = 0
while i < len(a):
@@ -87,7 +87,7 @@ iterator mpairs*[T](a: var openArray[T]): tuple[key:int, val:var T]{.inline.} =
inc(i)
iterator pairs*[IX, T](a: array[IX, T]): tuple[key: IX, val: T] {.inline.} =
## iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
var i = low(IX)
if i <= high(IX):
while true:
@@ -96,7 +96,7 @@ iterator pairs*[IX, T](a: array[IX, T]): tuple[key: IX, val: T] {.inline.} =
inc(i)
iterator mpairs*[IX, T](a:var array[IX, T]):tuple[key:IX,val:var T] {.inline.} =
## iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
## ``a[index]`` can be modified.
var i = low(IX)
if i <= high(IX):
@@ -106,14 +106,14 @@ iterator mpairs*[IX, T](a:var array[IX, T]):tuple[key:IX,val:var T] {.inline.} =
inc(i)
iterator pairs*[T](a: seq[T]): tuple[key: int, val: T] {.inline.} =
## iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
var i = 0
while i < len(a):
yield (i, a[i])
inc(i)
iterator mpairs*[T](a: var seq[T]): tuple[key: int, val: var T] {.inline.} =
## iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
## ``a[index]`` can be modified.
var i = 0
while i < len(a):
@@ -121,14 +121,14 @@ iterator mpairs*[T](a: var seq[T]): tuple[key: int, val: var T] {.inline.} =
inc(i)
iterator pairs*(a: string): tuple[key: int, val: char] {.inline.} =
## iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
var i = 0
while i < len(a):
yield (i, a[i])
inc(i)
iterator mpairs*(a: var string): tuple[key: int, val: var char] {.inline.} =
## iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
## ``a[index]`` can be modified.
var i = 0
while i < len(a):
@@ -136,22 +136,23 @@ iterator mpairs*(a: var string): tuple[key: int, val: var char] {.inline.} =
inc(i)
iterator pairs*(a: cstring): tuple[key: int, val: char] {.inline.} =
## iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
var i = 0
while a[i] != '\0':
yield (i, a[i])
inc(i)
iterator mpairs*(a: var cstring): tuple[key: int, val: var char] {.inline.} =
## iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
## ``a[index]`` can be modified.
var i = 0
while a[i] != '\0':
yield (i, a[i])
inc(i)
iterator items*[T](a: seq[T]): T {.inline.} =
## iterates over each item of `a`.
## Iterates over each item of `a`.
var i = 0
let L = len(a)
while i < L:
@@ -160,7 +161,7 @@ iterator items*[T](a: seq[T]): T {.inline.} =
assert(len(a) == L, "seq modified while iterating over it")
iterator mitems*[T](a: var seq[T]): var T {.inline.} =
## iterates over each item of `a` so that you can modify the yielded value.
## Iterates over each item of `a` so that you can modify the yielded value.
var i = 0
let L = len(a)
while i < L:
@@ -169,7 +170,7 @@ iterator mitems*[T](a: var seq[T]): var T {.inline.} =
assert(len(a) == L, "seq modified while iterating over it")
iterator items*(a: string): char {.inline.} =
## iterates over each item of `a`.
## Iterates over each item of `a`.
var i = 0
let L = len(a)
while i < L:
@@ -178,7 +179,7 @@ iterator items*(a: string): char {.inline.} =
assert(len(a) == L, "string modified while iterating over it")
iterator mitems*(a: var string): var char {.inline.} =
## iterates over each item of `a` so that you can modify the yielded value.
## Iterates over each item of `a` so that you can modify the yielded value.
var i = 0
let L = len(a)
while i < L:
@@ -186,19 +187,21 @@ iterator mitems*(a: var string): var char {.inline.} =
inc(i)
assert(len(a) == L, "string modified while iterating over it")
iterator fields*[T: tuple|object](x: T): RootObj {.
magic: "Fields", noSideEffect.}
## iterates over every field of `x`. Warning: This really transforms
## the 'for' and unrolls the loop. The current implementation also has a bug
## Iterates over every field of `x`.
##
## **Warning**: This really transforms the 'for' and unrolls the loop.
## The current implementation also has a bug
## that affects symbol binding in the loop body.
iterator fields*[S:tuple|object, T:tuple|object](x: S, y: T): tuple[a,b: untyped] {.
magic: "Fields", noSideEffect.}
## iterates over every field of `x` and `y`.
## Warning: This is really transforms the 'for' and unrolls the loop.
## Iterates over every field of `x` and `y`.
##
## **Warning**: This is really transforms the 'for' and unrolls the loop.
## The current implementation also has a bug that affects symbol binding
## in the loop body.
iterator fieldPairs*[T: tuple|object](x: T): RootObj {.
magic: "FieldPairs", noSideEffect.}
## Iterates over every field of `x` returning their name and value.
@@ -209,7 +212,6 @@ iterator fieldPairs*[T: tuple|object](x: T): RootObj {.
## operator <manual.html#generics-is-operator>`_. Example:
##
## .. code-block:: Nim
##
## type
## Custom = object
## foo: string
@@ -230,14 +232,17 @@ iterator fieldPairs*[T: tuple|object](x: T): RootObj {.
## picking the appropriate code to a secondary proc which you overload for
## each field type and pass the `value` to.
##
## Warning: This really transforms the 'for' and unrolls the loop. The
## **Warning**: This really transforms the 'for' and unrolls the loop. The
## current implementation also has a bug that affects symbol binding in the
## loop body.
iterator fieldPairs*[S: tuple|object, T: tuple|object](x: S, y: T): tuple[
a, b: untyped] {.
magic: "FieldPairs", noSideEffect.}
## iterates over every field of `x` and `y`.
## Warning: This really transforms the 'for' and unrolls the loop.
## Iterates over every field of `x` and `y`.
##
## **Warning**: This really transforms the 'for' and unrolls the loop.
## The current implementation also has a bug that affects symbol binding
## in the loop body.

14
lib/system/strmantle.nim
View File

@@ -41,6 +41,13 @@ proc hashString(s: string): int {.compilerproc.} =
result = h
proc add*(result: var string; x: int64) =
## Converts integer to its string representation and appends it to `result`.
##
## .. code-block:: Nim
## var
## a = "123"
## b = 45
## a.add(b) # a <- "12345"
let base = result.len
setLen(result, base + sizeof(x)*4)
var i = 0
@@ -64,6 +71,13 @@ proc nimIntToStr(x: int): string {.compilerRtl.} =
result.add x
proc add*(result: var string; x: float) =
## Converts float to its string representation and appends it to `result`.
##
## .. code-block:: Nim
## var
## a = "123"
## b = 45.67
## a.add(b) # a <- "12345.67"
when nimvm:
result.add $x
else: