From af4c0851c1981e00d49742ed40eb32cfcd8f3cb0 Mon Sep 17 00:00:00 2001 From: flaviut Date: Tue, 8 Apr 2014 17:05:32 -0400 Subject: [PATCH 1/7] Inline docs for sequence appending --- lib/system.nim | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/lib/system.nim b/lib/system.nim index 047b998c3a..441f81f6fb 100644 --- a/lib/system.nim +++ b/lib/system.nim @@ -534,6 +534,10 @@ proc `div` *(x, y: int32): int32 {.magic: "DivI", noSideEffect.} proc `div` *(x, y: int64): int64 {.magic: "DivI64", noSideEffect.} ## computes the integer division. This is roughly the same as ## ``floor(x/y)``. + ## .. code-block:: Nimrod + ## 1 div 2 == 0 + ## 2 div 2 == 1 + ## 3 div 2 == 1 proc `mod` *(x, y: int): int {.magic: "ModI", noSideEffect.} proc `mod` *(x, y: int8): int8 {.magic: "ModI", noSideEffect.} @@ -549,6 +553,10 @@ proc `shr` *(x, y: int16): int16 {.magic: "ShrI", noSideEffect.} proc `shr` *(x, y: int32): int32 {.magic: "ShrI", noSideEffect.} proc `shr` *(x, y: int64): int64 {.magic: "ShrI64", noSideEffect.} ## computes the `shift right` operation of `x` and `y`. + ## .. code-block:: Nimrod + ## 0b0001_0000'i8 shr 2 == 0b0100_0000'i8 + ## 0b1000_0000'i8 shr 2 == 0b0000_0000'i8 + ## 0b0000_0001'i8 shr 9 == 0b0000_0000'i8 proc `shl` *(x, y: int): int {.magic: "ShlI", noSideEffect.} proc `shl` *(x, y: int8): int8 {.magic: "ShlI", noSideEffect.} @@ -1535,6 +1543,11 @@ proc `@`*[T](a: openArray[T]): seq[T] = for i in 0..a.len-1: result[i] = a[i] proc `&` *[T](x, y: seq[T]): seq[T] {.noSideEffect.} = + ## Concatinates two sequences. + ## Requires copying of the sequences. + ## + ## .. code-block:: Nimrod + ## assert(@[1, 2, 3, 4] & @[5, 6] == @[1, 2, 3, 4, 5, 6]) newSeq(result, x.len + y.len) for i in 0..x.len-1: result[i] = x[i] @@ -1542,12 +1555,22 @@ proc `&` *[T](x, y: seq[T]): seq[T] {.noSideEffect.} = result[i+x.len] = y[i] proc `&` *[T](x: seq[T], y: T): seq[T] {.noSideEffect.} = + ## Appends element y to the end of the sequence. + ## Requires copying of the sequence + ## + ## .. code-block:: Nimrod + ## assert(@[1, 2, 3] & 4 == @[1, 2, 3, 4]) newSeq(result, x.len + 1) for i in 0..x.len-1: result[i] = x[i] result[x.len] = y proc `&` *[T](x: T, y: seq[T]): seq[T] {.noSideEffect.} = + ## Prepends the element x to the beginning of the sequence. + ## Requires copying of the sequence + ## + ## .. code-block:: Nimrod + ## assert(1 & @[2, 3, 4] == @[1, 2, 3, 4]) newSeq(result, y.len + 1) result[0] = x for i in 0..y.len-1: From fb547ef76b58f16a77c149acb227f746f20edb86 Mon Sep 17 00:00:00 2001 From: flaviut Date: Tue, 8 Apr 2014 17:44:53 -0400 Subject: [PATCH 2/7] Code docs for `contains`, `in`, `is`, and `of` --- lib/system.nim | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/lib/system.nim b/lib/system.nim index 441f81f6fb..8ce1387003 100644 --- a/lib/system.nim +++ b/lib/system.nim @@ -749,15 +749,49 @@ proc contains*[T](x: set[T], y: T): bool {.magic: "InSet", noSideEffect.} ## passes its arguments in reverse order. proc contains*[T](s: TSlice[T], value: T): bool {.noSideEffect, inline.} = + ## Checks if `value` is withing the range of `s`; returns true iff + ## `value >= s.a and value <= s.b` + ## + ## .. code-block:: Nimrod + ## assert((1..3).contains(1) == true) + ## assert((1..3).contains(2) == true) + ## assert((1..3).contains(4) == false) result = s.a <= value and value <= s.b template `in` * (x, y: expr): expr {.immediate.} = contains(y, x) + ## Suger for contains + ## + ## .. code-block:: Nimrod + ## assert(1 in (1..3) == true) + ## assert(5 in (1..3) == false) template `notin` * (x, y: expr): expr {.immediate.} = not contains(y, x) + ## Sugar for not containing + ## + ## .. code-block:: Nimrod + ## assert(1 notin (1..3) == false) + ## assert(5 notin (1..3) == true) proc `is` *[T, S](x: T, y: S): bool {.magic: "Is", noSideEffect.} + ## Checks if T is of the same type as S + ## + ## .. code-block:: Nimrod + ## proc test[T](a: T): int = + ## when (T is int): + ## return a + ## else: + ## return 0 + ## + ## assert(test[int](3) == 3) + ## assert(test[string]("xyz") == 0) template `isnot` *(x, y: expr): expr {.immediate.} = not (x is y) - + ## Negated version of `is`. Equivalent to `not(is(x,y))` proc `of` *[T, S](x: T, y: S): bool {.magic: "Of", noSideEffect.} + ## Checks if `x` has a type of `y` + ## + ## .. code-block:: Nimrod + ## assert(EFloatingPoint is EBase) + ## assert(EIO is ESystem) + ## assert(EDivByZero is EBase) proc cmp*[T](x, y: T): int {.procvar.} = ## Generic compare proc. Returns a value < 0 iff x < y, a value > 0 iff x > y From 6e70d8afb40f25ef12fbb40585d37d27458e3d73 Mon Sep 17 00:00:00 2001 From: flaviut Date: Tue, 8 Apr 2014 17:51:21 -0400 Subject: [PATCH 3/7] Code examples for string concatination --- lib/system.nim | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/lib/system.nim b/lib/system.nim index 8ce1387003..7b6f9716be 100644 --- a/lib/system.nim +++ b/lib/system.nim @@ -842,13 +842,28 @@ proc newStringOfCap*(cap: int): string {. proc `&` * (x: string, y: char): string {. magic: "ConStrStr", noSideEffect, merge.} + ## Concatinates `x` with `y` + ## + ## .. code-block:: Nimrod + ## assert("ab" & 'c' == "abc") proc `&` * (x: char, y: char): string {. magic: "ConStrStr", noSideEffect, merge.} + ## Concatinates `x` and `y` into a string + ## + ## .. code-block:: Nimrod + ## assert('a' & 'b' == "ab") proc `&` * (x, y: string): string {. magic: "ConStrStr", noSideEffect, merge.} + ## Concatinates `x` and `y` + ## + ## .. code-block:: Nimrod + ## assert("ab" & "cd" == "abcd") proc `&` * (x: char, y: string): string {. magic: "ConStrStr", noSideEffect, merge.} - ## is the `concatenation operator`. It concatenates `x` and `y`. + ## Concatinates `x` with `y` + ## + ## .. code-block:: Nimrod + ## assert('a' & "bc" == "abc") # implementation note: These must all have the same magic value "ConStrStr" so # that the merge optimization works properly. From 2a470c4217e0ee7d002afd7910e875e4079edc08 Mon Sep 17 00:00:00 2001 From: flaviut Date: Tue, 8 Apr 2014 17:56:11 -0400 Subject: [PATCH 4/7] Document inplace string appending --- lib/system.nim | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/lib/system.nim b/lib/system.nim index 7b6f9716be..6de9f3a8a5 100644 --- a/lib/system.nim +++ b/lib/system.nim @@ -869,7 +869,21 @@ proc `&` * (x: char, y: string): string {. # that the merge optimization works properly. proc add*(x: var string, y: char) {.magic: "AppendStrCh", noSideEffect.} + ## Appends `y` to `x` in place + ## + ## .. code-block:: Nimrod + ## var tmp = "" + ## tmp.add('a') + ## tmp.add('b') + ## assert(tmp == "ab") proc add*(x: var string, y: string) {.magic: "AppendStrStr", noSideEffect.} + ## Concatinates `x` and `y` in place + ## + ## .. code-block:: Nimrod + ## var tmp = "" + ## tmp.add("ab") + ## tmp.add("cd") + ## assert(tmp == "abcd") type TEndian* = enum ## is a type describing the endianness of a processor. From fde53bffd7ea707f70028ec42aa2d7cd225d4293 Mon Sep 17 00:00:00 2001 From: flaviut Date: Tue, 8 Apr 2014 18:00:44 -0400 Subject: [PATCH 5/7] Code example for `clamp` --- lib/system.nim | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/lib/system.nim b/lib/system.nim index 6de9f3a8a5..f5b1c3fe50 100644 --- a/lib/system.nim +++ b/lib/system.nim @@ -1507,7 +1507,11 @@ proc max*(x, y: float): float {.magic: "MaxF64", noSideEffect.} = {.pop.} proc clamp*[T](x, a, b: T): T = - ## limits the value ``x`` within the interval [a, b] + ## limits the value ``x`` within the interval [a, b] + ## + ## .. code-block:: Nimrod + ## assert((1.4).clamp(0.0, 1.0) == 1.0) + ## assert((0.5).clamp(0.0, 1.0) == 0.5) if x < a: return a if x > b: return b return x From 0dffbd66bb1f58200157c4045f28e78932eed366 Mon Sep 17 00:00:00 2001 From: flaviut Date: Tue, 8 Apr 2014 18:29:02 -0400 Subject: [PATCH 6/7] `Concatenates` was misspelled --- lib/system.nim | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/lib/system.nim b/lib/system.nim index f5b1c3fe50..ddf2cccb99 100644 --- a/lib/system.nim +++ b/lib/system.nim @@ -842,25 +842,25 @@ proc newStringOfCap*(cap: int): string {. proc `&` * (x: string, y: char): string {. magic: "ConStrStr", noSideEffect, merge.} - ## Concatinates `x` with `y` + ## Concatenates `x` with `y` ## ## .. code-block:: Nimrod ## assert("ab" & 'c' == "abc") proc `&` * (x: char, y: char): string {. magic: "ConStrStr", noSideEffect, merge.} - ## Concatinates `x` and `y` into a string + ## Concatenates `x` and `y` into a string ## ## .. code-block:: Nimrod ## assert('a' & 'b' == "ab") proc `&` * (x, y: string): string {. magic: "ConStrStr", noSideEffect, merge.} - ## Concatinates `x` and `y` + ## Concatenates `x` and `y` ## ## .. code-block:: Nimrod ## assert("ab" & "cd" == "abcd") proc `&` * (x: char, y: string): string {. magic: "ConStrStr", noSideEffect, merge.} - ## Concatinates `x` with `y` + ## Concatenates `x` with `y` ## ## .. code-block:: Nimrod ## assert('a' & "bc" == "abc") @@ -877,7 +877,7 @@ proc add*(x: var string, y: char) {.magic: "AppendStrCh", noSideEffect.} ## tmp.add('b') ## assert(tmp == "ab") proc add*(x: var string, y: string) {.magic: "AppendStrStr", noSideEffect.} - ## Concatinates `x` and `y` in place + ## Concatenates `x` and `y` in place ## ## .. code-block:: Nimrod ## var tmp = "" @@ -1610,7 +1610,7 @@ proc `@`*[T](a: openArray[T]): seq[T] = for i in 0..a.len-1: result[i] = a[i] proc `&` *[T](x, y: seq[T]): seq[T] {.noSideEffect.} = - ## Concatinates two sequences. + ## Concatenates two sequences. ## Requires copying of the sequences. ## ## .. code-block:: Nimrod From a157985e01cbf80383d5e50836072d70678c9de3 Mon Sep 17 00:00:00 2001 From: flaviut Date: Tue, 8 Apr 2014 18:36:03 -0400 Subject: [PATCH 7/7] Fix typos in system.nim --- lib/system.nim | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/lib/system.nim b/lib/system.nim index ddf2cccb99..d843bd5dd2 100644 --- a/lib/system.nim +++ b/lib/system.nim @@ -302,7 +302,7 @@ type ## value does not fit. EOutOfRange* = object of ESynch ## is raised if a range check error - ## occured. + ## occurred. EStackOverflow* = object of ESystem ## is raised if the hardware stack ## used for subroutine calls overflowed. @@ -993,9 +993,9 @@ const ## failure. var programResult* {.exportc: "nim_program_result".}: int - ## modify this varialbe to specify the exit code of the program + ## modify this variable to specify the exit code of the program ## under normal circumstances. When the program is terminated - ## prematurelly using ``quit``, this value is ignored. + ## prematurely using ``quit``, this value is ignored. proc quit*(errorcode: int = QuitSuccess) {. magic: "Exit", importc: "exit", header: "", noReturn.} @@ -1352,42 +1352,42 @@ template `>%` *(x, y: expr): expr {.immediate.} = y <% x ## Returns true iff ``unsigned(x) > unsigned(y)``. proc `$` *(x: int): string {.magic: "IntToStr", noSideEffect.} - ## The stingify operator for an integer argument. Returns `x` + ## The stringify operator for an integer argument. Returns `x` ## converted to a decimal string. proc `$` *(x: int64): string {.magic: "Int64ToStr", noSideEffect.} - ## The stingify operator for an integer argument. Returns `x` + ## The stringify operator for an integer argument. Returns `x` ## converted to a decimal string. when not defined(NimrodVM): when not defined(JS) and hostOS != "standalone": proc `$` *(x: uint64): string {.noSideEffect.} - ## The stingify operator for an unsigned integer argument. Returns `x` + ## The stringify operator for an unsigned integer argument. Returns `x` ## converted to a decimal string. proc `$` *(x: float): string {.magic: "FloatToStr", noSideEffect.} - ## The stingify operator for a float argument. Returns `x` + ## The stringify operator for a float argument. Returns `x` ## converted to a decimal string. proc `$` *(x: bool): string {.magic: "BoolToStr", noSideEffect.} - ## The stingify operator for a boolean argument. Returns `x` + ## The stringify operator for a boolean argument. Returns `x` ## converted to the string "false" or "true". proc `$` *(x: char): string {.magic: "CharToStr", noSideEffect.} - ## The stingify operator for a character argument. Returns `x` + ## The stringify operator for a character argument. Returns `x` ## converted to a string. proc `$` *(x: cstring): string {.magic: "CStrToStr", noSideEffect.} - ## The stingify operator for a CString argument. Returns `x` + ## The stringify operator for a CString argument. Returns `x` ## converted to a string. proc `$` *(x: string): string {.magic: "StrToStr", noSideEffect.} - ## The stingify operator for a string argument. Returns `x` + ## The stringify operator for a string argument. Returns `x` ## as it is. This operator is useful for generic code, so ## that ``$expr`` also works if ``expr`` is already a string. proc `$` *[TEnum: enum](x: TEnum): string {.magic: "EnumToStr", noSideEffect.} - ## The stingify operator for an enumeration argument. This works for + ## The stringify operator for an enumeration argument. This works for ## any enumeration type thanks to compiler magic. If ## a ``$`` operator for a concrete enumeration is provided, this is ## used instead. (In other words: *Overwriting* is possible.)