Skip to content

Commit

Permalink
Deprecate foo_new_clone() in favor of foo_clone()
Browse files Browse the repository at this point in the history
Consistency between const and non-const args for clone functions
  • Loading branch information
EmielBruijntjes authored and Allen Winter committed May 26, 2019
1 parent d101b17 commit 7dc9a96
Show file tree
Hide file tree
Showing 41 changed files with 227 additions and 121 deletions.
2 changes: 2 additions & 0 deletions .krazy
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ EXTRA style

#Skip foo_export.h
SKIP libical_.*_export\.h
#Skip installed macro headers
SKIP libical_deprecated\.h

#Skip examples
SKIP /examples/
Expand Down
19 changes: 15 additions & 4 deletions ReleaseNotes.txt
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,27 @@ Release Highlights
Version 3.1.0 (NOT RELEASED YET):
--------------------------------
* Requires CMake v3.11.0 or higher
* All ical*_new_clone() functions have been deprecated in favour of ical*_clone()
* New publicly available functions:
+ icalrecurrencetype_encode_day
+ icalrecurrencetype_encode_month
+ icaltzutil_set_zone_directory
+ icalcomponent_clone
+ icalproperty_clone
+ icalparameter_clone
+ icalvalue_clone
+ icalcluster_clone
* icaltzutil_get_zone_directory() can use the TZDIR environment to find system zoneinfo
* Deprecated functions:
+ caldat
+ juldat
+ caldat (replaced by internal function icaldat_int())
+ juldat (replaced by internal function juldat_int())
+ icalcomponent_new_clone
+ icalproperty_new_clone
+ icalparameter_new_clone
+ icalvalue_new_clone
+ icalcluster_new_clone
* Removed unused declarations:
(in the public headers but not used at all)
(were in the public headers but not used at all)
+ struct icaltimezonetype
+ struct icaltimezonephase
* Improved performance of recurrence iterators
Expand All @@ -30,7 +41,7 @@ Version 3.0.5 (14 May 2019):
including <libical-glib/libical-glib.h> to be able to use it.
* Built-in timezones updated to tzdata2019a
* De-fuzzifications and Coverity fixes

Version 3.0.4 (14 Aug 2018):
----------------------------
* Silently fail RSCALE recurrence clauses when RSCALE is disabled
Expand Down
15 changes: 0 additions & 15 deletions config.h.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -546,18 +546,3 @@ typedef ssize_t IO_SSIZE_T;
#define _unused(x) (void)x
#endif
#endif

#/* Deprecated function macro */
#if defined(NO_DEPRECATION_WARNINGS)
#define _deprecated(x) x
#else
#if !defined(_deprecated)
#ifdef __GNUC__
#define _deprecated(x) x __attribute__((deprecated))
#elif defined(_MSC_VER)
#define _deprecated(x) __declspec(deprecated) x
#else
#define _deprecated(x) x
#endif
#endif
#endif
3 changes: 2 additions & 1 deletion doc/Doxyfile.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -160,7 +160,8 @@ PREDEFINED = LIBICAL_ICAL_EXPORT="" \
LIBICAL_VCAL_EXPORT="" \
LIBICAL_ICAL_NO_EXPORT="" \
LIBICAL_ICALS_NO_EXPORT="" \
LIBICAL_VCAL_NO_EXPORT=""
LIBICAL_VCAL_NO_EXPORT="" \
LIBICAL_DEPRECATED=
EXPAND_AS_DEFINED =
SKIP_FUNCTION_MACROS = YES
#---------------------------------------------------------------------------
Expand Down
15 changes: 8 additions & 7 deletions doc/UsingLibical.md
Original file line number Diff line number Diff line change
Expand Up @@ -1225,13 +1225,14 @@ caller owns and must free, and some of the memory is managed by the
library. Here is a summary of the memory rules.

1. If the function name has "new" in it (such as `icalcomponent_new()`,
or `icalpropert_new_clone()`), the caller gets control
of the memory.

2. If you got the memory from a routine with new in it, you must
call the corresponding `*_free()` routine to free the memory, for
example use `icalcomponent_free()` to free objects created with
`icalcomponent_new()`)
or `icalproperty_new_from_string()`), the caller gets control
of the memory. The caller also gets control over an object that is
cloned via a function that ends with "_clone" (like `icalcomponent_clone()`)

2. If you got the memory from a routine with "clone" or "new" in it, you
must call the corresponding `*_free()` routine to free the memory,
for example use `icalcomponent_free()` to free objects created with
`icalcomponent_new()` or `icalcomponent_clone()`

3. If the function name has "add" in it, the caller is transferring
control of the memory to the routine, for example the function
Expand Down
14 changes: 8 additions & 6 deletions doc/UsingLibical.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1146,12 +1146,14 @@ caller owns and must free, and some of the memory is managed by the
library. Here is a summary of the memory rules.

