1Date::Tiny(3) User Contributed Perl Documentation Date::Tiny(3)
2
6 Date::Tiny - A date object with as little code as possible
7
9 # Create a date manually
10 $christmas = Date::Tiny->new(
11 year => 2006,
12 month => 12,
13 day => 25,
14 );
15 # Show the current date
17 $today = Date::Tiny->now;
18 print "Year : " . $today->year . "\n";
19 print "Month: " . $today->month . "\n";
20 print "Day : " . $today->day . "\n";
21
23 Date::Tiny is a member of the DateTime::Tiny suite of time modules.
24 It implements an extremely lightweight object that represents a date,
26 without any time data.
27 The Tiny Mandate
29 Many CPAN modules which provide the best implementation of a concept
30 can be very large. For some reason, this generally seems to be about 3
31 megabyte of ram usage to load the module.
32 For a lot of the situations in which these large and comprehensive
34 implementations exist, some people will only need a small fraction of
35 the functionality, or only need this functionality in an ancillary
36 role.
37 The aim of the Tiny modules is to implement an alternative to the large
39 module that implements a subset of the functionality, using as little
40 code as possible.
41 Typically, this means a module that implements between 50% and 80% of
43 the features of the larger module, but using only 100 kilobytes of
44 code, which is about 1/30th of the larger module.
45 The Concept of Tiny Date and Time
47 Due to the inherent complexity, Date and Time is intrinsically very
48 difficult to implement properly.
49 The arguably only module to implement it completely correct is
51 DateTime. However, to implement it properly DateTime is quite slow and
52 requires 3-4 megabytes of memory to load.
53 The challenge in implementing a Tiny equivalent to DateTime is to do so
55 without making the functionality critically flawed, and to carefully
56 select the subset of functionality to implement.
57 If you look at where the main complexity and cost exists, you will find
59 that it is relatively cheap to represent a date or time as an object,
60 but much much more expensive to modify or convert the object.
61 As a result, Date::Tiny provides the functionality required to
63 represent a date as an object, to stringify the date and to parse it
64 back in, but does not allow you to modify the dates.
65 The purpose of this is to allow for date object representations in
67 situations like log parsing and fast real-time work.
68 The problem with this is that having no ability to modify date limits
70 the usefulness greatly.
71 To make up for this, if you have DateTime installed, any Date::Tiny
73 module can be inflated into the equivalent DateTime as needing, loading
74 DateTime on the fly if necesary.
75 For the purposes of date/time logic, all Date::Tiny objects exist in
77 the "C" locale, and the "floating" time zone (although obviously in a
78 pure date context, the time zone largely doesn't matter).
79 When converting up to full DateTime objects, these local and time zone
81 settings will be applied (although an ability is provided to override
82 this).
83 In addition, the implementation is strictly correct and is intended to
85 be very easily to sub-class for specific purposes of your own.
86
88 In general, the intent is that the API be as close as possible to the
89 API for DateTime. Except, of course, that this module implements less
90 of it.
91 new
93 my $date = Date::Tiny->new(
94 year => 2006,
95 month => 12,
96 day => 31,
97 );
98 The "new" constructor creates a new Date::Tiny object.
100 It takes three named params. "day" should be the day of the month
102 (1-31), "month" should be the month of the year (1-12), "year" as a 4
103 digit year.
104 These are the only params accepted.
106 Returns a new Date::Tiny object.
108 now
110 my $current_date = Date::Tiny->now;
111 The "now" method creates a new date object for the current date.
113 The date created will be based on localtime, despite the fact that the
115 date is created in the floating time zone.
116 Returns a new Date::Tiny object.
118 year
120 The "year" accessor returns the 4-digit year for the date.
121 month
123 The "month" accessor returns the 1-12 month of the year for the date.
124 day
126 The "day" accessor returns the 1-31 day of the month for the date.
127 ymd
129 The "ymd" method returns the most common and accurate stringified date
130 format, which returns in the form "2006-04-12".
131 as_string
133 The "as_string" method converts the date to the default string, which
134 at present is the same as that returned by the "ymd" method above.
135 This string matches the ISO 8601 standard for the encoding of a date as
137 a string.
138 from_string
140 The "from_string" method creates a new Date::Tiny object from a string.
141 The string is expected to be a "yyyy-mm-dd" ISO 8601 time string.
143 my $almost_christmas = Date::Tiny->from_string( '2006-12-23' );
145 Returns a new Date::Tiny object, or throws an exception on error.
147 DateTime
149 The "DateTime" method is used to create a DateTime object that is
150 equivalent to the Date::Tiny object, for use in comversions and
151 caluculations.
152 As mentioned earlier, the object will be set to the 'C' locate, and the
154 'floating' time zone.
155 If installed, the DateTime module will be loaded automatically.
157 Returns a DateTime object, or throws an exception if DateTime is not
159 installed on the current host.
160
162 Bugs should be reported via the CPAN bug tracker at
163 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Date-Tiny
165 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Date-Tiny>
166 For other issues, or commercial enhancement or support, contact the
168 author.
169
171 Adam Kennedy <adamk@cpan.org>
172
174 DateTime, DateTime::Tiny, Time::Tiny, Config::Tiny, ali.as
175
177 Copyright 2006 - 2009 Adam Kennedy.
178 This program is free software; you can redistribute it and/or modify it
180 under the same terms as Perl itself.
181 The full text of the license can be found in the LICENSE file included
183 with this module.
184perl v5.12.0 2009-04-20 Date::Tiny(3)