date_and_time.rst (2870B)
1 This chapter describes the date and time functions in NSPR. 2 3 NSPR represents time in two ways, absolute time and clock/calendar time. 4 NSPR provides types and constants for both representations, and 5 functions to convert time values between the two. 6 7 - Absolute time representation treats time instants as points along the 8 time line. A time instant is represented by its position on the time 9 line relative to the origin, called the epoch. NSPR defines the epoch 10 to be midnight (00:00:00) 1 January 1970 UTC (Coordinated Universal 11 Time). In this form, time is just a point on the time line. There is 12 no notion of time zone. 13 14 - Clock/calendar time, used for human interfaces, represents time in 15 the familiar year, month, day, hour, minute, second components. In 16 this form, the time zone information is important. For example, 17 without specifying the time zone, the time 8:00AM 1 May 1998 is 18 ambiguous. The NSPR data type for clock/calendar time, called an 19 exploded time, has the time zone information in it, so that its 20 corresponding point in absolute time is uniquely specified. 21 22 Note that absolute and clock times are not normally used in timing 23 operations. For functions that deal with the measurement of elapsed time 24 and with timeouts, see `Interval Timing <Interval_Timing>`__. 25 26 - `Macros for Time Unit 27 Conversion <#Macros_for_Time_Unit_Conversion>`__ 28 - `Types and Constants <#Types_and_Constants>`__ 29 - `Time Parameter Callback 30 Functions <#Time_Parameter_Callback_Functions>`__ 31 - `Functions <#Functions>`__ 32 33 .. _Macros_for_Time_Unit_Conversion: 34 35 Macros for Time Unit Conversion 36 ------------------------------- 37 38 Macros for converting between seconds, milliseconds, microseconds, and 39 nanoseconds. 40 41 - :ref:`PR_MSEC_PER_SEC` 42 - :ref:`PR_USEC_PER_SEC` 43 - :ref:`PR_NSEC_PER_SEC` 44 - :ref:`PR_USEC_PER_MSEC` 45 - :ref:`PR_NSEC_PER_MSEC` 46 47 .. _Types_and_Constants: 48 49 Types and Constants 50 ------------------- 51 52 Types and constants defined for NSPR dates and times are: 53 54 - :ref:`PRTime` 55 - :ref:`PRTimeParameters` 56 - :ref:`PRExplodedTime` 57 58 .. _Time_Parameter_Callback_Functions: 59 60 Time Parameter Callback Functions 61 --------------------------------- 62 63 In some geographic locations, use of Daylight Saving Time (DST) and the 64 rule for determining the dates on which DST starts and ends have changed 65 a few times. Therefore, a callback function is used to determine time 66 zone information. 67 68 You can define your own time parameter callback functions, which must 69 conform to the definition :ref:`PRTimeParamFn`. Two often-used callback 70 functions of this type are provided by NSPR: 71 72 - :ref:`PRTimeParamFn` 73 - :ref:`PR_LocalTimeParameters` and :ref:`PR_GMTParameters` 74 75 Functions 76 --------- 77 78 The functions that create and manipulate time and date values are: 79 80 - :ref:`PR_Now` 81 - :ref:`PR_ExplodeTime` 82 - :ref:`PR_ImplodeTime` 83 - :ref:`PR_NormalizeTime`