[pdf-devel] Changes in the Time module API

[Aleksander Morgado]

Hi all,

I revised the Time module API and I propose the changes attached to the
email. Basically:

- Set as `const' those functions parameters that won't be modified in 
the function call, to easily detect which are input parameters and which 
are output parameters.

- Calendar type stores month/day... in 32bit variables. Probably 8 bits
are enough for these fields (not for `year', which remains in 32bit).

- Changed `pdf_i32_t' name to `pdf_32_t', as defined in pdf_types.h.
BTW, which one is better? I prefer `pdf_32_t', but I could change it.
`pdf_u32_t' remains as is.

- Those functions filling in output `struct pdf_time_cal_span_s' and
`struct pdf_time_cal_s' variables should manage pointers to the
structures (passing by reference the structure in order to be able to
modify its contents).

- Changed the name of the pdf_time_t variable passed to the functions
from `time' to `object', to avoid using the same name as the `time()'
function.

- The function `pdf_time_span_to_secs' was returning a 32bit value to 
represent the time span in seconds. As the time span is stored as a 
64bit value internally, it should return a pdf_64_t.



Cheers,
-Aleksander

Index: gnupdf.texi
===================================================================
RCS file: /cvsroot/pdf/libgnupdf/doc/gnupdf.texi,v
retrieving revision 1.51
diff -c -r1.51 gnupdf.texi
*** gnupdf.texi 21 Apr 2008 20:12:37 -0000      1.51
--- gnupdf.texi 29 Apr 2008 09:55:57 -0000
***************
*** 3470,3490 ****
  seconds and the relative offset with GMT.
  
  @table @code
! @item pdf_i32_t year
  A year number. Negative values may be supported in some systems.
! @item pdf_u32_t month
  A month number. The valid range is @code{1..12}.
! @item pdf_u32_t day
  A day number. The valid range is @code{1..31}.
! @item pdf_u32_t dow
  Day of the week. The valid range is @code{1..7} (Monday to Sunday).
! @item pdf_u32_t hour
  An hour. The valid range is @code{0..23}.
! @item pdf_u32_t minute
  A minute. The valid range is @code{0..59}.
! @item pdf_u32_t sec
  A second. The valid range is @code{0..59}.
! @item pdf_i32_t gmt_offset
  A GMT offset.
  @end table
  @end deftp
--- 3470,3490 ----
  seconds and the relative offset with GMT.
  
  @table @code
! @item pdf_32_t year
  A year number. Negative values may be supported in some systems.
! @item pdf_u8_t month
  A month number. The valid range is @code{1..12}.
! @item pdf_u8_t day
  A day number. The valid range is @code{1..31}.
! @item pdf_u8_t dow
  Day of the week. The valid range is @code{1..7} (Monday to Sunday).
! @item pdf_u8_t hour
  An hour. The valid range is @code{0..23}.
! @item pdf_u8_t minute
  A minute. The valid range is @code{0..59}.
! @item pdf_u8_t sec
  A second. The valid range is @code{0..59}.
! @item pdf_8_t gmt_offset
  A GMT offset.
  @end table
  @end deftp
***************
*** 3546,3552 ****
  @end table
  @end deftypefun
  
! @deftypefun pdf_time_t pdf_time_dup (pdf_time_t @var{orig})
  Dup a new time variable from a given one, allocating memory.
  
  @table @strong
--- 3546,3552 ----
  @end table
  @end deftypefun
  
! @deftypefun pdf_time_t pdf_time_dup (const pdf_time_t @var{orig})
  Dup a new time variable from a given one, allocating memory.
  
  @table @strong
***************
*** 3576,3588 ****
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_destroy (pdf_time_t @var{time})
! Destroy @var{mytime} and free all used memory.
  
  @table @strong
  @item Parameters
  @table @var
! @item time
  The time variable to be destroyed. Should be a properly created time
  variable.
  @end table
--- 3576,3588 ----
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_destroy (pdf_time_t @var{object})
! Destroy @var{object} and free all used memory.
  
  @table @strong
  @item Parameters
  @table @var
! @item object
  The time variable to be destroyed. Should be a properly created time
  variable.
  @end table
***************
*** 3605,3611 ****
  @node Managing Time Values
  @subsection Managing Time Values
  
! @deftypefun pdf_status_t pdf_time_copy (pdf_time_t orig, pdf_time_t 
@var{copy})
  Copies the data from @var{orig} to @var{copy}.
  
  @table @strong
--- 3605,3611 ----
  @node Managing Time Values
  @subsection Managing Time Values
  
! @deftypefun pdf_status_t pdf_time_copy (const pdf_time_t orig, pdf_time_t 
@var{copy})
  Copies the data from @var{orig} to @var{copy}.
  
  @table @strong
***************
*** 3641,3647 ****
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_clear (pdf_time_t @var{time})
  Reset @var{time} to the newly created state. After this call
  @var{time} will contain the same date as if returned by
  @code{pdf_time_new}.
--- 3641,3647 ----
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_clear (pdf_time_t @var{object})
  Reset @var{time} to the newly created state. After this call
  @var{time} will contain the same date as if returned by
  @code{pdf_time_new}.
***************
*** 3649,3655 ****
  @table @strong
  @item Parameters
  @table @var
! @item time
  The time variable to clear. Should be a properly create time variable.
  @end table
  @item Returns
--- 3649,3655 ----
  @table @strong
  @item Parameters
  @table @var
! @item object
  The time variable to clear. Should be a properly create time variable.
  @end table
  @item Returns
***************
*** 3671,3684 ****
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_add_cal_span (pdf_time_t @var{time}, struct 
pdf_time_cal_span_s @var{cal_span})
! Add the time span represented by @var{cal_span} to @var{time}.
  
  @table @strong
  @item Parameters
  
  @table @var
! @item time
  A properly created time variable.
  @item cal_span
  A calendar span with valid values.
--- 3671,3684 ----
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_add_cal_span (pdf_time_t @var{object}, 
const struct pdf_time_cal_span_s @var{cal_span})
! Add the time span represented by @var{cal_span} to @var{object}.
  
  @table @strong
  @item Parameters
  
  @table @var
! @item object
  A properly created time variable.
  @item cal_span
  A calendar span with valid values.
***************
*** 3719,3732 ****
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_sub_cal_span (pdf_time_t @var{time}, struct 
pdf_time_cal_span_s @var{cal_span})
! Subtract the time span represented by @var{cal_span} to @var{time}.
  
  @table @strong
  @item Parameters
  
  @table @var
! @item time
  A properly created time variable.
  @item cal_span
  A calendar span with valid values.
--- 3719,3732 ----
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_sub_cal_span (pdf_time_t @var{object}, 
const struct pdf_time_cal_span_s @var{cal_span})
! Subtract the time span represented by @var{cal_span} to @var{object}.
  
  @table @strong
  @item Parameters
  
  @table @var
! @item object
  A properly created time variable.
  @item cal_span
  A calendar span with valid values.
***************
*** 3777,3790 ****
  @end deftypefun
  
  
! @deftypefun pdf_status_t pdf_time_add_span (pdf_time_t @var{time}, 
pdf_time_span_t @var{time_span})
! Add the time span contained in @var{time_span} to @var{time}.
  
  @table @strong
  @item Parameters
  
  @table @var
! @item time
  A properly created time variable.
  @item time_span
  A properly created time span.
--- 3777,3790 ----
  @end deftypefun
  
  
! @deftypefun pdf_status_t pdf_time_add_span (pdf_time_t @var{object}, const 
pdf_time_span_t @var{time_span})
! Add the time span contained in @var{time_span} to @var{object}.
  
  @table @strong
  @item Parameters
  
  @table @var
! @item object
  A properly created time variable.
  @item time_span
  A properly created time span.
***************
*** 3811,3824 ****
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_sub_span (pdf_time_t @var{time}, 
pdf_time_span_t @var{time_span})
! Subtract the time span contained in @var{time_span} to @var{time}.
  
  @table @strong
  @item Parameters
  
  @table @var
! @item time
  A properly created time variable.
  @item time_span
  A properly created time span.
--- 3811,3824 ----
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_sub_span (pdf_time_t @var{object}, const 
pdf_time_span_t @var{time_span})
! Subtract the time span contained in @var{time_span} to @var{object}.
  
  @table @strong
  @item Parameters
  
  @table @var
! @item object
  A properly created time variable.
  @item time_span
  A properly created time span.
***************
*** 3845,3861 ****
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_get_local_cal (pdf_time_t @var{time}, 
struct pdf_time_cal_s @var{local_cal})
! Fill @var{local_cal} with the local calendar time of @var{time}.
  
  @table @strong
  @item Parameters
  
  @table @var
! @item time
  A properly created time variable.
! @item local_cal
! A time calendar structure that will hold the local time of @var{time}.
  @end table
  
  @item Returns
--- 3845,3862 ----
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_get_local_cal (const pdf_time_t 
@var{object}, struct pdf_time_cal_s address@hidden)
! Fill @var{p_local_cal} with the local calendar time of @var{object}.
  
  @table @strong
  @item Parameters
  
  @table @var
! @item object
  A properly created time variable.
! @item p_local_cal
! A pointer to the time calendar structure that will hold the local time
! of @var{object}.
  @end table
  
  @item Returns
***************
*** 3872,3893 ****
  
  /* ...create and manipulate `mytime'... */
  
