:right-sidebar: True

TimeVal
===================================================================

.. currentmodule:: gi.repository.GLib





.. deprecated:: 2.62

   Use :obj:`~gi.repository.GLib.DateTime` or :obj:`int` instead.


.. class:: TimeVal(*args, **kwargs)
   :no-contents-entry:






Represents a precise time, with seconds and microseconds.

Similar to the struct timeval returned by the ``gettimeofday()``
UNIX system call.

GLib is attempting to unify around the use of 64-bit integers to
represent microsecond-precision time. As such, this type will be
removed from a future version of GLib. A consequence of using ``glong`` for
``tv_sec`` is that on 32-bit systems ``GTimeVal`` is subject to the year 2038
problem.




Methods
-------

.. rst-class:: interim-class

.. class:: TimeVal
   :no-index:


   .. method:: add(microseconds: int) -> None

      Adds the given number of microseconds to ``time_``\. ``microseconds`` can
      also be negative to decrease the value of ``time_``\.





      .. deprecated:: 2.62

         :obj:`~gi.repository.GLib.TimeVal` is not year-2038-safe. Use ``guint64`` for
            representing microseconds since the epoch, or use :obj:`~gi.repository.GLib.DateTime`\.



      :param microseconds: number of microseconds to add to ``time``




   .. classmethod:: from_iso8601() -> ~typing.Tuple[bool, ~gi.repository.GLib.TimeVal]

      Converts a string containing an ISO 8601 encoded date and time
      to a :obj:`~gi.repository.GLib.TimeVal` and puts it into ``time_``\.

      ``iso_date`` must include year, month, day, hours, minutes, and
      seconds. It can optionally include fractions of a second and a time
      zone indicator. (In the absence of any time zone indication, the
      timestamp is assumed to be in local time.)

      Any leading or trailing space in ``iso_date`` is ignored.

      This function was deprecated, along with :obj:`~gi.repository.GLib.TimeVal` itself, in GLib 2.62.
      Equivalent functionality is available using code like:


      .. code-block::
          :dedent:

          GDateTime *dt = g_date_time_new_from_iso8601 (iso8601_string, NULL);
          gint64 time_val = g_date_time_to_unix (dt);
          g_date_time_unref (dt);


      .. versionadded:: 2.12




      .. deprecated:: 2.62

         :obj:`~gi.repository.GLib.TimeVal` is not year-2038-safe. Use
            :func:`~gi.repository.GLib.DateTime.new_from_iso8601` instead.






   .. method:: to_iso8601() -> str | None

      Converts ``time_`` into an RFC 3339 encoded string, relative to the
      Coordinated Universal Time (UTC). This is one of the many formats
      allowed by ISO 8601.

      ISO 8601 allows a large number of date/time formats, with or without
      punctuation and optional elements. The format returned by this function
      is a complete date and time, with optional punctuation included, the
      UTC time zone represented as "Z", and the ``tv_usec`` part included if
      and only if it is nonzero, i.e. either
      "YYYY-MM-DDTHH:MM:SSZ" or "YYYY-MM-DDTHH:MM:SS.fffffZ".

      This corresponds to the Internet date/time format defined by
      `RFC 3339 <https://www.ietf.org/rfc/rfc3339.txt>`__\,
      and to either of the two most-precise formats defined by
      the W3C Note
      `Date and Time Formats <http://www.w3.org/TR/NOTE-datetime-19980827>`__\.
      Both of these documents are profiles of ISO 8601.

      Use :func:`~gi.repository.GLib.DateTime.format` or :func:`~gi.repository.GLib.strdup_printf` if a different
      variation of ISO 8601 format is required.

      If ``time_`` represents a date which is too large to fit into a ``struct tm``\,
      :const:`None` will be returned. This is platform dependent. Note also that since
      ``GTimeVal`` stores the number of seconds as a ``glong``\, on 32-bit systems it
      is subject to the year 2038 problem. Accordingly, since GLib 2.62, this
      function has been deprecated. Equivalent functionality is available using:


      .. code-block::
          :dedent:

          GDateTime *dt = g_date_time_new_from_unix_utc (time_val);
          iso8601_string = g_date_time_format_iso8601 (dt);
          g_date_time_unref (dt);

      The return value of :func:`~gi.repository.GLib.TimeVal.to_iso8601` has been nullable since GLib
      2.54; before then, GLib would crash under the same conditions.


      .. versionadded:: 2.12




      .. deprecated:: 2.62

         :obj:`~gi.repository.GLib.TimeVal` is not year-2038-safe. Use
            g_date_time_format_iso8601(dt) instead.
















Fields
------

.. rst-class:: interim-class

.. class:: TimeVal
   :no-index:
   

   .. attribute:: tv_sec

      Seconds






   .. attribute:: tv_usec

      Microseconds