WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
08/17/2008 11:29:43 AM (17 years ago)
Author:
westi
Message:

phpdoc for formatting functions. See #5638 props scohoust.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • 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 ) {
Note: See TracChangeset for help on using the changeset viewer.