[+]: added some more doc's

[+]: fixed "Arrayy->random()"

README.md

@@ -129,20 +129,166 @@ function importing, and PHP 5.4 short array syntax. For further details,
 see the documentation for the create method above, as well as the notes
 on PHP 5.6 creation.
 
-##### append(mixed $value)
+##### "set a array value"
+
+```php
+$arrayy = a(['fòô' => 'bàř']);
+$arrayy['foo'] = 'bar';
+var_dump($arrayy); // Arrayy['fòô' => 'bàř', 'foo' => 'bar']
+```
+
+##### "get a array value"
+
+```php
+$arrayy = a(['fòô' => 'bàř']);
+var_dump($arrayy['fòô']); // 'bàř'
+```
+
+##### "delete a array value"
+
+```php
+$arrayy = A::create(['fòô' => 'bàř', 'lall']);
+unset($arrayy['fòô']);
+var_dump($arrayy); // Arrayy[0 => 'lall']
+```
+
+##### "check if a array value is-set"
+
+```php
+$arrayy = a(['fòô' => 'bàř']);
+isset($arrayy['fòô']); // true
+```
+
+##### "simple loop with a arrayy-object"
+
+```php
+foreach (a(['fòô' => 'bàř']) as $key => $value) {
+  echo $key . ' | ' . $value; // fòô | bàř
+}
+```
+
+##### append(mixed $value) : Arrayy
 
 Returns a new arrayy object with $value appended.
 
 ```php
-a(['fòô' => 'bàř'])->append('foo'); // a(['fòô' => 'bàř', 0 => 'foo'])
+a(['fòô' => 'bàř'])->append('foo'); // Arrayy['fòô' => 'bàř', 0 => 'foo']
+```
+
+##### searchValue(mixed $index) : Arrayy
+
+Search for the value of the current array via $index.
+
+```php
+a(['fòô' => 'bàř'])->searchValue('fòô'); // Arrayy[0 => 'bàř']
+```
+
+##### searchIndex(mixed $value) : Arrayy
+
+Search for the first index of the current array via $value.
+
+```php
+a(['fòô' => 'bàř', 'lall' => 'bàř'])->searchIndex('bàř'); // Arrayy[0 => 'fòô']
+```
+
+##### matches(Closure $closure) : boolean
+
+Check if all items in an array match a truth test.
+
+```php
+$closure = function ($value, $key) {
+  return ($value % 2 === 0);
+};
+a([2, 4, 8])->matches($closure); // true
+```
+
+##### matchesAny(Closure $closure) : boolean
+
+Check if any item in an array matches a truth test.
+
+```php
+$closure = function ($value, $key) {
+  return ($value % 2 === 0);
+};
+a([1, 4, 7])->matches($closure); // true
+```
+
+##### contains(mixed $value) : boolean
+
+Check if an item is in an array.
+
+```php
+a([1, true])->contains(true); // true
+```
+
+##### average(int $decimals) : int|double
+
+Returns the average value of an array
+
+```php
+a([-9, -8, -7, 1.32])->average(2); // -5.67
+```
+
+##### length() : int
+
+Count the values from the current array.
+
+alias: count() || size()
+
+```php
+a([-9, -8, -7, 1.32])->length(); // 4
+```
+
+##### max() : mixed
+
+Get the max value from an array.
+
+```php
+a([-9, -8, -7, 1.32])->max(); // 1.32
+```
+
+##### min() : mixed
+
+Get the min value from an array.
+
+```php
+a([-9, -8, -7, 1.32])->min(); // -9
+```
+
+##### find(Closure $closure) : mixed
+
+Find the first item in an array that passes the truth test, otherwise return false.
+
+```php
+$search = 'foo';
+$closure = function ($value, $key) use ($search) {
+  return $value === $search;
+};
+a(['foo', 'bar', 'lall'])->find($closure); // 'foo'
+```
+
+##### clean() : Arrayy
+
+Clean all falsy values from an array.
+
+```php
+a([-8 => -9, 1, 2 => false])->clean(); // Arrayy[-8 => -9, 1]
+```
+
+##### random(int|null $take) : Arrayy
+
+Get a random string from an array.
+
+```php
+a([1, 2, 3, 4])->random(2); // e.g.: Arrayy[1, 4]
 ```
 
 ##### prepend(mixed $value)
 
 Returns a new arrayy object with $value prepended.
 
 ```php
-a(['fòô' => 'bàř'])->prepend('foo'); // a([0 => 'foo', 'fòô' => 'bàř'])
+a(['fòô' => 'bàř'])->prepend('foo'); // Arrayy[0 => 'foo', 'fòô' => 'bàř']
 ```
 
 TODO ... add more examples ... v2

src/Arrayy.php

