Merge pull request #5431 from kenjis/fix-docs-time.rst

docs: fix time.rst

Author: paulbalandan

user_guide_src/source/libraries/time.rst

@@ -4,7 +4,7 @@ Times and Dates
 
 CodeIgniter provides a fully-localized, immutable, date/time class that is built on PHP's DateTime object, but uses the Intl
 extension's features to convert times across timezones and display the output correctly for different locales. This class
-is the **Time** class and lives in the **CodeIgniter\\I18n** namespace.
+is the ``Time`` class and lives in the ``CodeIgniter\I18n`` namespace.
 
 .. note:: Since the Time class extends DateTime, if there are features that you need that this class doesn't provide,
     you can likely find them within the DateTime class itself.
@@ -38,7 +38,7 @@ provided, the application defaults will be used.
 now()
 -----
 
-The Time class has several helper methods to instantiate the class. The first of these is the **now()** method
+The Time class has several helper methods to instantiate the class. The first of these is the ``now()`` method
 that returns a new instance set to the current time. You can pass in strings representing the timezone and the locale
 in the second and parameters, respectively. If no locale or timezone is provided, the application defaults will be used.
 
@@ -85,18 +85,18 @@ Given separate inputs for **year**, **month**, and **day**, will return a new in
 are not provided, it will use the current value to fill it in. Accepts strings for the timezone and locale in the
 fourth and fifth parameters::
 
-    $today       = Time::createFromDate(); // Uses current year, month, and day
+    $today       = Time::createFromDate();     // Uses current year, month, and day
     $anniversary = Time::createFromDate(2018); // Uses current month and day
     $date        = Time::createFromDate(2018, 3, 15, 'America/Chicago', 'en_US');
 
 createFromTime()
 ----------------
 
-Like **createFromDate** except it is only concerned with the **hours**, **minutes**, and **seconds**. Uses the
+Like ``createFromDate()`` except it is only concerned with the **hours**, **minutes**, and **seconds**. Uses the
 current day for the date portion of the Time instance. Accepts strings for the timezone and locale in the
 fourth and fifth parameters::
 
-    $lunch  = Time::createFromTime(11, 30); // 11:30 am today
+    $lunch  = Time::createFromTime(11, 30);     // 11:30 am today
     $dinner = Time::createFromTime(18, 00, 00); // 6:00 pm today
     $time   = Time::createFromTime($hour, $minutes, $seconds, $timezone, $locale);
 
@@ -113,7 +113,7 @@ createFromFormat()
 ------------------
 
 This is a replacement for DateTime's method of the same name. This allows the timezone to be set at the same time,
-and returns a **Time** instance, instead of DateTime::
+and returns a ``Time`` instance, instead of DateTime::
 
     $time = Time::createFromFormat('j-M-Y', '15-Feb-2009', 'America/Chicago');
 
@@ -154,7 +154,7 @@ to display localized versions of the value, though.
 toLocalizedString()
 -------------------
 
-This is the localized version of DateTime's format() method. Instead of using the values you might be familiar with, though,
+This is the localized version of DateTime's ``format()`` method. Instead of using the values you might be familiar with, though,
 you must use values acceptable to the `IntlDateFormatter <https://www.php.net/manual/en/class.intldateformatter.php>`__ class.
 A full listing of values can be found `here <https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classSimpleDateFormat.html#details>`__.
 ::
@@ -214,7 +214,7 @@ $time > now && < 1 hour          in 35 minutes / 35 minutes ago
 $time == now                     Now
 =============================== =================================
 
-The exact language used is controlled through the language file, Time.php.
+The exact language used is controlled through the language file, **Time.php**.
 
 ==============================
 Working with Individual Values
@@ -224,8 +224,8 @@ The Time object provides a number of methods to allow to get and set individual
 of an existing instance. All of the values retrieved through the following methods will be fully localized and respect
 the locale that the Time instance was created with.
 
-All of the following `getX` and `setX` methods can also be used as if they were a class property. So, any calls to methods
-like `getYear` can also be accessed through `$time->year`, and so on.
+All of the following ``getX()`` and ``setX()`` methods can also be used as if they were a class property. So, any calls to methods
+like ``getYear()`` can also be accessed through ``$time->year``, and so on.
 
 Getters
 -------
@@ -234,37 +234,37 @@ The following basic getters exist::
 
     $time = Time::parse('August 12, 2016 4:15:23pm');
 
