Re: [pdf-devel] Changes in the Time module API

[Aleksander Morgado]

>    >    - 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.
>    > 
>    > I much prefer the `pdf_i32_t' name, since it makes explicit that the
>    > stored value is a (signed) integer.
>
>    I bet yesterday with Daniel that you would say that :-). Ok, I will 
>    change the pdf_32_t with pdf_i32_t in the whole library (text module 
>    basically).
>
> Ok, thanks.

Done and commited to CVS.


>    > Hm? `time' is more explicit. Being an actual parameter, where is the
>    > confusion with time()?
>
>    Just didn't want to make the compiler unhappy if `time()' is actually 
>    used in a function receiving a variable named `time', which could really 
>    happen in this module.
>
> Then lets use `time_var'. It is a lot more autodocumented than
> `object'.

Ok, so here is the new patch with the changes in the API.

Index: gnupdf.texi
===================================================================
RCS file: /cvsroot/pdf/libgnupdf/doc/gnupdf.texi,v
retrieving revision 1.51
diff -r1.51 gnupdf.texi
3456c3456
< A variable of type @code{pdf_time_t} contain information about a
---
> A variable of type @code{pdf_time_t} contains information about a
3463c3463
< A variable of type @code{pdf_time_span_t} represent a span of time.
---
> A variable of type @code{pdf_time_span_t} represents a span of time.
3549c3549
< @deftypefun pdf_time_t pdf_time_dup (pdf_time_t @var{orig})
---
> @deftypefun pdf_time_t pdf_time_dup (const pdf_time_t @var{orig})
3579,3580c3579,3580
< @deftypefun pdf_status_t pdf_time_destroy (pdf_time_t @var{time})
< Destroy @var{mytime} and free all used memory.
---
> @deftypefun pdf_status_t pdf_time_destroy (pdf_time_t @var{time_var})
> Destroy @var{time_var} and free all used memory.
3585c3585
< @item time
---
> @item time_var
3608c3608
< @deftypefun pdf_status_t pdf_time_copy (pdf_time_t orig, pdf_time_t 
@var{copy})
---
> @deftypefun pdf_status_t pdf_time_copy (const pdf_time_t @var{orig}, 
> pdf_time_t @var{copy})
3644,3646c3644,3646
< @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
---
> @deftypefun pdf_status_t pdf_time_clear (pdf_time_t @var{time_var})
> Reset @var{time_var} to the newly created state. After this call
> @var{time_var} will contain the same date as if returned by
3652c3652
< @item time
---
> @item time_var
3674,3675c3674,3675
< @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}.
---
> @deftypefun pdf_status_t pdf_time_add_cal_span (pdf_time_t @var{time_var}, 
> const struct pdf_time_cal_span_s @var{cal_span})
> Add the time span represented by @var{cal_span} to @var{time_var}.
3681c3681
< @item time
---
> @item time_var
3722,3723c3722,3723
< @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}.
---
> @deftypefun pdf_status_t pdf_time_sub_cal_span (pdf_time_t @var{time_var}, 
> const struct pdf_time_cal_span_s @var{cal_span})
> Subtract the time span represented by @var{cal_span} to @var{time_var}.
3729c3729
< @item time
---
> @item time_var
3780,3781c3780,3781
< @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}.
---
> @deftypefun pdf_status_t pdf_time_add_span (pdf_time_t @var{time_var}, const 
> pdf_time_span_t @var{time_span})
> Add the time span contained in @var{time_span} to @var{time_var}.
3787c3787
< @item time
---
> @item time_var
3814,3815c3814,3815
< @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}.
---
> @deftypefun pdf_status_t pdf_time_sub_span (pdf_time_t @var{time_var}, const 
> pdf_time_span_t @var{time_span})
> Subtract the time span contained in @var{time_span} to @var{time_var}.
3821c3821
< @item time
---
> @item time_var
3848,3849c3848,3849
< @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}.
---
> @deftypefun pdf_status_t pdf_time_get_local_cal (const pdf_time_t 
> @var{time_var}, struct pdf_time_cal_s address@hidden)
> Fill @var{p_local_cal} with the local calendar time of @var{time_var}.
3855c3855
< @item time
---
> @item time_var
3857,3858c3857,3859
< @item local_cal
< A time calendar structure that will hold the local time of @var{time}.
---
> @item p_local_cal
> A pointer to the time calendar structure that will hold the local time
> of @var{time_var}.
3875c3876
< pdf_time_get_local_cal (mytime, cal);
---
> pdf_time_get_local_cal (mytime, &cal);
3880c3881
< @deftypefun pdf_status_t pdf_time_get_utc_cal (pdf_time_t @var{time}, struct 
pdf_time_cal_s @var{cal_time})
---
> @deftypefun pdf_status_t pdf_time_get_utc_cal (const pdf_time_t 
> @var{time_var}, struct pdf_time_cal_s address@hidden)
3887c3888
< @item time
---
> @item time_var
3889,3890c3890,3891
< @item cal_time
< A calendar time structure that will hold the UTC time of @var{time}.
---
> @item p_cal_time
> A pointer to the calendar time structure that will hold the UTC time of 
> @var{time_var}.
3907c3908
< pdf_time_get_utc_cal (mytime, cal_time);
---
> pdf_time_get_utc_cal (mytime, &cal_time);
3912c3913
< @deftypefun pdf_status_t pdf_time_from_cal (pdf_time_t @var{time}, struct 
pdf_time_cal_s @var{cal_time})
---
> @deftypefun pdf_status_t pdf_time_from_cal (pdf_time_t @var{time_var}, const 
> struct pdf_time_cal_s @var{cal_time})
3919,3920c3920,3921
< @item time
< A properly created time variable.
---
> @item time_var
> A properl created time variable.
3958,3959c3959,3960
< @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
---
> @deftypefun pdf_status_t pdf_time_set_local_offset (pdf_time_t @var{time_var})
> Set the local time offset of @var{time_var} to the one used by the
3990c3991
< @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})
---
> @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)
3992c3993
< store it in @var{cal_span}.
---
> store it in @var{p_cal_span}.
3994c3995
< Note that the highest possible distribution inside @var{cal_span} is used.
---
> Note that the highest possible distribution inside @var{p_cal_span} is used.
4003,4004c4004,4005
< @item cal_span
< The calendar time span structure that will hold the time span that
---
> @item p_cal_span
> Pointer to the calendar time span structure that will hold the time span that
4023c4024
< pdf_time_diff (time_begin, time_end, cal_span);
---
> pdf_time_diff (time_begin, time_end, &cal_span);
4028c4029
< @deftypefun pdf_status_t pdf_time_diff (pdf_time_t @var{time1}, pdf_time_t 
@var{time2}, pdf_time_span_t @var{time_span})
---
> @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})
4068c4069
< @deftypefun pdf_i32_t pdf_time_cmp (pdf_time_t @var{time1}, pdf_time_t 
@var{time2})
---
> @deftypefun pdf_i32_t pdf_time_cmp (const pdf_time_t @var{time1}, const 
> pdf_time_t @var{time2})
4129c4130
< @deftypefun char* pdf_time_to_string (pdf_time_t @var{time}, enum 
pdf_time_format_e @var{time_format})
---
> @deftypefun pdf_char_t* pdf_time_to_string (const pdf_time_t @var{time_var}, 
> const enum pdf_time_format_e @var{time_format})
4136c4137
< @item time
---
> @item time_var
4158c4159
< @deftypefun pdf_status_t pdf_time_from_string (pdf_time_t mytime, char 
address@hidden, enum pdf_time_format_e @var{time_format})
---
> @deftypefun pdf_status_t pdf_time_from_string (pdf_time_t @var{time_var}, 
> const pdf_char_t address@hidden, const enum pdf_time_format_e 
> @var{time_format})
4166c4167
< @item mytime
---
> @item time_var
4203,4204c4204,4205
< @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
---
> @deftypefun pdf_status_t pdf_time_set_to_current_local_time (pdf_time_t 
> @var{time_var})
> Set the value of @var{time_var} to the current local time used by the
4211c4212
< @item time
---
> @item time_var
4233,4234c4234,4235
< @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.
---
> @deftypefun pdf_status_t pdf_time_set_to_current_utc_time (pdf_time_t 
> @var{time_var})
> Set the value of @var{time_var} to the current UTC time used by the operating 
> system.
4240c4241
< @item time
---
> @item time_var
4287c4288
< @deftypefun pdf_time_span_t pdf_time_span_dup (pdf_time_span_t @var{span})
---
> @deftypefun pdf_time_span_t pdf_time_span_dup (const pdf_time_span_t 
> @var{span})
4347c4348
< @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})
---
> @deftypefun pdf_status_t pdf_time_span_set (pdf_time_span_t @var{span}, const 
> pdf_i32_t @var{high_value}, const pdf_u32_t @var{low_value})
4381c4382
< @deftypefun pdf_status_t pdf_time_span_set_from_i32 (pdf_time_span_t 
@var{span}, pdf_i32_t @var{seconds})
---
> @deftypefun pdf_status_t pdf_time_span_set_from_i32 (pdf_time_span_t 
> @var{span}, const pdf_i32_t @var{seconds})
4443c4444
< @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})
---
> @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})
4479c4480
< @deftypefun pdf_status_t pdf_time_span_copy (pdf_time_span_t @var{orig}, 
pdf_time_span_t @var{dest})
---
> @deftypefun pdf_status_t pdf_time_span_copy (const pdf_time_span_t 
> @var{orig}, pdf_time_span_t @var{dest})
4513c4514
< @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})
---
> @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})
4551c4552
< @deftypefun pdf_i32_t pdf_time_span_to_secs (pdf_time_span_t @var{span})
---
> @deftypefun pdf_64_t pdf_time_span_to_secs (const pdf_time_span_t @var{span})
4581c4582
< @deftypefun pdf_i32_t pdf_time_span_cmp (pdf_time_span_t @var{span1}, 
pdf_time_span_t @var{span2})
---
> @deftypefun pdf_i32_t pdf_time_span_cmp (const pdf_time_span_t @var{span1}, 
> const pdf_time_span_t @var{span2})
4637c4638
< @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})
---
> @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)
4653,4654c4654,4655
< @item result
< The calendar span to store the result of the add operation.
---
> @item p_result
> Pointer to the calendar span to store the result of the add operation.
4680c4681
<                                      cal_result) == PDF_EBADDATA)
---
>                                      &cal_result) == PDF_EBADDATA)
4689c4690
< @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})
---
> @deftypefun pdf_i32_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})
4749c4750
< @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})
---
> @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)
4764,4765c4765,4766
< @item result
< The calendar structure holding the result of the difference.
---
> @item p_result
> Pointer to the calendar structure holding the result of the difference.
4791c4792
<                             result) == PDF_EBADDATA)
---
>                             &result) == PDF_EBADDATA)