Changeset 8662

Show
Ignore:
Timestamp:
08/17/08 11:29:43 (3 months ago)
Author:
westi
Message:

phpdoc for formatting functions. See #5638 props scohoust.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/wp-includes/formatting.php

    r8600 r8662  
    11<?php 
    2  
     2/** 
     3 * Main Wordpress Formatting API  
     4 * 
     5 * Handles many functions for formatting output 
     6 * 
     7 * @package WordPress 
     8 **/ 
     9 
     10/** 
     11 * Replaces common plain text characters into formatted entities 
     12 * 
     13 * As an example,  
     14 * <code> 
     15 * 'cause today's effort makes it worth tomorrow's "holiday"... 
     16 * </code> 
     17 * Becomes: 
     18 * <code> 
     19 * &#8217;cause today&#8217;s effort makes it worth tomorrow&#8217;s &#8220;holiday&#8221;&#8230; 
     20 * </code> 
     21 * Code within certain html blocks are skipped.  
     22 * 
     23 * @since 0.71 
     24 * @uses $wp_cockneyreplace Array of formatted entities for certain common phrases 
     25 * 
     26 * @param string $text The text to be formatted 
     27 * @return string The string replaced with html entities 
     28 */ 
    329function wptexturize($text) { 
    430    global $wp_cockneyreplace; 
    …… 
    5076} 
    5177 
    52 // Accepts matches array from preg_replace_callback in wpautop() 
    53 // or a string 
     78/** 
     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. 
     82 * 
     83 * @since 1.2.0 
     84 * 
     85 * @param array|string $matches The array or string  
     86 * @return string The pre block without paragraph/line-break conversion. 
     87 */ 
    5488function clean_pre($matches) { 
    5589    if ( is_array($matches) ) 
    …… 
    6599} 
    66100 
     101/** 
     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 *  
     108 * 
     109 * @since 0.71 
     110 * 
     111 * @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.  
     114 */ 
    67115function wpautop($pee, $br = 1) { 
    68116    $pee = $pee . "\n"; // just to make things a little easier, pad the end 
    …… 
    103151} 
    104152 
    105  
     153/** 
     154 * Checks to see if a string is utf8 encoded. 
     155 * 
     156 * {@internal Missing Long Description}} 
     157 * 
     158 * @since 1.2.1 
     159 * 
     160 * @param string $Str The string to be checked 
     161 * @return bool True if $Str fits a UTF-8 model, false otherwise. 
     162 */ 
    106163function seems_utf8($Str) { # by bmorel at ssi dot fr 
    107164    $length = strlen($Str); 
    …… 
    122179} 
    123180 
     181/** 
     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.  
     189 * 
     190 * @since 1.2.2 
     191 * 
     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.  
     195 */ 
    124196function wp_specialchars( $text, $quotes = 0 ) { 
    125197    // Like htmlspecialchars except don't double-encode HTML entities 
    …… 
    140212} 
    141213 
     214/** 
     215 * {@internal Missing Short Description}} 
     216 * 
     217 * {@internal Missing Long Description}} 
     218 * 
     219 * @since 1.5.0 
     220 * 
     221 * @param unknown_type $utf8_string 
     222 * @param unknown_type $length 
     223 * @return unknown 
     224 */ 
    142225function utf8_uri_encode( $utf8_string, $length = 0 ) { 
    143226    $unicode = ''; 
    …… 
    181264} 
    182265 
     266/** 
     267 * Replaces accents in a string 
     268 * 
     269 * {@internal Missing Long Description}} 
     270 * 
     271 * @since 1.2.1 
     272 * 
     273 * @param string $string The text to be filtered. 
     274 * @return string Filtered string with replaced "nice" characters 
     275 */ 
    183276function remove_accents($string) { 
    184277    if ( !preg_match('/[\x80-\xff]/', $string) ) 
    …… 
    311404} 
    312405 
     406/** 
     407 * Filters certain characters from the file name.  
     408 * 
     409 * {@internal Missing Long Description}} 
     410 * 
     411 * @since 2.1.0 
     412 * 
     413 * @param string $name The string to be sanitized 
     414 * @return string Sanitized string 
     415 */ 
    313416function sanitize_file_name( $name ) { // Like sanitize_title, but with periods 
    314417    $name = strtolower( $name ); 
    …… 
    320423    $name = trim($name, '-'); 
    321424    return $name; 
    322 } 
    323  
     425     
     426} 
     427 
     428/** 
     429 * Removes characters from the username 
     430 * 
     431 * If $strict is true, only alphanumeric characters (as well as _, space, ., -, @) are returned.  
     432 * 
     433 * @since 2.0.0 
     434 * 
     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.  
     438 */ 
    324439function sanitize_user( $username, $strict = false ) { 
    325440    $raw_username = $username; 
    …… 
    336451} 
    337452 
     453/** 
     454 * Returns a string which has been sanitized.  
     455 * 
     456 * Specifically, HTML and PHP tags are stripped. Further actions can be added via the 
     457 * plugin API. If $title is empty and $fallback_title is set, the latter will be used.  
     458 * 
     459 * @since 1.0.0 
     460 * 
     461 * @param string $title The string to be sanitized.  
     462 * @param string $fallback_title Optional. A title to use if $title is empty.   
     463 * @return string The sanitized string.  
     464 */ 
    338465function sanitize_title($title, $fallback_title = '') { 
    339466    $title = strip_tags($title); 
    …… 
    346473} 
    347474 
     475/** 
     476 * Replaces the string with safe characters. Whitespace becomes a dash.  
     477 * 
     478 * Limits the output to alphanumeric characters, underscore (_) and dash (-).  
     479 * 
     480 * @since 1.2.0 
     481 * 
     482 * @param string $title The title to be sanitized 
     483 * @return string The sanitized title 
     484 */ 
    348485function sanitize_title_with_dashes($title) { 
    349486    $title = strip_tags($title); 
    …… 
    373510} 
    374511 
    375 // ensures a string is a valid SQL order by clause like: post_name ASC, ID DESC 
    376 // accepts one or more columns, with or without ASC/DESC, and also accepts RAND() 
     512/** 
     513 * Ensures a string is a valid SQL order by clause.  
     514 * 
     515 * Accepts one or more columns, with or without ASC/DESC, and also accepts RAND() 
     516 * 
     517 * @since 2.5.1 
     518 * 
     519 * @param string $orderby Order by string to be checked 
     520 * @return string|false Returns the order by clause if it is a match, false otherwise.  
     521 */ 
    377522function sanitize_sql_orderby( $orderby ){ 
    378523    preg_match('/^\s*([a-z0-9_]+(\s+(ASC|DESC))?(\s*,\s*|\s*$))+|^\s*RAND\(\s*\)\s*$/i', $orderby, $obmatches); 
    …… 
    382527} 
    383528 
     529/** 
     530 * Converts a number of characters from a string 
     531 * 
     532 * Metadata tags <<title>> and <<category>> are removed, <<br>> and <<hr>> are converted into correct 
     533 * XHTML and Unicode characters are converted to the valid range.  
     534 * 
     535 * @since 0.71 
     536 * 
     537 * @param string $content String of characters to be converted 
     538 * @param string $deprecated Not used 
     539 * @return string Converted string. 
     540 */ 
    384541function convert_chars($content, $deprecated = '') { 
    385542    // Translation of invalid Unicode references range to valid range 
    …… 
    436593} 
    437594 
     595/** 
     596 * Fixes javascript bugs in browsers.  
     597 * 
     598 * {@internal Missing Long Description}} 
     599 * 
     600 * @since 1.5.0 
     601 * @uses $is_macIE 
     602 * @uses $is_winIE 
     603 * 
     604 * @param string $text Text to be made safe 
     605 * @return string Fixed text 
     606 */ 
    438607function funky_javascript_fix($text) { 
    439608    // Fixes for browsers' javascript bugs 
    …… 
    446615} 
    447616 
     617/** 
     618 * balanceTags() - {@internal Missing Short Description}} 
     619 * 
     620 * {@internal Missing Long Description}} 
     621 * 
     622 * @since 0.71 
     623 * 
     624 * @param string $text Text to be balanced 
     625 * @param bool $force Forces balancing, ignoring the value of the option. Default false. 
     626 * @return string Balanced text 
     627 */ 
    448628function balanceTags( $text, $force = false ) { 
    449629    if ( !$force && get_option('use_balanceTags') == 0 ) 
    …… 
    452632} 
    453633 
    454 /* 
    455  force_balance_tags 
    456  
    457  Balances Tags of string using a modified stack. 
    458  
    459  @param text      Text to be balanced 
    460  @param force     Forces balancing, ignoring the value of the option 
    461  @return          Returns balanced text 
    462  @author          Leonard Lin (leonard@acm.org) 
    463  @version         v1.1 
    464  @date            November 4, 2001 
    465  @license         GPL v2.0 
    466  @notes 
    467  @changelog 
    468  ---  Modified by Scott Reilly (coffee2code) 02 Aug 2004 
    469     1.2  ***TODO*** Make better - change loop condition to $text 
    470     1.1  Fixed handling of append/stack pop order of end text 
    471          Added Cleaning Hooks 
    472     1.0  First Version 
    473 */ 
     634/** 
     635 * Balances tags of string using a modified stack. 
     636 * 
     637 * {@internal Missing Long Description}} 
     638 * 
     639 * @since 2.0.4 
     640 * 
     641 * @author Leonard Lin <leonard@acm.org> 
     642 * @license GPL v2.0 
     643 * @date November 4, 2001 
     644 * @version 1.1 
     645 * @todo Make better - change loop condition to $text in 1.2 
     646 * @internal Modified by Scott Reilly (coffee2code) 02 Aug 2004 
     647 *     1.1  Fixed handling of append/stack pop order of end text 
     648 *          Added Cleaning Hooks 
     649 *      1.0  First Version 
     650 * 
     651 * @param string $text Text to be balanced 
     652 * @return string Balanced text 
     653 */ 
    474654function force_balance_tags( $text ) { 
    475655    $tagstack = array(); $stacksize = 0; $tagqueue = ''; $newtext = ''; 
    …… 
    571751} 
    572752 
     753/** 
     754 * Acts on text which is about to be edited 
     755 * 
     756 * Unless $richedit is set, it is simply a holder for the 'format_to_edit' filter. If $richedit 
     757 * is set true htmlspecialchars() will be run on the content, converting special characters to  
     758 * HTMl entities.  
     759 * 
     760 * @since 0.71 
     761 * 
     762 * @param string $content The text about to be edited.  
     763 * @param bool $richedit Whether or not the $content should pass through htmlspecialchars(). Default false.  
     764 * @return string The text after the filter (and possibly htmlspecialchars()) has been run.  
     765 */ 
    573766function format_to_edit($content, $richedit = false) { 
    574767    $content = apply_filters('format_to_edit', $content); 
    …… 
    578771} 
    579772 
     773/** 
     774 * Holder for the 'format_to_post' filter. 
     775 * 
     776 * {@internal Deprecated? Unused in 2.6}} 
     777 * 
     778 * @since 0.71 
     779 * 
     780 * @param string $content The text to pass through the filter. 
     781 * @return string Text returned from the 'format_to_post' filter.  
     782 */ 
    580783function format_to_post($content) { 
    581784    $content = apply_filters('format_to_post', $content); 
    …… 
    583786} 
    584787 
    585 function zeroise($number,$threshold) { // function to add leading zeros when necessary 
     788/** 
     789 * Add leading zeros when necessary 
     790 * 
     791 * {@internal Missing Long Description}} 
     792 * 
     793 * @since 0.71 
     794 * 
     795 * @param mixed $number Will convert to string and add zeros 
     796 * @param int $threshold Amount of digits 
     797 * @return string Adds leading zeros to number if needed 
     798 */ 
     799function zeroise($number,$threshold) { 
    586800    return sprintf('%0'.$threshold.'s', $number); 
    587801} 
    588802 
    589  
     803/** 
     804 * Adds backslashes before letters and before a number at the start of a string. 
     805 * 
     806 * {@internal Missing Long Description}} 
     807 * 
     808 * @since 0.71 
     809 * 
     810 * @param string $string Value to which backslashes will be added. 
     811 * @return string String with backslashes inserted. 
     812 */ 
    590813function backslashit($string) { 
    591814    $string = preg_replace('/^([0-9])/', '\\\\\\\\\1', $string); 
    …… 
    594817} 
    595818 
     819/** 
     820 * Appends a trailing slash 
     821 * 
     822 * Will remove trailing slash if it exists already before adding 
     823 * a trailing slash. This prevents double slashing a string or 
     824 * path. 
     825 * 
     826 * The primary use of this is for paths and thus should be used 
     827 * for paths. It is not restricted to paths and offers no specific 
     828 * path support. 
     829 * 
     830 * @since 1.2.0 
     831 * @uses untrailingslashit() Unslashes string if it was slashed already 
     832 * 
     833 * @param string $string What to add the trailing slash to 
     834 * @return string String with trailing slash added 
     835 */ 
    596836function trailingslashit($string) { 
    597837    return untrailingslashit($string) . '/'; 
    598838} 
    599839 
     840/** 
     841 * Removes trailing slash if it exists 
     842 * 
     843 * The primary use of this is for paths and thus should be used 
     844 * for paths. It is not restricted to paths and offers no specific 
     845 * path support. 
     846 * 
     847 * @since 2.2.0 
     848 * 
     849 * @param string $string What to remove the trailing slash from 
     850 * @return string String without the trailing slash 
     851 */ 
    600852function untrailingslashit($string) { 
    601853    return rtrim($string, '/'); 
    602854} 
    603855 
     856/** 
     857 * addslashes_gpc() - {@internal Missing Short Description}} 
     858 * 
     859 * {@internal Missing Long Description}} 
     860 * 
     861 * @since 0.71 
     862 * 
     863 * @param unknown_type $gpc 
     864 * @return unknown 
     865 */ 
    604866function addslashes_gpc($gpc) { 
    605867    global $wpdb; 
    …… 
    612874} 
    613875 
    614  
     876/** 
     877 * stripslashes_deep() - {@internal Missing Short Description}} 
     878 * 
     879 * {@internal Missing Long Description}} 
     880 * 
     881 * @since 2.0.0 
     882 * 
     883 * @param unknown_type $value 
     884 * @return unknown 
     885 */ 
    615886function stripslashes_deep($value) { 
    616887     $value = is_array($value) ? 
    …… 
    621892} 
    622893 
     894/** 
     895 * urlencode_deep() - {@internal Missing Short Description}} 
     896 * 
     897 * {@internal Missing Long Description}} 
     898 * 
     899 * @since 2.2.0 
     900 * 
     901 * @param unknown_type $value 
     902 * @return unknown 
     903 */ 
    623904function urlencode_deep($value) { 
    624905     $value = is_array($value) ? 
    …… 
    629910} 
    630911 
     912/** 
     913 * antispambot() - {@internal Missing Short Description}} 
     914 * 
     915 * {@internal Missing Long Description}} 
     916 * 
     917 * @since 0.71 
     918 * 
     919 * @param unknown_type $emailaddy 
     920 * @param unknown_type $mailto 
     921 * @return unknown 
     922 */ 
    631923function antispambot($emailaddy, $mailto=0) { 
    632924    $emailNOSPAMaddy = ''; 
    …… 
    646938} 
    647939 
     940/** 
     941 * _make_url_clickable_cb() - {@internal Missing Short Description}} 
     942 * 
     943 * {@internal Missing Long Description}} 
     944 * 
     945 * @since 2.5 
     946 * @access private 
     947 * 
     948 * @param unknown_type $matches 
     949 * @return unknown 
     950 */ 
    648951function _make_url_clickable_cb($matches) { 
    649952    $ret = ''; 
    …… 
    660963} 
    661964 
     965/** 
     966 * _make_web_ftp_clickable_cb() - {@internal Missing Short Description}} 
     967 * 
     968 * {@internal Missing Long Description}} 
     969 * 
     970 * @since 2.5 
     971 * @access private 
     972 * 
     973 * @param unknown_type $matches 
     974 * @return unknown 
     975 */ 
    662976function _make_web_ftp_clickable_cb($matches) { 
    663977    $ret = ''; 
    …… 
    675989} 
    676990 
     991/** 
     992 * _make_email_clickable_cb() - {@internal Missing Short Description}} 
     993 * 
     994 * {@internal Missing Long Description}} 
     995 * 
     996 * @since 2.5 
     997 * @access private 
     998 * 
     999 * @param unknown_type $matches 
     1000 * @return unknown 
     1001 */ 
    6771002function _make_email_clickable_cb($matches) { 
    6781003    $email = $matches[2] . '@' . $matches[3]; 
    …… 
    6801005} 
    6811006 
     1007/** 
     1008 * make_clickable() - {@internal Missing Short Description}} 
     1009 * 
     1010 * {@internal Missing Long Description}} 
     1011 * 
     1012 * @since 0.71 
     1013 * 
     1014 * @param unknown_type $ret 
     1015 * @return unknown 
     1016 */ 
    6821017function make_clickable($ret) { 
    6831018    $ret = ' ' . $ret; 
    …… 
    6921027} 
    6931028 
     1029/** 
     1030 * wp_rel_nofollow() - {@internal Missing Short Description}} 
     1031 * 
     1032 * {@internal Missing Long Description}} 
     1033 * 
     1034 * @since 1.5.0 
     1035 * 
     1036 * @param unknown_type $text 
     1037 * @return unknown 
     1038 */ 
    6941039function wp_rel_nofollow( $text ) { 
    6951040    global $wpdb; 
    …… 
    7011046} 
    7021047 
     1048/** 
     1049 * wp_rel_nofollow_callback() - {@internal Missing Short Description}} 
     1050 * 
     1051 * {@internal Missing Long Description}} 
     1052 * 
     1053 * @since 2.3.0 
     1054 * 
     1055 * @param unknown_type $matches 
     1056 * @return unknown 
     1057 */ 
    7031058function wp_rel_nofollow_callback( $matches ) { 
    7041059    $text = $matches[1]; 
    …… 
    7071062} 
    7081063 
     1064/** 
     1065 * convert_smilies() - {@internal Missing Short Description}} 
     1066 * 
     1067 * {@internal Missing Long Description}} 
     1068 * 
     1069 * @since 0.71 
     1070 * 
     1071 * @param unknown_type $text 
     1072 * @return unknown 
     1073 */ 
    7091074function convert_smilies($text) { 
    7101075    global $wp_smiliessearch, $wp_smiliesreplace; 
    711     $output = ''; 
     1076   $output = ''; 
    7121077    if ( get_option('use_smilies') && !empty($wp_smiliessearch) && !empty($wp_smiliesreplace) ) { 
    7131078        // HTML loop taken from texturize function, could possible be consolidated 
    …… 
    7281093} 
    7291094 
    730  
     1095/** 
     1096 * is_email() - {@internal Missing Short Description}} 
     1097 * 
     1098 * {@internal Missing Long Description}} 
     1099 * 
     1100 * @since 0.71 
     1101 * 
     1102 * @param unknown_type $user_email 
     1103 * @return unknown 
     1104 */ 
    7311105function is_email($user_email) { 
    7321106    $chars = "/^([a-z0-9+_]|\\-|\\.)+@(([a-z0-9_]|\\-)+\\.)+[a-z]{2,6}\$/i"; 
    …… 
    7421116} 
    7431117 
    744 // used by wp-mail to handle charsets in email subjects 
     1118/** 
     1119 * wp_iso_descrambler() - {@internal Missing Short Description}} 
     1120 * 
     1121 * {@internal Missing Long Description}} 
     1122 * 
     1123 * @since 1.2.0 
     1124 * @usedby wp_mail() handles charsets in email subjects 
     1125 * 
     1126 * @param unknown_type $string 
     1127 * @return unknown 
     1128 */ 
    7451129function wp_iso_descrambler($string) { 
    746   /* this may only work with iso-8859-1, I'm afraid */ 
    747   if (!preg_match('#\=\?(.+)\?Q\?(.+)\?\=#i', $string, $matches)) { 
    748     return $string; 
    749   } else { 
    750     $subject = str_replace('_', ' ', $matches[2]); 
    751     $subject = preg_replace('#\=([0-9a-f]{2})#ei', "chr(hexdec(strtolower('$1')))", $subject); 
    752     return $subject; 
    753   } 
    754 } 
    755  
    756  
    757 // give it a date, it will give you the same date as GMT 
     1130    /* this may only work with iso-8859-1, I'm afraid */ 
     1131    if (!preg_match('#\=\?(.+)\?Q\?(.+)\?\=#i', $string, $matches)) { 
     1132        return $string; 
     1133    } else { 
     1134        $subject = str_replace('_', ' ', $matches[2]); 
     1135        $subject = preg_replace('#\=([0-9a-f]{2})#ei', "chr(hexdec(strtolower('$1')))", $subject); 
     1136        return $subject; 
     1137    } 
     1138} 
     1139 
     1140/** 
     1141 * get_gmt_from_date() - Give it a date, it will give you the same date as GMT 
     1142 * 
     1143 * {@internal Missing Long Description}} 
     1144 * 
     1145 * @since 1.2.0 
     1146 * 
     1147 * @param unknown_type $string 
     1148 * @return unknown 
     1149 */ 
    7581150function get_gmt_from_date($string) { 
    759   // note: this only substracts $time_difference from the given date 
    760   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); 
    761   $string_time = gmmktime($matches[4], $matches[5], $matches[6], $matches[2], $matches[3], $matches[1]); 
    762   $string_gmt = gmdate('Y-m-d H:i:s', $string_time - get_option('gmt_offset') * 3600); 
    763   return $string_gmt; 
    764 } 
    765  
    766 // give it a GMT date, it will give you the same date with $time_difference added 
     1151    // note: this only substracts $time_difference from the given date 
     1152    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); 
     1153    $string_time = gmmktime($matches[4], $matches[5], $matches[6], $matches[2], $matches[3], $matches[1]); 
     1154    $string_gmt = gmdate('Y-m-d H:i:s', $string_time - get_option('gmt_offset') * 3600); 
     1155    return $string_gmt; 
     1156} 
     1157 
     1158/** 
     1159 * get_date_from_gmt() - Give it a GMT date, it will give you the same date with $time_difference added 
     1160 * 
     1161 * {@internal Missing Long Description}} 
     1162 * 
     1163 * @since 1.2.0 
     1164 * 
     1165 * @param unknown_type $string 
     1166 * @return unknown 
     1167 */ 
    7671168function get_date_from_gmt($string) { 
    768   // note: this only adds $time_difference to the given date 
    769   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); 
    770   $string_time = gmmktime($matches[4], $matches[5], $matches[6], $matches[2], $matches[3], $matches[1]); 
    771   $string_localtime = gmdate('Y-m-d H:i:s', $string_time + get_option('gmt_offset')*3600); 
    772   return $string_localtime; 
    773 } 
    774  
    775 // computes an offset in seconds from an iso8601 timezone 
     1169    // note: this only adds $time_difference to the given date 
     1170    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); 
     1171    $string_time = gmmktime($matches[4], $matches[5], $matches[6], $matches[2], $matches[3], $matches[1]); 
     1172    $string_localtime = gmdate('Y-m-d H:i:s', $string_time + get_option('gmt_offset')*3600); 
     1173    return $string_localtime; 
     1174} 
     1175 
     1176/** 
     1177 * iso8601_timezone_to_offset() - Computes an offset in seconds from an iso8601 timezone 
     1178 * 
     1179 * {@internal Missing Long Description}} 
     1180 * 
     1181 * @since 1.5.0 
     1182 * 
     1183 * @param unknown_type $timezone 
     1184 * @return unknown 
     1185 */ 
    7761186function iso8601_timezone_to_offset($timezone) { 
    777   // $timezone is either 'Z' or '[+|-]hhmm' 
    778   if ($timezone == 'Z') { 
    779     $offset = 0; 
    780   } else { 
    781     $sign    = (substr($timezone, 0, 1) == '+') ? 1 : -1; 
    782     $hours   = intval(substr($timezone, 1, 2)); 
    783     $minutes = intval(substr($timezone, 3, 4)) / 60; 
    784     $offset  = $sign * 3600 * ($hours + $minutes); 
    785   } 
    786   return $offset; 
    787 } 
    788  
    789 // converts an iso8601 date to MySQL DateTime format used by post_date[_gmt] 
     1187    // $timezone is either 'Z' or '[+|-]hhmm' 
     1188    if ($timezone == 'Z') { 
     1189        $offset = 0; 
     1190    } else { 
     1191        $sign    = (substr($timezone, 0, 1) == '+') ? 1 : -1; 
     1192        $hours   = intval(substr($timezone, 1, 2)); 
     1193        $minutes = intval(substr($timezone, 3, 4)) / 60; 
     1194        $offset  = $sign * 3600 * ($hours + $minutes); 
     1195    } 
     1196    return $offset; 
     1197} 
     1198 
     1199/** 
     1200 * iso8601_to_datetime() - Converts an iso8601 date to MySQL DateTime format used by post_date[_gmt] 
     1201 * 
     1202 * {@internal Missing Long Description}} 
     1203 * 
     1204 * @since 1.5.0 
     1205 * 
     1206 * @param unknown_type $date_string 
     1207 * @param unknown_type $timezone 
     1208 * @return unknown 
     1209 */ 
    7901210function iso8601_to_datetime($date_string, $timezone = USER) { 
    791   if ($timezone == GMT) { 
    792     preg_match('#([0-9]{4})([0-9]{2})([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2})(Z|[\+|\-][0-9]{2,4}){0,1}#', $date_string, $date_bits); 
    793     if (!empty($date_bits[7])) { // we have a timezone, so let's compute an offset 
    794       $offset = iso8601_timezone_to_offset($date_bits[7]); 
    795     } else { // we don't have a timezone, so we assume user local timezone (not server's!) 
    796       $offset = 3600 * get_option('gmt_offset'); 
    797     } 
    798     $timestamp = gmmktime($date_bits[4], $date_bits[5], $date_bits[6], $date_bits[2], $date_bits[3], $date_bits[1]); 
    799     $timestamp -= $offset; 
    800     return gmdate('Y-m-d H:i:s', $timestamp); 
    801   } elseif ($timezone == USER) { 
    802     return preg_replace('#([0-9]{4})([0-9]{2})([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2})(Z|[\+|\-][0-9]{2,4}){0,1}#', '$1-$2-$3 $4:$5:$6', $date_string); 
    803   } 
    804 } 
    805  
     1211    if ($timezone == GMT) { 
     1212 
     1213        preg_match('#([0-9]{4})([0-9]{2})([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2})(Z|[\+|\-][0-9]{2,4}){0,1}#', $date_string, $date_bits); 
     1214 
     1215        if (!empty($date_bits[7])) { // we have a timezone, so let's compute an offset 
     1216            $offset = iso8601_timezone_to_offset($date_bits[7]); 
     1217        } else { // we don't have a timezone, so we assume user local timezone (not server's!) 
     1218            $offset = 3600 * get_option('gmt_offset'); 
     1219        } 
     1220 
     1221        $timestamp = gmmktime($date_bits[4], $date_bits[5], $date_bits[6], $date_bits[2], $date_bits[3], $date_bits[1]); 
     1222        $timestamp -= $offset; 
     1223 
     1224        return gmdate('Y-m-d H:i:s', $timestamp); 
     1225 
     1226    } else if ($timezone == USER) { 
     1227        return preg_replace('#([0-9]{4})([0-9]{2})([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2})(Z|[\+|\-][0-9]{2,4}){0,1}#', '$1-$2-$3 $4:$5:$6', $date_string); 
     1228    } 
     1229} 
     1230 
     1231/** 
     1232 * Adds a element attributes to open links in new windows 
     1233 * 
     1234 * Comment text in popup windows should be filtered through this. Right 
     1235 * now it's a moderately dumb function, ideally it would detect whether 
     1236 * a target or rel attribute was already there and adjust its actions 
     1237 * accordingly. 
     1238 * 
     1239 * @since 0.71 
     1240 * 
     1241 * @param string $text Content to replace links to open in a new window 
     1242 * @return string Content that has filtered links 
     1243 */ 
    8061244function popuplinks($text) { 
    807     // Comment text in popup windows should be filtered through this. 
    808     // Right now it's a moderately dumb function, ideally it would detect whether 
    809     // a target or rel attribute was already there and adjust its actions accordingly. 
    8101245    $text = preg_replace('/<a (.+?)>/i', "<a $1 target='_blank' rel='external'>", $text); 
    8111246    return $text; 
    8121247} 
    8131248 
     1249/** 
     1250 * Strips out all characters that are not allowable in an email 
     1251 * 
     1252 * @since 1.5.0 
     1253 * 
     1254 * @param string $email Email address to filter 
     1255 * @return string Filtered email address 
     1256 */ 
    8141257function sanitize_email($email) { 
    8151258    return preg_replace('/[^a-z0-9+_.@-]/i', '', $email); 
    8161259} 
    8171260 
     1261/** 
     1262 * human_time_diff() - {@internal Missing Short Description}} 
     1263 * 
     1264 * {@internal Missing Long Description}} 
     1265 * 
     1266 * @since 1.5.0 
     1267 * 
     1268 * @param unknown_type $from 
     1269 * @param unknown_type $to 
     1270 * @return unknown 
     1271 */ 
    8181272function human_time_diff( $from, $to = '' ) { 
    8191273    if ( empty($to) ) 
    …… 
    8421296} 
    8431297 
     1298/** 
     1299 * wp_trim_excerpt() - {@internal Missing Short Description}} 
     1300 * 
     1301 * {@internal Missing Long Description}} 
     1302 * 
     1303 * @since 1.5.0 
     1304 * 
     1305 * @param unknown_type $text 
     1306 * @return unknown 
     1307 */ 
    8441308function wp_trim_excerpt($text) { // Fakes an excerpt if needed 
    8451309    if ( '' == $text ) { 
    …… 
    8621326} 
    8631327 
     1328/** 
     1329 * ent2ncr() - {@internal Missing Short Description}} 
     1330 * 
     1331 * {@internal Missing Long Description}} 
     1332 * 
     1333 * @since 1.5.1 
     1334 * 
     1335 * @param unknown_type $text 
     1336 * @return unknown 
     1337 */ 
    8641338function ent2ncr($text) { 
    8651339    $to_ncr = array( 
    …… 
    11261600} 
    11271601 
     1602/** 
     1603 * wp_richedit_pre() - {@internal Missing Short Description}} 
     1604 * 
     1605 * {@internal Missing Long Description}} 
     1606 * 
     1607 * @since 2.0.0 
     1608 * 
     1609 * @param unknown_type $text 
     1610 * @return unknown 
     1611 */ 
    11281612function wp_richedit_pre($text) { 
    11291613    // Filtering a blank results in an annoying <br />\n 
    …… 
    11441628} 
    11451629 
     1630/** 
     1631 * clean_url() - {@internal Missing Short Description}} 
     1632 * 
     1633 * {@internal Missing Long Description}} 
     1634 * 
     1635 * @since 1.2.0 
     1636 * 
     1637 * @param unknown_type $url 
     1638 * @param unknown_type $protocols 
     1639 * @param unknown_type $context 
     1640 * @return unknown 
     1641 */ 
    11461642function clean_url( $url, $protocols = null, $context = 'display' ) { 
    11471643    $original_url = $url; 
    …… 
    11551651     * presume it needs http:// appended (unless a relative 
    11561652     * link starting with / or a php file). 
    1157     */ 
     1653    */ 
    11581654    if ( strpos($url, ':') === false && 
    11591655        substr( $url, 0, 1 ) != '/' && !preg_match('/^[a-z0-9-]+?\.php/i', $url) ) 
    …… 
    11721668} 
    11731669 
     1670/** 
     1671 * sanitize_url() - {@internal Missing Short Description}} 
     1672 * 
     1673 * {@internal Missing Long Description}} 
     1674 * 
     1675 * @since 2.3.1 
     1676 * 
     1677 * @param unknown_type $url 
     1678 * @param unknown_type $protocols 
     1679 * @return unknown 
     1680 */ 
    11741681function sanitize_url( $url, $protocols = null ) { 
    1175     return clean_url( $url, $protocols, 'db'); 
    1176 } 
    1177  
    1178 // Borrowed from the PHP Manual user notes. Convert entities, while 
    1179 // preserving already-encoded entities: 
     1682    return clean_url( $url, $protocols, 'db' ); 
     1683} 
     1684 
     1685/** 
     1686 * Convert entities, while preserving already-encoded entities 
     1687 * 
     1688 * {@internal Missing Long Description}} 
     1689 * 
     1690 * @link http://www.php.net/htmlentities Borrowed from the PHP Manual user notes. 
     1691 * 
     1692 * @since 1.2.2 
     1693 * 
     1694 * @param unknown_type $myHTML 
     1695 * @return unknown 
     1696 */ 
    11801697function htmlentities2($myHTML) { 
    1181     $translation_table=get_html_translation_table (HTML_ENTITIES,ENT_QUOTES); 
     1698    $translation_table = get_html_translation_table( HTML_ENTITIES, ENT_QUOTES ); 
    11821699    $translation_table[chr(38)] = '&'; 
    1183     return preg_replace("/&(?![A-Za-z]{0,4}\w{2,3};|#[0-9]{2,3};)/","&amp;" , strtr($myHTML, $translation_table)); 
    1184 } 
    1185  
    1186 // Escape single quotes, specialchar double quotes, and fix line endings. 
     1700    return preg_replace( "/&(?![A-Za-z]{0,4}\w{2,3};|#[0-9]{2,3};)/", "&amp;", strtr($myHTML, $translation_table) ); 
     1701} 
     1702 
     1703/** 
     1704 * Escape single quotes, specialchar double quotes, and fix line endings 
     1705 * 
     1706 * {@internal Missing Long Description}} 
     1707 * 
     1708 * @since 2.0.4 
     1709 * 
     1710 * @param string $text 
     1711 * @return unknown 
     1712 */ 
    11871713function js_escape($text) { 
    11881714    $safe_text = wp_specialchars($text, 'double'); 
    …… 
    12921818} 
    12931819 
     1820/** 
     1821 * wp_parse_str() - {@internal Missing Short Description}} 
     1822 * 
     1823 * {@internal Missing Long Description}} 
     1824 * 
     1825 * @since 2.2.1 
     1826 * @uses apply_filters()  
     1827 * 
     1828 * @param string $string 
     1829 * @param array $array 
     1830 */ 
    12941831function wp_parse_str( $string, &$array ) { 
    12951832    parse_str( $string, $array ); 
    …… 
    14111948 * @param integer $str String to get the excerpt from 
    14121949 * @param integer $count Maximum number of characters to take 
    1413  * @eaturn string the excerpt 
     1950 * @return string the excerpt 
    14141951 */ 
    14151952function wp_html_excerpt( $str, $count ) {