deprecates newSeqUninitialized replaced by unsafeseqs.newSeqUninit

changelog.md

@@ -13,8 +13,11 @@
 
 - Adds `newStringUninit` to system, which creates a new string of length `len` like `newString` but with uninitialized content.
 
+- Adds a module `std/unsafeseqs`, which contains `newSeqUninit` and `newSeqUnsafe` functions that create a new sequence of length `len` like `newSeq` but with uninitialized content.
+
 [//]: # "Deprecations:"
 
+- Deprecates `system.newSeqUninitialized`, which is replaced by `unsafeseqs.newSeqUninit`.
 
 [//]: # "Removals:"
 

lib/std/unsafeseqs.nim

@@ -0,0 +1,63 @@
+#
+#
+#            Nim's Runtime Library
+#        (c) Copyright 2023 Nim contributors
+#
+#    See the file "copying.txt", included in this
+#    distribution, for details about the copyright.
+#
+
+## This module provides some high performance sequence operations.
+
+import typetraits
+
+when not defined(js):
+  template newSeqImpl(T, len) =
+    result = newSeqOfCap[T](len)
+    when defined(nimSeqsV2):
+      cast[ptr int](addr result)[] = len
+    else:
+      var s = cast[PGenericSeq](result)
+      s.len = len
+
+  proc newSeqUnsafe*[T](len: Natural): seq[T] =
+    ## Creates a new sequence of type `seq[T]` with length `len`.
+    ##
+    ## Note that the sequence will be uninitialized.
+    ## After the creation of the sequence you should assign
+    ## entries to the sequence instead of adding them.
+    runnableExamples:
+      # newSeqUnsafe can be safely used for types, which don't contain
+      # managed memory or have destructors
+      var x = newSeqUnsafe[int](3)
+      assert len(x) == 3
+      x[0] = 10
+
+      # be cautious to use it with types with managed memory or destructors
+      # and `{.nodestroy.}` can be handy in these cases
+      proc initStringSeq(x: Natural): seq[string] {.nodestroy.} =
+        result = newSeqUnsafe[string](x)
+        for i in 0..<x: result[i] = "abc"
+
+      let s = initStringSeq(10)
+      assert len(s) == 10
+      assert s[0] == "abc"
+    newSeqImpl(T, len)
+
+  proc newSeqUninit*[T](len: Natural): seq[T] =
+    ## Creates a new sequence of type `seq[T]` with length `len`.
+    ##
+    ## Only available for types, which don't contain
+    ## managed memory or have destructors.
+    ## Note that the sequence will be uninitialized.
+    ## After the creation of the sequence you should assign
+    ## entries to the sequence instead of adding them.
+    runnableExamples:
+      var x = newSeqUninit[int](3)
+      assert len(x) == 3
+      x[0] = 10
+
+    when supportsCopyMem(T):
+      newSeqImpl(T, len)
+    else:
+      {.error: "The type T cannot contain managed memory or have destructors".}

lib/system.nim

@@ -631,7 +631,8 @@ proc newSeq*[T](len = 0.Natural): seq[T] =
   ##
   ## See also:
   ## * `newSeqOfCap <#newSeqOfCap,Natural>`_
-  ## * `newSeqUninitialized <#newSeqUninitialized,Natural>`_
+  ## * `newSeqUninit <unsafeseqs.html#newSeqUninit,Natural>`_
+  ## * `newSeqUnsafe <unsafeseqs.html#newSeqUnsafe,Natural>`_
   newSeq(result, len)
 
 proc newSeqOfCap*[T](cap: Natural): seq[T] {.
@@ -1611,7 +1612,7 @@ when notJSnotNims and defined(nimSeqsV2):
   include "system/seqs_v2"
 
 when not defined(js):
-  proc newSeqUninitialized*[T: SomeNumber](len: Natural): seq[T] =
+  proc newSeqUninitialized*[T: SomeNumber](len: Natural): seq[T] {.deprecated: "Use `unsafeseqs.newSeqUninit` instead".} =
     ## Creates a new sequence of type `seq[T]` with length `len`.
     ##
     ## Only available for numbers types. Note that the sequence will be