! pdf_time_get_local_cal (mytime, cal);
  @end example
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_get_utc_cal (pdf_time_t @var{time}, struct 
pdf_time_cal_s @var{cal_time})
  Get the UTC calendar time of a given time variable.
  
  @table @strong
  @item Parameters
  
  @table @var
! @item time
  A properly created time variable.
! @item cal_time
! A calendar time structure that will hold the UTC time of @var{time}.
  @end table
  
  @item Returns
--- 3873,3894 ----
  
  /* ...create and manipulate `mytime'... */
  
! pdf_time_get_local_cal (mytime, &cal);
  @end example
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_get_utc_cal (const pdf_time_t @var{object}, 
struct pdf_time_cal_s address@hidden)
  Get the UTC calendar time of a given time variable.
  
  @table @strong
  @item Parameters
  
  @table @var
! @item object
  A properly created time variable.
! @item p_cal_time
! A pointer to the calendar time structure that will hold the UTC time of 
@var{object}.
  @end table
  
  @item Returns
***************
*** 3904,3922 ****
  
  /* ...create and manipulate `mytime'... */
  
! pdf_time_get_utc_cal (mytime, cal_time);
  @end example
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_from_cal (pdf_time_t @var{time}, struct 
pdf_time_cal_s @var{cal_time})
  Set the value of a time variable to a given calendar time.
  
  @table @strong
  @item Parameters
  
  @table @var