1) If the function name has "new" in it (such as icalcomponent_new(),
or icalpropert_new_clone()), the caller gets control
of the memory.

2) If you got the memory from a routine with new in it, you must
call the corresponding *_free routine to free the memory. ( Use
icalcomponent_free() to free objects created with icalcomponent_new())
or icalproperty_new_from_string()), the caller gets control of the
memory. The caller also gets control over an object that is cloned via
a function that ends with "_clone" (like icalcomponent_clone())

2) If you got the memory from a routine with "clone" or "new" in it, you
must call the corresponding *_free() routine to free the memory, for
example use icalcomponent_free() to free objects created with
icalcomponent_new() or icalcomponent_clone().

3) If the function name has "add" in it, the caller is transferring
control of the memory to the routine. ( icalproperty_add_parameter() )
Expand Down
2 changes: 1 addition & 1 deletion examples/access_properties_and_parameters.c
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ void test_properties()
free(str);

/* Make a copy of the property. Caller owns the memory */
clone = icalproperty_new_clone(prop);
clone = icalproperty_clone(prop);

/* Get a reference to the value within the clone property */
value = icalproperty_get_value(clone);
Expand Down
2 changes: 1 addition & 1 deletion src/Net-ICal-Libical/lib/Net/ICal/Libical/Time.pm
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,7 @@ sub clone {

bless( {%$self},ref($self));

$self->{'ref'} = Net::ICal::Libical::icalproperty_new_clone($self->{'ref'});
$self->{'ref'} = Net::ICal::Libical::icalproperty_clone($self->{'ref'});

}

Expand Down
2 changes: 1 addition & 1 deletion src/Net-ICal-Libical/netical.i
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ icalcomponent* icalparser_parse_string(char* str);


icalcomponent* icalcomponent_new(icalcomponent_kind kind);
icalcomponent* icalcomponent_new_clone(icalcomponent* component);
icalcomponent* icalcomponent_clone(icalcomponent* component);
icalcomponent* icalcomponent_new_from_string(char* str);

char* icalcomponent_as_ical_string(icalcomponent* component);
Expand Down
11 changes: 6 additions & 5 deletions src/Net-ICal-Libical/netical_wrap.c
Original file line number Diff line number Diff line change
Expand Up @@ -515,7 +515,7 @@ XS(_wrap_icalcomponent_new) {
XSRETURN(argvi);
}

