From c04ae96e11de4f54e054498c7e44c2fc93c0a99e Mon Sep 17 00:00:00 2001 From: Jakob Oesterling Date: Fri, 25 Sep 2015 18:08:10 +0200 Subject: [PATCH 1/3] added examples in documenation for sizeof high low --- lib/system.nim | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/lib/system.nim b/lib/system.nim index 4d397a5fc5..ca5e180907 100644 --- a/lib/system.nim +++ b/lib/system.nim @@ -221,11 +221,21 @@ proc high*[T](x: T): T {.magic: "High", noSideEffect.} ## the highest possible value of an ordinal value `x`. As a special ## semantic rule, `x` may also be a type identifier. ## ``high(int)`` is Nim's way of writing `INT_MAX`:idx: or `MAX_INT`:idx:. + ## + ## .. code-block:: nim + ## var arr = [1,2,3,4,5,6,7] + ## high(arr) #=> 6 + ## high(2) #=> 9223372036854775807 proc low*[T](x: T): T {.magic: "Low", noSideEffect.} ## returns the lowest possible index of an array, a sequence, a string or ## the lowest possible value of an ordinal value `x`. As a special ## semantic rule, `x` may also be a type identifier. + ## + ## .. code-block:: nim + ## var arr = [1,2,3,4,5,6,7] + ## high(arr) #=> 0 + ## high(2) #=> -9223372036854775808 type range*{.magic: "Range".}[T] ## Generic type to construct range types. @@ -584,6 +594,10 @@ proc sizeof*[T](x: T): int {.magic: "SizeOf", noSideEffect.} ## its usage is discouraged - using ``new`` for the most cases suffices ## that one never needs to know ``x``'s size. As a special semantic rule, ## ``x`` may also be a type identifier (``sizeof(int)`` is valid). + ## + ## .. code-block:: nim + ## sizeof('A') #=> 1 + ## sizeof(2) #=> 8 when defined(nimtypedescfixed): proc sizeof*(x: typedesc): int {.magic: "SizeOf", noSideEffect.} @@ -703,12 +717,22 @@ template excl*[T](s: var set[T], flags: set[T]) = proc card*[T](x: set[T]): int {.magic: "Card", noSideEffect.} ## returns the cardinality of the set ``x``, i.e. the number of elements ## in the set. + ## + ## .. code-block:: nim + ## var i = {1,2,3,4} + ## card(i) #=> 4 proc ord*[T](x: T): int {.magic: "Ord", noSideEffect.} ## returns the internal int value of an ordinal value ``x``. + ## + ## .. code-block:: nim + ## card('A') #=> 65 proc chr*(u: range[0..255]): char {.magic: "Chr", noSideEffect.} ## converts an int in the range 0..255 to a character. + ## + ## .. code-block:: nim + ## chr(65) #=> A # -------------------------------------------------------------------------- # built-in operators From e429810220ad61e1d79a0d550f7b479ff8afe991 Mon Sep 17 00:00:00 2001 From: Jakob Oesterling Date: Fri, 25 Sep 2015 18:38:32 +0200 Subject: [PATCH 2/3] added examples in documenation for add del delete repr insert --- lib/system.nim | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/lib/system.nim b/lib/system.nim index ca5e180907..d37a8460e3 100644 --- a/lib/system.nim +++ b/lib/system.nim @@ -1337,6 +1337,10 @@ proc add *[T](x: var seq[T], y: openArray[T]) {.noSideEffect.} = ## containers should also call their adding proc `add` for consistency. ## Generic code becomes much easier to write if the Nim naming scheme is ## respected. + ## + ## .. code-block:: nim + ## var s: seq[string] = @["test2","test2"] + ## s.add("test") #=> @[test2, test2, test] let xl = x.len setLen(x, xl + y.len) for i in 0..high(y): x[xl+i] = y[i] @@ -1351,6 +1355,10 @@ proc shallowCopy*[T](x: var T, y: T) {.noSideEffect, magic: "ShallowCopy".} 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. + ## + ## .. code-block:: nim + ## var i = @[1,2,3,4,5] + ## i.del(2) #=> @[1, 2, 5, 4] let xl = x.len - 1 shallowCopy(x[i], x[xl]) setLen(x, xl) @@ -1358,6 +1366,10 @@ proc del*[T](x: var seq[T], i: Natural) {.noSideEffect.} = 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. + ## + ## .. code-block:: nim + ## var i = @[1,2,3,4,5] + ## i.del(2) #=> @[1, 2, 4, 5] template defaultImpl = let xl = x.len for j in i..xl-2: shallowCopy(x[j], x[j+1]) @@ -1373,6 +1385,10 @@ proc delete*[T](x: var seq[T], i: Natural) {.noSideEffect.} = proc insert*[T](x: var seq[T], item: T, i = 0.Natural) {.noSideEffect.} = ## inserts `item` into `x` at position `i`. + ## + ## .. code-block:: nim + ## var i = @[1,2,3,4,5] + ## i.insert(2,4) #=> @[1, 2, 3, 4, 2, 5] template defaultImpl = let xl = x.len setLen(x, xl+1) @@ -1393,6 +1409,12 @@ proc repr*[T](x: T): string {.magic: "Repr", noSideEffect.} ## takes any Nim variable and returns its string representation. It ## works even for complex data graphs with cycles. This is a great ## debugging tool. + ## + ## .. code-block:: nim + ## var s: seq[string] = @["test2","test2"] + ## var i = @[1,2,3,4,5] + ## repr(s) #=> 0x1055eb050[0x1055ec050"test2", 0x1055ec078"test2"] + ## repr(i) #=> 0x1055ed050[1, 2, 3, 4, 5] type ByteAddress* = int From ca9845dcc01c934256c8d679eb5c533bc7c9f098 Mon Sep 17 00:00:00 2001 From: Jakob Oesterling Date: Sat, 26 Sep 2015 01:08:49 +0200 Subject: [PATCH 3/3] fixed wrong examples --- lib/system.nim | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/system.nim b/lib/system.nim index 784e072a89..59d0d04b78 100644 --- a/lib/system.nim +++ b/lib/system.nim @@ -728,7 +728,7 @@ proc ord*[T](x: T): int {.magic: "Ord", noSideEffect.} ## returns the internal int value of an ordinal value ``x``. ## ## .. code-block:: nim - ## card('A') #=> 65 + ## ord('A') #=> 65 proc chr*(u: range[0..255]): char {.magic: "Chr", noSideEffect.} ## converts an int in the range 0..255 to a character. @@ -1371,7 +1371,7 @@ proc delete*[T](x: var seq[T], i: Natural) {.noSideEffect.} = ## ## .. code-block:: nim ## var i = @[1,2,3,4,5] - ## i.del(2) #=> @[1, 2, 4, 5] + ## i.delete(2) #=> @[1, 2, 4, 5] template defaultImpl = let xl = x.len for j in i..xl-2: shallowCopy(x[j], x[j+1])