pr_normalizetime.rst (1745B)
1 PR_NormalizeTime 2 ================ 3 4 Adjusts the fields of a clock/calendar time to their proper ranges, 5 using a callback function. 6 7 8 Syntax 9 ------ 10 11 .. code:: 12 13 #include <prtime.h> 14 15 void PR_NormalizeTime ( 16 PRExplodedTime *time, 17 PRTimeParamFn params); 18 19 20 Parameters 21 ~~~~~~~~~~ 22 23 The function has these parameters: 24 25 ``time`` 26 A pointer to a clock/calendar time in the :ref:`PRExplodedTime` format. 27 ``params`` 28 A time parameter callback function. 29 30 31 Returns 32 ~~~~~~~ 33 34 Nothing; the ``time`` parameter is altered by the callback function. 35 36 37 Description 38 ----------- 39 40 This function adjusts the fields of the specified time structure using 41 the specified time parameter callback function, so that they are in the 42 proper range. 43 44 Call this function in these situations: 45 46 - To normalize a time after performing arithmetic operations directly 47 on the field values of the calendar time object. For example, if you 48 have a ``]`` object that represents the date 3 March 1998 and you 49 want to say "forty days from 3 March 1998", you can simply add 40 to 50 the ``tm_mday`` field and then call ``PR_NormalizeTime()``. 51 52 - To calculate the optional field values ``tm_wday`` and ``tm_yday``. 53 For example, suppose you want to compute the day of week for 3 March 54 1998. You can set ``tm_mday`` to 3, ``tm_month`` to 2, and 55 ``tm_year`` to 1998, and all the other fields to 0, then call 56 ``PR_NormalizeTime()`` with :ref:`PR_GMTParameters`. On return, 57 ``tm_wday`` (and ``tm_yday``) are set for you. 58 59 - To convert from one time zone to another. For example, if the input 60 argument time is in time zone A and the input argument ``params`` 61 represents time zone B, when ``PR_NormalizeTime()`` returns, time 62 will be in time zone B.