XS(_wrap_icalcomponent_new_clone) {
XS(_wrap_icalcomponent_clone) {

icalcomponent * _result;
icalcomponent * _arg0;
Expand All @@ -524,12 +524,12 @@ XS(_wrap_icalcomponent_new_clone) {

cv = cv;
if ((items < 1) || (items > 1))
croak("Usage: icalcomponent_new_clone(component);");
croak("Usage: icalcomponent_clone(component);");
if (SWIG_GetPtr(ST(0),(void **) &_arg0,(char *) 0 )) {
croak("Type error in argument 1 of icalcomponent_new_clone. Expected icalcomponentPtr.");
croak("Type error in argument 1 of icalcomponent_clone. Expected icalcomponentPtr.");
XSRETURN(1);
}
_result = (icalcomponent *)icalcomponent_new_clone(_arg0);
_result = (icalcomponent *)icalcomponent_clone(_arg0);
ST(argvi) = sv_newmortal();
sv_setref_pv(ST(argvi++),"icalcomponentPtr", (void *) _result);
XSRETURN(argvi);
Expand Down Expand Up @@ -2901,7 +2901,8 @@ XS(boot_Net__ICal__Libical) {
newXS("Net::ICal::Libical::var_Net__ICal__Libical_init", _wrap_perl5_Net__ICal__Libical_var_init, file);
newXS("Net::ICal::Libical::icalparser_parse_string", _wrap_icalparser_parse_string, file);
newXS("Net::ICal::Libical::icalcomponent_new", _wrap_icalcomponent_new, file);
newXS("Net::ICal::Libical::icalcomponent_new_clone", _wrap_icalcomponent_new_clone, file);
newXS("Net::ICal::Libical::icalcomponent_new_clone", _wrap_icalcomponent_clone, file);
newXS("Net::ICal::Libical::icalcomponent_clone", _wrap_icalcomponent_clone, file);
newXS("Net::ICal::Libical::icalcomponent_new_from_string", _wrap_icalcomponent_new_from_string, file);
newXS("Net::ICal::Libical::icalcomponent_as_ical_string", _wrap_icalcomponent_as_ical_string, file);
newXS("Net::ICal::Libical::icalcomponent_free", _wrap_icalcomponent_free, file);
Expand Down
2 changes: 1 addition & 1 deletion src/Net-ICal-Libical/netical_wrap.doc
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ icalparser_parse_string(str);
icalcomponent_new(kind);
[ returns icalcomponent * ]

icalcomponent_new_clone(component);
icalcomponent_clone(component);
[ returns icalcomponent * ]

icalcomponent_new_from_string(str);
Expand Down
4 changes: 2 additions & 2 deletions src/libical-glib/api/i-cal-component.xml
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@
<returns type="ICalComponent *" annotation="transfer full" comment="The newly created #ICalComponent."/>
<comment xml:space="preserve">Create a new #ICalComponent with specific type.</comment>
</method>
<method name="i_cal_component_clone" corresponds="icalcomponent_new_clone" kind="clone" since="1.0">
<parameter type="ICalComponent *" name="component" comment="The #ICalComponent to be created."/>
<method name="i_cal_component_clone" corresponds="icalcomponent_clone" kind="clone" since="3.1">
<parameter type="const ICalComponent *" name="component" comment="The #ICalComponent to be created."/>
<returns type="ICalComponent *" annotation="transfer full" comment="The newly deeply cloned #ICalComponent."/>
<comment xml:space="preserve">Deeply clone a #ICalComponent.</comment>
</method>
Expand Down
4 changes: 2 additions & 2 deletions src/libical-glib/api/i-cal-parameter.xml
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@
<returns type="ICalParameter *" annotation="transfer full" comment="The newly created #ICalParameter." />
<comment xml:space="preserve">Create a new #ICalParameter according to the kind type</comment>
</method>
<method name="i_cal_parameter_clone" corresponds="icalparameter_new_clone" kind="clone" since="1.0">
<parameter type="ICalParameter *" name="p" annotation="in" comment="The #ICalParameter to be cloned"/>
<method name="i_cal_parameter_clone" corresponds="icalparameter_clone" kind="clone" since="3.1">
<parameter type="const ICalParameter *" name="p" annotation="in" comment="The #ICalParameter to be cloned"/>
<returns type="ICalParameter *" annotation="transfer full" comment="The newly created #ICalParameter with the same properties as the @p." />
<comment xml:space="preserve">Deep clone a #ICalParameter</comment>
</method>
Expand Down
4 changes: 2 additions & 2 deletions src/libical-glib/api/i-cal-property.xml
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@
<returns type="ICalProperty *" annotation="transfer full" comment="The newly created #ICalProperty with the type @kind."/>
<comment xml:space="preserve">Create a #ICalProperty of the target type.</comment>
</method>
<method name="i_cal_property_clone" corresponds="icalproperty_new_clone" kind="clone" since="1.0">
<parameter type="ICalProperty *" name="prop" comment="The #ICalProperty to be cloned."/>
<method name="i_cal_property_clone" corresponds="icalproperty_clone" kind="clone" since="3.1">
<parameter type="const ICalProperty *" name="prop" comment="The #ICalProperty to be cloned."/>
<returns type="ICalProperty *" annotation="transfer full" comment="The newly created #ICalProperty deeply cloned from @prop."/>
<comment xml:space="preserve">Deeply clone a #ICalProperty.</comment>
</method>
Expand Down
2 changes: 1 addition & 1 deletion src/libical-glib/api/i-cal-value.xml
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
<returns type="ICalValue *" annotation="transfer full" comment="The newly created #ICalValue."/>
<comment xml:space="preserve">Create a new #ICalValue with specific kind.</comment>
</method>
<method name="i_cal_value_clone" corresponds="icalvalue_new_clone" kind="clone" since="1.0">
<method name="i_cal_value_clone" corresponds="icalvalue_clone" kind="clone" since="3.1">
<parameter type="const ICalValue *" name="value" comment="The #ICalValue to be cloned."/>
<returns type="ICalValue *" annotation="transfer full" comment="The newly created #ICalValue with the same property as @value."/>
<comment xml:space="preserve">Deeply clone a #ICalValue.</comment>
Expand Down
1 change: 1 addition & 0 deletions src/libical/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -399,6 +399,7 @@ install(FILES
icaltimezone.h
icaltypes.h
icalvalue.h
libical_deprecated.h
libical_ical_export.h
pvl.h
sspm.h
Expand Down
6 changes: 3 additions & 3 deletions src/libical/astime.h
Original file line number Diff line number Diff line change
Expand Up @@ -67,8 +67,8 @@
#ifndef ICAL_ASTIME_H
#define ICAL_ASTIME_H

#include "libical_deprecated.h"
#include "libical_ical_export.h"
#include <config.h>

typedef struct ut_instant
{
Expand All @@ -91,12 +91,12 @@ typedef struct ut_instant
/** converts julian date to year,mo,da
* @deprecated use caldat_int() instead
*/
LIBICAL_ICAL_EXPORT _deprecated(long caldat(UTinstantPtr));
LIBICAL_ICAL_EXPORT LIBICAL_DEPRECATED(long caldat(UTinstantPtr));

/** returns julian day from year,mo,da
* @deprecated use juldat_int() instead
*/
LIBICAL_ICAL_EXPORT _deprecated(double juldat(UTinstantPtr));
LIBICAL_ICAL_EXPORT LIBICAL_DEPRECATED(double juldat(UTinstantPtr));

typedef struct ut_instant_int
{
Expand Down
11 changes: 8 additions & 3 deletions src/libical/icalcomponent.c
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ icalcomponent *icalcomponent_new_from_string(const char *str)

/** @brief Constructor
*/
icalcomponent *icalcomponent_new_clone(icalcomponent *old)
icalcomponent *icalcomponent_clone(const icalcomponent *old)
{
icalcomponent *new;
icalproperty *p;
Expand All @@ -162,17 +162,22 @@ icalcomponent *icalcomponent_new_clone(icalcomponent *old)

for (itr = pvl_head(old->properties); itr != 0; itr = pvl_next(itr)) {
p = (icalproperty *) pvl_data(itr);
icalcomponent_add_property(new, icalproperty_new_clone(p));
icalcomponent_add_property(new, icalproperty_clone(p));
}

for (itr = pvl_head(old->components); itr != 0; itr = pvl_next(itr)) {
c = (icalcomponent *) pvl_data(itr);
icalcomponent_add_component(new, icalcomponent_new_clone(c));
icalcomponent_add_component(new, icalcomponent_clone(c));
}

return new;
}

icalcomponent *icalcomponent_new_clone(icalcomponent *old)
{
return icalcomponent_clone(old);
}

/** @brief Constructor
*/
icalcomponent *icalcomponent_new_x(const char *x_name)
Expand Down
23 changes: 16 additions & 7 deletions src/libical/icalcomponent.h
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
#ifndef ICALCOMPONENT_H
#define ICALCOMPONENT_H

#include "libical_deprecated.h"
#include "libical_ical_export.h"
#include "icalenums.h" /* defines icalcomponent_kind */
#include "icalproperty.h"
Expand All @@ -36,9 +37,14 @@ typedef struct icalcompiter

} icalcompiter;

/**
* Deeply clone an icalcomponent.
* Returns a pointer to the memory for the newly cloned icalcomponent.
* @since 3.1.0
*/
LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new(icalcomponent_kind kind);

LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_clone(icalcomponent *component);
LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_clone(const icalcomponent *component);

LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_from_string(const char *str);

Expand All @@ -58,9 +64,14 @@ LIBICAL_ICAL_EXPORT icalcomponent_kind icalcomponent_isa(const icalcomponent *co

LIBICAL_ICAL_EXPORT int icalcomponent_isa_component(void *component);

/*
* Working with properties
/**
* @copydoc icalcomponent_clone()
* @deprecated use icalcomponent_clone() instead
*/
LIBICAL_ICAL_EXPORT LIBICAL_DEPRECATED(icalcomponent *icalcomponent_new_clone(
icalcomponent *component));

/***** Working with Properties *****/

LIBICAL_ICAL_EXPORT void icalcomponent_add_property(icalcomponent *component,
icalproperty *property);
Expand Down Expand Up @@ -91,9 +102,7 @@ LIBICAL_ICAL_EXPORT icalproperty *icalcomponent_get_first_property(icalcomponent
LIBICAL_ICAL_EXPORT icalproperty *icalcomponent_get_next_property(icalcomponent *component,
icalproperty_kind kind);

/*
* Working with components
*/
/***** Working with Components *****/

/* Return the first VEVENT, VTODO or VJOURNAL sub-component of cop, or
comp if it is one of those types */
Expand Down Expand Up @@ -141,7 +150,7 @@ LIBICAL_ICAL_EXPORT icalcomponent *icalcompiter_prior(icalcompiter * i);

LIBICAL_ICAL_EXPORT icalcomponent *icalcompiter_deref(icalcompiter * i);

/* Working with embedded error properties */
/***** Working with embedded error properties *****/

/* Check the component against itip rules and insert error properties*/
/* Working with embedded error properties */
Expand Down
7 changes: 6 additions & 1 deletion src/libical/icalparameter.c
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ void icalparameter_free(icalparameter *param)
free(param);
}

icalparameter *icalparameter_new_clone(icalparameter *old)
icalparameter *icalparameter_clone(const icalparameter *old)
{
struct icalparameter_impl *new;

Expand Down Expand Up @@ -117,6 +117,11 @@ icalparameter *icalparameter_new_clone(icalparameter *old)
return new;
}

icalparameter *icalparameter_new_clone(icalparameter *old)
{
return icalparameter_clone(old);
}

icalparameter *icalparameter_new_from_string(const char *str)
{
char *eq;
Expand Down
Loading

0 comments on commit 7dc9a96

Please sign in to comment.