system/classes/Collection.php
public function getByValue($key, $value)
    {
        $collection = $this->getIterator();

        foreach($collection as $result) {
            if ($result->$key == $value) {
                return $result;
            }
        }
        return null;
    }
public function getByValue($key, $value)
    {
        $collection = $this->getIterator();

        foreach($collection as $result) {
            if ($result->$key == $value) {
                return $result;
            }
        }
        return null;
    }
Returns the FIRST result with a matching key=>value, else NULL.
Example: if objects representing Users are stored and you want the result with
an Email value of 'Bob@gmail.com'

@param key A string representing a key or property.
@param value A value for which you are searching.