WordPress.org

Make WordPress Core

Changeset 8743


Ignore:
Timestamp:
08/27/08 06:49:21 (7 years ago)
Author:
westi
Message:

phpDoc updates for formatting functions. See #5638 props scohoust and santosj.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-includes/formatting.php

    r8704 r8743  
    11<?php 
    22/** 
    3  * Main Wordpress Formatting API  
    4  * 
    5  * Handles many functions for formatting output 
     3 * Main Wordpress Formatting API. 
     4 * 
     5 * Handles many functions for formatting output. 
    66 * 
    77 * @package WordPress 
     
    1919 * &#8217;cause today&#8217;s effort makes it worth tomorrow&#8217;s &#8220;holiday&#8221;&#8230; 
    2020 * </code> 
    21  * Code within certain html blocks are skipped.  
     21 * Code within certain html blocks are skipped. 
    2222 * 
    2323 * @since 0.71 
     
    7777 
    7878/** 
    79  * Accepts matches array from preg_replace_callback in wpautop() or a string 
    80  * 
    81  * Ensures that the contents of a <<pre>>...<</pre>> HTML block are not converted into paragraphs or line-breaks. 
     79 * Accepts matches array from preg_replace_callback in wpautop() or a string. 
     80 * 
     81 * Ensures that the contents of a <<pre>>...<</pre>> HTML block are not 
     82 * converted into paragraphs or line-breaks. 
    8283 * 
    8384 * @since 1.2.0 
    8485 * 
    85  * @param array|string $matches The array or string  
     86 * @param array|string $matches The array or string 
    8687 * @return string The pre block without paragraph/line-break conversion. 
    8788 */ 
     
    100101 
    101102/** 
    102  * Replaces double line-breaks with paragraph elements 
    103  * 
    104  * A group of regex replaces used to identify text formatted with newlines and replace 
    105  * double line-breaks with HTML paragraph tags. The remaining line-breaks after conversion 
    106  * become <<br />> tags, unless $br is set to '0' or 'false'.  
    107  *  
     103 * Replaces double line-breaks with paragraph elements. 
     104 * 
     105 * A group of regex replaces used to identify text formatted with newlines and 
     106 * replace double line-breaks with HTML paragraph tags. The remaining 
     107 * line-breaks after conversion become <<br />> tags, unless $br is set to '0' 
     108 *  or 'false'. 
    108109 * 
    109110 * @since 0.71 
    110111 * 
    111112 * @param string $pee The text which has to be formatted. 
    112  * @param int|bool $br Optional. If set, this will convert all remaining line-breaks after paragraphing. Default true.  
    113  * @return string Text which has been converted into correct paragraph tags.  
     113 * @param int|bool $br Optional. If set, this will convert all remaining line-breaks after paragraphing. Default true. 
     114 * @return string Text which has been converted into correct paragraph tags. 
    114115 */ 
    115116function wpautop($pee, $br = 1) { 
     
    180181 
    181182/** 
    182  * Converts a number of special characters into their HTML entities 
    183  * 
    184  * Differs from htmlspecialchars as existing HTML entities will not be encoded. Specificically 
    185  * changes: & to &#038;, < to &lt; and > to &gt;.  
    186  * 
    187  * $quotes can be set to 'single' to encode ' to &#039;, 'double' to encode " to &quot;, or '1' to do both.  
    188  * Default is 0 where no quotes are encoded.  
     183 * Converts a number of special characters into their HTML entities. 
     184 * 
     185 * Differs from htmlspecialchars as existing HTML entities will not be encoded. 
     186 * Specificically changes: & to &#038;, < to &lt; and > to &gt;. 
     187 * 
     188 * $quotes can be set to 'single' to encode ' to &#039;, 'double' to encode " to 
     189 * &quot;, or '1' to do both. Default is 0 where no quotes are encoded. 
    189190 * 
    190191 * @since 1.2.2 
    191192 * 
    192  * @param string $text The text which is to be encoded 
    193  * @param mixed $quotes Optional. Converts single quotes if set to 'single', double if set to 'double' or both if otherwise set. Default 0.  
    194  * @return string The encoded text with HTML entities.  
     193 * @param string $text The text which is to be encoded. 
     194 * @param mixed $quotes Optional. Converts single quotes if set to 'single', double if set to 'double' or both if otherwise set. Default 0. 
     195 * @return string The encoded text with HTML entities. 
    195196 */ 
    196197function wp_specialchars( $text, $quotes = 0 ) { 
     
    265266 
    266267/** 
    267  * Replaces accents in a string 
     268 * Replaces accents in a string. 
    268269 * 
    269270 * {@internal Missing Long Description}} 
     
    272273 * 
    273274 * @param string $string The text to be filtered. 
    274  * @return string Filtered string with replaced "nice" characters 
     275 * @return string Filtered string with replaced "nice" characters. 
    275276 */ 
    276277function remove_accents($string) { 
     
    405406 
    406407/** 
    407  * Filters certain characters from the file name.  
     408 * Filters certain characters from the file name. 
    408409 * 
    409410 * {@internal Missing Long Description}} 
     
    411412 * @since 2.1.0 
    412413 * 
    413  * @param string $name The string to be sanitized 
    414  * @return string Sanitized string 
     414 * @param string $name The string to be sanitized. 
     415 * @return string Sanitized string. 
    415416 */ 
    416417function sanitize_file_name( $name ) { // Like sanitize_title, but with periods 
     
    427428 
    428429/** 
    429  * Removes characters from the username 
    430  * 
    431  * If $strict is true, only alphanumeric characters (as well as _, space, ., -, @) are returned.  
     430 * Removes characters from the username. 
     431 * 
     432 * If $strict is true, only alphanumeric characters (as well as _, space, ., -, 
     433 * @) are returned. 
    432434 * 
    433435 * @since 2.0.0 
    434436 * 
    435  * @param string $username The username to be sanitized.  
    436  * @param bool $strict If set limits $username to specific characters. Default false.  
    437  * @return string The sanitized username, after passing through filters.  
     437 * @param string $username The username to be sanitized. 
     438 * @param bool $strict If set limits $username to specific characters. Default false. 
     439 * @return string The sanitized username, after passing through filters. 
    438440 */ 
    439441function sanitize_user( $username, $strict = false ) { 
     
    455457 
    456458/** 
    457  * Returns a string which has been sanitized.  
    458  * 
    459  * Specifically, HTML and PHP tags are stripped. Further actions can be added via the 
    460  * plugin API. If $title is empty and $fallback_title is set, the latter will be used.  
     459 * Returns a string which has been sanitized. 
     460 * 
     461 * Specifically, HTML and PHP tags are stripped. Further actions can be added 
     462 * via the plugin API. If $title is empty and $fallback_title is set, the latter 
     463 * will be used. 
    461464 * 
    462465 * @since 1.0.0 
    463466 * 
    464  * @param string $title The string to be sanitized.  
    465  * @param string $fallback_title Optional. A title to use if $title is empty.   
    466  * @return string The sanitized string.  
     467 * @param string $title The string to be sanitized. 
     468 * @param string $fallback_title Optional. A title to use if $title is empty. 
     469 * @return string The sanitized string. 
    467470 */ 
    468471function sanitize_title($title, $fallback_title = '') { 
     
    477480 
    478481/** 
    479  * Replaces the string with safe characters. Whitespace becomes a dash.  
    480  * 
    481  * Limits the output to alphanumeric characters, underscore (_) and dash (-).  
     482 * Replaces the string with safe characters. Whitespace becomes a dash. 
     483 * 
     484 * Limits the output to alphanumeric characters, underscore (_) and dash (-). 
    482485 * 
    483486 * @since 1.2.0 
    484487 * 
    485  * @param string $title The title to be sanitized 
    486  * @return string The sanitized title 
     488 * @param string $title The title to be sanitized. 
     489 * @return string The sanitized title. 
    487490 */ 
    488491function sanitize_title_with_dashes($title) { 
     
    514517 
    515518/** 
    516  * Ensures a string is a valid SQL order by clause.  
    517  * 
    518  * Accepts one or more columns, with or without ASC/DESC, and also accepts RAND() 
     519 * Ensures a string is a valid SQL order by clause. 
     520 * 
     521 * Accepts one or more columns, with or without ASC/DESC, and also accepts 
     522 * RAND(). 
    519523 * 
    520524 * @since 2.5.1 
    521525 * 
    522  * @param string $orderby Order by string to be checked 
     526 * @param string $orderby Order by string to be checked. 
    523527 * @return string|false Returns the order by clause if it is a match, false otherwise.  
    524528 */ 
     
    531535 
    532536/** 
    533  * Converts a number of characters from a string 
    534  * 
    535  * Metadata tags <<title>> and <<category>> are removed, <<br>> and <<hr>> are converted into correct 
    536  * XHTML and Unicode characters are converted to the valid range.  
     537 * Converts a number of characters from a string. 
     538 * 
     539 * Metadata tags <<title>> and <<category>> are removed, <<br>> and <<hr>> are 
     540 * converted into correct XHTML and Unicode characters are converted to the 
     541 * valid range. 
    537542 * 
    538543 * @since 0.71 
    539544 * 
    540  * @param string $content String of characters to be converted 
    541  * @param string $deprecated Not used 
     545 * @param string $content String of characters to be converted. 
     546 * @param string $deprecated Not used. 
    542547 * @return string Converted string. 
    543548 */ 
     
    597602 
    598603/** 
    599  * Fixes javascript bugs in browsers.  
     604 * Fixes javascript bugs in browsers. 
    600605 * 
    601606 * {@internal Missing Long Description}} 
     
    605610 * @uses $is_winIE 
    606611 * 
    607  * @param string $text Text to be made safe 
    608  * @return string Fixed text 
     612 * @param string $text Text to be made safe. 
     613 * @return string Fixed text. 
    609614 */ 
    610615function funky_javascript_fix($text) { 
     
    652657 *      1.0  First Version 
    653658 * 
    654  * @param string $text Text to be balanced 
    655  * @return string Balanced text 
     659 * @param string $text Text to be balanced. 
     660 * @return string Balanced text. 
    656661 */ 
    657662function force_balance_tags( $text ) { 
     
    755760 
    756761/** 
    757  * Acts on text which is about to be edited 
    758  * 
    759  * Unless $richedit is set, it is simply a holder for the 'format_to_edit' filter. If $richedit 
    760  * is set true htmlspecialchars() will be run on the content, converting special characters to  
    761  * HTMl entities.  
     762 * Acts on text which is about to be edited. 
     763 * 
     764 * Unless $richedit is set, it is simply a holder for the 'format_to_edit' 
     765 * filter. If $richedit is set true htmlspecialchars() will be run on the 
     766 * content, converting special characters to HTMl entities. 
    762767 * 
    763768 * @since 0.71 
    764769 * 
    765  * @param string $content The text about to be edited.  
    766  * @param bool $richedit Whether or not the $content should pass through htmlspecialchars(). Default false.  
    767  * @return string The text after the filter (and possibly htmlspecialchars()) has been run.  
     770 * @param string $content The text about to be edited. 
     771 * @param bool $richedit Whether or not the $content should pass through htmlspecialchars(). Default false. 
     772 * @return string The text after the filter (and possibly htmlspecialchars()) has been run. 
    768773 */ 
    769774function format_to_edit($content, $richedit = false) { 
     
    782787 * 
    783788 * @param string $content The text to pass through the filter. 
    784  * @return string Text returned from the 'format_to_post' filter.  
     789 * @return string Text returned from the 'format_to_post' filter. 
    785790 */ 
    786791function format_to_post($content) { 
     
    790795 
    791796/** 
    792  * Add leading zeros when necessary 
     797 * Add leading zeros when necessary. 
    793798 * 
    794799 * {@internal Missing Long Description}} 
     
    821826 
    822827/** 
    823  * Appends a trailing slash 
    824  * 
    825  * Will remove trailing slash if it exists already before adding 
    826  * a trailing slash. This prevents double slashing a string or 
    827  * path. 
    828  * 
    829  * The primary use of this is for paths and thus should be used 
    830  * for paths. It is not restricted to paths and offers no specific 
    831  * path support. 
     828 * Appends a trailing slash. 
     829 * 
     830 * Will remove trailing slash if it exists already before adding a trailing 
     831 * slash. This prevents double slashing a string or path. 
     832 * 
     833 * The primary use of this is for paths and thus should be used for paths. It is 
     834 * not restricted to paths and offers no specific path support. 
    832835 * 
    833836 * @since 1.2.0 
    834  * @uses untrailingslashit() Unslashes string if it was slashed already 
    835  * 
    836  * @param string $string What to add the trailing slash to 
    837  * @return string String with trailing slash added 
     837 * @uses untrailingslashit() Unslashes string if it was slashed already. 
     838 * 
     839 * @param string $string What to add the trailing slash to. 
     840 * @return string String with trailing slash added. 
    838841 */ 
    839842function trailingslashit($string) { 
     
    842845 
    843846/** 
    844  * Removes trailing slash if it exists 
    845  * 
    846  * The primary use of this is for paths and thus should be used 
    847  * for paths. It is not restricted to paths and offers no specific 
    848  * path support. 
     847 * Removes trailing slash if it exists. 
     848 * 
     849 * The primary use of this is for paths and thus should be used for paths. It is 
     850 * not restricted to paths and offers no specific path support. 
    849851 * 
    850852 * @since 2.2.0 
    851853 * 
    852  * @param string $string What to remove the trailing slash from 
    853  * @return string String without the trailing slash 
     854 * @param string $string What to remove the trailing slash from. 
     855 * @return string String without the trailing slash. 
    854856 */ 
    855857function untrailingslashit($string) { 
     
    858860 
    859861/** 
    860  * addslashes_gpc() - {@internal Missing Short Description}} 
    861  * 
    862  * {@internal Missing Long Description}} 
     862 * Adds slashes to escape strings. 
     863 * 
     864 * Slashes will first be removed if magic_quotes_gpc is set,  
     865 * see {@link http://www.php.net/magic_quotes} for more details.  
    863866 * 
    864867 * @since 0.71 
    865868 * 
    866  * @param unknown_type $gpc 
    867  * @return unknown 
     869 * @param string $gpc The string returned from HTTP request data. 
     870 * @return string Returns a string escaped with slashes.  
    868871 */ 
    869872function addslashes_gpc($gpc) { 
     
    878881 
    879882/** 
    880  * stripslashes_deep() - {@internal Missing Short Description}} 
    881  * 
    882  * {@internal Missing Long Description}} 
     883 * Navigates through an array and removes slashes from the values. 
     884 * 
     885 * If an array is passed, the array_map() function causes a callback to 
     886 * pass the value back to the function. The slashes from this value will 
     887 * removed.  
    883888 * 
    884889 * @since 2.0.0 
    885890 * 
    886  * @param unknown_type $value 
    887  * @return unknown 
     891 * @param array|string $value The array or string to be striped. 
     892 * @return array|string Stripped array (or string in the callback). 
    888893 */ 
    889894function stripslashes_deep($value) { 
     
    896901 
    897902/** 
    898  * urlencode_deep() - {@internal Missing Short Description}} 
    899  * 
    900  * {@internal Missing Long Description}} 
     903 * Navigates through an array and encodes the values to be used in a URL. 
     904 * 
     905 * Uses a callback to pass the value of the array back to the function as a  
     906 * string.  
    901907 * 
    902908 * @since 2.2.0 
    903909 * 
    904  * @param unknown_type $value 
    905  * @return unknown 
     910 * @param array|string $value The array or string to be encoded. 
     911 * @return array|string $value The encoded array (or string from the callback). 
    906912 */ 
    907913function urlencode_deep($value) { 
     
    946952 * {@internal Missing Long Description}} 
    947953 * 
    948  * @since 2.5 
     954 * @since 2.5.0 
    949955 * @access private 
    950956 * 
     
    971977 * {@internal Missing Long Description}} 
    972978 * 
    973  * @since 2.5 
     979 * @since 2.5.0 
    974980 * @access private 
    975981 * 
     
    9971003 * {@internal Missing Long Description}} 
    9981004 * 
    999  * @since 2.5 
     1005 * @since 2.5.0 
    10001006 * @access private 
    10011007 * 
     
    10971103 
    10981104/** 
    1099  * is_email() - {@internal Missing Short Description}} 
     1105 * Checks to see if the text is a valid email address. 
    11001106 * 
    11011107 * {@internal Missing Long Description}} 
     
    11031109 * @since 0.71 
    11041110 * 
    1105  * @param unknown_type $user_email 
    1106  * @return unknown 
     1111 * @param string $user_email The email address to be checked. 
     1112 * @return bool Returns true if valid, otherwise false. 
    11071113 */ 
    11081114function is_email($user_email) { 
     
    11421148 
    11431149/** 
    1144  * get_gmt_from_date() - Give it a date, it will give you the same date as GMT 
    1145  * 
    1146  * {@internal Missing Long Description}} 
     1150 * Returns a date in the GMT equivalent. 
     1151 * 
     1152 * Requires and returns a date in the Y-m-d H:i:s format. 
     1153 * Simply subtracts the value of gmt_offset. 
    11471154 * 
    11481155 * @since 1.2.0 
    11491156 * 
    1150  * @param unknown_type $string 
    1151  * @return unknown 
     1157 * @param string $string The date to be converted. 
     1158 * @return string GMT version of the date provided. 
    11521159 */ 
    11531160function get_gmt_from_date($string) { 
    1154     // note: this only substracts $time_difference from the given date 
    11551161    preg_match('#([0-9]{1,4})-([0-9]{1,2})-([0-9]{1,2}) ([0-9]{1,2}):([0-9]{1,2}):([0-9]{1,2})#', $string, $matches); 
    11561162    $string_time = gmmktime($matches[4], $matches[5], $matches[6], $matches[2], $matches[3], $matches[1]); 
     
    11601166 
    11611167/** 
    1162  * get_date_from_gmt() - Give it a GMT date, it will give you the same date with $time_difference added 
    1163  * 
    1164  * {@internal Missing Long Description}} 
     1168 * Converts a GMT date into the correct format for the blog. 
     1169 * 
     1170 * Requires and returns in the Y-m-d H:i:s format. Simply 
     1171 * adds the value of gmt_offset. 
    11651172 * 
    11661173 * @since 1.2.0 
    11671174 * 
    1168  * @param unknown_type $string 
    1169  * @return unknown 
     1175 * @param string $string The date to be converted. 
     1176 * @return string Formatted date relative to the GMT offset. 
    11701177 */ 
    11711178function get_date_from_gmt($string) { 
    1172     // note: this only adds $time_difference to the given date 
    11731179    preg_match('#([0-9]{1,4})-([0-9]{1,2})-([0-9]{1,2}) ([0-9]{1,2}):([0-9]{1,2}):([0-9]{1,2})#', $string, $matches); 
    11741180    $string_time = gmmktime($matches[4], $matches[5], $matches[6], $matches[2], $matches[3], $matches[1]); 
     
    11781184 
    11791185/** 
    1180  * iso8601_timezone_to_offset() - Computes an offset in seconds from an iso8601 timezone 
     1186 * Computes an offset in seconds from an iso8601 timezone. 
    11811187 * 
    11821188 * {@internal Missing Long Description}} 
     
    11841190 * @since 1.5.0 
    11851191 * 
    1186  * @param unknown_type $timezone 
    1187  * @return unknown 
     1192 * @param string $timezone Either 'Z' for 0 offset or '±hhmm'. 
     1193 * @return int|float The offset in seconds.  
    11881194 */ 
    11891195function iso8601_timezone_to_offset($timezone) { 
     
    12011207 
    12021208/** 
    1203  * iso8601_to_datetime() - Converts an iso8601 date to MySQL DateTime format used by post_date[_gmt] 
     1209 * Converts an iso8601 date to MySQL DateTime format used by post_date[_gmt]. 
    12041210 * 
    12051211 * {@internal Missing Long Description}} 
     
    12071213 * @since 1.5.0 
    12081214 * 
    1209  * @param unknown_type $date_string 
    1210  * @param unknown_type $timezone 
    1211  * @return unknown 
     1215 * @param string $date_string Date and time in ISO 8601 format {@link http://en.wikipedia.org/wiki/ISO_8601}. 
     1216 * @param unknown_type $timezone Optional. If set to GMT returns the time minus gmt_offset. Default USER. 
     1217 * @return string The date and time in MySQL DateTime format - Y-m-d H:i:s. 
    12121218 */ 
    12131219function iso8601_to_datetime($date_string, $timezone = USER) { 
     
    12331239 
    12341240/** 
    1235  * Adds a element attributes to open links in new windows 
    1236  * 
    1237  * Comment text in popup windows should be filtered through this. Right 
    1238  * now it's a moderately dumb function, ideally it would detect whether 
    1239  * a target or rel attribute was already there and adjust its actions 
    1240  * accordingly. 
     1241 * Adds a element attributes to open links in new windows. 
     1242 * 
     1243 * Comment text in popup windows should be filtered through this. Right now it's 
     1244 * a moderately dumb function, ideally it would detect whether a target or rel 
     1245 * attribute was already there and adjust its actions accordingly. 
    12411246 * 
    12421247 * @since 0.71 
    12431248 * 
    1244  * @param string $text Content to replace links to open in a new window 
    1245  * @return string Content that has filtered links 
     1249 * @param string $text Content to replace links to open in a new window. 
     1250 * @return string Content that has filtered links. 
    12461251 */ 
    12471252function popuplinks($text) { 
     
    12511256 
    12521257/** 
    1253  * Strips out all characters that are not allowable in an email 
     1258 * Strips out all characters that are not allowable in an email. 
    12541259 * 
    12551260 * @since 1.5.0 
    12561261 * 
    1257  * @param string $email Email address to filter 
    1258  * @return string Filtered email address 
     1262 * @param string $email Email address to filter. 
     1263 * @return string Filtered email address. 
    12591264 */ 
    12601265function sanitize_email($email) { 
     
    12631268 
    12641269/** 
    1265  * human_time_diff() - {@internal Missing Short Description}} 
    1266  * 
    1267  * {@internal Missing Long Description}} 
     1270 * Determines the difference between two timestamps. 
     1271 * 
     1272 * The difference is returned in a human readable format such as 
     1273 * "1 hour", "5 mins", "2 days".  
    12681274 * 
    12691275 * @since 1.5.0 
    12701276 * 
    1271  * @param unknown_type $from 
    1272  * @param unknown_type $to 
    1273  * @return unknown 
     1277 * @param int $from Unix timestamp from which the difference begins. 
     1278 * @param int $to Optional. Unix timestamp to end the time difference. Default becomes time() if not set. 
     1279 * @return string Human readable time difference. 
    12741280 */ 
    12751281function human_time_diff( $from, $to = '' ) { 
     
    13001306 
    13011307/** 
    1302  * wp_trim_excerpt() - {@internal Missing Short Description}} 
     1308 * Generates an excerpt from the content if needed. 
    13031309 * 
    13041310 * {@internal Missing Long Description}} 
     
    13061312 * @since 1.5.0 
    13071313 * 
    1308  * @param unknown_type $text 
    1309  * @return unknown 
     1314 * @param string $text The exerpt. If set to empty an excerpt is generated. 
     1315 * @return string The excerpt. 
    13101316 */ 
    13111317function wp_trim_excerpt($text) { // Fakes an excerpt if needed 
     
    13301336 
    13311337/** 
    1332  * ent2ncr() - {@internal Missing Short Description}} 
     1338 * Converts named entities into numbered entities. 
    13331339 * 
    13341340 * {@internal Missing Long Description}} 
     
    13361342 * @since 1.5.1 
    13371343 * 
    1338  * @param unknown_type $text 
    1339  * @return unknown 
     1344 * @param string $text The text within which entities will be converted. 
     1345 * @return string Text with converted entities.  
    13401346 */ 
    13411347function ent2ncr($text) { 
     
    16041610 
    16051611/** 
    1606  * wp_richedit_pre() - {@internal Missing Short Description}} 
    1607  * 
    1608  * {@internal Missing Long Description}} 
     1612 * Formats text for the rich text editor and applies filter. 
     1613 * 
     1614 * The filter 'richedit_pre' is applied here. If $text is empty 
     1615 * the filter will be applied to an empty string. 
    16091616 * 
    16101617 * @since 2.0.0 
    16111618 * 
    1612  * @param unknown_type $text 
    1613  * @return unknown 
     1619 * @param string $text The text to be formatted. 
     1620 * @return string The formatted text after filter is applied. 
    16141621 */ 
    16151622function wp_richedit_pre($text) { 
     
    16241631} 
    16251632 
     1633/** 
     1634 * Formats text for the HTML editor and applies a filter. 
     1635 * 
     1636 * Unless $output is empty it will pass through htmlspecialchars 
     1637 * before the 'htmledit_pre' filter is applied. 
     1638 * 
     1639 * @since unknown 
     1640 * 
     1641 * @param string $output The text to be formatted. 
     1642 * @return string Formatted text after filter applied. 
     1643 */ 
    16261644function wp_htmledit_pre($output) { 
    16271645    if ( !empty($output) ) 
     
    16321650 
    16331651/** 
    1634  * clean_url() - {@internal Missing Short Description}} 
    1635  * 
    1636  * {@internal Missing Long Description}} 
     1652 * Checks and cleans a URL.  
     1653 * 
     1654 * A number of characters are removed from the URL. If the URL is 
     1655 * for displaying (the default behaviour) amperstands are also replaced. 
     1656 * The 'clean_url' filter is applied to the returned cleaned URL. 
    16371657 * 
    16381658 * @since 1.2.0 
    1639  * 
    1640  * @param unknown_type $url 
    1641  * @param unknown_type $protocols 
    1642  * @param unknown_type $context 
    1643  * @return unknown 
     1659 * @uses wp_kses_bad_protocol() To only permit protocols in the URL set 
     1660 *  via $protocols or the common ones set in the function. 
     1661 * 
     1662 * @param string $url The URL to be cleaned. 
     1663 * @param array $protocols Optional. An array of acceptable protocols.  
     1664 *      Defaults to 'http', 'https', 'ftp', 'ftps', 'mailto', 'news', 'irc', 'gopher', 'nntp', 'feed', 'telnet' if not set.  
     1665 * @param string $context Optional. How the URL will be used. Default is 'display'.  
     1666 * @return string The cleaned $url after the 'cleaned_url' filter is applied. 
    16441667 */ 
    16451668function clean_url( $url, $protocols = null, $context = 'display' ) { 
     
    16591682        $url = 'http://' . $url; 
    16601683 
    1661     // Replace ampersands ony when displaying. 
     1684    // Replace ampersands only when displaying. 
    16621685    if ( 'display' == $context ) 
    16631686        $url = preg_replace('/&([^#])(?![a-z]{2,8};)/', '&#038;$1', $url); 
     
    16721695 
    16731696/** 
    1674  * sanitize_url() - {@internal Missing Short Description}} 
    1675  * 
    1676  * {@internal Missing Long Description}} 
     1697 * Performs clean_url() for database usage. 
     1698 * 
     1699 * @see clean_url() 
    16771700 * 
    16781701 * @since 2.3.1 
    16791702 * 
    1680  * @param unknown_type $url 
    1681  * @param unknown_type $protocols 
    1682  * @return unknown 
     1703 * @param string $url The URL to be cleaned. 
     1704 * @param array $protocols An array of acceptable protocols. 
     1705 * @return string The cleaned URL. 
    16831706 */ 
    16841707function sanitize_url( $url, $protocols = null ) { 
     
    16871710 
    16881711/** 
    1689  * Convert entities, while preserving already-encoded entities 
     1712 * Convert entities, while preserving already-encoded entities. 
    16901713 * 
    16911714 * {@internal Missing Long Description}} 
     
    16951718 * @since 1.2.2 
    16961719 * 
    1697  * @param unknown_type $myHTML 
    1698  * @return unknown 
     1720 * @param string $myHTML The text to be converted. 
     1721 * @return string Converted text. 
    16991722 */ 
    17001723function htmlentities2($myHTML) { 
     
    17051728 
    17061729/** 
    1707  * Escape single quotes, specialchar double quotes, and fix line endings 
    1708  * 
    1709  * {@internal Missing Long Description}} 
     1730 * Escape single quotes, specialchar double quotes, and fix line endings. 
     1731 * 
     1732 * The filter 'js_escape' is also applied here. 
    17101733 * 
    17111734 * @since 2.0.4 
    17121735 * 
    1713  * @param string $text 
    1714  * @return unknown 
     1736 * @param string $text The text to be escaped. 
     1737 * @return string Escaped text. 
    17151738 */ 
    17161739function js_escape($text) { 
     
    17211744} 
    17221745 
    1723 // Escaping for HTML attributes 
     1746/** 
     1747 * Escaping for HTML attributes. 
     1748 * 
     1749 * @since unknown 
     1750 * 
     1751 * @param string $text 
     1752 * @return string 
     1753 */ 
    17241754function attribute_escape($text) { 
    17251755    $safe_text = wp_specialchars($text, true); 
     
    17271757} 
    17281758 
    1729 // Escape a HTML tag name 
     1759/** 
     1760 * Escape a HTML tag name. 
     1761 * 
     1762 * @since unknown 
     1763 * 
     1764 * @param string $tag_name 
     1765 * @return string 
     1766 */ 
    17301767function tag_escape($tag_name) { 
    17311768    $safe_tag = strtolower( preg_replace('[^a-zA-Z_:]', '', $tag_name) ); 
     
    17341771 
    17351772/** 
    1736  * Escapes text for SQL LIKE special characters % and _ 
    1737  * 
    1738  * @param string text the text to be escaped 
    1739  * @return string text, safe for inclusion in LIKE query 
     1773 * Escapes text for SQL LIKE special characters % and _. 
     1774 * 
     1775 * @since unknown 
     1776 * 
     1777 * @param string $text The text to be escaped. 
     1778 * @return string text, safe for inclusion in LIKE query. 
    17401779 */ 
    17411780function like_escape($text) { 
     
    17431782} 
    17441783 
     1784/** 
     1785 * {@internal Missing Short Description}} 
     1786 * 
     1787 * @since unknown 
     1788 * 
     1789 * @param string $link 
     1790 * @return string 
     1791 */ 
    17451792function wp_make_link_relative( $link ) { 
    17461793    return preg_replace('|https?://[^/]+(/.*)|i', '$1', $link ); 
    17471794} 
    17481795 
     1796/** 
     1797 * Sanitises various option values based on the nature of the option. 
     1798 * 
     1799 * This is basically a switch statement which will pass $value through 
     1800 * a number of functions depending on the $option.  
     1801 * 
     1802 * @since 2.0.5 
     1803 * 
     1804 * @param string $option The name of the option. 
     1805 * @param string $value The unsanitised value. 
     1806 * @return string Sanitized value. 
     1807 */ 
    17491808function sanitize_option($option, $value) { // Remember to call stripslashes! 
    17501809 
     
    18221881 
    18231882/** 
    1824  * wp_parse_str() - {@internal Missing Short Description}} 
    1825  * 
    1826  * {@internal Missing Long Description}} 
     1883 * Parses a string into variables to be stored in an array. 
     1884 * 
     1885 * Uses {@link http://www.php.net/parse_str parse_str()} and stripslashes 
     1886 * if {@link http://www.php.net/magic_quotes magic_quotes_gpc} is on. 
    18271887 * 
    18281888 * @since 2.2.1 
    1829  * @uses apply_filters()  
    1830  * 
    1831  * @param string $string 
    1832  * @param array $array 
     1889 * @uses apply_filters() for the 'wp_parse_str' filter. 
     1890 * 
     1891 * @param string $string The string to be parsed. 
     1892 * @param array $array Variables will be stored in this array. 
    18331893 */ 
    18341894function wp_parse_str( $string, &$array ) { 
    18351895    parse_str( $string, $array ); 
    18361896    if ( get_magic_quotes_gpc() ) 
    1837         $array = stripslashes_deep( $array ); // parse_str() adds slashes if magicquotes is on.  See: http://php.net/parse_str 
     1897        $array = stripslashes_deep( $array ); 
    18381898    $array = apply_filters( 'wp_parse_str', $array ); 
    18391899} 
    18401900 
    1841 // Convert lone less than signs.  KSES already converts lone greater than signs. 
     1901/** 
     1902 * Convert lone less than signs. 
     1903 * 
     1904 * KSES already converts lone greater than signs.  
     1905 * 
     1906 * @uses wp_pre_kses_less_than_callback in the callback function. 
     1907 * @since unknown 
     1908 * 
     1909 * @param string $text Text to be converted. 
     1910 * @return string Converted text. 
     1911 */ 
    18421912function wp_pre_kses_less_than( $text ) { 
    18431913    return preg_replace_callback('%<[^>]*?((?=<)|>|$)%', 'wp_pre_kses_less_than_callback', $text); 
    18441914} 
    18451915 
     1916/** 
     1917 * Callback function used by preg_replace. 
     1918 * 
     1919 * @since unknown 
     1920 * @uses wp_specialchars to format the $matches text. 
     1921 * 
     1922 * @param array $matches Populated by matches to preg_replace. 
     1923 * @return string The text returned after wp_specialchars if needed. 
     1924 */ 
    18461925function wp_pre_kses_less_than_callback( $matches ) { 
    18471926    if ( false === strpos($matches[0], '>') ) 
     
    18511930 
    18521931/** 
    1853  * wp_sprintf() - sprintf() with filters 
     1932 * WordPress implementation of PHP sprintf() with filters. 
     1933 * 
     1934 * @since unknown 
     1935 * @link http://www.php.net/sprintf 
     1936 * 
     1937 * @param string $pattern The string which formatted args are inserted. 
     1938 * @param mixed $args,... Arguments to be formatted into the $pattern string. 
     1939 * @return string The formatted string. 
    18541940 */ 
    18551941function wp_sprintf( $pattern ) { 
     
    19061992 
    19071993/** 
    1908  * wp_sprintf_l - List specifier %l for wp_sprintf 
     1994 * List specifier %l for wp_sprintf. 
     1995 * 
     1996 * @since unknown 
    19091997 * 
    19101998 * @param unknown_type $pattern 
     
    19442032 
    19452033/** 
    1946  * Safely extracts not more than the first $count characters from html string 
    1947  * 
    1948  * UTF-8, tags and entities safe prefix extraction. Entities inside will *NOT* be 
    1949  * counted as one character. For example &amp; will be counted as 4, &lt; as 3, etc. 
    1950  * 
    1951  * @param integer $str String to get the excerpt from 
    1952  * @param integer $count Maximum number of characters to take 
    1953  * @return string the excerpt 
     2034 * Safely extracts not more than the first $count characters from html string. 
     2035 * 
     2036 * UTF-8, tags and entities safe prefix extraction. Entities inside will *NOT* 
     2037 * be counted as one character. For example &amp; will be counted as 4, &lt; as 
     2038 * 3, etc. 
     2039 * 
     2040 * @param integer $str String to get the excerpt from. 
     2041 * @param integer $count Maximum number of characters to take. 
     2042 * @return string The excerpt. 
    19542043 */ 
    19552044function wp_html_excerpt( $str, $count ) { 
     
    19702059 * @since 2.7 
    19712060 * 
    1972  * @param string $content String to search for links in 
    1973  * @param string $base The base URL to prefix to links 
     2061 * @param string $content String to search for links in. 
     2062 * @param string $base The base URL to prefix to links. 
    19742063 * @param array $attrs The attributes which should be processed. 
    1975  * @eaturn string The processed content. 
     2064 * @return string The processed content. 
    19762065 */ 
    19772066function links_add_base_url( $content, $base, $attrs = array('src', 'href') ) { 
     
    19892078 * @since 2.7 
    19902079 * 
    1991  * @internal 
    1992  * @param string $m The matched link 
    1993  * @param string $base The base URL to prefix to links 
    1994  * @eaturn string The processed link 
     2080 * @param string $m The matched link. 
     2081 * @param string $base The base URL to prefix to links. 
     2082 * @return string The processed link. 
    19952083 */ 
    19962084function _links_add_base($m, $base) { 
     
    20132101 * @since 2.7 
    20142102 * 
    2015  * @param string $content String to search for links in 
    2016  * @param string $target The Target to add to the links 
     2103 * @param string $content String to search for links in. 
     2104 * @param string $target The Target to add to the links. 
    20172105 * @param array $tags An array of tags to apply to. 
    2018  * @eaturn string The processed content. 
     2106 * @return string The processed content. 
    20192107 */ 
    20202108function links_add_target( $content, $target = '_blank', $tags = array('a') ) { 
     
    20252113} 
    20262114/** 
    2027  * Callback to add a target attribute to all links in passed content 
     2115 * Callback to add a target attribute to all links in passed content. 
    20282116 * 
    20292117 * 
     
    20312119 * @since 2.7 
    20322120 * 
    2033  * @internal 
    2034  * @param string $m The matched link 
    2035  * @param string $target The Target to add to the links 
    2036  * @eaturn string The processed link. 
     2121 * @param string $m The matched link. 
     2122 * @param string $target The Target to add to the links. 
     2123 * @return string The processed link. 
    20372124 */ 
    20382125function _links_add_target( $m, $target ) { 
Note: See TracChangeset for help on using the changeset viewer.