-    echo $time->getYear(); // 2016
-    echo $time->getMonth(); // 8
-    echo $time->getDay(); // 12
-    echo $time->getHour(); // 16
+    echo $time->getYear();   // 2016
+    echo $time->getMonth();  // 8
+    echo $time->getDay();    // 12
+    echo $time->getHour();   // 16
     echo $time->getMinute(); // 15
     echo $time->getSecond(); // 23
 
-    echo $time->year; // 2016
-    echo $time->month; // 8
-    echo $time->day; // 12
-    echo $time->hour; // 16
+    echo $time->year;   // 2016
+    echo $time->month;  // 8
+    echo $time->day;    // 12
+    echo $time->hour;   // 16
     echo $time->minute; // 15
     echo $time->second; // 23
 
 In addition to these, a number of methods exist to provide additional information about the date::
 
     $time = Time::parse('August 12, 2016 4:15:23pm');
 
-    echo $time->getDayOfWeek(); // 6 - but may vary based on locale's starting day of the week
-    echo $time->getDayOfYear(); // 225
+    echo $time->getDayOfWeek();   // 6 - but may vary based on locale's starting day of the week
+    echo $time->getDayOfYear();   // 225
     echo $time->getWeekOfMonth(); // 2
-    echo $time->getWeekOfYear(); // 33
-    echo $time->getTimestamp(); // 1471018523 - UNIX timestamp
-    echo $time->getQuarter(); // 3
+    echo $time->getWeekOfYear();  // 33
+    echo $time->getTimestamp();   // 1471018523 - UNIX timestamp
+    echo $time->getQuarter();     // 3
 
-    echo $time->dayOfWeek; // 6
-    echo $time->dayOfYear; // 225
+    echo $time->dayOfWeek;   // 6
+    echo $time->dayOfYear;   // 225
     echo $time->weekOfMonth; // 2
-    echo $time->weekOfYear; // 33
-    echo $time->timestamp; // 1471018523
-    echo $time->quarter; // 3
+    echo $time->weekOfYear;  // 33
+    echo $time->timestamp;   // 1471018523
+    echo $time->quarter;     // 3
 
 getAge()
 --------
@@ -275,22 +275,22 @@ the age of someone based on their birthday::
     $time = Time::parse('5 years ago');
 
     echo $time->getAge(); // 5
-    echo $time->age; // 5
+    echo $time->age;      // 5
 
 getDST()
 --------
 
 Returns boolean true/false based on whether the Time instance is currently observing Daylight Savings Time::
 
     echo Time::createFromDate(2012, 1, 1)->getDst(); // false
-    echo Time::createFromDate(2012, 9, 1)->dst; // true
+    echo Time::createFromDate(2012, 9, 1)->dst;      // true
 
 getLocal()
 ----------
 
 Returns boolean true if the Time instance is in the same timezone as the application is currently running in::
 
-    echo Time::now()->getLocal(); // true
+    echo Time::now()->getLocal();    // true
     echo Time::now('Europe/London'); // false
 
 getUtc()
@@ -299,7 +299,7 @@ getUtc()
 Returns boolean true if the Time instance is in UTC time::
 
     echo Time::now('America/Chicago')->getUtc(); // false
-    echo Time::now('UTC')->utc; // true
+    echo Time::now('UTC')->utc;                  // true
 
 getTimezone()
 -------------
@@ -319,7 +319,7 @@ getTimezoneName()
 Returns the full `timezone string <https://www.php.net/manual/en/timezones.php>`__ of the Time instance::
 
     echo Time::now('America/Chicago')->getTimezoneName(); // America/Chicago
-    echo Time::now('Europe/London')->timezoneName; // Europe/London
+    echo Time::now('Europe/London')->timezoneName;        // Europe/London
 
 Setters
 =======
@@ -334,11 +334,11 @@ thrown.
 ::
 
     $time = $time->setYear(2017);
-    $time = $time->setMonthNumber(4); // April
-    $time = $time->setMonthLongName('April');
-    $time = $time->setMonthShortName('Feb'); // February
+    $time = $time->setMonth(4);       // April
+    $time = $time->setMonth('April');
+    $time = $time->setMonth('Feb');   // February
     $time = $time->setDay(25);
-    $time = $time->setHour(14); // 2:00 pm
+    $time = $time->setHour(14);       // 2:00 pm
     $time = $time->setMinute(30);
     $time = $time->setSecond(54);
 
@@ -350,10 +350,10 @@ Converts the time from it's current timezone into the new one::
     $time  = Time::parse('13 May 2020 10:00', 'America/Chicago');
     $time2 = $time->setTimezone('Europe/London'); // Returns new instance converted to new timezone
 
