Where is the documentation for the `values()` method of Enum?

java

enum-methods

compiler-generated-methods

java-enum

byAlex Kataev·Mar 13, 2025

The values() method is a neat trick up Java's sleeve for all enums. It's responsible for returning an array of the enum's constants. Unlike other methods, it's invisible in the actual code and Javadoc since it's implicitly added during compile-time.

A basic usage example:

public enum Direction {
    NORTH, EAST, SOUTH, WEST;
}

// Retrieve all constants
Direction[] directions = Direction.values();

// Each direction has its moment of fame
for (Direction dir : directions) {
    System.out.println(dir);
}

Leave no stone unturned, use enumName.values() to get a list of all the enum constants.

The unseen workings of `values()` method

Declaration and materialization

The elusive values() method is a neat trick from the Java compiler. Even though it doesn't explicitly exist in your enum code, it's certainly there, added by the compiler during the compile-time.

Acting in sequence

This clever method, values(), holds the memory of the original declaration order of the enum constants. The array it returns keeps this respected order of procession, making it vital for logic that depends on the sequence.

The missing method in Javadoc

If you're browsing your enum's methods in the Javadoc and don't find values(), don't panic! The compiler-generated methods often elude Javadoc, including this little useful gem.

Peek into the implementation

Intrigued on how it works? If you're an adventurous coder and decompile your enum classes, you can have a glimpse into the backstage workings of both this and other implicit methods.

A day in the life of an enum constant

Birth of enum constant

When you announce an enum and its constants:

public enum Season {
    SPRING, SUMMER, AUTUMN, WINTER; // Current available roles...
}

Consider it as a new season of your favorite series, with each enum constant a character.

The big show

Whenever you call Season.values(), consider it a roll call for all the characters, who march out one by one in the order of their introduction.

for (Season season : Season.values()) {
    System.out.println(season); // Showtime!
}

Alike celebrities in a series, each constant in an enum has a name and an ordinal position, enabling you to access and iterate over them.

It's all about introspection

The values() method is your introspective guide in dark, it lets you iteratively traverse through constants when creating UI components which require enumeration of all possibilities.

Practical insights and potential pitfalls

Navigating enum constants

values() is often called upon to navigate through the constants of an enum:

for (Color c : Color.values()) {
    System.out.println(c);  // Printing fashion trends
}

This simple method turns highly useful when tasked to populate UI components, display options, or implement logic over all possible options.

Naming, the game changer

values() enhances the importance of explicit and consistent naming conventions in your enums since these methods are compiler-generated, having a readable and understandable set of enum constants only makes your codebase cleaner and more maintainable.

Collaboration with `valueOf()`

A cool thing to note is that Enum.valueOf() depends on values() to do its job of locating a specific constant:

// Retrieve a specific enum constant by name
Season s = Enum.valueOf(Season.class, "SUMMER");  // SUMMER is here!

This highlights how values() powers even the other key functionalities in the enum class.

Beware of the malformed array

A crucial thing to bear in mind is that the array returned by values() should be taken as read-only. Although runtime modifications can't add or remove enum elements, they can still mutate the array, leading to chaos and mayhem in your code.

To prevent the zombie apocalypse, if modification is a necessity, copy the array:

Season[] modifiableSeasons = Arrays.copyOf(Season.values(), Season.values().length);
// Now the modifiableSeasons is fair game!

explain-codes / Java / Where is the documentation for the `values()` method of Enum?

Linked

What is the difference between `Enum.name()` and `Enum.toString()`?



A for-loop to iterate over an enum in Java



What are enums and why are they useful?



Can enums be subclassed to add new elements?



Can I set enum start value in Java?



Cast Int to enum in Java



Best way to create enum of strings?



The unseen workings of method A day in the life of an enum constant Practical insights and potential pitfalls