src/share/classes/java/time/DayOfWeek.java

Print this page




 153      * <p>
 154      * {@code DayOfWeek} is an enum representing the 7 days of the week.
 155      * This factory allows the enum to be obtained from the {@code int} value.
 156      * The {@code int} value follows the ISO-8601 standard, from 1 (Monday) to 7 (Sunday).
 157      *
 158      * @param dayOfWeek  the day-of-week to represent, from 1 (Monday) to 7 (Sunday)
 159      * @return the day-of-week singleton, not null
 160      * @throws DateTimeException if the day-of-week is invalid
 161      */
 162     public static DayOfWeek of(int dayOfWeek) {
 163         if (dayOfWeek < 1 || dayOfWeek > 7) {
 164             throw new DateTimeException("Invalid value for DayOfWeek: " + dayOfWeek);
 165         }
 166         return ENUMS[dayOfWeek - 1];
 167     }
 168 
 169     //-----------------------------------------------------------------------
 170     /**
 171      * Obtains an instance of {@code DayOfWeek} from a temporal object.
 172      * <p>
 173      * A {@code TemporalAccessor} represents some form of date and time information.
 174      * This factory converts the arbitrary temporal object to an instance of {@code DayOfWeek}.

 175      * <p>
 176      * The conversion extracts the {@link ChronoField#DAY_OF_WEEK DAY_OF_WEEK} field.
 177      * <p>
 178      * This method matches the signature of the functional interface {@link TemporalQuery}
 179      * allowing it to be used as a query via method reference, {@code DayOfWeek::from}.
 180      *
 181      * @param temporal  the temporal object to convert, not null
 182      * @return the day-of-week, not null
 183      * @throws DateTimeException if unable to convert to a {@code DayOfWeek}
 184      */
 185     public static DayOfWeek from(TemporalAccessor temporal) {
 186         if (temporal instanceof DayOfWeek) {
 187             return (DayOfWeek) temporal;
 188         }
 189         return of(temporal.get(DAY_OF_WEEK));
 190     }
 191 
 192     //-----------------------------------------------------------------------
 193     /**
 194      * Gets the day-of-week {@code int} value.
 195      * <p>
 196      * The values are numbered following the ISO-8601 standard, from 1 (Monday) to 7 (Sunday).
 197      * See {@link WeekFields#dayOfWeek} for localized week-numbering.
 198      *
 199      * @return the day-of-week, from 1 (Monday) to 7 (Sunday)
 200      */
 201     public int getValue() {
 202         return ordinal() + 1;
 203     }
 204 
 205     //-----------------------------------------------------------------------
 206     /**
 207      * Gets the textual representation, such as 'Mon' or 'Friday'.
 208      * <p>
 209      * This returns the textual name used to identify the day-of-week.
 210      * The parameters control the length of the returned text and the locale.

 211      * <p>
 212      * If no textual mapping is found then the {@link #getValue() numeric value} is returned.
 213      *
 214      * @param style  the length of the text required, not null
 215      * @param locale  the locale to use, not null
 216      * @return the text value of the day-of-week, not null
 217      */
 218     public String getText(TextStyle style, Locale locale) {
 219         return new DateTimeFormatterBuilder().appendText(DAY_OF_WEEK, style).toFormatter(locale).print(this);
 220     }
 221 
 222     //-----------------------------------------------------------------------
 223     /**
 224      * Checks if the specified field is supported.
 225      * <p>
 226      * This checks if this day-of-week can be queried for the specified field.
 227      * If false, then calling the {@link #range(TemporalField) range} and
 228      * {@link #get(TemporalField) get} methods will throw an exception.
 229      * <p>
 230      * If the field is {@link ChronoField#DAY_OF_WEEK DAY_OF_WEEK} then
 231      * this method returns true.
 232      * All other {@code ChronoField} instances will return false.
 233      * <p>
 234      * If the field is not a {@code ChronoField}, then the result of this method
 235      * is obtained by invoking {@code TemporalField.doIsSupported(TemporalAccessor)}
 236      * passing {@code this} as the argument.
 237      * Whether the field is supported is determined by the field.
 238      *
 239      * @param field  the field to check, null returns false
 240      * @return true if the field is supported on this day-of-week, false if not
 241      */
 242     @Override
 243     public boolean isSupported(TemporalField field) {
 244         if (field instanceof ChronoField) {
 245             return field == DAY_OF_WEEK;
 246         }
 247         return field != null && field.doIsSupported(this);
 248     }
 249 
 250     /**
 251      * Gets the range of valid values for the specified field.
 252      * <p>
 253      * The range object expresses the minimum and maximum valid values for a field.
 254      * This day-of-week is used to enhance the accuracy of the returned range.
 255      * If it is not possible to return the range, because the field is not supported
 256      * or for some other reason, an exception is thrown.
 257      * <p>
 258      * If the field is {@link ChronoField#DAY_OF_WEEK DAY_OF_WEEK} then the
 259      * range of the day-of-week, from 1 to 7, will be returned.
 260      * All other {@code ChronoField} instances will throw a {@code DateTimeException}.
 261      * <p>
 262      * If the field is not a {@code ChronoField}, then the result of this method
 263      * is obtained by invoking {@code TemporalField.doRange(TemporalAccessor)}
 264      * passing {@code this} as the argument.
 265      * Whether the range can be obtained is determined by the field.
 266      *
 267      * @param field  the field to query the range for, not null
 268      * @return the range of valid values for the field, not null
 269      * @throws DateTimeException if the range for the field cannot be obtained
 270      */
 271     @Override
 272     public ValueRange range(TemporalField field) {
 273         if (field == DAY_OF_WEEK) {
 274             return field.range();
 275         }
 276         return TemporalAccessor.super.range(field);
 277     }
 278 
 279     /**
 280      * Gets the value of the specified field from this day-of-week as an {@code int}.
 281      * <p>
 282      * This queries this day-of-week for the value for the specified field.
 283      * The returned value will always be within the valid range of values for the field.
 284      * If it is not possible to return the value, because the field is not supported
 285      * or for some other reason, an exception is thrown.
 286      * <p>
 287      * If the field is {@link ChronoField#DAY_OF_WEEK DAY_OF_WEEK} then the
 288      * value of the day-of-week, from 1 to 7, will be returned.
 289      * All other {@code ChronoField} instances will throw a {@code DateTimeException}.
 290      * <p>
 291      * If the field is not a {@code ChronoField}, then the result of this method
 292      * is obtained by invoking {@code TemporalField.doGet(TemporalAccessor)}
 293      * passing {@code this} as the argument. Whether the value can be obtained,
 294      * and what the value represents, is determined by the field.
 295      *
 296      * @param field  the field to get, not null
 297      * @return the value for the field, within the valid range of values
 298      * @throws DateTimeException if a value for the field cannot be obtained
 299      * @throws DateTimeException if the range of valid values for the field exceeds an {@code int}
 300      * @throws DateTimeException if the value is outside the range of valid values for the field
 301      * @throws ArithmeticException if numeric overflow occurs
 302      */
 303     @Override
 304     public int get(TemporalField field) {
 305         if (field == DAY_OF_WEEK) {
 306             return getValue();
 307         }
 308         return TemporalAccessor.super.get(field);
 309     }
 310 
 311     /**
 312      * Gets the value of the specified field from this day-of-week as a {@code long}.
 313      * <p>
 314      * This queries this day-of-week for the value for the specified field.
 315      * If it is not possible to return the value, because the field is not supported
 316      * or for some other reason, an exception is thrown.
 317      * <p>
 318      * If the field is {@link ChronoField#DAY_OF_WEEK DAY_OF_WEEK} then the
 319      * value of the day-of-week, from 1 to 7, will be returned.
 320      * All other {@code ChronoField} instances will throw a {@code DateTimeException}.
 321      * <p>
 322      * If the field is not a {@code ChronoField}, then the result of this method
 323      * is obtained by invoking {@code TemporalField.doGet(TemporalAccessor)}
 324      * passing {@code this} as the argument. Whether the value can be obtained,
 325      * and what the value represents, is determined by the field.
 326      *
 327      * @param field  the field to get, not null
 328      * @return the value for the field
 329      * @throws DateTimeException if a value for the field cannot be obtained
 330      * @throws ArithmeticException if numeric overflow occurs
 331      */
 332     @Override
 333     public long getLong(TemporalField field) {
 334         if (field == DAY_OF_WEEK) {
 335             return getValue();
 336         } else if (field instanceof ChronoField) {
 337             throw new DateTimeException("Unsupported field: " + field.getName());
 338         }
 339         return field.doGet(this);
 340     }
 341 
 342     //-----------------------------------------------------------------------
 343     /**
 344      * Returns the day-of-week that is the specified number of days after this one.
 345      * <p>
 346      * The calculation rolls around the end of the week from Sunday to Monday.
 347      * The specified period may be negative.
 348      * <p>
 349      * This instance is immutable and unaffected by this method call.
 350      *
 351      * @param days  the days to add, positive or negative
 352      * @return the resulting day-of-week, not null
 353      */
 354     public DayOfWeek plus(long days) {
 355         int amount = (int) (days % 7);
 356         return ENUMS[(ordinal() + (amount + 7)) % 7];
 357     }
 358 
 359     /**




 153      * <p>
 154      * {@code DayOfWeek} is an enum representing the 7 days of the week.
 155      * This factory allows the enum to be obtained from the {@code int} value.
 156      * The {@code int} value follows the ISO-8601 standard, from 1 (Monday) to 7 (Sunday).
 157      *
 158      * @param dayOfWeek  the day-of-week to represent, from 1 (Monday) to 7 (Sunday)
 159      * @return the day-of-week singleton, not null
 160      * @throws DateTimeException if the day-of-week is invalid
 161      */
 162     public static DayOfWeek of(int dayOfWeek) {
 163         if (dayOfWeek < 1 || dayOfWeek > 7) {
 164             throw new DateTimeException("Invalid value for DayOfWeek: " + dayOfWeek);
 165         }
 166         return ENUMS[dayOfWeek - 1];
 167     }
 168 
 169     //-----------------------------------------------------------------------
 170     /**
 171      * Obtains an instance of {@code DayOfWeek} from a temporal object.
 172      * <p>
 173      * This obtains a day-of-week based on the specified temporal.
 174      * A {@code TemporalAccessor} represents an arbitrary set of date and time information,
 175      * which this factory converts to an instance of {@code DayOfWeek}.
 176      * <p>
 177      * The conversion extracts the {@link ChronoField#DAY_OF_WEEK DAY_OF_WEEK} field.
 178      * <p>
 179      * This method matches the signature of the functional interface {@link TemporalQuery}
 180      * allowing it to be used as a query via method reference, {@code DayOfWeek::from}.
 181      *
 182      * @param temporal  the temporal object to convert, not null
 183      * @return the day-of-week, not null
 184      * @throws DateTimeException if unable to convert to a {@code DayOfWeek}
 185      */
 186     public static DayOfWeek from(TemporalAccessor temporal) {
 187         if (temporal instanceof DayOfWeek) {
 188             return (DayOfWeek) temporal;
 189         }
 190         return of(temporal.get(DAY_OF_WEEK));
 191     }
 192 
 193     //-----------------------------------------------------------------------
 194     /**
 195      * Gets the day-of-week {@code int} value.
 196      * <p>
 197      * The values are numbered following the ISO-8601 standard, from 1 (Monday) to 7 (Sunday).
 198      * See {@link WeekFields#dayOfWeek} for localized week-numbering.
 199      *
 200      * @return the day-of-week, from 1 (Monday) to 7 (Sunday)
 201      */
 202     public int getValue() {
 203         return ordinal() + 1;
 204     }
 205 
 206     //-----------------------------------------------------------------------
 207     /**
 208      * Gets the textual representation, such as 'Mon' or 'Friday'.
 209      * <p>
 210      * This returns the textual name used to identify the day-of-week,
 211      * suitable for presentation to the user.
 212      * The parameters control the style of the returned text and the locale.
 213      * <p>
 214      * If no textual mapping is found then the {@link #getValue() numeric value} is returned.
 215      *
 216      * @param style  the length of the text required, not null
 217      * @param locale  the locale to use, not null
 218      * @return the text value of the day-of-week, not null
 219      */
 220     public String getDisplayName(TextStyle style, Locale locale) {
 221         return new DateTimeFormatterBuilder().appendText(DAY_OF_WEEK, style).toFormatter(locale).format(this);
 222     }
 223 
 224     //-----------------------------------------------------------------------
 225     /**
 226      * Checks if the specified field is supported.
 227      * <p>
 228      * This checks if this day-of-week can be queried for the specified field.
 229      * If false, then calling the {@link #range(TemporalField) range} and
 230      * {@link #get(TemporalField) get} methods will throw an exception.
 231      * <p>
 232      * If the field is {@link ChronoField#DAY_OF_WEEK DAY_OF_WEEK} then
 233      * this method returns true.
 234      * All other {@code ChronoField} instances will return false.
 235      * <p>
 236      * If the field is not a {@code ChronoField}, then the result of this method
 237      * is obtained by invoking {@code TemporalField.isSupportedBy(TemporalAccessor)}
 238      * passing {@code this} as the argument.
 239      * Whether the field is supported is determined by the field.
 240      *
 241      * @param field  the field to check, null returns false
 242      * @return true if the field is supported on this day-of-week, false if not
 243      */
 244     @Override
 245     public boolean isSupported(TemporalField field) {
 246         if (field instanceof ChronoField) {
 247             return field == DAY_OF_WEEK;
 248         }
 249         return field != null && field.isSupportedBy(this);
 250     }
 251 
 252     /**
 253      * Gets the range of valid values for the specified field.
 254      * <p>
 255      * The range object expresses the minimum and maximum valid values for a field.
 256      * This day-of-week is used to enhance the accuracy of the returned range.
 257      * If it is not possible to return the range, because the field is not supported
 258      * or for some other reason, an exception is thrown.
 259      * <p>
 260      * If the field is {@link ChronoField#DAY_OF_WEEK DAY_OF_WEEK} then the
 261      * range of the day-of-week, from 1 to 7, will be returned.
 262      * All other {@code ChronoField} instances will throw a {@code DateTimeException}.
 263      * <p>
 264      * If the field is not a {@code ChronoField}, then the result of this method
 265      * is obtained by invoking {@code TemporalField.rangeRefinedBy(TemporalAccessor)}
 266      * passing {@code this} as the argument.
 267      * Whether the range can be obtained is determined by the field.
 268      *
 269      * @param field  the field to query the range for, not null
 270      * @return the range of valid values for the field, not null
 271      * @throws DateTimeException if the range for the field cannot be obtained
 272      */
 273     @Override
 274     public ValueRange range(TemporalField field) {
 275         if (field == DAY_OF_WEEK) {
 276             return field.range();
 277         }
 278         return TemporalAccessor.super.range(field);
 279     }
 280 
 281     /**
 282      * Gets the value of the specified field from this day-of-week as an {@code int}.
 283      * <p>
 284      * This queries this day-of-week for the value for the specified field.
 285      * The returned value will always be within the valid range of values for the field.
 286      * If it is not possible to return the value, because the field is not supported
 287      * or for some other reason, an exception is thrown.
 288      * <p>
 289      * If the field is {@link ChronoField#DAY_OF_WEEK DAY_OF_WEEK} then the
 290      * value of the day-of-week, from 1 to 7, will be returned.
 291      * All other {@code ChronoField} instances will throw a {@code DateTimeException}.
 292      * <p>
 293      * If the field is not a {@code ChronoField}, then the result of this method
 294      * is obtained by invoking {@code TemporalField.getFrom(TemporalAccessor)}
 295      * passing {@code this} as the argument. Whether the value can be obtained,
 296      * and what the value represents, is determined by the field.
 297      *
 298      * @param field  the field to get, not null
 299      * @return the value for the field, within the valid range of values
 300      * @throws DateTimeException if a value for the field cannot be obtained


 301      * @throws ArithmeticException if numeric overflow occurs
 302      */
 303     @Override
 304     public int get(TemporalField field) {
 305         if (field == DAY_OF_WEEK) {
 306             return getValue();
 307         }
 308         return TemporalAccessor.super.get(field);
 309     }
 310 
 311     /**
 312      * Gets the value of the specified field from this day-of-week as a {@code long}.
 313      * <p>
 314      * This queries this day-of-week for the value for the specified field.
 315      * If it is not possible to return the value, because the field is not supported
 316      * or for some other reason, an exception is thrown.
 317      * <p>
 318      * If the field is {@link ChronoField#DAY_OF_WEEK DAY_OF_WEEK} then the
 319      * value of the day-of-week, from 1 to 7, will be returned.
 320      * All other {@code ChronoField} instances will throw a {@code DateTimeException}.
 321      * <p>
 322      * If the field is not a {@code ChronoField}, then the result of this method
 323      * is obtained by invoking {@code TemporalField.getFrom(TemporalAccessor)}
 324      * passing {@code this} as the argument. Whether the value can be obtained,
 325      * and what the value represents, is determined by the field.
 326      *
 327      * @param field  the field to get, not null
 328      * @return the value for the field
 329      * @throws DateTimeException if a value for the field cannot be obtained
 330      * @throws ArithmeticException if numeric overflow occurs
 331      */
 332     @Override
 333     public long getLong(TemporalField field) {
 334         if (field == DAY_OF_WEEK) {
 335             return getValue();
 336         } else if (field instanceof ChronoField) {
 337             throw new DateTimeException("Unsupported field: " + field.getName());
 338         }
 339         return field.getFrom(this);
 340     }
 341 
 342     //-----------------------------------------------------------------------
 343     /**
 344      * Returns the day-of-week that is the specified number of days after this one.
 345      * <p>
 346      * The calculation rolls around the end of the week from Sunday to Monday.
 347      * The specified period may be negative.
 348      * <p>
 349      * This instance is immutable and unaffected by this method call.
 350      *
 351      * @param days  the days to add, positive or negative
 352      * @return the resulting day-of-week, not null
 353      */
 354     public DayOfWeek plus(long days) {
 355         int amount = (int) (days % 7);
 356         return ENUMS[(ordinal() + (amount + 7)) % 7];
 357     }
 358 
 359     /**