Merge pull request #450 from wmde/getStatementIndex

Replace StatementList::getIndexByGuid with getFirstStatementByGuid

Author: JeroenDeDauw

RELEASE-NOTES.md

@@ -23,7 +23,7 @@
 * Removed `Claims::getHash` (and `Claims` no longer implements `Hashable`)
 * Removed `Claims::hasClaim`
 * Removed `Claims::isEmpty` (you can use `StatementList::isEmpty` instead)
-* Removed `Claims::indexOf` (you can use `StatementList::getIndexByGuid` instead)
+* Removed `Claims::indexOf`, use `StatementList::getFirstStatementByGuid` or `StatementByGuidMap` instead
 * Removed `Claims::removeClaim`
 * Removed `Entity::getAllSnaks`, use `StatementList::getAllSnaks` instead
 * Removed `EntityId::getPrefixedId`, use `EntityId::getSerialization` instead
@@ -32,7 +32,7 @@
 #### Additions
 
 * Added `StatementByGuidMap`
-* Added `StatementList::getIndexByGuid`
+* Added `StatementList::getFirstStatementByGuid`
 * `ReferenceList::addNewReference` and `Statement::addNewReference` support an array of Snaks now
 
 ## Version 2.6.0 (2015-03-08)

src/Claim/Claims.php

@@ -92,7 +92,7 @@ public function addClaim( Claim $claim ) {
 
 	/**
 	 * @since 0.3
-	 * @deprecated since 1.0, use StatementList::getIndexByGuid() instead.
+	 * @deprecated since 1.0, use StatementList::getFirstStatementByGuid() instead.
 	 *
 	 * @param string $claimGuid
 	 *
@@ -116,7 +116,7 @@ public function removeClaimWithGuid( $claimGuid ) {
 
 	/**
 	 * @since 0.3
-	 * @deprecated since 1.0, use StatementList::getIndexByGuid() instead.
+	 * @deprecated since 1.0, use StatementList::getFirstStatementByGuid() instead.
 	 *
 	 * @param string $claimGuid
 	 *

src/Statement/StatementList.php

@@ -285,27 +285,20 @@ public function isEmpty() {
 
 	/**
 	 * @since 3.0
+	 * @see StatementByGuidMap
 	 *
 	 * @param string|null $statementGuid
 	 *
-	 * @throws InvalidArgumentException
-	 * @return int|bool Zero-based index or false if not found.
+	 * @return Statement|null The first statement with the given GUID or null if not found.
 	 */
-	public function getIndexByGuid( $statementGuid ) {
-		if ( !is_string( $statementGuid ) && $statementGuid !== null ) {
-			throw new InvalidArgumentException( '$statementGuid needs to be string or null' );
-		}
-
-		$index = 0;
-
-		foreach ( $this->statements as $s ) {
-			if ( $s->getGuid() === $statementGuid ) {
-				return $index;
+	public function getFirstStatementByGuid( $statementGuid ) {
+		foreach ( $this->statements as $statement ) {
+			if ( $statement->getGuid() === $statementGuid ) {
+				return $statement;
 			}
-			$index++;
 		}
 
-		return false;
+		return null;
 	}
 
 }

tests/unit/Statement/StatementListTest.php

@@ -567,57 +567,46 @@ public function testWhenNoPreferredStatements_getBestStatementsReturnsOnlyNormal
 		);
 	}
 
-	public function testGivenNotPresentStatement_getIndexByGuidReturnsFalse() {
+	public function testGivenNotPresentStatement_getFirstStatementByGuidReturnsNull() {
 		$statements = new StatementList();
 
-		$this->assertFalse( $statements->getIndexByGuid( 'kittens' ) );
+		$this->assertNull( $statements->getFirstStatementByGuid( 'kittens' ) );
 	}
 
-	public function testGivenPresentStatement_getIndexByGuidReturnsItsIndex() {
-		$statements = new StatementList( array(
-			$this->getStatement( 43, 'kittens43' ),
-			$this->getStatement( 42, 'kittens42' ),
-			$this->getStatement( 41, 'kittens41' ),
-		) );
+	public function testGivenPresentStatement_getFirstStatementByGuidReturnsStatement() {
+		$statement1 = $this->getStatement( 1, 'guid1' );
+		$statement2 = $this->getStatement( 2, 'guid2' );
+		$statement3 = $this->getStatement( 3, 'guid3' );
+		$statements = new StatementList( $statement1, $statement2, $statement3 );
 
-		$this->assertSame(
-			1,
-			$statements->getIndexByGuid( 'kittens42' )
-		);
+		$actual = $statements->getFirstStatementByGuid( 'guid2' );
+		$this->assertSame( $statement2, $actual );
 	}
 
-	public function testGivenDoublyPresentStatement_getIndexByGuidReturnsTheFirstIndex() {
-		$statements = new StatementList( array(
-			$this->getStatement( 43, 'kittens43' ),
-			$this->getStatement( 42, 'kittens42' ),
-			$this->getStatement( 41, 'kittens41' ),
-			$this->getStatement( 42, 'kittens42' ),
-		) );
+	public function testGivenDoublyPresentStatement_getFirstStatementByGuidReturnsFirstMatch() {
+		$statement1 = $this->getStatement( 1, 'guid1' );
+		$statement2 = $this->getStatement( 2, 'guid2' );
+		$statement3 = $this->getStatement( 3, 'guid3' );
+		$statement4 = $this->getStatement( 2, 'guid2' );
+		$statements = new StatementList( $statement1, $statement2, $statement3, $statement4 );
 
-		$this->assertSame(
-			1,
-			$statements->getIndexByGuid( 'kittens42' )
-		);
+		$actual = $statements->getFirstStatementByGuid( 'guid2' );
+		$this->assertSame( $statement2, $actual );
 	}
 
-	public function testGivenDifferentStatementWithSameGuid_getIndexByGuidReturnsItsIndex() {
-		$statements = new StatementList( array(
-			$this->getStatement( 1, 'kittens43' ),
-			$this->getStatement( 2, 'kittens42' ),
-			$this->getStatement( 3, 'kittens41' ),
-		) );
+	public function testGivenStatementsWithNoGuid_getFirstStatementByGuidReturnsFirstMatch() {
+		$statement1 = $this->getStatement( 1, null );
+		$statement2 = $this->getStatement( 2, null );
+		$statements = new StatementList( $statement1, $statement2 );
 
-		$this->assertSame(
-			2,
-			$statements->getIndexByGuid( 'kittens41' )
-		);
+		$actual = $statements->getFirstStatementByGuid( null );
+		$this->assertSame( $statement1, $actual );
 	}
 
-	public function testGivenInvalidGuid_getIndexByGuidThrowsException() {
+	public function testGivenInvalidGuid_getFirstStatementByGuidReturnsNull() {
 		$statements = new StatementList();
 
-		$this->setExpectedException( 'InvalidArgumentException' );
-		$statements->getIndexByGuid( false );
+		$this->assertNull( $statements->getFirstStatementByGuid( false ) );
 	}
 
 }