includes/search/SearchSuggestionSet.php

   1 <?php
   2
   3 /**
   4  * Search suggestion sets
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License along
  17  * with this program; if not, write to the Free Software Foundation, Inc.,
  18  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  19  * http://www.gnu.org/copyleft/gpl.html
  20  */
  21
  22 /**
  23  * A set of search suggestions.
  24  * The set is always ordered by score, with the best match first.
  25  */
  26 class SearchSuggestionSet {
  27         /**
  28          * @var SearchSuggestion[]
  29          */
  30         private $suggestions = [];
  31
  32         /**
  33          *
  34          * @var array
  35          */
  36         private $pageMap = [];
  37
  38         /**
  39          * Builds a new set of suggestions.
  40          *
  41          * NOTE: the array should be sorted by score (higher is better),
  42          * in descending order.
  43          * SearchSuggestionSet will not try to re-order this input array.
  44          * Providing an unsorted input array is a mistake and will lead to
  45          * unexpected behaviors.
  46          *
  47          * @param SearchSuggestion[] $suggestions (must be sorted by score)
  48          */
  49         public function __construct( array $suggestions ) {
  50                 foreach ( $suggestions as $suggestion ) {
  51                         $pageID = $suggestion->getSuggestedTitleID();
  52                         if ( $pageID && empty( $this->pageMap[$pageID] ) ) {
  53                                 $this->pageMap[$pageID] = true;
  54                         }
  55                         $this->suggestions[] = $suggestion;
  56                 }
  57         }
  58
  59         /**
  60          * Get the list of suggestions.
  61          * @return SearchSuggestion[]
  62          */
  63         public function getSuggestions() {
  64                 return $this->suggestions;
  65         }
  66
  67         /**
  68          * Call array_map on the suggestions array
  69          * @param callback $callback
  70          * @return array
  71          */
  72         public function map( $callback ) {
  73                 return array_map( $callback, $this->suggestions );
  74         }
  75
  76         /**
  77          * Add a new suggestion at the end.
  78          * If the score of the new suggestion is greater than the worst one,
  79          * the new suggestion score will be updated (worst - 1).
  80          *
  81          * @param SearchSuggestion $suggestion
  82          */
  83         public function append( SearchSuggestion $suggestion ) {
  84                 $pageID = $suggestion->getSuggestedTitleID();
  85                 if ( $pageID && isset( $this->pageMap[$pageID] ) ) {
  86                         return;
  87                 }
  88                 if ( $this->getSize() > 0 && $suggestion->getScore() >= $this->getWorstScore() ) {
  89                         $suggestion->setScore( $this->getWorstScore() - 1 );
  90                 }
  91                 $this->suggestions[] = $suggestion;
  92                 if ( $pageID ) {
  93                         $this->pageMap[$pageID] = true;
  94                 }
  95         }
  96
  97         /**
  98          * Add suggestion set to the end of the current one.
  99          * @param SearchSuggestionSet $set
 100          */
 101         public function appendAll( SearchSuggestionSet $set ) {
 102                 foreach ( $set->getSuggestions() as $sugg ) {
 103                         $this->append( $sugg );
 104                 }
 105         }
 106
 107         /**
 108          * Move the suggestion at index $key to the first position
 109          */
 110         public function rescore( $key ) {
 111                 $removed = array_splice( $this->suggestions, $key, 1 );
 112                 unset( $this->pageMap[$removed[0]->getSuggestedTitleID()] );
 113                 $this->prepend( $removed[0] );
 114         }
 115
 116         /**
 117          * Add a new suggestion at the top. If the new suggestion score
 118          * is lower than the best one its score will be updated (best + 1)
 119          * @param SearchSuggestion $suggestion
 120          */
 121         public function prepend( SearchSuggestion $suggestion ) {
 122                 $pageID = $suggestion->getSuggestedTitleID();
 123                 if ( $pageID && isset( $this->pageMap[$pageID] ) ) {
 124                         return;
 125                 }
 126                 if ( $this->getSize() > 0 && $suggestion->getScore() <= $this->getBestScore() ) {
 127                         $suggestion->setScore( $this->getBestScore() + 1 );
 128                 }
 129                 array_unshift( $this->suggestions,  $suggestion );
 130                 if ( $pageID ) {
 131                         $this->pageMap[$pageID] = true;
 132                 }
 133         }
 134
 135         /**
 136          * @return float the best score in this suggestion set
 137          */
 138         public function getBestScore() {
 139                 if ( empty( $this->suggestions ) ) {
 140                         return 0;
 141                 }
 142                 return $this->suggestions[0]->getScore();
 143         }
 144
 145         /**
 146          * @return float the worst score in this set
 147          */
 148         public function getWorstScore() {
 149                 if ( empty( $this->suggestions ) ) {
 150                         return 0;
 151                 }
 152                 return end( $this->suggestions )->getScore();
 153         }
 154
 155         /**
 156          * @return int the number of suggestion in this set
 157          */
 158         public function getSize() {
 159                 return count( $this->suggestions );
 160         }
 161
 162         /**
 163          * Remove any extra elements in the suggestions set
 164          * @param int $limit the max size of this set.
 165          */
 166         public function shrink( $limit ) {
 167                 if ( count( $this->suggestions ) > $limit ) {
 168                         $this->suggestions = array_slice( $this->suggestions, 0, $limit );
 169                 }
 170         }
 171
 172         /**
 173          * Builds a new set of suggestion based on a title array.
 174          * Useful when using a backend that supports only Titles.
 175          *
 176          * NOTE: Suggestion scores will be generated.
 177          *
 178          * @param Title[] $titles
 179          * @return SearchSuggestionSet
 180          */
 181         public static function fromTitles( array $titles ) {
 182                 $score = count( $titles );
 183                 $suggestions = array_map( function( $title ) use ( &$score ) {
 184                         return SearchSuggestion::fromTitle( $score--, $title );
 185                 }, $titles );
 186                 return new SearchSuggestionSet( $suggestions );
 187         }
 188
 189         /**
 190          * Builds a new set of suggestion based on a string array.
 191          *
 192          * NOTE: Suggestion scores will be generated.
 193          *
 194          * @param string[] $titles
 195          * @return SearchSuggestionSet
 196          */
 197         public static function fromStrings( array $titles ) {
 198                 $score = count( $titles );
 199                 $suggestions = array_map( function( $title ) use ( &$score ) {
 200                         return SearchSuggestion::fromText( $score--, $title );
 201                 }, $titles );
 202                 return new SearchSuggestionSet( $suggestions );
 203         }
 204
 205         /**
 206          * @return SearchSuggestionSet an empty suggestion set
 207          */
 208         public static function emptySuggestionSet() {
 209                 return new SearchSuggestionSet( [] );
 210         }
 211 }