Added filter() method

CHANGELOG.rst

@@ -6,6 +6,7 @@ Changelog
 - Add ``compact()``.
 - Add ``every()``.
 - Add ``exclude()``.
+- Add ``filter()``.
 
 
 v0.1.1 (2016-10-10)

README.rst

@@ -62,6 +62,11 @@ Install using pip:
     >>> sugar.exclude([11, 22, 33], [11, 22])
     [33]
 
+    >>> sugar.filter([1, 2, 2, 4], value=2)
+    [2, 2]
+    >>> sugar.filter([1, 2, 2, 4], callback=lambda x: x > 1)
+    [2, 2, 4]
+
     >>> sugar.subtract([1, 2, 3], 2)
     [1, 3]
     >>> sugar.subtract ([1, 2, 3], [1, 3])

sugar/__init__.py

@@ -19,5 +19,6 @@
     count,
     every,
     exclude,
+    filter,
     subtract
 )

sugar/arrays.py

@@ -163,6 +163,35 @@ def exclude(array, value):
     return subtract(array, value)
 
 
+def filter(array, value=None, callback=None):
+    """Returns list of elements in the :attr:`array` that match :attr:`value`.
+    Also, returns list of elements based on the given callback method.
+
+    Args:
+        array (list): List of values provided by the user.
+        value (int/float/str): A value that needs to be matched with.
+        callback: A method that takes the value, filters the variable based
+            on the given condition and returns the filtered value.
+
+    Returns:
+        list: List of values that match with the :attr:`value` or the given
+            filter.
+
+    Example:
+
+        >>> filter([1, 2, 2, 4], value=2)
+        [2, 2]
+        >>> filter([1, 2, 2, 4], callback=lambda x: x > 1)
+        [2, 2, 4]
+
+    .. versionadded:: 0.2.0-dev
+    """
+    if value:
+        return [element for element in array if element == value]
+
+    return [element for element in array if callback(element) is True]
+
+
 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

@@ -10,6 +10,7 @@
     count,
     every,
     exclude,
+    filter,
     subtract
 )
 
@@ -86,6 +87,15 @@ def test_exclude(array, item, expected_output):
     assert exclude(array, item) == expected_output
 
 
+@parametrize('array,value,callback,expected_output', [
+    ([1, 2, 2, 4], 2, None, [2, 2]),
+    ([1, 2, 3, 3, 4], None, lambda x: x > 1, [2, 3, 3, 4])
+])
+def test_filter(array, value, callback, expected_output):
+    """Tests whether the filter method is working properly or not."""
+    assert filter(array, value, callback) == expected_output
+
+
 @parametrize('array,item,expected_output', [
     ([1, 2, 3], 3, [1, 2]),
     ([1, 2, 3], [1, 3], [2]),