Java Doc for TimeOfDay.java in  » Development » Joda-Time » org » joda » time » Java Source Code / Java DocumentationJava Source Code and Java Documentation

NOTE: This class only supports the four fields listed above. Thus, you cannot query the millisOfDay or secondOfDay fields for example. The new LocalTime class removes this restriction.

Calculations on TimeOfDay are performed using a Chronology . This chronology is set to be in the UTC time zone for all calculations.

Each individual field can be queried in two ways:

• getHourOfDay()
• hourOfDay().get()

• numeric value - hourOfDay().get()
• text value - hourOfDay().getAsText()
• short text value - hourOfDay().getAsShortText()
• maximum/minimum values - hourOfDay().getMaximumValue()
• add/subtract - hourOfDay().addToCopy()
• set - hourOfDay().setCopy()

TimeOfDay is thread-safe and immutable, provided that the Chronology is as well. All standard Chronology classes supplied are thread-safe and immutable.
author:
   Stephen Colebourne
author:
   Brian S O'Neill
since:
   1.0

The constructor uses the default time zone, resulting in the local time being initialised.

The constructor uses the default time zone, resulting in the local time being initialised.

The recognised object types are defined in org.joda.time.convert.ConverterManager ConverterManager and include ReadableInstant, String, Calendar and Date. The String formats are described by ISODateTimeFormat.timeParser .

The chronology used will be derived from the object, defaulting to ISO.

NOTE: Prior to v1.3 the string format was described by ISODateTimeFormat.dateTimeParser .

The recognised object types are defined in org.joda.time.convert.ConverterManager ConverterManager and include ReadableInstant, String, Calendar and Date. The String formats are described by ISODateTimeFormat.timeParser .

The constructor uses the time zone of the chronology specified. Once the constructor is complete, all further calculations are performed without reference to a timezone (by switching to UTC). The specified chronology overrides that of the object.

NOTE: Prior to v1.3 the string format was described by ISODateTimeFormat.dateTimeParser .

Each field is queried from the Calendar and assigned to the TimeOfDay. This is useful to ensure that the field values are the same in the created TimeOfDay no matter what the time zone is.

Each field is queried from the Date and assigned to the TimeOfDay. This is useful to ensure that the field values are the same in the created TimeOfDay no matter what the time zone is.

If the addition is zero, then this is returned. Fields in the period that aren't present in the partial are ignored.

This method is typically used to add multiple copies of complex period instances.

The constructor uses the default time zone, resulting in the local time being initialised. Once the constructor is complete, all further calculations are performed without reference to a timezone (by switching to UTC).

The constructor uses the specified time zone to obtain the current time. Once the constructor is complete, all further calculations are performed without reference to a timezone (by switching to UTC).
Parameters:
  zone - the zone to use, null means default zone
since:
   1.1

The constructor uses the time zone of the chronology specified. Once the constructor is complete, all further calculations are performed without reference to a timezone (by switching to UTC).
Parameters:
  chronology - the chronology, null means ISOChronology in the default zone

The constructor uses the default time zone, resulting in the local time being initialised. Once the constructor is complete, all further calculations are performed without reference to a timezone (by switching to UTC).
Parameters:
  instant - the milliseconds from 1970-01-01T00:00:00Z

The constructor uses the time zone of the chronology specified. Once the constructor is complete, all further calculations are performed without reference to a timezone (by switching to UTC).
Parameters:
  instant - the milliseconds from 1970-01-01T00:00:00Z
Parameters:
  chronology - the chronology, null means ISOChronology in the default zone

The recognised object types are defined in org.joda.time.convert.ConverterManager ConverterManager and include ReadableInstant, String, Calendar and Date. The String formats are described by ISODateTimeFormat.timeParser .

The chronology used will be derived from the object, defaulting to ISO.

NOTE: Prior to v1.3 the string format was described by ISODateTimeFormat.dateTimeParser . Dates are now rejected.
Parameters:
  instant - the datetime object, null means now
throws:
  IllegalArgumentException - if the instant is invalid

The recognised object types are defined in org.joda.time.convert.ConverterManager ConverterManager and include ReadableInstant, String, Calendar and Date. The String formats are described by ISODateTimeFormat.timeParser .

The constructor uses the time zone of the chronology specified. Once the constructor is complete, all further calculations are performed without reference to a timezone (by switching to UTC). The specified chronology overrides that of the object.

NOTE: Prior to v1.3 the string format was described by ISODateTimeFormat.dateTimeParser . Dates are now rejected.
Parameters:
  instant - the datetime object, null means now
Parameters:
  chronology - the chronology, null means ISO default
throws:
  IllegalArgumentException - if the instant is invalid

The constructor uses the no time zone initialising the fields as provided. Once the constructor is complete, all further calculations are performed without reference to a timezone (by switching to UTC).
Parameters:
  hourOfDay - the hour of the day
