Added arrays.first() method

CHANGELOG.rst

@@ -10,6 +10,7 @@ Changelog
 - Add ``every()``.
 - Add ``exclude()``.
 - Add ``filter()``.
+- Add ``first()``.
 - Add ``is_array()``.
 - Add ``is_boolean()``.
 - Add ``is_number()``.

README.rst

@@ -96,6 +96,15 @@ Install using pip:
     >>> _.filter([1, 2, 2, 4], callback=lambda x: x > 1)
     [2, 2, 4]
 
+    >>> first([11, 22, 33, 44], 1)
+    [11]
+    >>> first([11, 22, 33, 44], None)
+    []
+    >>> first([11, 22, 33, 44], -3)
+    []
+    >>> first([11, 22, 33, 44], 9)
+    [11, 22, 33, 44]
+
     >>> _.subtract([1, 2, 3], 2)
     [1, 3]
     >>> _.subtract ([1, 2, 3], [1, 3])

sugar/__init__.py

@@ -23,6 +23,7 @@
     every,
     exclude,
     filter,
+    first,
     subtract
 )
 

sugar/arrays.py

@@ -311,6 +311,35 @@ def filter(array, value=None, callback=None):
     return [element for element in array if callback(element) is True]
 
 
+def first(array, num=1):
+    """Returns the first element(s) in the array. When num is passed, returns
+    the first num elements in the array.
+
+    Args:
+        array (list): List of values passed in by the user.
+        num (int): Number passed in by the user.
+
+    Returns:
+        list: Returns an array of first :attr:`num` elements.
+
+    Example:
+
+        >>> first([11, 22, 33, 44], 1)
+        [11]
+        >>> first([11, 22, 33, 44], None)
+        []
+        >>> first([11, 22, 33, 44], -3)
+        []
+        >>> first([11, 22, 33, 44], 9)
+        [11, 22, 33, 44]
+
+    .. versionadded:: TODO
+    """
+    num = 0 if (not num or num < 0) else num
+
+    return array[0:num]
+
+
 def subtract(array, item):
     """Subtracts :attr:`item` from the :attr:`array` and returns the result
     as a new array. If :attr:`item` is also an array, all elements in it will

tests/test_arrays.py

@@ -47,15 +47,13 @@ def test_append(array, item, index, expected):
     ([1, 2, 3], 2)
 ])
 def test_average(array, expected_average):
-    """Tests whether the average method is working properly or not."""
     assert _.average(array) == expected_average
 
 
 @parametrize('array,expected', [
     ([1, 2, 3], [1, 2, 3])
 ])
 def test_clone(array, expected):
-    """Tests whether the clone method is working properly or not."""
     assert _.clone(array) == expected
 
 
@@ -64,7 +62,6 @@ def test_clone(array, expected):
     ([1, None, '', False, 2], True, [1, 2])
 ])
 def test_compact(array, all, expected):
-    """Tests whether the compact method is working properly or not."""
     assert _.compact(array, all) == expected
 
 
@@ -73,7 +70,6 @@ def test_compact(array, all, expected):
     (4, triple, [0, 3, 6, 9])
 ])
 def test_construct(length, callback, expected):
-    """Tests whether the construct method is working properly or not."""
     assert _.construct(length, callback) == expected
 
 
@@ -82,7 +78,6 @@ def test_construct(length, callback, expected):
     ([1, 2, 3, 3, 4], 5, 0)
 ])
 def test_count(array, value, expected):
-    """Tests whether the count method is working properly or not."""
     assert _.count(array, value) == expected
 
 
@@ -104,7 +99,6 @@ def test_create(obj, copy, expected):
     ([2, 3, 4], 2, False)
 ])
 def test_every(array, value, expected):
-    """Tests whether the every method is working properly or not."""
     assert _.every(array, value) == expected
 
 
@@ -114,7 +108,6 @@ def test_every(array, value, expected):
     ([1, 2, 3], 4, [1, 2, 3])
 ])
 def test_exclude(array, item, expected):
-    """Tests whether the exclude method is working properly or not."""
     assert _.exclude(array, item) == expected
 
 
@@ -123,15 +116,23 @@ def test_exclude(array, item, expected):
     ([1, 2, 3, 3, 4], None, lambda x: x > 1, [2, 3, 3, 4])
 ])
 def test_filter(array, value, callback, expected):
-    """Tests whether the filter method is working properly or not."""
     assert _.filter(array, value, callback) == expected
 
 
+@parametrize('array,num,expected', [
+    ([11, 22, 33, 44], 1, [11]),
+    ([11, 22, 33, 44], None, []),
+    ([11, 22, 33, 44], -3, []),
+    ([11, 22, 33, 44], 9, [11, 22, 33, 44])
+])
+def test_first(array, num, expected):
+    assert _.first(array, num) == expected
+
+
 @parametrize('array,item,expected', [
     ([1, 2, 3], 3, [1, 2]),
     ([1, 2, 3], [1, 3], [2]),
     ([1, 2, 3], [4], [1, 2, 3])
 ])
 def test_subtract(array, item, expected):
-    """Tests whether the subtract method is working properly or not."""
     assert _.subtract(array, item) == expected