system: more runnableExamples + doc improvements (#17075)

lib/system.nim

@@ -695,20 +695,19 @@ when not defined(js):
       var s = cast[PGenericSeq](result)
       s.len = len
 
-proc len*[TOpenArray: openArray|varargs](x: TOpenArray): int {.
+func len*[TOpenArray: openArray|varargs](x: TOpenArray): int {.magic: "LengthOpenArray".} =
-  magic: "LengthOpenArray", noSideEffect.}
   ## Returns the length of an openArray.
-  ##
+  runnableExamples:
-  ## .. code-block:: Nim
+    proc bar[T](a: openArray[T]): int = len(a)
-  ##   var s = [1, 1, 1, 1, 1]
+    assert bar([1,2]) == 2
-  ##   echo len(s) # => 5
+    assert [1,2].len == 2
 
-proc len*(x: string): int {.magic: "LengthStr", noSideEffect.}
+func len*(x: string): int {.magic: "LengthStr".} =
   ## Returns the length of a string.
-  ##
+  runnableExamples:
-  ## .. code-block:: Nim
+    assert "abc".len == 3
-  ##   var str = "Hello world!"
+    assert "".len == 0
-  ##   echo len(str) # => 12
+    assert string.default.len == 0
 
 proc len*(x: cstring): int {.magic: "LengthStr", noSideEffect.} =
   ## Returns the length of a compatible string. This is an O(n) operation except
@@ -729,37 +728,47 @@ proc len*(x: cstring): int {.magic: "LengthStr", noSideEffect.} =
       var a2: cstring = "ab\0c"
       doAssert a2.len == 2 # \0 is a null terminator, even in js vm
 
-proc len*(x: (type array)|array): int {.magic: "LengthArray", noSideEffect.}
+func len*(x: (type array)|array): int {.magic: "LengthArray".} =
   ## Returns the length of an array or an array type.
   ## This is roughly the same as `high(T)-low(T)+1`.
-  ##
+  runnableExamples:
-  ## .. code-block:: Nim
+    var a = [1, 1, 1]
-  ##   var arr = [1, 1, 1, 1, 1]
+    assert a.len == 3
-  ##   echo len(arr) # => 5
+    assert array[0, float].len == 0
-  ##   echo len(array[3..8, int]) # => 6
+    static: assert array[-2..2, float].len == 5
 
-proc len*[T](x: seq[T]): int {.magic: "LengthSeq", noSideEffect.}
+func len*[T](x: seq[T]): int {.magic: "LengthSeq".} =
-  ## Returns the length of a sequence.
+  ## Returns the length of `x`.
-  ##
+  runnableExamples:
-  ## .. code-block:: Nim
+    assert @[0, 1].len == 2
-  ##   var s = @[1, 1, 1, 1, 1]
+    assert seq[int].default.len == 0
-  ##   echo len(s) # => 5
+    assert newSeq[int](3).len == 3
+    let s = newSeqOfCap[int](3)
+    assert s.len == 0
+  # xxx this gives cgen error: assert newSeqOfCap[int](3).len == 0
 
+func ord*[T: Ordinal|enum](x: T): int {.magic: "Ord".} =
+  ## Returns the internal `int` value of `x`, including for enum with holes
+  ## and distinct ordinal types.
+  runnableExamples:
+    assert ord('A') == 65
+    type Foo = enum
+      f0 = 0, f1 = 3
+    assert f1.ord == 3
+    type Bar = distinct int
+    assert 3.Bar.ord == 3
 
-proc ord*[T: Ordinal|enum](x: T): int {.magic: "Ord", noSideEffect.}
+func chr*(u: range[0..255]): char {.magic: "Chr".} =
-  ## Returns the internal `int` value of an ordinal value `x`.
+  ## Converts `u` to a `char`, same as `char(u)`.
-  ##
+  runnableExamples:
-  ## .. code-block:: Nim
+    doAssert chr(65) == 'A'
-  ##   echo ord('A') # => 65
+    doAssert chr(255) == '\255'
-  ##   echo ord('a') # => 97
+    doAssert chr(255) == char(255)
-
+    doAssert not compiles chr(256)
-proc chr*(u: range[0..255]): char {.magic: "Chr", noSideEffect.}
+    doAssert not compiles char(256)
-  ## Converts an `int` in the range `0..255` to a character.
+    var x = 256
-  ##
+    doAssertRaises(RangeDefect): discard chr(x)
-  ## .. code-block:: Nim
+    doAssertRaises(RangeDefect): discard char(x)
-  ##   echo chr(65) # => A
-  ##   echo chr(97) # => a
-
 
 # floating point operations:
 proc `+`*(x: float32): float32 {.magic: "UnaryPlusF64", noSideEffect.}