Re: [pdf-devel] time module unit test cases

[jemarch]

Hi Anish.

   > >>  I have following queries regarding time module-

   Again i am having some queries :)

Let's see :)

   >>Since it is an opaque type you (as a library user and while writing
   >>unit tests) dont need to know how it is implemented. If you find
   >>yourself needing to know how pdf_time_t is implemented then there is a
   >>bug in the API.

   1  I want to create time object of following type pdf_time_t as follows:-

       FEB 2 2008-01-01 12:00:00 IST

      How do i create it ? Is their any function for this?

   2:  From the documentation regarding data type pdf_time_span_t i understood
   that it contains time difference between two time objects

       Is my understanding correct?

       so if i want to create  time span of say 12000 seconds How to create
   that?

To answer both questions. The time module provides two kind of data
types: 

- Opaque types: pdf_time_t (for discrete times) and pdf_time_span_t
  (for time intervals)

- Structure types: pdf_time_cal_s (for discrete times) and
  pdf_time_cal_span_s (for time intervals)

The structure types are used as "holders" to pass information to the
opaque types. Lets see some examples.

Say we want to store the FEB 2 2008-01-01 12:00:00 IST date into a
pdf_time_t. Since pdf_time_t is an opaque type I cannot access to its
implementation. Instead I fill the structure type pdf_time_cal_s with
appropriate values:

   struct pdf_time_cal_s my_time_cal;
   
   my_time_cal.year = 2008;
   my_time_cal.month = 2;   /* For february */
   my_time_cal.day = 2;
   my_time_cal.hour = 12;
   my_time_cal.minute = 0;
   my_time_cal.sec = 0;
   my_time_cal.gmt_offset = +4; /* For IST */

Then I make a pdf_time_t variable and initialize it:

   pdf_time_t my_time;

   my_time = pdf_time_new ();

And finally I set its value using the my_time_cal variable and the
`pdf_time_from_cal' function (described in the reference manual):

   pdf_time_from_cal (my_time, my_time_cal);

Later on I would like to get the value of `my_time' out:

   pdf_time_get_local_cal (my_time, my_other_time_cal);

The operation of time span variables (pdf_time_span_t) is quite
similar. We can fill out a time span structure type
(pdf_time_cal_span_s):

    struct pdf_time_cal_span_s my_cal_time_span;
    
    my_cal_time_span.year = 0;
    my_cal_time_span.month = 0;
    my_cal_time_span.day = 0;
    my_cal_time_span.hour = 0;
    my_cal_time_span.minute = 0;
    my_cal_time_span.second = 12000;

and install it into an initialized pdf_time_span_t variable.

Alternatively you could achieve the same functionality using a regular
integer: 

    pdf_time_span_set_from_i32 (my_time_span, 12000);

   3:  I am not getting meaning of function  pdf_status_t pdf_time_span_set
   (pdf_time_span_t span, pdf_i32_t high_value, pdf_u32_t low_value)?

The time module will use an internal signed 64 bit integer variable to
hold the number of seconds of a time span. The pdf_time_span_set
function allow to use two 32bit integers to build the 64bit value. The
HIGH_VALUE argument contain the sign bit and the 31 highest bits of
the 64bit value and the LOW_VALUE argument (an unsigned 32bit integer)
contain the lower 32 bits of the 64bit value.

-- 
Jose E. Marchesi  <address@hidden>
                  <address@hidden>

GNU Spain         http://es.gnu.org
GNU Project       http://www.gnu.org