includes/collation/Collation.php

   1 <?php
   2 /**
   3  * Database row sorting.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  */
  22
  23 /**
  24  * @since 1.16.3
  25  * @author Tim Starling
  26  * @stable to extend
  27  */
  28 abstract class Collation {
  29
  30         /**
  31          * Given a string, convert it to a (hopefully short) key that can be used
  32          * for efficient sorting.  A binary sort according to the sortkeys
  33          * corresponds to a logical sort of the corresponding strings.  Current
  34          * code expects that a line feed character should sort before all others, but
  35          * has no other particular expectations (and that one can be changed if
  36          * necessary).
  37          *
  38          * @since 1.16.3
  39          *
  40          * @param string $string UTF-8 string
  41          * @return string Binary sortkey
  42          */
  43         abstract public function getSortKey( $string );
  44
  45         /**
  46          * Get multiple sort keys
  47          *
  48          * @param string[] $strings
  49          * @return string[]
  50          */
  51         public function getSortKeys( $strings ) {
  52                 $ret = [];
  53                 foreach ( $strings as $key => $s ) {
  54                         $ret[$key] = $this->getSortKey( $s );
  55                 }
  56                 return $ret;
  57         }
  58
  59         /**
  60          * Given a string, return the logical "first letter" to be used for
  61          * grouping on category pages and so on.  This has to be coordinated
  62          * carefully with convertToSortkey(), or else the sorted list might jump
  63          * back and forth between the same "initial letters" or other pathological
  64          * behavior.  For instance, if you just return the first character, but "a"
  65          * sorts the same as "A" based on getSortKey(), then you might get a
  66          * list like
  67          *
  68          * == A ==
  69          * * [[Aardvark]]
  70          *
  71          * == a ==
  72          * * [[antelope]]
  73          *
  74          * == A ==
  75          * * [[Ape]]
  76          *
  77          * etc., assuming for the sake of argument that $wgCapitalLinks is false.
  78          *
  79          * @since 1.16.3
  80          *
  81          * @param string $string UTF-8 string
  82          * @return string UTF-8 string corresponding to the first letter of input
  83          */
  84         abstract public function getFirstLetter( $string );
  85
  86 }