docs: add docs

Author: kenjis

user_guide_src/source/changelogs/v4.6.0.rst

@@ -59,6 +59,12 @@ executed twice, an exception will be thrown. See
 
 .. _v460-interface-changes:
 
+Time with Microseconds
+----------------------
+
+Fixed bugs that some methods in ``Time`` to lose microseconds have been fixed.
+See :ref:`Upgrading Guide <upgrade-460-time-keeps-microseconds>` for details.
+
 Interface Changes
 =================
 

user_guide_src/source/installation/upgrade_460.rst

@@ -29,6 +29,42 @@ See :ref:`ChangeLog <v460-behavior-changes-exceptions>` for details.
 
 If you have code that catches these exceptions, change the exception classes.
 
+.. _upgrade-460-time-keeps-microseconds:
+
+Time keeps Microseconds
+=======================
+
+In previous versions, :doc:`Time <../libraries/time>` lost microseconds in some
+cases. But the bugs have been fixed.
+
+The results of the ``Time`` comparison may differ due to these fixes:
+
+.. literalinclude:: upgrade_460/006.php
+   :lines: 2-
+
+In a such case, you need to remove the microseconds:
+
+.. literalinclude:: upgrade_460/007.php
+   :lines: 2-
+
+The following cases now keeps microseconds:
+
+.. literalinclude:: upgrade_460/002.php
+   :lines: 2-
+
+.. literalinclude:: upgrade_460/003.php
+   :lines: 2-
+
+Note that ``Time`` with the current time has been holding microseconds since before.
+
+.. literalinclude:: upgrade_460/004.php
+   :lines: 2-
+
+Also, methods that returns an ``int`` still lose the microseconds.
+
+.. literalinclude:: upgrade_460/005.php
+   :lines: 2-
+
 .. _upgrade-460-registrars-with-dirty-hack:
 
 Registrars with Dirty Hack

user_guide_src/source/installation/upgrade_460/002.php

@@ -0,0 +1,8 @@
+<?php
+
+use CodeIgniter\I18n\Time;
+
+$time = Time::createFromFormat('Y-m-d H:i:s.u', '2024-07-09 09:13:34.654321');
+echo $time->format('Y-m-d H:i:s.u');
+// Before: 2024-07-09 09:13:34.000000
+//  After: 2024-07-09 09:13:34.654321

user_guide_src/source/installation/upgrade_460/003.php

@@ -0,0 +1,8 @@
+<?php
+
+use CodeIgniter\I18n\Time;
+
+$time = new Time('1 hour ago');
+echo $time->format('Y-m-d H:i:s.u');
+// Before: 2024-07-26 21:05:57.000000
+//  After: 2024-07-26 21:05:57.857235

user_guide_src/source/installation/upgrade_460/004.php

@@ -0,0 +1,8 @@
+<?php
+
+use CodeIgniter\I18n\Time;
+
+$time = Time::now();
+echo $time->format('Y-m-d H:i:s.u');
+// Before: 2024-07-26 21:39:32.249072
+//  After: 2024-07-26 21:39:32.249072

user_guide_src/source/installation/upgrade_460/005.php

@@ -0,0 +1,9 @@
+<?php
+
+use CodeIgniter\I18n\Time;
+
+$time1 = new Time('2024-01-01 12:00:00');
+echo $time1->getTimestamp(); // 1704110400
+
+$time2 = new Time('2024-01-01 12:00:00.654321');
+echo $time2->getTimestamp(); // 1704110400

user_guide_src/source/installation/upgrade_460/006.php

@@ -0,0 +1,10 @@
+<?php
+
+use CodeIgniter\I18n\Time;
+
+$time1 = new Time('2024-01-01 12:00:00.654321');
+$time2 = new Time('2024-01-01 12:00:00');
+
+$time1->equals($time2);
+// Before: true
+//  After: false

user_guide_src/source/installation/upgrade_460/007.php

@@ -0,0 +1,17 @@
+<?php
+
+use CodeIgniter\I18n\Time;
+
+$time1 = new Time('2024-01-01 12:00:00.654321');
+$time2 = new Time('2024-01-01 12:00:00');
+
+// Removes the microseconds.
+$time1 = Time::createFromFormat(
+    'Y-m-d H:i:s',
+    $time1->format('Y-m-d H:i:s'),
+    $time1->getTimezone()
+);
+
+$time1->equals($time2);
+// Before: true
+//  After: true