/**
* Returns the code for the current language
*
+ * @category string
* @return string
*/
function current_language() {
/**
* Returns parent language of current active language if defined
*
+ * @category string
* @uses COURSE
* @uses SESSION
* @param string $lang null means current language
* The param $forcereload is needed for CLI installer only where the string_manager instance
* must be replaced during the install.php script life time.
*
+ * @category string
* @param bool $forcereload shall the singleton be released and new instance created instead?
* @return string_manager
*/
/**
+ * Interface for string manager
+ *
* Interface describing class which is responsible for getting
* of localised strings from language packs.
*
- * @package moodlecore
+ * @package core
* @copyright 2010 Petr Skoda (http://skodak.org)
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
public function get_list_of_languages($lang = NULL, $standard = 'iso6392');
/**
- * Does the translation exist?
+ * Checks if the translation exists for the language
*
* @param string $lang moodle translation language code
- * @param bool include also disabled translations?
- * @return boot true if exists
+ * @param bool $includeall include also disabled translations
+ * @return bool true if exists
*/
public function translation_exists($lang, $includeall = true);
/**
* Standard string_manager implementation
*
- * @package moodlecore
+ * Implements string_manager with getting and printing localised strings
+ *
+ * @package core
+ * @category string
* @copyright 2010 Petr Skoda (http://skodak.org)
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
protected $countdiskcache = 0;
/** @var bool use disk cache */
protected $usediskcache;
- /* @var array limit list of translations */
+ /** @var array limit list of translations */
protected $translist;
/** @var string location of a file that caches the list of available translations */
protected $menucache;
/**
* Returns dependencies of current language, en is not included.
+ *
* @param string $lang
* @return array all parents, the lang itself is last
*/
/**
* Load all strings for one component
+ *
* @param string $component The module the string is associated with
* @param string $lang
* @param bool $disablecache Do not use caches, force fetching the strings from sources
*
* get_string() is throwing debug warnings, sometimes we do not want them
* or we want to display better explanation of the problem.
- *
- * Use with care!
+ * Note: Use with care!
*
* @param string $identifier The identifier of the string to search for
* @param string $component The module the string is associated with
/**
* Returns information about the string_manager performance
+ *
* @return array
*/
public function get_performance_summary() {
}
/**
- * Does the translation exist?
+ * Checks if the translation exists for the language
*
* @param string $lang moodle translation language code
- * @param bool include also disabled translations?
- * @return boot true if exists
+ * @param bool $includeall include also disabled translations
+ * @return bool true if exists
*/
public function translation_exists($lang, $includeall = true) {
/**
* Returns localised list of installed translations
+ *
* @param bool $returnall return all or just enabled
* @return array moodle translation code => localised translation name
*/
/**
+ * Fetches minimum strings for installation
+ *
* Minimalistic string fetching implementation
* that is used in installer before we fetch the wanted
* language pack from moodle.org lang download site.
*
- * @package moodlecore
+ * @package core
* @copyright 2010 Petr Skoda (http://skodak.org)
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
}
/**
- * Does the translation exist?
+ * Checks if the translation exists for the language
*
* @param string $lang moodle translation language code
- * @param bool include also disabled translations?
- * @return boot true if exists
+ * @param bool $includeall include also disabled translations
+ * @return bool true if exists
*/
public function translation_exists($lang, $includeall = true) {
return file_exists($this->installroot.'/'.$lang.'/langconfig.php');
* But you should never do that anyway!
* For more information {@see lang_string}
*
+ * @category string
* @param string $identifier The key identifier for the localized string
* @param string $component The module where the key identifier is stored,
* usually expressed as the filename in the language pack without the
* Converts an array of strings to their localized value.
*
* @param array $array An array of strings
- * @param string $module The language module that these strings can be found in.
- * @return array and array of translated strings.
+ * @param string $component The language module that these strings can be found in.
+ * @return stdClass translated strings.
*/
function get_strings($array, $component = '') {
$string = new stdClass;
* echo '</h1>';
* </code>
*
+ * @category string
* @param string $identifier The key identifier for the localized string
* @param string $component The module where the key identifier is stored. If none is specified then moodle.php is used.
- * @param mixed $a An object, string or number that can be used within translation strings
+ * @param string|object|array $a An object, string or number that can be used within translation strings
*/
function print_string($identifier, $component = '', $a = NULL) {
echo get_string($identifier, $component, $a);
/**
* Sets the system locale
*
- * @todo Finish documenting this function
- *
- * @global object
+ * @category string
* @param string $locale Can be used to force a locale
*/
function moodle_setlocale($locale='') {
/**
* Converts string to lowercase using most compatible function available.
*
- * @todo Remove this function when no longer in use
- * @deprecated Use textlib->strtolower($text) instead.
+ * @deprecated since Moodle 2.0 use textlib::strtolower()
+ * @todo MDL-31250 Remove this function when no longer in use
+ * @see textlib::strtolower($text)
*
* @param string $string The string to convert to all lowercase characters.
* @param string $encoding The encoding on the string.
*
* Words are defined as things between whitespace.
*
+ * @category string
* @param string $string The text to be searched for words.
* @return int The count of words in the specified string
*/
*
* Letters are defined as chars not in tags and different from whitespace.
*
+ * @category string
* @param string $string The text to be searched for letters.
* @return int The count of letters in the specified text.
*/
* Given some text (which may contain HTML) and an ideal length,
* this function truncates the text neatly on a word boundary if possible
*
- * @global object
- * @param string $text - text to be shortened
- * @param int $ideal - ideal string length
+ * @category string
+ * @global stdClass $CFG
+ * @param string $text text to be shortened
+ * @param int $ideal ideal string length
* @param boolean $exact if false, $text will not be cut mid-word
* @param string $ending The string to append if the passed string is truncated
- * @return string $truncate - shortened string
+ * @return string $truncate shortened string
*/
function shorten_text($text, $ideal=30, $exact = false, $ending='...') {
* {@link http://www.phpbuilder.com/columns/jesus19990502.php3} and
* {@link http://es2.php.net/manual/en/function.str-shuffle.php#73254}
*
- * @global object
+ * @global stdClass $CFG
* @param int $maxlen The maximum size of the password being generated.
* @return string
*/
* Localized floats must not be used in calculations!
*
* @param float $float The float to print
- * @param int $places The number of decimal places to print.
+ * @param int $decimalpoints The number of decimal places to print.
* @param bool $localized use localized decimal separator
* @return string locale float
*/
* Converts locale specific floating point/comma number back to standard PHP float value
* Do NOT try to do any math operations before this conversion on any user submitted floats!
*
- * @param string $locale_float locale aware float representation
+ * @param string $locale_float locale aware float representation
* @return float
*/
function unformat_float($locale_float) {
* 1. You cannot use a lang_string object as an array offset. Doing so will
* result in PHP throwing an error. (You can use it as an object property!)
*
- * @package moodlecore
- *
+ * @package core
+ * @category string
* @copyright 2011 Sam Hemelryk
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
+ * Defines string apis
+ *
* @package core
- * @subpackage lib
* @copyright (C) 2001-3001 Eloy Lafuente (stronk7) {@link http://contiento.com}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
* Original singleton helper function, please use static methods instead,
* ex: textlib::convert()
*
- * @deprecated
+ * @deprecated since Moodle 2.1 MDL-29027 textlib contains static functions
+ * @todo MDL-31301 calling of textlib functions should be static.
+ * @see textlib
* @return textlib instance
*/
function textlib_get_instance() {
/**
+ * defines string api's for manipulating strings
+ *
* This class is used to manipulate strings under Moodle 1.6 an later. As
* utf-8 text become mandatory a pool of safe functions under this encoding
* become necessary. The name of the methods is exactly the
* its capabilities so, don't forget to make the conversion
* from every wrapper function!
*
- * @package core
- * @subpackage lib
+ * @package core
+ * @category string
* @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class textlib {
/**
- * Return t3lib helper class
+ * Return t3lib helper class, which is used for conversion between charsets
+ *
* @return t3lib_cs
*/
protected static function typo3() {
/**
* Multibyte safe substr() function, uses mbstring or iconv for UTF-8, falls back to typo3.
*
- * @param string $text
+ * @param string $text string to truncate
* @param int $start negative value means from end
- * @param int $len
+ * @param int $len maximum length of characters beginning from start
* @param string $charset encoding of the text
- * @return string
+ * @return string portion of string specified by the $start and $len
*/
public static function substr($text, $start, $len=null, $charset='utf-8') {
$charset = self::parse_charset($charset);
/**
* Multibyte safe strlen() function, uses mbstring or iconv for UTF-8, falls back to typo3.
*
- * @param string $text
+ * @param string $text input string
* @param string $charset encoding of the text
* @return int number of characters
*/
/**
* Multibyte safe strtolower() function, uses mbstring, falls back to typo3.
*
- * @param string $text
+ * @param string $text input string
* @param string $charset encoding of the text (may not work for all encodings)
* @return string lower case text
*/
/**
* Multibyte safe strtoupper() function, uses mbstring, falls back to typo3.
*
- * @param string $text
+ * @param string $text input string
* @param string $charset encoding of the text (may not work for all encodings)
* @return string upper case text
*/
}
/**
+ * Find the position of the first occurrence of a substring in a string.
* UTF-8 ONLY safe strpos(), uses mbstring, falls back to iconv.
*
- * @param string $haystack
- * @param string $needle
- * @param int $offset
- * @return string
+ * @param string $haystack the string to search in
+ * @param string $needle one or more charachters to search for
+ * @param int $offset offset from begining of string
+ * @return int the numeric position of the first occurrence of needle in haystack.
*/
public static function strpos($haystack, $needle, $offset=0) {
if (function_exists('mb_strpos')) {
}
/**
+ * Find the position of the last occurrence of a substring in a string
* UTF-8 ONLY safe strrpos(), uses mbstring, falls back to iconv.
*
- * @param string $haystack
- * @param string $needle
- * @return string
+ * @param string $haystack the string to search in
+ * @param string $needle one or more charachters to search for
+ * @return int the numeric position of the last occurrence of needle in haystack
*/
public static function strrpos($haystack, $needle) {
if (function_exists('mb_strpos')) {
* Try to convert upper unicode characters to plain ascii,
* the returned string may contain unconverted unicode characters.
*
- * @param string $text
+ * @param string $text input string
* @param string $charset encoding of the text
- * @return string
+ * @return string converted ascii string
*/
public static function specialtoascii($text, $charset='utf-8') {
$charset = self::parse_charset($charset);
* This function seems to be 100% compliant with RFC1342. Credits go to:
* paravoid (http://www.php.net/manual/en/function.mb-encode-mimeheader.php#60283).
*
- * @param string $text
+ * @param string $text input string
* @param string $charset encoding of the text
- * @return string
+ * @return string base64 encoded header
*/
public static function encode_mimeheader($text, $charset='utf-8') {
if (empty($text)) {
* http://php.net/manual/en/function.html-entity-decode.php#75153
* with some custom mods to provide more functionality
*
- * @param string $str input string
- * @param boolean $htmlent convert also html entities (defaults to true)
- * @return string
+ * @param string $str input string
+ * @param boolean $htmlent convert also html entities (defaults to true)
+ * @return string encoded UTF-8 string
*
* NOTE: we could have used typo3 entities_to_utf8() here
* but the direct alternative used runs 400% quicker
/**
* Converts all Unicode chars > 127 to numeric entities &#nnnn; or &#xnnn;.
*
- * @param string $str input string
- * @param boolean $dec output decadic only number entities
- * @param boolean $nonnum remove all non-numeric entities
- * @return string converted string
+ * @param string $str input string
+ * @param boolean $dec output decadic only number entities
+ * @param boolean $nonnum remove all non-numeric entities
+ * @return string converted string
*/
public static function utf8_to_entities($str, $dec=false, $nonnum=false) {
// Avoid some notices from Typo3 code
}
/**
- * Removes the BOM from unicode string - see http://unicode.org/faq/utf_bom.html
+ * Removes the BOM from unicode string {@link http://unicode.org/faq/utf_bom.html}
*
- * @param string $str
+ * @param string $str input string
* @return string
*/
public static function trim_utf8_bom($str) {
/**
* Returns encoding options for select boxes, utf-8 and platform encoding first
+ *
* @return array encodings
*/
public static function get_encodings() {
* Makes first letter of each word capital - words must be separated by spaces.
* Use with care, this function does not work properly in many locales!!!
*
- * @param string $text
+ * @param string $text input string
* @return string
*/
public static function strtotitle($text) {
/**
* A collator class with static methods that can be used for sorting.
*
- * @package core
- * @subpackage lib
+ * @package core
* @copyright 2011 Sam Hemelryk
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
* 0 if str1 is equal to str2
* -1 if str1 is less than str2
*
+ * @param string $str1 first string to compare
+ * @param string $str2 second string to compare
* @return int
*/
public static function compare($str1, $str2) {
}
/**
+ * Object comparison using collator
+ *
* Abstract class to aid the sorting of objects with respect to proper language
* comparison using collator
*
- * @package core
- * @subpackage lib
+ * @package core
* @copyright 2011 Sam Hemelryk
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
}
/**
+ * Compare properties of two objects
+ *
* A comparison helper for comparing properties of two objects
*
- * @package core
- * @subpackage lib
+ * @package core
+ * @category string
* @copyright 2011 Sam Hemelryk
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
protected $property;
/**
+ * Constructor
+ *
* @param string $property
*/
public function __construct($property) {
}
/**
+ * Compare method of two objects
+ *
* A comparison helper for comparing the result of a method on two objects
*
- * @package core
- * @subpackage lib
+ * @package core
* @copyright 2011 Sam Hemelryk
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
protected $method;
/**
+ * Constructor
+ *
* @param string $method The method to call against each object
*/
public function __construct($method) {