! @item time
  A properly created time variable.
  @item cal_time
  A calendar time structure.
--- 3905,3923 ----
  
  /* ...create and manipulate `mytime'... */
  
! pdf_time_get_utc_cal (mytime, &cal_time);
  @end example
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_from_cal (pdf_time_t @var{object}, const 
struct pdf_time_cal_s @var{cal_time})
  Set the value of a time variable to a given calendar time.
  
  @table @strong
  @item Parameters
  
  @table @var
! @item object
  A properly created time variable.
  @item cal_time
  A calendar time structure.
***************
*** 3955,3962 ****
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_set_local_offset (pdf_time_t @var{time})
! Set the local time offset of @var{time} to the one used by the
  operating system.
  
  @table @strong
--- 3956,3963 ----
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_set_local_offset (pdf_time_t @var{object})
! Set the local time offset of @var{object} to the one used by the
  operating system.
  
  @table @strong
***************
*** 3987,3997 ****
  @node Getting Time Intervals
  @subsection Getting Time Intervals
  
! @deftypefun pdf_status_t pdf_time_diff_cal (pdf_time_t @var{time1}, 
pdf_time_t @var{time2}, struct pdf_time_cal_span_s @var{cal_span})
  Calculate the time span that goes from @var{time1} to @var{time2} and
! store it in @var{cal_span}.
  
! Note that the highest possible distribution inside @var{cal_span} is used.
  @table @strong
  @item Parameters
  
--- 3988,3998 ----
  @node Getting Time Intervals
  @subsection Getting Time Intervals
  
! @deftypefun pdf_status_t pdf_time_diff_cal (const pdf_time_t @var{time1}, 
const pdf_time_t @var{time2}, struct pdf_time_cal_span_s address@hidden)
  Calculate the time span that goes from @var{time1} to @var{time2} and
! store it in @var{p_cal_span}.
  
! Note that the highest possible distribution inside @var{p_cal_span} is used.
  @table @strong
  @item Parameters
  
***************
*** 4000,4007 ****
  The beginning of the time interval (inclusive).
  @item time2
  The end of the time interval (exclusive).
