From 0e42d1d3a6fb34b8205666abdb95f95481781655 Mon Sep 17 00:00:00 2001
From: Daniel Convissor <danielc@php.net>
Date: Wed, 28 Apr 2010 15:58:26 +0000
Subject: [PATCH] Reworked examples to new oop/procedural combination format.
 Changed several titles. Simplified some initial examples and moved some parts
 to new examples. Per discussion on php-doc.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@298705 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/datetime/datetime/add.xml           | 32 +++++++++--
 reference/datetime/datetime/construct.xml     | 27 +++++++++
 .../datetime/datetime/createfromformat.xml    | 29 +++++++++-
 reference/datetime/datetime/diff.xml          | 13 ++---
 reference/datetime/datetime/format.xml        | 23 ++++----
 reference/datetime/datetime/getlasterrors.xml | 21 ++++++-
 reference/datetime/datetime/getoffset.xml     | 29 +++++++++-
 reference/datetime/datetime/gettimezone.xml   | 13 ++++-
 reference/datetime/datetime/setdate.xml       | 57 ++++++++++++-------
 reference/datetime/datetime/setisodate.xml    | 43 ++++++++++++--
 reference/datetime/datetime/settime.xml       | 55 +++++++++++++++---
 reference/datetime/datetime/settimezone.xml   | 17 +++++-
 reference/datetime/datetime/sub.xml           | 32 +++++++++--
 13 files changed, 321 insertions(+), 70 deletions(-)

diff --git a/reference/datetime/datetime/add.xml b/reference/datetime/datetime/add.xml
index 92e9891212..94790e86d2 100644
--- a/reference/datetime/datetime/add.xml
+++ b/reference/datetime/datetime/add.xml
@@ -56,14 +56,39 @@
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
-   <title><function>date_add</function> example</title>
+   <title><function>DateTime::add</function> example</title>
+   <para>&style.oop;</para>
    <programlisting role="php">
 <![CDATA[
 <?php
 $date = new DateTime('2000-01-01');
 $date->add(new DateInterval('P10D'));
-echo $date->format('Y-m-d H:i:s') . "\n";
-
+echo $date->format('Y-m-d') . "\n";
+?>
+]]>
+   </programlisting>
+   <para>&style.procedural;</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$date = date_create('2000-01-01');
+date_add($date, date_interval_create_from_date_string('10 days'));
+echo date_format($date, 'Y-m-d');
+?>
+]]>
+   </programlisting>
+   &examples.outputs;
+   <screen>
+<![CDATA[
+2000-01-11
+]]>
+   </screen>
+  </example>
+  <example>
+   <title>Further <function>DateTime::add</function> examples</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
 $date = new DateTime('2000-01-01');
 $date->add(new DateInterval('PT10H30S'));
 echo $date->format('Y-m-d H:i:s') . "\n";
@@ -77,7 +102,6 @@ echo $date->format('Y-m-d H:i:s') . "\n";
    &example.outputs;
    <screen>
 <![CDATA[
-2000-01-11 00:00:00
 2000-01-01 10:00:30
 2007-06-05 04:03:02
 ]]>
diff --git a/reference/datetime/datetime/construct.xml b/reference/datetime/datetime/construct.xml
index 55a608c14a..559965cc72 100644
--- a/reference/datetime/datetime/construct.xml
+++ b/reference/datetime/datetime/construct.xml
@@ -82,6 +82,33 @@
   &reftitle.examples;
   <example>
    <title><function>DateTime::__construct</function> example</title>