@@ -229,7 +229,7 @@ public function searchValue($index)
   }
 
   /**
-   * Search for the index of the current array via $value.
+   * Search for the first index of the current array via $value.
    *
    * @param mixed $value
    *
@@ -307,7 +307,7 @@ public function contains($value)
    *
    * @param int $decimals The number of decimals to return
    *
-   * @return int The average value
+   * @return int|double The average value
    */
   public function average($decimals = null)
   {
@@ -426,14 +426,14 @@ function ($value) {
   /**
    * Get a random string from an array.
    *
-   * @param null $take
+   * @param null|int $take how many values you will take?
    *
    * @return self
    */
   public function random($take = null)
   {
-    if ($take !== null) {
-      return $this->array[array_rand($this->array)];
+    if ($take === null) {
+      return Arrayy::create((array)$this->array[array_rand($this->array)]);
     }
 
     shuffle($this->array);
@@ -472,7 +472,7 @@ public function intersects(array $search)
   /**
    * Get the first value from an array.
    *
-   * @param int|null $take
+   * @param int|null $take how many values you will take?
    *
    * @return self
    */

tests/ArrayyTest.php

@@ -7,13 +7,6 @@
  */
 class ArrayyTest extends PHPUnit_Framework_TestCase
 {
-  public function testConstruct()
-  {
-    $arrayy = new A(array('foo bar', 'UTF-8'));
-    self::assertArrayy($arrayy);
-    self::assertEquals('foo bar,UTF-8', (string)$arrayy);
-  }
-
   /**
    * Asserts that a variable is of a Arrayy instance.
    *
@@ -24,6 +17,58 @@ public function assertArrayy($actual)
     self::assertInstanceOf('Arrayy\Arrayy', $actual);
   }
 
+  public function testConstruct()
+  {
+    $arrayy = new A(array('foo bar', 'UTF-8'));
+    self::assertArrayy($arrayy);
+    self::assertEquals('foo bar,UTF-8', (string)$arrayy);
+  }
+
+  public function testSet()
+  {
+    $arrayy = new A(array('foo bar', 'UTF-8'));
+    $arrayy[1] = 'öäü';
+    self::assertArrayy($arrayy);
+    self::assertEquals('foo bar,öäü', (string)$arrayy);
+  }
+
+  public function testGet()
+  {
+    $arrayy = new A(array('foo bar', 'öäü'));
+    self::assertArrayy($arrayy);
+    self::assertEquals('öäü', $arrayy[1]);
+  }
+
+  public function testUnset()
+  {
+    $arrayy = new A(array('foo bar', 'öäü'));
+    unset($arrayy[1]);
+    self::assertArrayy($arrayy);
+    self::assertEquals('foo bar', $arrayy[0]);
+    self::assertEquals(null, $arrayy[1]);
+  }
+
+  public function testIsSet()
+  {
+    $arrayy = new A(array('foo bar', 'öäü'));
+    self::assertArrayy($arrayy);
+    self::assertEquals(true, isset($arrayy[0]));
+  }
+
+  public function testForEach()
+  {
+    $arrayy = new A(array(1 => 'foo bar', 'öäü'));
+
+    foreach ($arrayy as $key => $value) {
+      if ($key === 1) {
+        self::assertEquals('foo bar', $arrayy[$key]);
+      } else if ($key === 2) {
+        self::assertEquals('öäü', $arrayy[$key]);
+      }
+    }
+
+  }
+
   public function testEmptyConstruct()
   {
     $arrayy = new A();
@@ -139,6 +184,26 @@ public function searchValueProvider()
     );
   }
 
+  public function testMatchesSimple()
+  {
+    /** @noinspection PhpUnusedParameterInspection */
+    /**
+     * @param $value
+     * @param $key
+     *
+     * @return bool
+     */
+    $closure = function ($value, $key) {
+      return ($value % 2 === 0);
+    };
+
+    $result = A::create(array(2, 4, 8))->matches($closure);
+    self::assertEquals(true, $result);
+
+    $result = A::create(array(2, 3, 8))->matches($closure);
+    self::assertEquals(false, $result);
+  }
+
   /**
    * @dataProvider matchesProvider()
    *
@@ -176,6 +241,26 @@ public function matchesProvider()
     );
   }
 
+  public function testMatchesAnySimple()
+  {
+    /** @noinspection PhpUnusedParameterInspection */
+    /**
+     * @param $value
+     * @param $key
+     *
+     * @return bool
+     */
+    $closure = function ($value, $key) {
+      return ($value % 2 === 0);
+    };
+
+    $result = A::create(array(1, 4, 7))->matchesAny($closure);
+    self::assertEquals(true, $result);
+
+    $result = A::create(array(1, 3, 7))->matchesAny($closure);
+    self::assertEquals(false, $result);
+  }
+
   /**
    * @dataProvider matchesAnyProvider()
    *
@@ -383,12 +468,11 @@ public function minProvider()
    */
   public function testFind($array, $search, $result)
   {
-    $arrayy = A::create($array);
-
     $closure = function ($value) use ($search) {
       return $value === $search;
     };
 
+    $arrayy = A::create($array);
     $resultMatch = $arrayy->find($closure);
 
     self::assertEquals($result, $resultMatch);
@@ -439,18 +523,24 @@ public function cleanProvider()
     );
   }
 
+  public function testSimpleRandom()
+  {
+    $result = A::create(array(-8 => -9, 1, 2 => false))->random(3);
+    self::assertEquals(3, count($result));
+  }
+
   /**
    * @dataProvider randomProvider()
    *
-   * @param $array
+   * @param array $array
+   * @param bool  $take
    */
-  public function testRandom($array)
+  public function testRandom($array, $take = null)
   {
     $arrayy = A::create($array);
+    $result = $arrayy->random($take)->getArray();
 
-    $tmpArray = $arrayy->random()->getArray();
-
-    self::assertEquals(true, in_array($tmpArray[0], $array, true));
+    self::assertEquals(true, in_array($result[0], $array, true));
   }
 
   /**
@@ -462,8 +552,11 @@ public function randomProvider()
         array(array(0 => true)),
         array(array(0 => -9, 0)),
         array(array(-8 => -9, 1, 2 => false)),
+        array(array(-8 => -9, 1, 2 => false), 2),
         array(array(1.18, false)),
         array(array('foo' => false, 'foo', 'lall')),
+        array(array('foo' => false, 'foo', 'lall'), 1),
+        array(array('foo' => false, 'foo', 'lall'), 3),
     );
   }