! @item cal_span
! The calendar time span structure that will hold the time span that
  goes between @var{time1} and @var{time2}.
  @end table
  
--- 4001,4008 ----
  The beginning of the time interval (inclusive).
  @item time2
  The end of the time interval (exclusive).
! @item p_cal_span
! Pointer to the calendar time span structure that will hold the time span that
  goes between @var{time1} and @var{time2}.
  @end table
  
***************
*** 4020,4031 ****
  
  /* ...create and manipulate `time_begin' and `time_end' */
  
! pdf_time_diff (time_begin, time_end, cal_span);
  @end example
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_diff (pdf_time_t @var{time1}, pdf_time_t 
@var{time2}, pdf_time_span_t @var{time_span})
  Calculate the time span between two dates.
  
  @table @strong
--- 4021,4032 ----
  
  /* ...create and manipulate `time_begin' and `time_end' */
  
! pdf_time_diff (time_begin, time_end, &cal_span);
  @end example
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_diff (const pdf_time_t @var{time1}, const 
pdf_time_t @var{time2}, pdf_time_span_t @var{time_span})
  Calculate the time span between two dates.
  
  @table @strong
***************
*** 4065,4071 ****
  @node Time Comparison
  @subsection Time Comparison
  
! @deftypefun pdf_i32_t pdf_time_cmp (pdf_time_t @var{time1}, pdf_time_t 
@var{time2})
  Compares two times.
  
  @table @strong
--- 4066,4072 ----
  @node Time Comparison
  @subsection Time Comparison
  
! @deftypefun pdf_32_t pdf_time_cmp (const pdf_time_t @var{time1}, const 
pdf_time_t @var{time2})
  Compares two times.
  
  @table @strong
***************
*** 4126,4139 ****
  @node Time Printing and Parsing
  @subsection Time Printing and Parsing
  
! @deftypefun char* pdf_time_to_string (pdf_time_t @var{time}, enum 
pdf_time_format_e @var{time_format})
  Create a string representation of a given time.
  
  @table @strong
  @item Parameters
  
  @table @var
! @item time
  A properly created time variable.
  @item time_format
  The format to use when creating the string representation of @var{time}. 
--- 4127,4140 ----
  @node Time Printing and Parsing
  @subsection Time Printing and Parsing
  
! @deftypefun pdf_char_t* pdf_time_to_string (const pdf_time_t @var{object}, 
const enum pdf_time_format_e @var{time_format})
  Create a string representation of a given time.
  
  @table @strong
  @item Parameters
  
  @table @var
! @item object
  A properly created time variable.
  @item time_format
  The format to use when creating the string representation of @var{time}. 
***************
*** 4155,4161 ****
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_from_string (pdf_time_t mytime, char 
address@hidden, enum pdf_time_format_e @var{time_format})
  Get a string containing a time specification in some format and fill a
  time variable with the parsed values.
  
--- 4156,4162 ----
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_from_string (pdf_time_t object, const 
pdf_char_t address@hidden, const enum pdf_time_format_e @var{time_format})
  Get a string containing a time specification in some format and fill a
  time variable with the parsed values.
  
***************
*** 4200,4214 ****
  @node Getting the Current Time
  @subsection Getting the Current Time
  
! @deftypefun pdf_status_t pdf_time_set_to_current_local_time (pdf_time_t 
@var{time})
! Set the value of @var{time} to the current local time used by the
  operating system.
  
  @table @strong
  @item Parameters
  
  @table @var
! @item time
  A properly created time variable.
  @end table
  
--- 4201,4215 ----
  @node Getting the Current Time
  @subsection Getting the Current Time
  
! @deftypefun pdf_status_t pdf_time_set_to_current_local_time (pdf_time_t 
@var{object})
! Set the value of @var{object} to the current local time used by the
  operating system.
  
  @table @strong
  @item Parameters
  
  @table @var
! @item object
  A properly created time variable.
  @end table
  
***************
*** 4230,4243 ****
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_set_to_current_utc_time (pdf_time_t 
@var{time})
! Set the value of @var{time} to the current UTC time used by the operating 
system.
  
  @table @strong
  @item Parameters
  
  @table @var
! @item time
  A properly created time variable.
  @end table
  
--- 4231,4244 ----
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_set_to_current_utc_time (pdf_time_t 
@var{object})
! Set the value of @var{object} to the current UTC time used by the operating 
system.
  
  @table @strong
  @item Parameters
  
  @table @var