+   <para>&style.oop;</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$date = new DateTime('2000-01-01');
+echo $date->format('Y-m-d');
+?>
+]]>
+   </programlisting>
+   <para>&style.procedural;</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$date = date_create('2000-01-01');
+echo date_format($date, 'Y-m-d');
+?>
+]]>
+   </programlisting>
+   &examples.outputs;
+   <screen>
+<![CDATA[
+2000-01-01
+]]>
+   </screen>
+  </example>
+  <example>
+   <title>Intricacies of <function>DateTime::__construct</function></title>
    <programlisting role="php">
 <![CDATA[
 <?php
diff --git a/reference/datetime/datetime/createfromformat.xml b/reference/datetime/datetime/createfromformat.xml
index c1403bb91c..240ae31394 100644
--- a/reference/datetime/datetime/createfromformat.xml
+++ b/reference/datetime/datetime/createfromformat.xml
@@ -93,7 +93,34 @@
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
-   <title><methodname>DateTime::createFromFormat</methodname> example</title>
+   <title><function>DateTime::createFromFormat</function> example</title>
+   <para>&style.oop;</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$date = DateTime::createFromFormat('j-M-Y', '15-Feb-2009');
+echo $date->format('Y-m-d');
+?>
+]]>
+   </programlisting>
+   <para>&style.procedural;</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$date = date_create_from_format('j-M-Y', '15-Feb-2009');
+echo date_format($date, 'Y-m-d');
+?>
+]]>
+   </programlisting>
+   &examples.outputs;
+   <screen>
+<![CDATA[
+2009-02-15
+]]>
+   </screen>
+  </example>
+  <example>
+   <title>Intricacies of <function>DateTime::createFromFormat</function></title>
    <programlisting role="php">
 <![CDATA[
 <?php
diff --git a/reference/datetime/datetime/diff.xml b/reference/datetime/datetime/diff.xml
index d7368e6e2e..d4cc5e19ee 100644
--- a/reference/datetime/datetime/diff.xml
+++ b/reference/datetime/datetime/diff.xml
@@ -59,7 +59,8 @@
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
-   <title>Object oriented style example of <function>DateTime::diff</function></title>
+   <title><function>DateTime::diff</function> example</title>
+   <para>&style.oop;</para>
    <programlisting role="php">
 <![CDATA[
 <?php
@@ -70,21 +71,19 @@ echo $interval->format('%R%d days');
 ?>
 ]]>
    </programlisting>
-  </example>
-  <example>
-   <title>Procedural style example of <function>date_diff</function></title>
+   <para>&style.procedural;</para>
    <programlisting role="php">
 <![CDATA[
 <?php
-$datetime1 = new DateTime('2009-10-11');
-$datetime2 = new DateTime('2009-10-13');
+$datetime1 = date_create('2009-10-11');
+$datetime2 = date_create('2009-10-13');
 $interval = date_diff($datetime1, $datetime2);
 echo $interval->format('%R%d days');
 ?>
 ]]>
    </programlisting>
   </example>
-  &example.outputs;
+  &examples.outputs;
   <screen>
 <![CDATA[
 +2 days
diff --git a/reference/datetime/datetime/format.xml b/reference/datetime/datetime/format.xml
index 6500f19d75..58cfc15e14 100644
--- a/reference/datetime/datetime/format.xml
+++ b/reference/datetime/datetime/format.xml
@@ -47,24 +47,23 @@
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
-   <title>Displaying the date and time using the procedural form</title>
-   <programlisting role="php">
-<![CDATA[
-<?php
-$date = date_create('2000-01-01');
-echo date_format($date, 'Y-m-d H:i:s');
-?>
-]]>
-   </programlisting>
-  </example>
-  <example>
-   <title>Displaying the date and time using the object oriented form</title>
+   <title><function>DateTime::format</function> example</title>
+   <para>&style.oop;</para>
    <programlisting role="php">
 <![CDATA[
 <?php
 $date = new DateTime('2000-01-01');
 echo $date->format('Y-m-d H:i:s');
 ?>
+]]>
+   </programlisting>
+   <para>&style.procedural;</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$date = date_create('2000-01-01');
+echo date_format($date, 'Y-m-d H:i:s');
+?>
 ]]>
    </programlisting>
    &example.outputs;
diff --git a/reference/datetime/datetime/getlasterrors.xml b/reference/datetime/datetime/getlasterrors.xml
index efa5683878..a06219bf3d 100644
--- a/reference/datetime/datetime/getlasterrors.xml
+++ b/reference/datetime/datetime/getlasterrors.xml
@@ -40,15 +40,32 @@
   &reftitle.examples;
   <example>
    <title><function>DateTime::getLastErrors</function> example</title>
+   <para>&style.oop;</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+try {
+    $date = new DateTime('asdfasdf');
+} catch (Exception $e) {
+    // For demonstration purposes only...
+    print_r(DateTime::getLastErrors());
+
+    // The real object oriented way to do this is
+    // echo $e->getMessage();
+}
+?>
+]]>
+   </programlisting>
+   <para>&style.procedural;</para>
    <programlisting role="php">
 <![CDATA[
 <?php
 $date = date_create('asdfasdf');
-print_r(DateTime::getLastErrors());
+print_r(date_get_last_errors());
 ?>
 ]]>
    </programlisting>
