Add size(BasicList) to get capacity

Author: d-torrance

M2/Macaulay2/d/actors5.d

@@ -528,6 +528,13 @@ examine(e:Expr):Expr := (
      else WrongArg("(), a function, a symbol, or a basic list"));
 setupfun("examine",examine);
 
+size(e:Expr):Expr := (
+    when e
+    is x:Sequence do toExpr(length(x))
+    is x:List do toExpr(x.capacity)
+    else WrongArg("a list or sequence"));
+setupfun("size0", size);
+
 numparms(e:Expr):Expr := (
      when e
      is fc:FunctionClosure do toExpr(if fc.model.desc.restargs then -1 else fc.model.desc.numparms)

M2/Macaulay2/m2/lists.m2

@@ -11,6 +11,8 @@ needs "methods.m2"
  MutableList.synonym = "mutable list"
 AngleBarList.synonym = "angle bar list"
 
+size BasicList := ZZ => size0
+
 List ? List := (s,t) -> if class s === class t then toSequence s ? toSequence t else (class s) ? (class t)
 Option ? Option := (s,t) -> toSequence s ? toSequence t
 

M2/Macaulay2/packages/Macaulay2Doc/doc_rings.m2

@@ -294,16 +294,36 @@ document {
     SeeAlso => {IndexedVariable}
     }
 
-document {
-     Key => {size, (size, RingElement)},
-     Headline => "the size of an object",
-     TT "size x", " -- returns the size of ", TT "x", " which usually gives
-     a rough indication of memory space required to store the object ", TT "x", ".",
-     PARA{},
-     "For a polynomial, the size is the number of terms.",
-     PARA{},
-     "This function should be replaced by something more generally useful."
-     }
+doc ///
+  Key
+     size
+    (size, RingElement)
+    (size, BasicList)
+  Usage
+    size x
+  Headline
+    the size of an object
+  Description
+    Text
+      @M2CODE "size x"@ returns the size of @VAR "x"@, which usually gives
+      a rough indication of memory space required to store it.
+
+      For a polynomial, the size is the number of terms.
+    Example
+      R = QQ[x,y,z,w]
+      f = z^2 - y*w
+      size f
+    Text
+      For lists, @M2CODE "size"@ reports the capacity of the underlying
+      sequence, which may exceed the number of elements when the list is
+      mutable.  This reflects the amount of memory currently allocated to allow
+      efficient growth without reallocating on every insertion.
+    Example
+      x = new MutableList
+      x#5 = 2;
+      #x
+      size x
+///
 
 document {
     Key => {