! @item object
  A properly created time variable.
  @end table
  
***************
*** 4284,4290 ****
  @end table
  @end deftypefun
  
! @deftypefun pdf_time_span_t pdf_time_span_dup (pdf_time_span_t @var{span})
  
  Allocate and dup a new time span from an existing one. The new time
  span has the same value as the base time span.
--- 4285,4291 ----
  @end table
  @end deftypefun
  
! @deftypefun pdf_time_span_t pdf_time_span_dup (const pdf_time_span_t 
@var{span})
  
  Allocate and dup a new time span from an existing one. The new time
  span has the same value as the base time span.
***************
*** 4344,4350 ****
  @node Managing Time Span Values
  @subsection Managing Time Span Values
  
! @deftypefun pdf_status_t pdf_time_span_set (pdf_time_span_t @var{span}, 
pdf_i32_t @var{high_value}, pdf_u32_t @var{low_value})
  
  Set the value of a time span. The internal representation of the time
  span is 64 bits long (signed).
--- 4345,4351 ----
  @node Managing Time Span Values
  @subsection Managing Time Span Values
  
! @deftypefun pdf_status_t pdf_time_span_set (pdf_time_span_t @var{span}, const 
pdf_32_t @var{high_value}, const pdf_u32_t @var{low_value})
  
  Set the value of a time span. The internal representation of the time
  span is 64 bits long (signed).
***************
*** 4378,4384 ****
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_span_set_from_i32 (pdf_time_span_t 
@var{span}, pdf_i32_t @var{seconds})
  
  Set the value of a time span from a 32 bits signed number.
  
--- 4379,4385 ----
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_span_set_from_i32 (pdf_time_span_t 
@var{span}, const pdf_32_t @var{seconds})
  
  Set the value of a time span from a 32 bits signed number.
  
***************
*** 4440,4446 ****
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_span_add (pdf_time_span_t @var{span1}, 
pdf_time_span_t @var{span2}, pdf_time_span_t @var{result})
  
  Add two time spans and store the result in another time span.
  
--- 4441,4447 ----
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_span_add (const pdf_time_span_t 
@var{span1}, const pdf_time_span_t @var{span2}, pdf_time_span_t @var{result})
  
  Add two time spans and store the result in another time span.
  
***************
*** 4476,4482 ****
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_span_copy (pdf_time_span_t @var{orig}, 
pdf_time_span_t @var{dest})
  
  Copy the value of a time span into another time span.
  
--- 4477,4483 ----
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_span_copy (const pdf_time_span_t 
@var{orig}, pdf_time_span_t @var{dest})
  
  Copy the value of a time span into another time span.
  
***************
*** 4510,4516 ****
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_span_diff (pdf_time_span_t @var{span1}, 
pdf_time_span_t @var{span2}, pdf_time_span_t @var{result})
  
  Difference two time spans and store the result (maybe negative) into
  another time span.
--- 4511,4517 ----
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_span_diff (const pdf_time_span_t 
@var{span1}, const pdf_time_span_t @var{span2}, pdf_time_span_t @var{result})
  
  Difference two time spans and store the result (maybe negative) into
  another time span.
***************
*** 4548,4554 ****
  @end table
  @end deftypefun
  
! @deftypefun pdf_i32_t pdf_time_span_to_secs (pdf_time_span_t @var{span})
  
  Get the value of a time span in seconds. 
  
--- 4549,4555 ----
  @end table
  @end deftypefun
  
! @deftypefun pdf_64_t pdf_time_span_to_secs (const pdf_time_span_t @var{span})
  
  Get the value of a time span in seconds. 
  
***************
*** 4578,4584 ****
  @node Time Span Comparison
  @subsection Time Span Comparison
  
! @deftypefun pdf_i32_t pdf_time_span_cmp (pdf_time_span_t @var{span1}, 
pdf_time_span_t @var{span2})
  
  Compare the length two time spans.
  
--- 4579,4585 ----
  @node Time Span Comparison
  @subsection Time Span Comparison
  
! @deftypefun pdf_32_t pdf_time_span_cmp (const pdf_time_span_t @var{span1}, 
const pdf_time_span_t @var{span2})
  
  Compare the length two time spans.
  
***************
*** 4634,4640 ****
  @node Calendar Spans Management
  @subsection  Calendar Spans Management
  