-   &example.outputs;
+   &examples.outputs;
    <screen>
 <![CDATA[
 Array
diff --git a/reference/datetime/datetime/getoffset.xml b/reference/datetime/datetime/getoffset.xml
index fdbf99c5c1..d94a27b457 100644
--- a/reference/datetime/datetime/getoffset.xml
+++ b/reference/datetime/datetime/getoffset.xml
@@ -39,18 +39,41 @@
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
-   <title>Comparing offsets between Summer and Winter</title>
+   <title><function>DateTime::getOffset</function> example</title>
+   <para>&style.oop;</para>
    <programlisting role="php">
 <![CDATA[
 <?php
 $winter = new DateTime('2010-12-21', new DateTimeZone('America/New_York'));
 $summer = new DateTime('2008-06-21', new DateTimeZone('America/New_York'));
 
-echo $winter->getOffset() . "\n";  // "-18000"  (-5 hours)
-echo $summer->getOffset() . "\n";  // "-14400"  (-4 hours)
+echo $winter->getOffset() . "\n";
+echo $summer->getOffset() . "\n";
 ?>
 ]]>
    </programlisting>
+   <para>&style.procedural;</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$winter = new date_create('2010-12-21', timezone_open('America/New_York'));
+$summer = new date_create('2008-06-21', timezone_open('America/New_York'));
+
+echo $winter->getOffset() . "\n";
+echo $summer->getOffset() . "\n";
+?>
+]]>
+   </programlisting>
+   &examples.outputs;
+   <screen>
+<![CDATA[
+-18000
+-14400
+]]>
+   </screen>
+   <para>
+    Note: -18000 = -5 hours, -14400 = -4 hours.
+   </para>
   </example>
  </refsect1>
 
diff --git a/reference/datetime/datetime/gettimezone.xml b/reference/datetime/datetime/gettimezone.xml
index 767f4ded76..9a3a337333 100644
--- a/reference/datetime/datetime/gettimezone.xml
+++ b/reference/datetime/datetime/gettimezone.xml
@@ -39,6 +39,7 @@
   &reftitle.examples;
   <example>
    <title><function>DateTime::getTimezone</function> example</title>
+   <para>&style.oop;</para>
    <programlisting role="php">
 <![CDATA[
 <?php
@@ -48,7 +49,17 @@ echo $tz->getName();
 ?>
 ]]>
    </programlisting>
-   &example.outputs;
+   <para>&style.procedural;</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$date = date_create(null, timezone_open('Europe/London'));
+$tz = date_timezone_get($date);
+echo timezone_name_get($tz);
+?>
+]]>
+   </programlisting>
+   &examples.outputs;
    <screen>
 <![CDATA[
 Europe/London
diff --git a/reference/datetime/datetime/setdate.xml b/reference/datetime/datetime/setdate.xml
index ad70ce7cb0..fdd92039a7 100644
--- a/reference/datetime/datetime/setdate.xml
+++ b/reference/datetime/datetime/setdate.xml
@@ -87,42 +87,57 @@
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
-   <title>Object oriented example usage</title>
+   <title><function>DateTime::setDate</function> example</title>
+   <para>&style.oop;</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$date = new DateTime();
+$date->setDate(2001, 2, 3);
+echo $date->format('Y-m-d');
+?>
+]]>
+   </programlisting>
+   <para>&style.procedural;</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$date = date_create();
+date_date_set($date, 2001, 2, 3);
+echo date_format($date, 'Y-m-d');
+?>
+]]>
+   </programlisting>
+   &examples.outputs;
+   <screen>
+<![CDATA[
+2001-02-03
+]]>
+   </screen>
+  </example>
+  <example>
+   <title>Values exceeding ranges are added to their parent values</title>
    <programlisting role="php">
 <![CDATA[
 <?php
 $date = new DateTime();
 
-$date->setDate(2001, 2, 3);
+$date->setDate(2001, 2, 28);
+echo $date->format('Y-m-d') . "\n";
+
+$date->setDate(2001, 2, 29);
 echo $date->format('Y-m-d') . "\n";
 
-// Values exceeding ranges are added to their parent values.
 $date->setDate(2001, 14, 3);
 echo $date->format('Y-m-d') . "\n";
 ?>
-]]>
-   </programlisting>
-  </example>
-  <example>
-   <title>Procedural example usage</title>
-   <programlisting role="php">
-<![CDATA[
-<?php
-$date = date_create();
-
-date_date_set($date, 2001, 2, 3);
-echo date_format($date, 'Y-m-d') . "\n";
-
-// Values exceeding ranges are added to their parent values.
-date_date_set($date, 2001, 14, 3);
-echo date_format($date, 'Y-m-d') . "\n";
-?>
 ]]>
    </programlisting>
    &example.outputs;
    <screen>
 <![CDATA[
-2001-02-03
+2001-02-28
+2001-03-01
 2002-02-03
 ]]>
    </screen>