-    echo $time->getTimezoneName(); // American/Chicago
+    echo $time->getTimezoneName();  // American/Chicago
     echo $time2->getTimezoneName(); // Europe/London
 
-    echo $time->toDateTimeString(); // 2020-05-13 10:00:00
+    echo $time->toDateTimeString();  // 2020-05-13 10:00:00
     echo $time2->toDateTimeString(); // 2020-05-13 18:00:00
 
 setTimestamp()
@@ -364,7 +364,7 @@ Returns a new instance with the date set to the new timestamp::
     $time = Time::parse('May 10, 2017', 'America/Chicago');
     $time2 = $time->setTimestamp(strtotime('April 1, 2017'));
 
-    echo $time->toDateTimeString(); // 2017-05-10 00:00:00
+    echo $time->toDateTimeString();  // 2017-05-10 00:00:00
     echo $time2->toDateTimeString(); // 2017-04-01 00:00:00
 
 Modifying the Value
@@ -416,13 +416,13 @@ a timezone string in as the second parameter. If no timezone is given, the syste
 sameAs()
 --------
 
-This is identical to the **equals** method, except that it only returns true when the date, time, AND timezone are
+This is identical to the ``equals()`` method, except that it only returns true when the date, time, AND timezone are
 all identical::
 
     $time1 = Time::parse('January 10, 2017 21:50:00', 'America/Chicago');
     $time2 = Time::parse('January 11, 2017 03:50:00', 'Europe/London');
 
-    $time1->sameAs($time2);    // false
+    $time1->sameAs($time2); // false
     $time2->sameAs('January 10, 2017 21:50:00', 'America/Chicago'); // true
 
 isBefore()
@@ -446,7 +446,7 @@ a timezone string in as the second parameter. If no timezone is given, the syste
 isAfter()
 ---------
 
-Works exactly the same as **isBefore()** except checks if the time is after the time passed in::
+Works exactly the same as ``isBefore()`` except checks if the time is after the time passed in::
 
     $time1 = Time::parse('January 10, 2017 21:50:00', 'America/Chicago');
     $time2 = Time::parse('January 11, 2017 03:50:00', 'America/Chicago');
@@ -457,7 +457,7 @@ Works exactly the same as **isBefore()** except checks if the time is after the
 Viewing Differences
 ===================
 
-To compare two Times directly, you would use the **difference()** method, which returns a **CodeIgniter\\I18n\\TimeDifference**
+To compare two Times directly, you would use the ``difference()`` method, which returns a ``CodeIgniter\I18n\TimeDifference``
 instance. The first parameter is either a Time instance, a DateTime instance, or a string with the date/time. If
 a string is passed in the first parameter, the second parameter can be a timezone string::
 
@@ -476,28 +476,28 @@ the original time::
 
     $diff = $current->difference($test);
 
-    echo $diff->getYears(); // -7
-    echo $diff->getMonths(); // -84
-    echo $diff->getWeeks(); // -365
-    echo $diff->getDays(); // -2557
-    echo $diff->getHours(); // -61368
+    echo $diff->getYears();   // -7
+    echo $diff->getMonths();  // -84
+    echo $diff->getWeeks();   // -365
+    echo $diff->getDays();    // -2557
+    echo $diff->getHours();   // -61368
     echo $diff->getMinutes(); // -3682080
     echo $diff->getSeconds(); // -220924800
 
-You can use either **getX()** methods, or access the calculate values as if they were properties::
+You can use either ``getX()`` methods, or access the calculate values as if they were properties::
 
     echo $diff->years;   // -7
-    echo $diff->months; // -84
-    echo $diff->weeks; // -365
-    echo $diff->days; // -2557
-    echo $diff->hours; // -61368
+    echo $diff->months;  // -84
+    echo $diff->weeks;   // -365
+    echo $diff->days;    // -2557
+    echo $diff->hours;   // -61368
     echo $diff->minutes; // -3682080
     echo $diff->seconds; // -220924800
 
 humanize()
 ----------
 
-Much like Time's humanize() method, this returns a string that displays the difference between the times in a
+Much like Time's ``humanize()`` method, this returns a string that displays the difference between the times in a
 human readable format that is geared towards being easily understood. It can create strings like '3 hours ago',
 'in 1 month', etc. The biggest differences are in how very recent dates are handled::
 
@@ -522,4 +522,4 @@ $time > 1 minute && < 1 hour     in 35 minutes / 35 minutes ago
 $time < 1 minute                 Now
 =============================== =================================
 
-The exact language used is controlled through the language file, Time.php.
+The exact language used is controlled through the language file, **Time.php**.