! @deftypefun pdf_status_t pdf_time_add_cal_span_with_base (struct 
pdf_time_cal_span_s @var{span1}, struct pdf_time_cal_span_s @var{span2}, 
pdf_time_t @var{base_time}, struct pdf_time_cal_span_s @var{result})
  
  Add two calendar spans. Since the calendar spans are relative (some
  years has more days than another) the calendar spans are first
--- 4635,4641 ----
  @node Calendar Spans Management
  @subsection  Calendar Spans Management
  
! @deftypefun pdf_status_t pdf_time_add_cal_span_with_base (const struct 
pdf_time_cal_span_s @var{span1}, const struct pdf_time_cal_span_s @var{span2}, 
const pdf_time_t @var{base_time}, struct pdf_time_cal_span_s address@hidden)
  
  Add two calendar spans. Since the calendar spans are relative (some
  years has more days than another) the calendar spans are first
***************
*** 4650,4657 ****
  The second calendar span to add.
  @item base_time
  The base time to use.
! @item result
! The calendar span to store the result of the add operation.
  @end table
  
  @item Returns
--- 4651,4658 ----
  The second calendar span to add.
  @item base_time
  The base time to use.
! @item p_result
! Pointer to the calendar span to store the result of the add operation.
  @end table
  
  @item Returns
***************
*** 4677,4683 ****
  if (pdf_time_add_cal_span_with_base (cal_span1,
                                       cal_span2,
                                       mytime,
!                                      cal_result) == PDF_EBADDATA)
  @{
    /* Invalid data in `cal_span1' or `cal_span2' */
  @}      
--- 4678,4684 ----
  if (pdf_time_add_cal_span_with_base (cal_span1,
                                       cal_span2,
                                       mytime,
!                                      &cal_result) == PDF_EBADDATA)
  @{
    /* Invalid data in `cal_span1' or `cal_span2' */
  @}      
***************
*** 4686,4692 ****
  @end deftypefun
  
  
! @deftypefun pdf_i32_t pdf_time_cal_span_cmp (struct pdf_time_cal_span_s 
@var{span1}, struct pdf_time_cal_span_s @var{span2}, pdf_time_t @var{base_time})
  
  Compare two calendar spans previously resolved with a given base time.
  
--- 4687,4693 ----
  @end deftypefun
  
  
! @deftypefun pdf_32_t pdf_time_cal_span_cmp (const struct pdf_time_cal_span_s 
@var{span1}, const struct pdf_time_cal_span_s @var{span2}, const pdf_time_t 
@var{base_time})
  
  Compare two calendar spans previously resolved with a given base time.
  
***************
*** 4746,4752 ****
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_cal_span_diff (struct pdf_time_cal_span_s 
@var{span1}, struct pdf_time_cal_span_s @var{span2}, pdf_time_t 
@var{base_time}, struct pdf_time_cal_span_s @var{result})
  
  Compute the difference between two calendar spans relative to a given
  base time and store it in a given calendar span.
--- 4747,4753 ----
  @end table
  @end deftypefun
  
! @deftypefun pdf_status_t pdf_time_cal_span_diff (const struct 
pdf_time_cal_span_s @var{span1}, const struct pdf_time_cal_span_s @var{span2}, 
const pdf_time_t @var{base_time}, struct pdf_time_cal_span_s address@hidden)
  
  Compute the difference between two calendar spans relative to a given
  base time and store it in a given calendar span.
***************
*** 4761,4768 ****
  The second calendar span to diff.
  @item base_time
  The base time. Should be a correctly created time variable.
! @item result
! The calendar structure holding the result of the difference.
  @end table
  
  @item Returns
--- 4762,4769 ----
  The second calendar span to diff.
  @item base_time
  The base time. Should be a correctly created time variable.
! @item p_result
! Pointer to the calendar structure holding the result of the difference.
  @end table
  
  @item Returns
***************
*** 4788,4794 ****
  if (pdf_time_cal_span_diff (span1,
                              span2,
                              mytime,
!                             result) == PDF_EBADDATA)
  @{
    /* Invalid data in `span1' or `span2' */
  @}
--- 4789,4795 ----
  if (pdf_time_cal_span_diff (span1,
                              span2,
                              mytime,
!                             &result) == PDF_EBADDATA)
  @{
    /* Invalid data in `span1' or `span2' */
  @}