diff --git a/reference/datetime/datetime/setisodate.xml b/reference/datetime/datetime/setisodate.xml
index fa46662b6f..db66e2cd21 100644
--- a/reference/datetime/datetime/setisodate.xml
+++ b/reference/datetime/datetime/setisodate.xml
@@ -88,7 +88,8 @@
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
-   <title>Finding the date from a week number and day offset</title>
+   <title><function>DateTime::setISODate</function> example</title>
+   <para>&style.oop;</para>
    <programlisting role="php">
 <![CDATA[
 <?php
@@ -97,25 +98,57 @@ $date = new DateTime();
 $date->setISODate(2008, 2);
 echo $date->format('Y-m-d') . "\n";
 
-$date->setISODate(2008, 2, 1);
+$date->setISODate(2008, 2, 7);
 echo $date->format('Y-m-d') . "\n";
+?>
+]]>
+   </programlisting>
+   <para>&style.procedural;</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$date = date_create();
+
+date_isodate_set($date, 2008, 2);
+echo date_format($date, 'Y-m-d') . "\n";
+
+date_isodate_set($date, 2008, 2, 7);
+echo date_format($date, 'Y-m-d') . "\n";
+?>
+]]>
+   </programlisting>
+   &examples.outputs;
+   <screen>
+<![CDATA[
+2008-01-07
+2008-01-13
+]]>
+   </screen>
+  </example>
+  <example>
+   <title>Values exceeding ranges are added to their parent values</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$date = new DateTime();
 
 $date->setISODate(2008, 2, 7);
 echo $date->format('Y-m-d') . "\n";
 
-// Values exceeding ranges are added to their parent values.
 $date->setISODate(2008, 2, 8);
 echo $date->format('Y-m-d') . "\n";
+
+$date->setISODate(2008, 53, 7);
+echo $date->format('Y-m-d') . "\n";
 ?>
 ]]>
    </programlisting>
    &example.outputs;
    <screen>
 <![CDATA[
-2008-01-07
-2008-01-07
 2008-01-13
 2008-01-14
+2009-01-04
 ]]>
    </screen>
   </example>
diff --git a/reference/datetime/datetime/settime.xml b/reference/datetime/datetime/settime.xml
index 968dddaf74..349da12b46 100644
--- a/reference/datetime/datetime/settime.xml
+++ b/reference/datetime/datetime/settime.xml
@@ -87,32 +87,71 @@
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
-   <title>Changing the time of a DateTime object</title>
+   <title><function>DateTime::setTime</function> example</title>
+   <para>&style.oop;</para>
    <programlisting role="php">
 <![CDATA[
 <?php
-$date = new DateTime('2000-01-01');
-echo $date->format('Y-m-d H:i:s') . "\n";
+$date = new DateTime('2001-01-01');
 
 $date->setTime(14, 55);
 echo $date->format('Y-m-d H:i:s') . "\n";
 
 $date->setTime(14, 55, 24);
 echo $date->format('Y-m-d H:i:s') . "\n";
+?>
+]]>
+   </programlisting>
+   <para>&style.procedural;</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$date = date_create('2001-01-01');
+
+date_time_set($date, 14, 55);
+echo date_format($date, 'Y-m-d H:i:s') . "\n";
+
+date_time_set($date, 14, 55, 24);
+echo date_format($date, 'Y-m-d H:i:s') . "\n";
+?>
+]]>
+   </programlisting>
+   &examples.outputs.similar;
+   <screen>
+<![CDATA[
+2000-01-01 14:55:00
+2000-01-01 14:55:24
+]]>
+   </screen>
+  </example>
+  <example>
+   <title>Values exceeding ranges are added to their parent values</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$date = new DateTime('2001-01-01');
+
+$date->setTime(14, 55, 24);
+echo $date->format('Y-m-d H:i:s') . "\n";
+
+$date->setTime(14, 55, 65);
+echo $date->format('Y-m-d H:i:s') . "\n";
 