Parameters:
  minuteOfHour - the minute of the hour

The constructor uses the time zone of the chronology specified. Once the constructor is complete, all further calculations are performed without reference to a timezone (by switching to UTC).
Parameters:
  hourOfDay - the hour of the day
Parameters:
  minuteOfHour - the minute of the hour
Parameters:
  chronology - the chronology, null means ISOChronology in the default zone

The constructor uses the no time zone initialising the fields as provided. Once the constructor is complete, all further calculations are performed without reference to a timezone (by switching to UTC).
Parameters:
  hourOfDay - the hour of the day
Parameters:
  minuteOfHour - the minute of the hour
Parameters:
  secondOfMinute - the second of the minute

The constructor uses the time zone of the chronology specified. Once the constructor is complete, all further calculations are performed without reference to a timezone (by switching to UTC).
Parameters:
  hourOfDay - the hour of the day
Parameters:
  minuteOfHour - the minute of the hour
Parameters:
  secondOfMinute - the second of the minute
Parameters:
  chronology - the chronology, null means ISOChronology in the default zone

The constructor uses the no time zone initialising the fields as provided. Once the constructor is complete, all further calculations are performed without reference to a timezone (by switching to UTC).
Parameters:
  hourOfDay - the hour of the day
Parameters:
  minuteOfHour - the minute of the hour
Parameters:
  secondOfMinute - the second of the minute
Parameters:
  millisOfSecond - the millisecond of the second

The constructor uses the time zone of the chronology specified. Once the constructor is complete, all further calculations are performed without reference to a timezone (by switching to UTC).
Parameters:
  hourOfDay - the hour of the day
Parameters:
  minuteOfHour - the minute of the hour
Parameters:
  secondOfMinute - the second of the minute
Parameters:
  millisOfSecond - the millisecond of the second
Parameters:
  chronology - the chronology, null means ISOChronology in the default zone

Each field is queried from the Calendar and assigned to the TimeOfDay. This is useful to ensure that the field values are the same in the created TimeOfDay no matter what the time zone is. For example, if the Calendar states that the time is 04:29, then the created TimeOfDay will always have the time 04:29 irrespective of time zone issues.

This factory method ignores the type of the calendar and always creates a TimeOfDay with ISO chronology.
Parameters:
  calendar - the Calendar to extract fields from the created TimeOfDay
throws:
  IllegalArgumentException - if the calendar is null
throws:
  IllegalArgumentException - if the time is invalid for the ISO chronology
since:
   1.2

Each field is queried from the Date and assigned to the TimeOfDay. This is useful to ensure that the field values are the same in the created TimeOfDay no matter what the time zone is. For example, if the Calendar states that the time is 04:29, then the created TimeOfDay will always have the time 04:29 irrespective of time zone issues.

This factory method always creates a TimeOfDay with ISO chronology.
Parameters:
  date - the Date to extract fields from the created TimeOfDay
throws:
  IllegalArgumentException - if the calendar is null
throws:
  IllegalArgumentException - if the date is invalid for the ISO chronology
since:
   1.2

The millisOfDay value may exceed the number of millis in one day, but additional days will be ignored. This method uses the UTC time zone internally.
Parameters:
  millisOfDay - the number of milliseconds into a day to convert

The millisOfDay value may exceed the number of millis in one day, but additional days will be ignored. This method uses the UTC time zone internally.
Parameters:
  millisOfDay - the number of milliseconds into a day to convert
Parameters:
  chrono - the chronology, null means ISO chronology

This method must not use any instance variables.
Parameters:
  index - the index to retrieve
Parameters:
  chrono - the chronology to use the field

The fields are returned largest to smallest, Hour, Minute, Second, Millis. the array of field types (cloned), largest to smallest

If the amount is zero or null, then this is returned.

This method is typically used to subtract complex period instances. Subtracting one field is best achieved using methods like TimeOfDay.minusHours(int) .
Parameters:
  period - the period to reduce this instant by a copy of this instance with the period taken away
throws:
  ArithmeticException - if the new time exceeds capacity

This time instance is immutable and unaffected by this method call.

The following three lines are identical in effect:

 TimeOfDay subtracted = dt.minusHours(6);
 TimeOfDay subtracted = dt.minus(Period.hours(6));
 TimeOfDay subtracted = dt.withFieldAdded(DurationFieldType.hours(), -6);
 

This time instance is immutable and unaffected by this method call.

The following three lines are identical in effect:

 TimeOfDay subtracted = dt.minusMillis(6);
 TimeOfDay subtracted = dt.minus(Period.millis(6));
 TimeOfDay subtracted = dt.withFieldAdded(DurationFieldType.millis(), -6);
 

This time instance is immutable and unaffected by this method call.

