/**
  * descend inside an array, using dot.notation.support, and optionally
  * extending the array if the end of the dot.notation.path is missing
  *
  * @param  array &$arr
  *         the array to dig into
  * @param  string $index
  *         the dot.notation.support path to descend
  * @param  array|callable|string|null $extendingItem
  *         if we need to extend, what data type do we extend using?
  * @return mixed
  */
 public static function &intoArray(&$arr, $index, $extendingItem = null)
 {
     // robustness!
     RequireIndexable::check($arr, E4xx_UnsupportedType::class);
     $retval =& self::getPathFromRoot($arr, $index, $extendingItem);
     return $retval;
 }
 /**
  * merge their array into our array
  *
  * @param  array &$ours
  *         the array that we want to merge into
  * @param  array|Traversable $theirs
  *         the array that we want to merge from
  * @return void
  */
 public static function fromArray(&$ours, $theirs)
 {
     // robustness!
     RequireIndexable::check($ours, E4xx_UnsupportedType::class);
     RequireTraversable::check($theirs, E4xx_UnsupportedType::class);
     // copy from them to us
     foreach ($theirs as $key => $value) {
         self::mergeKeyIntoArray($ours, $key, $value);
     }
     // all done
 }
 /**
  * merge their data into our array, using dot.notation.support to
  * find the point where the merge starts
  *
  * @param  array &$arr
  *         the array that we want to merge into
  * @param  string $path
  *         the dot.notation.support path to where the merge should start
  * @param  mixed $value
  *         the data that we want to merge from
  * @param  array|callable|string|null
  *         if $path goes beyond what exists in $ours, how do we want to
  *         extend $ours?
  * @return void
  */
 public static function intoArray(&$arr, $path, $value, $extendingItem = null)
 {
     // robustness!
     RequireIndexable::check($arr, E4xx_UnsupportedType::class);
     RequireDotNotationPath::check($path);
     // find the point where we want to merge
     list($firstPart, $finalPart) = self::splitPathInTwo($path);
     if ($firstPart !== null) {
         $leaf =& DescendDotNotationPath::intoArray($arr, $firstPart, $extendingItem);
     } else {
         $leaf =& $arr;
     }
     // merge it
     MergeIntoProperty::of($leaf, $finalPart, $value);
 }
 /**
  * merge their data into one of our array's properties
  *
  * @param  array &$arr
  *         the array that we want to merge into
  * @param  string $property
  *         the property to merge into
  * @param  mixed $value
  *         the data that we want to merge from
  * @return void
  */
 public static function ofArray(&$arr, $property, $value)
 {
     // robustness!
     RequireIndexable::check($arr, E4xx_UnsupportedType::class);
     // easiest case - no clash
     if (ShouldOverwrite::intoArray($arr, $property, $value)) {
         $arr[$property] = $value;
         return;
     }
     // special case - we are merging into an object
     if (is_object($arr[$property])) {
         MergeIntoAssignable::from($arr[$property], $value);
         return;
     }
     // if we get here, then we must be merging into an array
     MergeIntoIndexable::from($arr[$property], $value);
 }
 /**
  * @covers ::check
  * @covers ::checkMixed
  * @dataProvider provideNonIndexables
  * @expectedException GanbaroDigital\Reflection\Exceptions\E4xx_UnsupportedType
  */
 public function testRejectsNonIndexablesWhenCalledStatically($item)
 {
     // ----------------------------------------------------------------
     // setup your test
     // ----------------------------------------------------------------
     // perform the change
     RequireIndexable::check($item);
 }
 /**
  * does $path point to a valid piece of data inside $container?
  *
  * @param  array $container
  *         the container to look inside
  * @param  string $path
  *         the dot.notation.support path to walk
  * @return boolean
  *         TRUE if $path points to a vlaid piece of data
  *         FALSE otherwise
  */
 public static function inArray($container, $path)
 {
     // defensive programming!
     RequireIndexable::check($container, E4xx_UnsupportedType::class);
     RequireAnyOneOf::check([new IsDotNotationPath(), new IsStringy()], [$path], E4xx_NotDotNotationPath::class);
     try {
         DescendDotNotationPath::intoArray($container, $path);
         return true;
     } catch (E4xx_NoSuchIndex $e) {
         return false;
     } catch (E4xx_NoSuchProperty $e) {
         return false;
     }
 }
 /**
  * extract a value from an array, using dot.notation.support
  *
  * @param  array $arr
  *         the array to extract from
  * @param  string $index
  *         the dot.notation.support path to walk
  * @return mixed
  *         whatever we find when we walk the path
  */
 public static function fromArray($arr, $index)
 {
     // robustness!
     RequireIndexable::check($arr, E4xx_UnsupportedType::class);
     return DescendDotNotationPath::intoArray($arr, $index);
 }