Introduce StatementGroup

Per #479 (comment)

src/Statement/StatementGroup.php

@@ -0,0 +1,72 @@
+<?php
+
+namespace Wikibase\DataModel\Statement;
+
+use InvalidArgumentException;
+use Traversable;
+use Wikibase\DataModel\Entity\PropertyId;
+use Wikibase\DataModel\PropertyIdProvider;
+
+/**
+ * List of statements with the same property id, grouped by rank.
+ *
+ * @since 3.1
+ *
+ * @license GNU GPL v2+
+ * @author Bene* < [email protected] >
+ */
+class StatementGroup implements PropertyIdProvider {
+
+	/**
+	 * @var Statement[][]
+	 */
+	private $statementsByRank = array();
+
+	/**
+	 * @var PropertyId
+	 */
+	private $propertyId;
+
+	public function __construct( PropertyId $propertyId ) {
+		$this->propertyId = $propertyId;
+	}
+
+	/**
+	 * @param Statement[]|Traversable $statements
+	 * @throws InvalidArgumentException
+	 */
+	public function addStatements( $statements ) {
+		if ( !is_array( $statements ) && !( $statements instanceof Traversable ) ) {
+			throw new InvalidArgumentException( '$statements must be an array or an instance of Traversable' );
+		}
+
+		foreach ( $statements as $statement ) {
+			if ( !( $statement instanceof Statement ) ) {
+				throw new InvalidArgumentException( 'Every element in $statements must be an instance of Statement' );
+			}
+
+			$this->addStatement( $statement );
+		}
+	}
+
+	/**
+	 * @param Statement $statement
+	 * @throws InvalidArgumentException
+	 */
+	public function addStatement( Statement $statement ) {
+		if ( !$statement->getPropertyId()->equals( $this->propertyId ) ) {
+			throw new InvalidArgumentException( '$statement must have the property id ' . $this->propertyId->getSerialization() );
+		}
+
+		$this->statementsByRank[$statement->getRank()][] = $statement;
+	}
+
+	/**
+	 * @see PropertyIdProvider::getPropertyId
+	 * @return PropertyId
+	 */
+	public function getPropertyId() {
+		return $this->propertyId;
+	}
+
+}