Skip to content
This repository
Browse code

Tidy OffsetDateTime Javadoc and implementation

  • Loading branch information...
commit 330835c4fae60fcf8b9510e5ed3e4997fc4a7a83 1 parent d2faeca
Stephen Colebourne authored December 01, 2012
90  src/main/java/javax/time/OffsetDateTime.java
@@ -340,7 +340,7 @@ public static OffsetDateTime of(LocalDateTime dateTime, ZoneOffset offset) {
340 340
      *
341 341
      * @param instant  the instant to create a date-time from, not null
342 342
      * @return the offset date-time in UTC, not null
343  
-     * @throws DateTimeException if the instant exceeds the supported date range
  343
+     * @throws DateTimeException if the result exceeds the supported range
344 344
      */
345 345
     public static OffsetDateTime ofInstantUTC(Instant instant) {
346 346
         return ofInstant(instant, ZoneOffset.UTC);
@@ -355,7 +355,7 @@ public static OffsetDateTime ofInstantUTC(Instant instant) {
355 355
      * @param instant  the instant to create the date-time from, not null
356 356
      * @param offset  the zone offset to use, not null
357 357
      * @return the offset date-time, not null
358  
-     * @throws DateTimeException if the instant exceeds the supported date range
  358
+     * @throws DateTimeException if the result exceeds the supported range
359 359
      */
360 360
     public static OffsetDateTime ofInstant(Instant instant, ZoneOffset offset) {
361 361
         Objects.requireNonNull(instant, "instant");
@@ -368,11 +368,13 @@ public static OffsetDateTime ofInstant(Instant instant, ZoneOffset offset) {
368 368
      * <p>
369 369
      * The resulting date-time represents exactly the same instant on the time-line.
370 370
      * Calling {@link #toInstant()} will return an instant equal to the one used here.
  371
+     * Converting an instant to a zoned date-time is simple as there is only one valid
  372
+     * offset for each instant.
371 373
      *
372 374
      * @param instant  the instant to create the date-time from, not null
373 375
      * @param zone  the time-zone to use, not null
374 376
      * @return the offset date-time, not null
375  
-     * @throws DateTimeException if the instant exceeds the supported date range
  377
+     * @throws DateTimeException if the result exceeds the supported range
376 378
      */
377 379
     public static OffsetDateTime ofInstant(Instant instant, ZoneId zone) {
378 380
         Objects.requireNonNull(instant, "instant");
@@ -385,12 +387,16 @@ public static OffsetDateTime ofInstant(Instant instant, ZoneId zone) {
385 387
      * Obtains an instance of {@code OffsetDateTime} using seconds from the
386 388
      * epoch of 1970-01-01T00:00:00Z.
387 389
      * <p>
388  
-     * This allows the {@link ChronoField#INSTANT_SECONDS epoch-seconds} field
  390
+     * This allows the {@link ChronoField#INSTANT_SECONDS epoch-second} field
389 391
      * to be converted to an offset date-time. This is primarily intended for
390 392
      * low-level conversions rather than general application usage.
  393
+     * <p>
  394
+     * The epoch-second is equivalent to an instant and there is only one valid
  395
+     * offset for each instant.
391 396
      *
392 397
      * @param epochSecond  the number of seconds from the epoch of 1970-01-01T00:00:00Z
393 398
      * @param nanoOfSecond  the nanosecond within the second, from 0 to 999,999,999
  399
+     * @param offset  the zone offset, not null
394 400
      * @return the offset date-time, not null
395 401
      * @throws DateTimeException if the result exceeds the supported range
396 402
      */
@@ -406,7 +412,7 @@ public static OffsetDateTime ofEpochSecond(long epochSecond, int nanoOfSecond, Z
406 412
      * @param epochSecond  the number of seconds from the epoch of 1970-01-01T00:00:00Z
407 413
      * @param nanoOfSecond  the nanosecond within the second, from 0 to 999,999,999
408 414
      * @return the offset date-time, not null
409  
-     * @throws DateTimeException if the instant exceeds the supported date range
  415
+     * @throws DateTimeException if the result exceeds the supported range
410 416
      */
411 417
     static OffsetDateTime create(long epochSecond, int nanoOfSecond, ZoneOffset offset) {
412 418
         LocalDateTime ldt = LocalDateTime.ofEpochSecond(epochSecond, nanoOfSecond, offset);
@@ -432,19 +438,20 @@ public static OffsetDateTime from(DateTimeAccessor dateTime) {
432 438
         try {
433 439
             try {
434 440
                 LocalDateTime ldt = LocalDateTime.from(dateTime);
435  
-                return of(ldt, offset);
  441
+                return OffsetDateTime.of(ldt, offset);
436 442
             } catch (DateTimeException ignore) {
437 443
                 Instant instant = Instant.from(dateTime);
438 444
                 return OffsetDateTime.ofInstant(instant, offset);
439 445
             }
440 446
         } catch (DateTimeException ex) {
441  
-            throw new DateTimeException("Unable to convert date-time to OffsetDateTime: " + dateTime.getClass(), ex);
  447
+            throw new DateTimeException("Unable to convert DateTimeAccessor to OffsetDateTime: " + dateTime.getClass(), ex);
442 448
         }
443 449
     }
444 450
 
445 451
     //-----------------------------------------------------------------------
446 452
     /**
447  
-     * Obtains an instance of {@code OffsetDateTime} from a text string such as {@code 2007-12-03T10:15:30+01:00}.
  453
+     * Obtains an instance of {@code OffsetDateTime} from a text string
  454
+     * such as {@code 2007-12-03T10:15:30+01:00}.
448 455
      * <p>
449 456
      * The string must represent a valid date-time and is parsed using
450 457
      * {@link javax.time.format.DateTimeFormatters#isoOffsetDateTime()}.
@@ -511,7 +518,6 @@ public boolean isSupported(DateTimeField field) {
511 518
      *
512 519
      * @return the zone offset, not null
513 520
      */
514  
-    @Override
515 521
     public ZoneOffset getOffset() {
516 522
         return offset;
517 523
     }
@@ -871,8 +877,7 @@ public OffsetDateTime withDayOfYear(int dayOfYear) {
871 877
      * @throws DateTimeException if the hour value is invalid
872 878
      */
873 879
     public OffsetDateTime withHour(int hour) {
874  
-        LocalDateTime newDT = dateTime.withHour(hour);
875  
-        return (newDT == dateTime ? this : new OffsetDateTime(newDT, offset));
  880
+        return with(dateTime.withHour(hour), offset);
876 881
     }
877 882
 
878 883
     /**
@@ -885,8 +890,7 @@ public OffsetDateTime withHour(int hour) {
885 890
      * @throws DateTimeException if the minute value is invalid
886 891
      */
887 892
     public OffsetDateTime withMinute(int minute) {
888  
-        LocalDateTime newDT = dateTime.withMinute(minute);
889  
-        return (newDT == dateTime ? this : new OffsetDateTime(newDT, offset));
  893
+        return with(dateTime.withMinute(minute), offset);
890 894
     }
891 895
 
892 896
     /**
@@ -899,8 +903,7 @@ public OffsetDateTime withMinute(int minute) {
899 903
      * @throws DateTimeException if the second value is invalid
900 904
      */
901 905
     public OffsetDateTime withSecond(int second) {
902  
-        LocalDateTime newDT = dateTime.withSecond(second);
903  
-        return (newDT == dateTime ? this : new OffsetDateTime(newDT, offset));
  906
+        return with(dateTime.withSecond(second), offset);
904 907
     }
905 908
 
906 909
     /**
@@ -913,8 +916,7 @@ public OffsetDateTime withSecond(int second) {
913 916
      * @throws DateTimeException if the nanos value is invalid
914 917
      */
915 918
     public OffsetDateTime withNano(int nanoOfSecond) {
916  
-        LocalDateTime newDT = dateTime.withNano(nanoOfSecond);
917  
-        return (newDT == dateTime ? this : new OffsetDateTime(newDT, offset));
  919
+        return with(dateTime.withNano(nanoOfSecond), offset);
918 920
     }
919 921
 
920 922
     //-----------------------------------------------------------------------
@@ -986,8 +988,7 @@ public OffsetDateTime plus(long amountToAdd, PeriodUnit unit) {
986 988
      * @throws DateTimeException if the result exceeds the supported date range
987 989
      */
988 990
     public OffsetDateTime plusYears(long years) {
989  
-        LocalDateTime newDT = dateTime.plusYears(years);
990  
-        return (newDT == dateTime ? this : new OffsetDateTime(newDT, offset));
  991
+        return with(dateTime.plusYears(years), offset);
991 992
     }
992 993
 
993 994
     /**
@@ -1011,8 +1012,7 @@ public OffsetDateTime plusYears(long years) {
1011 1012
      * @throws DateTimeException if the result exceeds the supported date range
1012 1013
      */
1013 1014
     public OffsetDateTime plusMonths(long months) {
1014  
-        LocalDateTime newDT = dateTime.plusMonths(months);
1015  
-        return (newDT == dateTime ? this : new OffsetDateTime(newDT, offset));
  1015
+        return with(dateTime.plusMonths(months), offset);
1016 1016
     }
1017 1017
 
1018 1018
     /**
@@ -1031,8 +1031,7 @@ public OffsetDateTime plusMonths(long months) {
1031 1031
      * @throws DateTimeException if the result exceeds the supported date range
1032 1032
      */
1033 1033
     public OffsetDateTime plusWeeks(long weeks) {
1034  
-        LocalDateTime newDT = dateTime.plusWeeks(weeks);
1035  
-        return (newDT == dateTime ? this : new OffsetDateTime(newDT, offset));
  1034
+        return with(dateTime.plusWeeks(weeks), offset);
1036 1035
     }
1037 1036
 
1038 1037
     /**
@@ -1051,8 +1050,7 @@ public OffsetDateTime plusWeeks(long weeks) {
1051 1050
      * @throws DateTimeException if the result exceeds the supported date range
1052 1051
      */
1053 1052
     public OffsetDateTime plusDays(long days) {
1054  
-        LocalDateTime newDT = dateTime.plusDays(days);
1055  
-        return (newDT == dateTime ? this : new OffsetDateTime(newDT, offset));
  1053
+        return with(dateTime.plusDays(days), offset);
1056 1054
     }
1057 1055
 
1058 1056
     /**
@@ -1065,8 +1063,7 @@ public OffsetDateTime plusDays(long days) {
1065 1063
      * @throws DateTimeException if the result exceeds the supported date range
1066 1064
      */
1067 1065
     public OffsetDateTime plusHours(long hours) {
1068  
-        LocalDateTime newDT = dateTime.plusHours(hours);
1069  
-        return (newDT == dateTime ? this : new OffsetDateTime(newDT, offset));
  1066
+        return with(dateTime.plusHours(hours), offset);
1070 1067
     }
1071 1068
 
1072 1069
     /**
@@ -1079,8 +1076,7 @@ public OffsetDateTime plusHours(long hours) {
1079 1076
      * @throws DateTimeException if the result exceeds the supported date range
1080 1077
      */
1081 1078
     public OffsetDateTime plusMinutes(long minutes) {
1082  
-        LocalDateTime newDT = dateTime.plusMinutes(minutes);
1083  
-        return (newDT == dateTime ? this : new OffsetDateTime(newDT, offset));
  1079
+        return with(dateTime.plusMinutes(minutes), offset);
1084 1080
     }
1085 1081
 
1086 1082
     /**
@@ -1093,8 +1089,7 @@ public OffsetDateTime plusMinutes(long minutes) {
1093 1089
      * @throws DateTimeException if the result exceeds the supported date range
1094 1090
      */
1095 1091
     public OffsetDateTime plusSeconds(long seconds) {
1096  
-        LocalDateTime newDT = dateTime.plusSeconds(seconds);
1097  
-        return (newDT == dateTime ? this : new OffsetDateTime(newDT, offset));
  1092
+        return with(dateTime.plusSeconds(seconds), offset);
1098 1093
     }
1099 1094
 
1100 1095
     /**
@@ -1107,8 +1102,7 @@ public OffsetDateTime plusSeconds(long seconds) {
1107 1102
      * @throws DateTimeException if the unit cannot be added to this type
1108 1103
      */
1109 1104
     public OffsetDateTime plusNanos(long nanos) {
1110  
-        LocalDateTime newDT = dateTime.plusNanos(nanos);
1111  
-        return (newDT == dateTime ? this : new OffsetDateTime(newDT, offset));
  1105
+        return with(dateTime.plusNanos(nanos), offset);
1112 1106
     }
1113 1107
 
1114 1108
     //-----------------------------------------------------------------------
@@ -1176,8 +1170,7 @@ public OffsetDateTime minus(long amountToSubtract, PeriodUnit unit) {
1176 1170
      * @throws DateTimeException if the result exceeds the supported date range
1177 1171
      */
1178 1172
     public OffsetDateTime minusYears(long years) {
1179  
-        LocalDateTime newDT = dateTime.minusYears(years);
1180  
-        return (newDT == dateTime ? this : new OffsetDateTime(newDT, offset));
  1173
+        return (years == Long.MIN_VALUE ? plusYears(Long.MAX_VALUE).plusYears(1) : plusYears(-years));
1181 1174
     }
1182 1175
 
1183 1176
     /**
@@ -1201,8 +1194,7 @@ public OffsetDateTime minusYears(long years) {
1201 1194
      * @throws DateTimeException if the result exceeds the supported date range
1202 1195
      */
1203 1196
     public OffsetDateTime minusMonths(long months) {
1204  
-        LocalDateTime newDT = dateTime.minusMonths(months);
1205  
-        return (newDT == dateTime ? this : new OffsetDateTime(newDT, offset));
  1197
+        return (months == Long.MIN_VALUE ? plusMonths(Long.MAX_VALUE).plusMonths(1) : plusMonths(-months));
1206 1198
     }
1207 1199
 
1208 1200
     /**
@@ -1221,8 +1213,7 @@ public OffsetDateTime minusMonths(long months) {
1221 1213
      * @throws DateTimeException if the result exceeds the supported date range
1222 1214
      */
1223 1215
     public OffsetDateTime minusWeeks(long weeks) {
1224  
-        LocalDateTime newDT = dateTime.minusWeeks(weeks);
1225  
-        return (newDT == dateTime ? this : new OffsetDateTime(newDT, offset));
  1216
+        return (weeks == Long.MIN_VALUE ? plusWeeks(Long.MAX_VALUE).plusWeeks(1) : plusWeeks(-weeks));
1226 1217
     }
1227 1218
 
1228 1219
     /**
@@ -1241,8 +1232,7 @@ public OffsetDateTime minusWeeks(long weeks) {
1241 1232
      * @throws DateTimeException if the result exceeds the supported date range
1242 1233
      */
1243 1234
     public OffsetDateTime minusDays(long days) {
1244  
-        LocalDateTime newDT = dateTime.minusDays(days);
1245  
-        return (newDT == dateTime ? this : new OffsetDateTime(newDT, offset));
  1235
+        return (days == Long.MIN_VALUE ? plusDays(Long.MAX_VALUE).plusDays(1) : plusDays(-days));
1246 1236
     }
1247 1237
 
1248 1238
     /**
@@ -1255,8 +1245,7 @@ public OffsetDateTime minusDays(long days) {
1255 1245
      * @throws DateTimeException if the result exceeds the supported date range
1256 1246
      */
1257 1247
     public OffsetDateTime minusHours(long hours) {
1258  
-        LocalDateTime newDT = dateTime.minusHours(hours);
1259  
-        return (newDT == dateTime ? this : new OffsetDateTime(newDT, offset));
  1248
+        return (hours == Long.MIN_VALUE ? plusHours(Long.MAX_VALUE).plusHours(1) : plusHours(-hours));
1260 1249
     }
1261 1250
 
1262 1251
     /**
@@ -1269,8 +1258,7 @@ public OffsetDateTime minusHours(long hours) {
1269 1258
      * @throws DateTimeException if the result exceeds the supported date range
1270 1259
      */
1271 1260
     public OffsetDateTime minusMinutes(long minutes) {
1272  
-        LocalDateTime newDT = dateTime.minusMinutes(minutes);
1273  
-        return (newDT == dateTime ? this : new OffsetDateTime(newDT, offset));
  1261
+        return (minutes == Long.MIN_VALUE ? plusMinutes(Long.MAX_VALUE).plusMinutes(1) : plusMinutes(-minutes));
1274 1262
     }
1275 1263
 
1276 1264
     /**
@@ -1283,8 +1271,7 @@ public OffsetDateTime minusMinutes(long minutes) {
1283 1271
      * @throws DateTimeException if the result exceeds the supported date range
1284 1272
      */
1285 1273
     public OffsetDateTime minusSeconds(long seconds) {
1286  
-        LocalDateTime newDT = dateTime.minusSeconds(seconds);
1287  
-        return (newDT == dateTime ? this : new OffsetDateTime(newDT, offset));
  1274
+        return (seconds == Long.MIN_VALUE ? plusSeconds(Long.MAX_VALUE).plusSeconds(1) : plusSeconds(-seconds));
1288 1275
     }
1289 1276
 
1290 1277
     /**
@@ -1297,8 +1284,7 @@ public OffsetDateTime minusSeconds(long seconds) {
1297 1284
      * @throws DateTimeException if the result exceeds the supported date range
1298 1285
      */
1299 1286
     public OffsetDateTime minusNanos(long nanos) {
1300  
-        LocalDateTime newDT = dateTime.minusNanos(nanos);
1301  
-        return (newDT == dateTime ? this : new OffsetDateTime(newDT, offset));
  1287
+        return (nanos == Long.MIN_VALUE ? plusNanos(Long.MAX_VALUE).plusNanos(1) : plusNanos(-nanos));
1302 1288
     }
1303 1289
 
1304 1290
     //-----------------------------------------------------------------------
@@ -1410,7 +1396,7 @@ public long periodUntil(DateTime endDateTime, PeriodUnit unit) {
1410 1396
         if (unit instanceof ChronoUnit) {
1411 1397
             OffsetDateTime end = (OffsetDateTime) endDateTime;
1412 1398
             end = end.withOffsetSameInstant(offset);
1413  
-            return dateTime.periodUntil(end, unit);
  1399
+            return dateTime.periodUntil(end.dateTime, unit);
1414 1400
         }
1415 1401
         return unit.between(this, endDateTime).getAmount();
1416 1402
     }
@@ -1418,6 +1404,8 @@ public long periodUntil(DateTime endDateTime, PeriodUnit unit) {
1418 1404
     //-----------------------------------------------------------------------
1419 1405
     /**
1420 1406
      * Converts this date-time to an {@code OffsetDate}.
  1407
+     * <p>
  1408
+     * This returns an offset date with the same local date and offset.
1421 1409
      *
1422 1410
      * @return an OffsetDate representing the date and offset, not null
1423 1411
      */
@@ -1427,6 +1415,8 @@ public OffsetDate toOffsetDate() {
1427 1415
 
1428 1416
     /**
1429 1417
      * Converts this date-time to an {@code OffsetTime}.
  1418
+     * <p>
  1419
+     * This returns an offset time with the same local time and offset.
1430 1420
      *
1431 1421
      * @return an OffsetTime representing the time and offset, not null
1432 1422
      */

0 notes on commit 330835c

Please sign in to comment.
Something went wrong with that request. Please try again.