-// Values exceeding ranges are added to their parent values.
 $date->setTime(14, 65, 24);
 echo $date->format('Y-m-d H:i:s') . "\n";
+
+$date->setTime(25, 55, 24);
+echo $date->format('Y-m-d H:i:s') . "\n";
 ?>
 ]]>
    </programlisting>
    &example.outputs;
    <screen>
 <![CDATA[
-2000-01-01 00:00:00
-2000-01-01 14:55:00
-2000-01-01 14:55:24
-2000-01-01 15:05:24
+2001-01-01 14:55:24
+2001-01-01 14:56:05
+2001-01-01 15:05:24
+2001-01-02 01:55:24
 ]]>
    </screen>
   </example>
diff --git a/reference/datetime/datetime/settimezone.xml b/reference/datetime/datetime/settimezone.xml
index 01daa9bf38..9f5180bae0 100644
--- a/reference/datetime/datetime/settimezone.xml
+++ b/reference/datetime/datetime/settimezone.xml
@@ -71,7 +71,8 @@
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
-   <title>Setting and getting DateTimeZone objects</title>
+   <title><function>DateTime::setTimeZone</function> example</title>
+   <para>&style.oop;</para>
    <programlisting role="php">
 <![CDATA[
 <?php
@@ -83,7 +84,19 @@ echo $date->format('Y-m-d H:i:sP') . "\n";
 ?>
 ]]>
    </programlisting>
-   &example.outputs;
+   <para>&style.procedural;</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$date = date_create('2000-01-01', timezone_open('Pacific/Nauru'));
+echo date_format($date, 'Y-m-d H:i:sP') . "\n";
+
+date_timezone_set($date, timezone_open('Pacific/Chatham'));
+echo date_format($date, 'Y-m-d H:i:sP') . "\n";
+?>
+]]>
+   </programlisting>
+   &examples.outputs;
    <screen>
 <![CDATA[
 2000-01-01 00:00:00+12:00
diff --git a/reference/datetime/datetime/sub.xml b/reference/datetime/datetime/sub.xml
index 956111cd64..9336b19e79 100644
--- a/reference/datetime/datetime/sub.xml
+++ b/reference/datetime/datetime/sub.xml
@@ -56,14 +56,39 @@
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
-   <title><function>date_sub</function> example</title>
+   <title><function>DateTime::sub</function> example</title>
+   <para>&style.oop;</para>
    <programlisting role="php">
 <![CDATA[
 <?php
 $date = new DateTime('2000-01-20');
 $date->sub(new DateInterval('P10D'));
-echo $date->format('Y-m-d H:i:s') . "\n";
-
+echo $date->format('Y-m-d') . "\n";
+?>
+]]>
+   </programlisting>
+   <para>&style.procedural;</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$date = date_create('2000-01-20');
+date_sub($date, date_interval_create_from_date_string('10 days'));
+echo date_format($date, 'Y-m-d');
+?>
+]]>
+   </programlisting>
+   &examples.outputs;
+   <screen>
+<![CDATA[
+2000-01-10
+]]>
+   </screen>
+  </example>
+  <example>
+   <title>Further <function>DateTime::sub</function> examples</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
 $date = new DateTime('2000-01-20');
 $date->sub(new DateInterval('PT10H30S'));
 echo $date->format('Y-m-d H:i:s') . "\n";
@@ -77,7 +102,6 @@ echo $date->format('Y-m-d H:i:s') . "\n";
    &example.outputs;
    <screen>
 <![CDATA[
-2000-01-10 00:00:00
 2000-01-19 13:59:30
 1992-08-15 19:56:58
 ]]>