The following three lines are identical in effect:

 TimeOfDay subtracted = dt.minusMinutes(6);
 TimeOfDay subtracted = dt.minus(Period.minutes(6));
 TimeOfDay subtracted = dt.withFieldAdded(DurationFieldType.minutes(), -6);
 

This time instance is immutable and unaffected by this method call.

The following three lines are identical in effect:

 TimeOfDay subtracted = dt.minusSeconds(6);
 TimeOfDay subtracted = dt.minus(Period.seconds(6));
 TimeOfDay subtracted = dt.withFieldAdded(DurationFieldType.seconds(), -6);
 

If the amount is zero or null, then this is returned.

This method is typically used to add complex period instances. Adding one field is best achieved using methods like TimeOfDay.plusHours(int) .
Parameters:
  period - the duration to add to this one, null means zero a copy of this instance with the period added
throws:
  ArithmeticException - if the new datetime exceeds the capacity of a long

This time instance is immutable and unaffected by this method call.

The following three lines are identical in effect:

 TimeOfDay added = dt.plusHours(6);
 TimeOfDay added = dt.plus(Period.hours(6));
 TimeOfDay added = dt.withFieldAdded(DurationFieldType.hours(), 6);
 

This time instance is immutable and unaffected by this method call.

The following three lines are identical in effect:

 TimeOfDay added = dt.plusMillis(6);
 TimeOfDay added = dt.plus(Period.millis(6));
 TimeOfDay added = dt.withFieldAdded(DurationFieldType.millis(), 6);
 

This time instance is immutable and unaffected by this method call.

The following three lines are identical in effect:

 TimeOfDay added = dt.plusMinutes(6);
 TimeOfDay added = dt.plus(Period.minutes(6));
 TimeOfDay added = dt.withFieldAdded(DurationFieldType.minutes(), 6);
 

This time instance is immutable and unaffected by this method call.

The following three lines are identical in effect:

 TimeOfDay added = dt.plusSeconds(6);
 TimeOfDay added = dt.plus(Period.seconds(6));
 TimeOfDay added = dt.withFieldAdded(DurationFieldType.seconds(), 6);
 

This method uses the chronology from this instance plus the time zone specified.
Parameters:
  zone - the zone to use, null means default this date as a datetime with the time as the current time

This method retains the values of the fields, thus the result will typically refer to a different instant.

The time zone of the specified chronology is ignored, as TimeOfDay operates without a time zone.
Parameters:
  newChronology - the new chronology, null means ISO a copy of this datetime with a different chronology
throws:
  IllegalArgumentException - if the values are invalid for the new chronology

For example, if the field type is minuteOfHour then the day would be changed in the returned instance.

These three lines are equivalent:

 TimeOfDay updated = tod.withField(DateTimeFieldType.minuteOfHour(), 6);
 TimeOfDay updated = tod.minuteOfHour().setCopy(6);
 TimeOfDay updated = tod.property(DateTimeFieldType.minuteOfHour()).setCopy(6);
 

If the addition is zero, then this is returned.

These three lines are equivalent:

 TimeOfDay added = tod.withFieldAdded(DurationFieldType.minutes(), 6);
 TimeOfDay added = tod.plusMinutes(6);
 TimeOfDay added = tod.minuteOfHour().addToCopy(6);
 

TimeOfDay is immutable, so there are no set methods. Instead, this method returns a new instance with the value of hour of day changed.
Parameters:
  hour - the hour of day to set a copy of this object with the field set
throws:
  IllegalArgumentException - if the value is invalid
since:
   1.3

TimeOfDay is immutable, so there are no set methods. Instead, this method returns a new instance with the value of millis of second changed.
Parameters:
  millis - the millis of second to set a copy of this object with the field set
throws:
  IllegalArgumentException - if the value is invalid
since:
   1.3

TimeOfDay is immutable, so there are no set methods. Instead, this method returns a new instance with the value of minute of hour changed.
Parameters:
  minute - the minute of hour to set a copy of this object with the field set
throws:
  IllegalArgumentException - if the value is invalid
since:
   1.3

If the addition is zero, then this is returned. Fields in the period that aren't present in the partial are ignored.

This method is typically used to add multiple copies of complex period instances. Adding one field is best achieved using methods like TimeOfDay.withFieldAdded(DurationFieldType,int) or TimeOfDay.plusHours(int) .
Parameters:
  period - the period to add to this one, null means zero
Parameters:
  scalar - the amount of times to add, such as -1 to subtract once a copy of this instance with the period added
throws:
  ArithmeticException - if the new datetime exceeds the capacity

TimeOfDay is immutable, so there are no set methods. Instead, this method returns a new instance with the value of second of minute changed.
Parameters:
  second - the second of minute to set a copy of this object with the field set
throws:
  IllegalArgumentException - if the value is invalid
since:
   1.3