1Date::Manip::InterfacesU(s3e)r Contributed Perl DocumentaDtaitoen::Manip::Interfaces(3)
2
6 Date::Manip::Interfaces - A description of functional and OO interfaces
7
9 There are three different ways to use Date::Manip . A complete
10 description of each is included below. They are:
11 Functional interface (version 5)
13 Date::Manip version 5 runs on very old versions of perl. If you
14 need to use Date::Manip with a version of perl older than 5.10,
15 this is the only interface available.
16 Functional interface (version 6)
18 When Date::Manip was rewritten (version 6), it made use of some
19 features of perl 5.10 . This is the recommended interface if you
20 are supporting a script that uses the functional interface, but
21 where a newer version of perl is available.
22 Object-oriented interface
24 The OO interface is the recommended interface wherever possible.
25 It is the only one with access to the full functionality of the
26 module.
27
29 Date::Manip version 5.xx was available for many years, but suffered
30 from several weaknesses. It was slow, and did not handle timezones or
31 daylight saving time correctly. It was written as a functional
32 interface, even though an object-oriented interface would have been
33 better. It did have the advantage of running on very old versions of
34 perl (it is known to work on perl 5.6 and may work on even older
35 versions of perl).
36 Date::Manip version 6.00 was a complete rewrite of the module. For
38 detailed information about the differences, please refer to the
39 Date::Manip::Changes5to6 document. The rewrite was needed in order to
40 handle timezone operations, in addition to many other improvements
41 including much better performance and more robust parsing.
42 The rewrite made use of features introduced in perl 5.10 which made the
44 date parsing routines significantly cleaner. In addition, the 6.xx
45 release was written as an object oriented set of modules which are much
46 more powerful than the older functional interface. For backward
47 compatibility, a new functional interface was rewritten (which is
48 simply a set of wrapper functions which call the OO methods) which is
49 almost entirely backward compatible with the version 5.xx interface.
50 The Date::Manip distribution includes all three of these interfaces:
52 the older version 5 interface, and both the new OO interface and the
53 backward compatible functional interface. Also, all three are
54 installed, so you can use whichever interface is appropriate.
55 Since there are three different interfaces available, choosing the
57 interface is the necessary.
58 If you are running on a system with a very old version of perl (older
60 than 5.10), the version 5 interface is your only option.
61 If you are on a system running a newer version of perl, but need to
63 support a script that was written using the functional interface, then
64 you can use the version 6 functional interface.
65 For everyone else, it is strongly recommended that you use the object-
67 oriented interface.
68 A more detailed description of each interface is included below. If
70 you already know which interface you want to use, just go to the "SEE
71 ALSO" in Date::Manip section for documentation for each interface.
72
74 When using a version of perl older than 5.10, this is the only
75 interface available. This interface is documented in the
76 Date::Manip::DM5 document. This interface has several weaknesses that
77 need to be understood when using it:
78 Limited Support
80 The version 5 functional interface is no longer being developed,
81 and only limited support is available for it.
82 As of December 2012, no development will be done, and I will not
84 correct any remaining bugs in version 5. If a patch is supplied by
85 someone else to fix bugs, I will apply it, provided it applies
86 cleanly, and the resulting code continues to pass all tests. I
87 will not apply patches to add features.
88 I intend to remove this in version 7.00.
90 Limited Time Zone Support
92 Time zone support is extremely limited, and is often incorrect. The
93 lack of time zone support was the primary reason for rewriting
94 Date::Manip.
95 The version 5 interface does not handle daylight saving time
97 changes correctly.
98 Performance Issues
100 Considerable time has been spent speeding up Date::Manip, and
101 fairly simple benchmarks show that version 6 is around twice as
102 fast as version 5.
103 Feel free to email me concerns and comments.
105
107 The version 6 functional interface is almost completely identical to
108 the version 5 functional interface, except that it uses the object-
109 oriented modules to do all the real work.
110 Time zone support is greatly improved, but is still somewhat limited.
112 Since the version 6 interface is backward compatible, dates do not
113 store time zone information in them, so the programmer is responsible
114 for keeping track of what time zone each date is in. If you want full
115 access to the time zone support offered in Date::Manip, you have to use
116 the object-oriented interface.
117 For the most part, scripts written for older versions of Date::Manip
119 will continue to work (and scripts written for the version 6 functional
120 interface will run with the version 5 interface), however in a few
121 cases, you may need to modify your scripts. Please refer to the
122 Date::Manip::Migration5to6 document for a list of changes which may be
123 necessary.
124
126 As of 6.00, Date::Manip consists of a set of OO modules. Each have
127 their own document (see the "SEE ALSO" in Date::Manip section).
128 The OO interface consists of the following modules: Date::Manip::Date,
130 Date::Manip::Delta, Date::Manip::Recur, Date::Manip::TZ, and
131 Date::Manip::Base.
132 The object-oriented interface is the only way to get the full
134 functionality of Date::Manip. It fully support time zones (and daylight
135 saving time).
136
138 If you are running an older version of perl, the version 5 functional
139 interface is the only one available to you, and it will automatically
140 be used.
141 If you are running a newer version of perl (5.10 or higher), you can
143 use the object-oriented modules by loading them directly, or you can
144 use a functional interface.
145 If you use a functional interface, it will default to the version 6
147 interface, but you can choose to run the version 5 interface in one of
148 three ways:
149 Using the OO interface
151 By including any of the following:
152 use Date::Manip::Date;
154 use Date::Manip::Delta;
155 use Date::Manip::Recur;
156 use Date::Manip::TZ;
157 use Date::Manip::Base;
158 you have access to the OO interface for the appropriate types of
160 objects.
161 Use the default functional interface
163 By including:
164 use Date::Manip;
166 in your script, one of the functional interfaces will be loaded.
168 If you are running a version of perl older than 5.10, it will
169 automatically be the version 5 interface. If you are running a
170 newer version of perl, it will automatically load the version 6
171 interface.
172 DATE_MANIP environment variable
174 By setting the DATE_MANIP environment variable to 'DM5' before
175 running the perl script, the version 5 interface will be used.
176 Date::Manip::Backend variable
178 Alternately, you can set the Date::Manip::Backend variable to be
179 'DM5' before loading the module. Typically, this will be done in
180 the following way:
181 BEGIN {
183 $Date::Manip::Backend = 'DM5';
184 }
185 use Date::Manip;
186 Once a functional interface is loaded, you cannot switch between the
188 version 5 and version 6 interfaces.
189
191 Date::Manip - main module documentation
192
194 This script is free software; you can redistribute it and/or modify it
195 under the same terms as Perl itself.
196
198 Sullivan Beck (sbeck@cpan.org)
199perl v5.38.0 2023-07-20 Date::Manip::Interfaces(3)