array: fix missing documentation warnings

[nit.git] / lib / standard / collection / array.nit

diff --git a/lib/standard/collection/array.nit b/lib/standard/collection/array.nit
index 3b1b3cd..a71b6c8 100644 (file)
--- a/lib/standard/collection/array.nit
+++ b/lib/standard/collection/array.nit
@@ -21,8 +21,7 @@ import abstract_collection
 abstract class AbstractArrayRead[E]
        super SequenceRead[E]
 
-       var _length: Int = 0
-       redef fun length do return _length
+       redef var length = 0
 
        redef fun is_empty do return _length == 0
 
@@ -347,14 +346,14 @@ class Array[E]
        end
 
        # The internal storage.
-       var _items: nullable NativeArray[E] = null
+       private var items: nullable NativeArray[E] = null
 
        # Do not use this method
        # FIXME: Remove it once modules can intrude non local modules
        fun intern_items: NativeArray[E] do return _items.as(not null)
 
        # The size of `_items`.
-       var _capacity: Int = 0
+       private var capacity: Int = 0
 
        redef fun ==(o)
        do
@@ -371,6 +370,50 @@ class Array[E]
                end
                return true
        end
+
+       # Concatenation of arrays.
+       #
+       # Returns a new array built by concatenating `self` and `other` together.
+       #
+       #     var a1 = [1,2,3]
+       #     var a2 = [4,5,6]
+       #     var a3 = a1 + a2
+       #     assert a3 == [1,2,3,4,5,6]
+       #
+       # Because a new array is always created, future modification on `self` and `other`
+       # does not impact the previously computed result.
+       #
+       #     a1.add(30)
+       #     a2.add(60)
+       #     assert a3      == [1,2,3,4,5,6] # unchanged
+       #     assert a1 + a2 == [1,2,3,30,4,5,6,60]
+       fun +(other: Array[E]): Array[E]
+       do
+               var res = new Array[E].with_capacity(length + other.length)
+               res.append(self)
+               res.append(other)
+               return res
+       end
+
+       # Repetition of arrays.
+       #
+       # returns a new array built by concatenating `self` `repeat` times.
+       #
+       #    var a = [1,2,3]
+       #    assert (a * 0).is_empty
+       #    assert a * 1  ==  [1,2,3]
+       #    assert a * 2  ==  [1,2,3,1,2,3]
+       #    assert (a * 10).length  ==  30
+       fun *(repeat: Int): Array[E]
+       do
+               assert repeat >= 0
+               var res = new Array[E].with_capacity(length * repeat)
+               while repeat > 0 do
+                       res.add_all(self)
+                       repeat -= 1
+               end
+               return res
+       end
 end
 
 # An `Iterator` on `AbstractArray`
@@ -385,15 +428,9 @@ private class ArrayIterator[E]
 
        redef fun next do _index += 1
 
-       init(a: AbstractArrayRead[E])
-       do
-               _array = a
-               _index = 0
-       end
+       redef var index = 0
 
-       var _index: Int = 0
-       redef fun index do return _index
-       var _array: AbstractArrayRead[E]
+       var array: AbstractArrayRead[E]
 end
 
 private class ArrayReverseIterator[E]
@@ -403,10 +440,9 @@ private class ArrayReverseIterator[E]
 
        redef fun next do _index -= 1
 
-       init(a: AbstractArrayRead[E])
+       init
        do
-               _array = a
-               _index = a.length - 1
+               _index = _array.length - 1
        end
 end
 
@@ -417,7 +453,7 @@ class ArraySet[E: Object]
        super Set[E]
 
        # The stored elements.
-       var _array: Array[E]
+       private var array: Array[E] is noinit
 
        redef fun has(e) do return _array.has(e)
 
@@ -473,9 +509,7 @@ private class ArraySetIterator[E: Object]
 
        redef fun item: E do return _iter.item
 
-       init(iter: ArrayIterator[E]) do _iter = iter
-
-       var _iter: ArrayIterator[E]
+       var iter: ArrayIterator[E]
 end
 
 
@@ -531,7 +565,7 @@ class ArrayMap[K: Object, E]
        end
 
        # Internal storage.
-       var _items = new Array[Couple[K,E]]
+       private var items = new Array[Couple[K,E]]
 
        # fast remove the ith element of the array
        private fun remove_at_index(i: Int)
@@ -541,7 +575,7 @@ class ArrayMap[K: Object, E]
        end
 
        # The last positive result given by a index(1) call
-       var _last_index: Int = 0
+       private var last_index: Int = 0
 
        # Where is the `key` in `_item`?
        # return -1 if not found
@@ -745,12 +779,20 @@ end
 # Access are unchecked and it has a fixed size
 # Not for public use: may become private.
 universal NativeArray[E]
+       # Creates a new NativeArray of capacity `length`
+       new(length: Int) is intern
        # The length of the array
        fun length: Int is intern
        # Use `self` to initialize a standard Nit Array.
        fun to_a: Array[E] do return new Array[E].with_native(self, length)
+
+       # Get item at `index`.
        fun [](index: Int): E is intern
+
+       # Set `item` at `index`.
        fun []=(index: Int, item: E) is intern
+
+       # Copy `length` items to `dest`.
        fun copy_to(dest: NativeArray[E], length: Int) is intern
        #fun =(o: NativeArray[E]): Bool is intern
        #fun !=(o: NativeArray[E]): Bool is intern