001 
002 /*
003  *  Descripter 1.0 - Java Script Engines
004  *  Copyright (C) 2010-2015  Jianjun Liu (J.J.Liu)
005  *  
006  *  This program is free software: you can redistribute it and/or modify
007  *  it under the terms of the GNU Affero General Public License as published by
008  *  the Free Software Foundation, either version 3 of the License, or
009  *  (at your option) any later version.
010  *  
011  *  This program is distributed in the hope that it will be useful,
012  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
013  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014  *  GNU Affero General Public License for more details.
015  *  
016  *  You should have received a copy of the GNU Affero General Public License
017  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
018  */
019 
020 package org.descripter.js.api.core;
021 
022 import java.text.DateFormat;
023 import java.text.ParseException;
024 import java.util.Calendar;
025 import java.util.GregorianCalendar;
026 
027 import org.descripter.js.api.Function;
028 
029 /**
030  * <p>Emulates JavaScript Date objects.</p>
031  * 
032  * @author <a href="mailto:jianjunliu@126.com">J.J.Liu (Jianjun Liu)</a> at <a href="http://www.descripter.org" target="_blank">http://www.descripter.org</a>
033  * @since Descripter 1.0
034  */
035 public class CDate extends CObject
036 {
037     private final Calendar cal;
038 
039     /**
040      * <p>Constructs a {@link CObject} context of this type.</p>
041      * @param constructor The constructor {@link Function} object.
042      * @since Descripter 1.0
043      */
044     public CDate(Function<?> constructor) {
045         super(constructor);
046         cal = new GregorianCalendar();
047     }
048 
049     /**
050      * <p>Constructs a {@link CObject} context of this type.</p>
051      * @param constructor The constructor {@link Function} object.
052      * @param n The initial number value for the date object in milliseconds
053      * @since Descripter 1.0
054      */
055     public CDate(Function<?> constructor, Number n) {
056         super(constructor);
057         cal = new GregorianCalendar();
058         cal.setTimeInMillis(n.longValue());
059     }
060 
061     /**
062      * <p>Constructs a {@link CObject} context of this type.</p>
063      * @param constructor The constructor {@link Function} object.
064      * @param s A string representation for the initial value of the date object
065      * @since Descripter 1.0
066      */
067     public CDate(Function<?> constructor, String s) {
068         super(constructor);
069         cal = new GregorianCalendar();
070         try {
071             cal.setTime(DateFormat.getInstance().parse(s));
072         } catch (ParseException e) {
073             e.printStackTrace();
074         }
075     }
076 
077     /**
078      * <p>Returns the day of the month of the current date instance, in local time.</p>
079      * @return The day of the month of the current date instance, using local time. 
080      * Return values are between 1 and 31.
081      * @see #getUTCDate()
082      * @since Descripter 1.0
083      */
084     public final Number getDate() {
085         return cal.get(Calendar.DATE);
086     }
087 
088     /**
089      * <p>Returns the day of the week of the current date instance, in local time.</p>
090      * @return The day of the week of the current date instance, using local time. Return values 
091      * are between 0 (Sunday) and 6 (Saturday).
092      * @see #getUTCDay()
093      * @since Descripter 1.0
094      */
095     public final Number getDay() {
096         return cal.get(Calendar.DAY_OF_WEEK);
097     }
098 
099     /**
100      * <p>Returns the year of the current date instance in full four-digit form, in local 
101      * time.</p>
102      * @return The year that results when the current date instance is expressed in local 
103      * time. The return value is a full four-digit year, including the century, not a 
104      * two-digit abbreviation..
105      * @see #getUTCFullYear()
106      * @since Descripter 1.0
107      */
108     public final Number getFullYear() {
109         return cal.get(Calendar.YEAR);
110     }
111 
112     /**
113      * <p>Returns the hours field of the current date instance, in local time.</p>
114      * @return The hours field, expressed in local time, of the current date instance. 
115      * Return values are between 0 (midnight) and 23 (11 p.m.).
116      * @see #getUTCHours()
117      * @since Descripter 1.0
118      */
119     public final Number getHours() {
120         return cal.get(Calendar.HOUR_OF_DAY);
121     }
122 
123     /**
124      * <p>Returns the milliseconds field of the current date instance, in local time.</p>
125      * @return The milliseconds field, expressed in local time, of the current date instance.
126      * @see #getUTCMilliseconds()
127      * @since Descripter 1.0
128      */
129     public final Number getMilliseconds() {
130         return cal.get(Calendar.MILLISECOND);
131     }
132 
133     /**
134      * <p>Returns the minutes field of a Date object, in local or universal time.</p>
135      * @return The minutes field, expressed in local time, of the current date instance. 
136      * Return values are between 0 and 59.
137      * @see #getUTCMinutes()
138      * @since Descripter 1.0
139      */
140     public final Number getMinutes() {
141         return cal.get(Calendar.MINUTE);
142     }
143 
144     /**
145      * <p>Returns the month field of the current date instance, in local time.</p>
146      * @return The month of the year that results when the current date instance is 
147      * expressed in local time. The return value is an integer between 0 (January) 
148      * and 11 (December). Note that the date represents the first day of the month as 1 
149      * but represents the first month of the year as 0.
150      * @see #getUTCMonth()
151      * @since Descripter 1.0
152      */
153     public final Number getMonth() {
154         return cal.get(Calendar.MONTH);
155     }
156 
157     /**
158      * <p>Returns the seconds field of the current date instance, in local time.</p>
159      * @return The seconds field, expressed in local time, of the current date instance. 
160      * Return values are between 0 and 59.
161      * @see #getUTCSeconds()
162      * @since Descripter 1.0
163      */
164     public final Number getSeconds() {
165         return cal.get(Calendar.SECOND);
166     }
167 
168     /**
169      * <p>Returns the internal, millisecond representation of the current date instance.</p>
170      * <p>It converts the current date instance to a single integer. This is useful when 
171      * you want to compare two date instances or to determine the time elapsed between two 
172      * dates. Note that the millisecond representation of a date is independent of the 
173      * time zone, so there is no <tt>getUTCTime()</tt> method in addition to this one. 
174      * Don't confuse this method with the {@link #getDay()} and {@link #getDate()} methods, 
175      * which return the day of the week and the day of the month, respectively</p>
176      * @return The millisecond representation of the current date instance, that is, the 
177      * number of milliseconds between midnight (GMT) on 1/1/1970 and the date and time 
178      * specified by the date.
179      * @see #setTime(Number)
180      * @since Descripter 1.0
181      */
182     public final Number getTime() {
183         return cal.getTimeInMillis();
184     }
185 
186     /**
187      * <p>Returns the difference, in minutes, between the local and UTC representations of 
188      * the current date instance. Note that the value returned depends on whether daylight 
189      * saving time is or would be in effect at the specific date.</p>
190      * <p>The return value is measured in minutes, rather than hours, because some 
191      * countries have time zones that are not at even one-hour intervals.</p>
192      * @return The difference, in minutes, between GMT and local time.
193      * @since Descripter 1.0
194      */
195     public final Number getTimezoneOffset() {
196         return cal.get(Calendar.ZONE_OFFSET) / 60000;
197     }
198 
199     /**
200      * <p>Returns the day of the month of the current date instance, in universal time.</p>
201      * @return The day of the month (a value between 1 and 31) that results when the 
202      * current date instance is expressed in universal time.
203      * @see #getDate()
204      * @since Descripter 1.0
205      */
206     public final Number getUTCDate() {
207         return cal.get(Calendar.DATE);
208     }
209 
210     /**
211      * <p>Returns the day of the week of current date instance, in universal time.</p>
212      * @return The day of the week that results when the current date instance is expressed 
213      * in universal time. Return values are between 0 (Sunday) and 6 (Saturday).
214      * @see #getDay()
215      * @since Descripter 1.0
216      */
217     public final Number getUTCDay() {
218         return cal.get(Calendar.DAY_OF_WEEK);
219     }
220 
221     /**
222      * <p>Returns the year of the current date instance in full four-digit form, in 
223      * universal time.</p>
224      * @return The year that results when the current date instance is expressed in 
225      * universal time. The return value is a full four-digit year, not a two-digit 
226      * abbreviation.
227      * @see #getFullYear()
228      * @since Descripter 1.0
229      */
230     public final Number getUTCFullYear() {
231         return cal.get(Calendar.YEAR);
232     }
233 
234     /**
235      * <p>Returns the hours field of the current date instance, in universal time.</p>
236      * @return The hours field, expressed in universal time, of the current date instance. 
237      * The return value is an integer between 0 (midnight) and 23 (11 p.m.).
238      * @see #getHours()
239      * @since Descripter 1.0
240      */
241     public final Number getUTCHours() {
242         return cal.get(Calendar.HOUR_OF_DAY);
243     }
244 
245     /**
246      * <p>Returns the milliseconds field of current date instance, in universal time.</p>
247      * @return The milliseconds field, expressed in universal time, of the current date instance.
248      * @see #getMilliseconds()
249      * @since Descripter 1.0
250      */
251     public final Number getUTCMilliseconds() {
252         return cal.get(Calendar.MILLISECOND);
253     }
254 
255     /**
256      * <p>Returns the minutes field of the current date instance, in universal time.</p>
257      * @return The minutes field, expressed in universal time, of the current date instance. 
258      * The return value is an integer between 0 and 59.
259      * @see #getMinutes()
260      * @since Descripter 1.0
261      */
262     public final Number getUTCMinutes() {
263         return cal.get(Calendar.MINUTE);
264     }
265 
266     /**
267      * <p>Returns the month field of the current date instance, in universal time.</p>
268      * @return The month of the year that results when the current date instance is 
269      * expressed in universal time. The return value is an integer between 0 (January) 
270      * and 11 (December). Note that the date represents the first day of the month as 1 
271      * but represents the first month of the year as 0.
272      * @see #getMonth()
273      * @since Descripter 1.0
274      */
275     public final Number getUTCMonth() {
276         return cal.get(Calendar.MONTH);
277     }
278 
279     /**
280      * <p>Returns the seconds field of the current date instance, in universal time.</p>
281      * @return The seconds field, expressed in universal time, of the current date instance. 
282      * The return value is an integer between 0 and 59.
283      * @see #getSeconds()
284      * @since Descripter 1.0
285      */
286     public final Number getUTCSeconds() {
287         return cal.get(Calendar.SECOND);
288     }
289 
290     /**
291      * <p>Sets the day of the month field of the current date instance, using local time.</p>
292      * @param day An integer between 1 and 31 that is used as the new value in local time 
293      * of the day-of-the-month field of the current date instance.
294      * @return The millisecond representation of the adjusted date. 
295      * Prior to ECMAScript standardization, this method returns nothing.
296      * @see #setUTCDate(Number)
297      * @since Descripter 1.0
298      */
299     public final Number setDate(Number day) {
300         cal.set(Calendar.DATE, day.intValue());
301         return getTime();
302     }
303 
304     /**
305      * <p>Sets the year and optionally month and day fields of the current date instance, 
306      * using local time.</p>
307      * @param args An array of arguments:<ul><li><tt>
308      * yr</tt>, The year, expressed in local time, to be set in the current date instance. 
309      * This argument should be an integer that includes the century, such as 1999; it 
310      * should not be an abbreviation, such as 99.</li><li><tt>
311      * mo</tt>, An optional integer between 0 and 11 that is used as the new value in 
312      * local time of the month field of the current date instance.</li><li><tt>
313      * day</tt>, An optional integer between 1 and 31 that is used as the new value in 
314      * local time of the day-of-the-month field of the current date instance.</li></ul>
315      * @return The millisecond representation of the adjusted date. 
316      * @see #setUTCFullYear(CArray)
317      * @since Descripter 1.0
318      */
319     public final Number setFullYear(CArray args) {
320         if (args.has(0)) {
321             cal.set(Calendar.YEAR, intValue(args.get(0)));
322         }
323         if (args.has(1)) {
324             cal.set(Calendar.MONTH, intValue(args.get(1)));
325         }
326         if (args.has(2)) {
327             cal.set(Calendar.DAY_OF_MONTH, intValue(args.get(2)));
328         }
329         return getTime();
330     }
331 
332     /**
333      * <p>Sets the hour field and optionally the minutes, seconds, and milliseconds fields 
334      * of the current date instance, using local time.</p>
335      * @param args An array of arguments:<ul><li><tt>
336      * hr</tt>, An integer between 0 (midnight) and 23 (11 p.m.) local time that is set 
337      * as the new hours value of the current date instance.</li><li><tt>
338      * min</tt>, An optional integer, between 0 and 59, that is used as the new value 
339      * in local time of the minutes field of the current date instance. This argument is 
340      * not supported prior to ECMAScript standardization.</li><li><tt>
341      * sec</tt>, An optional integer, between 0 and 59, that is used as the new value 
342      * in local time of the seconds field of the current date instance. This argument is 
343      * not supported prior to ECMAScript standardization.</li><li><tt>
344      * ms</tt>, An optional integer, between 0 and 999, that is used as the new value 
345      * in local time of the milliseconds field of the current date instance. This argument 
346      * is not supported prior to ECMAScript standardization.</li></ul>
347      * @return The millisecond representation of the adjusted date. 
348      * Prior to ECMAScript standardization, this method returns nothing.
349      * @see #setUTCHours(CArray)
350      * @since Descripter 1.0
351      */
352     public final Number setHours(CArray args) {
353         if (args.has(0)) {
354             cal.set(Calendar.HOUR, intValue(args.get(0)));
355         }
356         if (args.has(1)) {
357             cal.set(Calendar.MINUTE, intValue(args.get(1)));
358         }
359         if (args.has(2)) {
360             cal.set(Calendar.SECOND, intValue(args.get(2)));
361         }
362         if (args.has(3)) {
363             cal.set(Calendar.MILLISECOND, intValue(args.get(3)));
364         }
365         return getTime();
366     }
367 
368     /**
369      * <p>Sets the milliseconds field of a date, using local time.</p>
370      * @param ms The milliseconds field, expressed in local time, to be set in the current 
371      * date instance. This argument should be an integer between 0 and 999.
372      * @return The millisecond representation of the adjusted date.
373      * @see #setUTCMilliseconds(Number)
374      * @since Descripter 1.0
375      */
376     public final Number setMilliseconds(Number ms) {
377         cal.set(Calendar.MILLISECOND, ms.intValue());
378         return getTime();
379     }
380 
381     /**
382      * <p>Sets the minutes field and optionally the seconds and milliseconds fields of the 
383      * current date instance, using local time.</p>
384      * @param args An array of arguments:<ul><li><tt>
385      * min</tt>, An optional integer, between 0 and 59, that is used as the new value 
386      * in local time of the minutes field of the current date instance. This argument is 
387      * not supported prior to ECMAScript standardization.</li><li><tt>
388      * sec</tt>, An optional integer, between 0 and 59, that is used as the new value 
389      * in local time of the seconds field of the current date instance. This argument is 
390      * not supported prior to ECMAScript standardization.</li><li><tt>
391      * ms</tt>, An optional integer, between 0 and 999, that is used as the new value 
392      * in local time of the milliseconds field of the current date instance. This argument 
393      * is not supported prior to ECMAScript standardization.</li></ul>
394      * @return The millisecond representation of the adjusted date. 
395      * Prior to ECMAScript standardization, this method returns nothing.
396      * @see #setUTCMinutes(CArray)
397      * @since Descripter 1.0
398      */
399     public final Number setMinutes(CArray args) {
400         if (args.has(0)) {
401             cal.set(Calendar.MINUTE, intValue(args.get(0)));
402         }
403         if (args.has(1)) {
404             cal.set(Calendar.SECOND, intValue(args.get(1)));
405         }
406         if (args.has(2)) {
407             cal.set(Calendar.MILLISECOND, intValue(args.get(2)));
408         }
409         return getTime();
410     }
411 
412     /**
413      * <p>Sets the month field and optionally the day of the month of the current date 
414      * instance, using universal time.</p>
415      * @param args An array of arguments:<ul><li><tt>
416      * mo</tt>, The month, expressed in universal time, to be set in the current date
417      * instance. This argument should be an integer between 0 (January) and 11 (December). 
418      * Note that months are numbered beginning with 0, while days within the month are 
419      * numbered beginning with 1.</li><li><tt>
420      * day</tt>, An optional integer between 1 and 31 that is used as the new value in 
421      * universal time of the day-of-the-month field of the current date instance.</li></ul>
422      * @return The millisecond representation of the adjusted date. 
423      * @see #setUTCMonth(CArray)
424      * @since Descripter 1.0
425      */
426     public final Number setMonth(CArray args) {
427         if (args.has(0)) {
428             cal.set(Calendar.MONTH, intValue(args.get(0)));
429         }
430         if (args.has(1)) {
431             cal.set(Calendar.DAY_OF_MONTH, intValue(args.get(1)));
432         }
433         return getTime();
434     }
435 
436     /**
437      * <p>Sets the seconds field and optionally the milliseconds field of the current date 
438      * instance, using local .</p>
439      * @param args An array of arguments:<ul><li><tt>
440      * sec</tt>, An integer between 0 and 59 that is set as the seconds value for the 
441      * current date instance.</li><li><tt>
442      * ms</tt>, An optional integer, between 0 and 999, that is used as the new value 
443      * in local time of the milliseconds field of the current date instance. This argument 
444      * is not supported prior to ECMAScript standardization.</li></ul>
445      * @return The millisecond representation of the adjusted date. Prior to ECMAScript 
446      * standardization, this method returns nothing.
447      * @see #setUTCSeconds(CArray)
448      * @since Descripter 1.0
449      */
450     public final Number setSeconds(CArray args) {
451         if (args.has(0)) {
452             cal.set(Calendar.SECOND, intValue(args.get(0)));
453         }
454         if (args.has(1)) {
455             cal.set(Calendar.MILLISECOND, intValue(args.get(1)));
456         }
457         return getTime();
458     }
459 
460     /**
461      * <p>Sets the fields of the current date instance using the millisecond format.</p>
462      * @param time The number of milliseconds between the desired date and time and 
463      * midnight GMT on January 1, 1970. Representing a date in this millisecond format makes 
464      * it independent of time zone.
465      * @return The <tt>time</tt> argument. Prior to ECMAScript standardization, 
466      * this method returns nothing.
467      * @since Descripter 1.0
468      */
469     public final Number setTime(Number time) {
470         cal.setTimeInMillis(time.longValue());
471         return getTime();
472     }
473 
474     /**
475      * <p>Sets the day of the month field of the current date instance, using universal 
476      * time.</p>
477      * @param day The day of the month, expressed in universal time, to be set in the 
478      * current date instance. This argument should be an integer between 1 and 31.
479      * @return The millisecond representation of the adjusted date. 
480      * @see #setDate(Number)
481      * @since Descripter 1.0
482      */
483     public final Number setUTCDate(Number day) {
484         cal.set(Calendar.DATE, day.intValue());
485         return getTime();
486     }
487 
488     /**
489      * <p>Sets the year and optionally month and day fields of the current date instance, 
490      * using universal time.</p>
491      * @param args An array of arguments:<ul><li><tt>
492      * yr</tt>, The year, expressed in universal time, to be set in the current date 
493      * instance. This argument should be an integer that includes the century, such as 
494      * 1999, not an abbreviation, such as 99.</li><li><tt>
495      * mo</tt>, An optional integer between 0 and 11 that is used as the new value in 
496      * universal time of the month field of the current date instance. Note that months 
497      * are numbered beginning with 0, while days within the month are numbered beginning 
498      * with 1.</li><li><tt>
499      * day</tt>, An optional integer between 1 and 31 that is used as the new value in 
500      * universal time of the day-of-the-month field of the current date instance.</li></ul>
501      * @return The millisecond representation of the adjusted date. 
502      * @see #setFullYear(CArray)
503      * @since Descripter 1.0
504      */
505     public final Number setUTCFullYear(CArray args) {
506         if (args.has(0)) {
507             cal.set(Calendar.YEAR, intValue(args.get(0)));
508         }
509         if (args.has(1)) {
510             cal.set(Calendar.MONTH, intValue(args.get(1)));
511         }
512         if (args.has(2)) {
513             cal.set(Calendar.DAY_OF_MONTH, intValue(args.get(2)));
514         }
515         return getTime();
516     }
517 
518     /**
519      * <p>Sets the hour field and optionally the minutes, seconds, and milliseconds fields 
520      * of the current date instance, using universal time.</p>
521      * @param args An array of arguments:<ul><li><tt>
522      * hr</tt>, The hours field, expressed in universal time, to be set in the current 
523      * date instance. This argument should be an integer between 0 (midnight) and 23 
524      * (11 p.m.).</li><li><tt>
525      * min</tt>, An optional integer, between 0 and 59, that is used as the new value 
526      * in universal time of the minutes field of the current date instance.</li><li><tt>
527      * sec</tt>, An optional integer, between 0 and 59, that is used as the new value 
528      * in universal time of the seconds field of the current date instance.</li><li><tt>
529      * ms</tt>, An optional integer, between 0 and 999, that is used as the new value 
530      * in universal time of the milliseconds field of the current date instance.</li></ul>
531      * @return The millisecond representation of the adjusted date.
532      * @see #setHours(CArray)
533      * @since Descripter 1.0
534      */
535     public final Number setUTCHours(CArray args) {
536         if (args.has(0)) {
537             cal.set(Calendar.HOUR, intValue(args.get(0)));
538         }
539         if (args.has(1)) {
540             cal.set(Calendar.MINUTE, intValue(args.get(1)));
541         }
542         if (args.has(2)) {
543             cal.set(Calendar.SECOND, intValue(args.get(2)));
544         }
545         if (args.has(3)) {
546             cal.set(Calendar.MILLISECOND, intValue(args.get(3)));
547         }
548         return getTime();
549     }
550 
551     /**
552      * <p>Sets the milliseconds field of the current date instance, using universal time.</p>
553      * @param ms The milliseconds field, expressed in universal time, to be set in the 
554      * current date instance. This argument should be an integer between 0 and 999.
555      * @return The millisecond representation of the adjusted date.
556      * @see #setMilliseconds(Number)
557      * @since Descripter 1.0
558      */
559     public final Number setUTCMilliseconds(Number ms) {
560         cal.set(Calendar.MILLISECOND, ms.intValue());
561         return getTime();
562     }
563 
564     /**
565      * <p>Sets the minutes field of the current date instance, using universal time.</p>
566      * @param args An array of arguments:<ul><li><tt>
567      * min</tt>, An optional integer, between 0 and 59, that is used as the new value 
568      * in universal time of the minutes field of the current date instance.</li><li><tt>
569      * sec</tt>, An optional integer, between 0 and 59, that is used as the new value 
570      * in universal time of the seconds field of the current date instance.</li><li><tt>
571      * ms</tt>, An optional integer, between 0 and 999, that is used as the new value 
572      * in universal time of the milliseconds field of the current date instance.</li></ul>
573      * @return The millisecond representation of the adjusted date. 
574      * Prior to ECMAScript standardization, this method returns nothing.
575      * @see #setMinutes(CArray)
576      * @since Descripter 1.0
577      */
578     public final Number setUTCMinutes(CArray args) {
579         if (args.has(0)) {
580             cal.set(Calendar.MINUTE, intValue(args.get(0)));
581         }
582         if (args.has(1)) {
583             cal.set(Calendar.SECOND, intValue(args.get(1)));
584         }
585         if (args.has(2)) {
586             cal.set(Calendar.MILLISECOND, intValue(args.get(2)));
587         }
588         return getTime();
589     }
590 
591     /**
592      * <p>Sets the month field and optionally the day of the month of the current date 
593      * instance, using universal time.</p>
594      * @param args An array of arguments:<ul><li><tt>
595      * mo</tt>, The month, expressed in universal time, to be set in the current date
596      * instance. This argument should be an integer between 0 (January) and 11 (December). 
597      * Note that months are numbered beginning with 0, while days within the month are 
598      * numbered beginning with 1.</li><li><tt>
599      * day</tt>, An optional integer between 1 and 31 that is used as the new value in 
600      * universal time of the day-of-the-month field of the current date instance.</li></ul>
601      * @return The millisecond representation of the adjusted date. 
602      * @see #setMonth(CArray)
603      * @since Descripter 1.0
604      */
605     public final Number setUTCMonth(CArray args) {
606         if (args.has(0)) {
607             cal.set(Calendar.MONTH, intValue(args.get(0)));
608         }
609         if (args.has(1)) {
610             cal.set(Calendar.DAY_OF_MONTH, intValue(args.get(1)));
611         }
612         return getTime();
613     }
614 
615     /**
616      * <p>Sets the seconds field and optionally the milliseconds field of the current date 
617      * instance, using universal time.</p>
618      * @param args An array of arguments:<ul><li><tt>
619      * sec</tt>, The seconds field, expressed in universal time, to be set in the current 
620      * date instance. This argument should be an integer between 0 and 59.</li><li><tt>
621      * ms</tt>, An optional integer, between 0 and 999, that is used as the new value 
622      * in universal time of the milliseconds field of the current date instance.</li></ul>
623      * @return The millisecond representation of the adjusted date.
624      * @see #setSeconds(CArray)
625      * @since Descripter 1.0
626      */
627     public final Number setUTCSeconds(CArray args) {
628         if (args.has(0)) {
629             cal.set(Calendar.SECOND, intValue(args.get(0)));
630         }
631         if (args.has(1)) {
632             cal.set(Calendar.MILLISECOND, intValue(args.get(1)));
633         }
634         return getTime();
635     }
636 
637     /**
638      * <p>Returns a string that represents the date portion of the current date instance, 
639      * expressed in the local time zone.</p>
640      * @return An implementation-dependent, human-readable string representation of the 
641      * date portion of the current date instance, expressed in the local time zone.
642      * @see #toLocaleDateString()
643      * @see #toLocaleString()
644      * @see #toLocaleTimeString()
645      * @see #toString()
646      * @see #toTimeString()
647      * @since Descripter 1.0
648      */
649     public final String toDateString() {
650         return cal.getTime().toString();
651     }
652 
653 
654     /**
655      * <p>Returns a string that represents the date portion of the current date instance, 
656      * expressed in the local time zone, using the local date formatting conventions.</p>
657      * @return An implementation-dependent, human-readable string representation of the 
658      * date portion of the current date instance, expressed in the local time zone and 
659      * formatted according to local conventions.
660      * @see #toDateString()
661      * @see #toLocaleString()
662      * @see #toLocaleTimeString()
663      * @see #toString()
664      * @see #toTimeString()
665      * @since Descripter 1.0
666      */
667     public final String toLocaleDateString() {
668         return cal.getTime().toString();
669     }
670 
671     /**
672      * <p>Converts a date to a string, using the local time zone and the local date 
673      * formatting conventions.</p>
674      * <p>This method also uses local conventions for date and time formatting, so the 
675      * format may vary from platform to platform and from country to country. It returns 
676      * a string formatted in what is likely the user's preferred date and time format.</p>
677      * @return A string representation of the date and time specified by the current date 
678      * instance. The date and time are represented in the local time zone and formatted 
679      * using locally appropriate conventions.
680      * @see #toLocaleDateString()
681      * @see #toLocaleTimeString()
682      * @see #toString()
683      * @see #toUTCString()
684      * @since Descripter 1.0
685      */
686     @Override
687     public final String toLocaleString() {
688         return cal.getTime().toString();
689     }
690 
691     /**
692      * <p>Returns a string that represents the time portion of the current date instance, 
693      * expressed in the local time zone, using the local time formatting conventions.</p>
694      * @return An implementation-dependent, human-readable string representation of the 
695      * time portion of the current date instance, expressed in the local time zone and 
696      * formatted according to local conventions.
697      * @see #toDateString()
698      * @see #toLocaleDateString()
699      * @see #toLocaleString()
700      * @see #toString()
701      * @see #toTimeString()
702      * @since Descripter 1.0
703      */
704     public final String toLocaleTimeString() {
705         return cal.getTime().toString();
706     }
707 
708     /**
709      * <p>Returns a string that represents the time portion of the current date instance, 
710      * expressed in the local time zone.</p>
711      * @return An implementation-dependent, human-readable string representation of the 
712      * time portion of the current date instance, expressed in the local time zone.
713      * @see #toDateString()
714      * @see #toLocaleDateString()
715      * @see #toLocaleString()
716      * @see #toLocaleTimeString()
717      * @see #toString()
718      * @since Descripter 1.0
719      */
720     public final String toTimeString() {
721         return cal.getTime().toString();
722     }
723 
724     /**
725      * <p>Returns a string representation of the current object.</p>
726      * @return The string representation of the current object
727      * @since Descripter 1.0
728      */
729     @Override
730     public final String toString() {
731         return cal.getTime().toString();
732     }
733 
734 
735     /**
736      * <p>Converts the current date instance to a string, using universal time.</p>
737      * @return A human-readable string representation, expressed in universal time, of the 
738      * current date instance.
739      * @see #toLocaleString()
740      * @see #toString()
741      * @since Descripter 1.0
742      */
743     public final String toUTCString() {
744         return cal.getTime().toString();
745     }
746 
747     /**
748      * <p>Returns the primitive value associated with this object, if there is one. </p>
749      * @return The primitive value associated with this object, if there is one, or this object itself.
750      * @since Descripter 1.0
751      */
752     @Override
753     public final Number valueOf() {
754         return cal.getTime().getTime();
755     }
756 }