Ticket #11264: 12277-add-get_the_date.diff

general-template.php

@@ -1207 +1207 @@
 }
 
 /**
- * Display or Retrieve the date the post was written.
+ * Display or Retrieve the date the current $post was written (once per date)
  *
  * Will only output the date if the current post's date is different from the
  * previous one output.
+
+ * i.e. Only one date listing will show per day worth of posts shown in the loop, even if the
+ * function is called several times for each post.
  *
- * @since 0.71
+ * HTML output can be filtered with 'the_date'.
+ * Date string output can be filtered with 'get_the_date'.
  *
+ * @since 0.71
+ * @uses get_the_date()
  * @param string $d Optional. PHP date format defaults to the date_format option if not specified.
  * @param string $before Optional. Output before the date.
  * @param string $after Optional. Output after the date.
@@ -1221 +1227 @@
  * @return string|null Null if displaying, string if retrieving.
  */
 function the_date($d='', $before='', $after='', $echo = true) {
-        global $post, $day, $previousday;
+        global $day, $previousday;
         $the_date = '';
         if ( $day != $previousday ) {
                 $the_date .= $before;
-                if ( $d=='' )
-                        $the_date .= mysql2date(get_option('date_format'), $post->post_date);
-                else
-                        $the_date .= mysql2date($d, $post->post_date);
+                $the_date .= get_the_date( $d );
                 $the_date .= $after;
                 $previousday = $day;
 
@@ -1241 +1244 @@
 }
 
 /**
+ * Retrieve the date the current $post was written.
+ *
+ * Unlike the_date() this function will always return the date.
+ * Modify output with 'get_the_date' filter.
+ *
+ * @since 2.9
+ *
+ * @param string $d Optional. PHP date format defaults to the date_format option if not specified.
+ * @return string|null Null if displaying, string if retrieving.
+ */
+function get_the_date($d='') {
+        global $post, $day;
+        $the_date = '';
+
+        if ( '' == $d )
+                $the_date .= mysql2date(get_option('date_format'), $post->post_date);
+        else
+                $the_date .= mysql2date($d, $post->post_date);
+
+        return apply_filters('get_the_date', $the_date, $d);
+}
+
+/**
+ No newline at end of file
  * Display the date on which the post was last modified.
  *
  * @since 2.1.0