jupyter/chapter17-enum.ipynb

{
  "cells": [{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["# Enum\n", "An enum is a kind of class where all instances are known and can be enumerated\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["By example, for a program they may be 3 ways to list files of a directory,\n", "either all files (ALL), either only the normal file (NORMAL) or only the directory (DIRECTORY)\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["enum FileListMode { ALL, NORMAL, DIRECTORY }\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["## Enum instances\n", "The enumerated instances are considered as constants thus can be accessed like any constant\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["System.out.println(FileListMode.ALL);\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["All enums inherits from the class `java.lang.Enum` that defines two components\n", "- name which is the name of the instance\n", "- ordinal which is the index (starting at 0)\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["System.out.println(FileListMode.ALL.name());\n", "System.out.println(FileListMode.ALL.ordinal());\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["equals()/hashCode() and toString() are inherited from `java.lang.Enum`\n", "- equals() delegates to ==\n", "- hashCode() returns ordinal\n", "- toString() returns name\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["System.out.println(FileListMode.ALL.equals(FileListMode.NORMAL));\n", "System.out.println(FileListMode.NORMAL);\n", "System.out.println(FileListMode.DIRECTORY.hashCode());\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["Enum instances are comparable (their ordinal value is used) so\n", "ALL < NORMAL < DIRECTORY\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["System.out.println(FileListMode.ALL.compareTo(FileListMode.NORMAL) < 0);\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["Two supplementary static methods are generated by the compiler\n", "- values() return an array of all instances\n", "- valueOf(name) return the instance corresponding to the name or an exception\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["System.out.println(Arrays.toString(FileListMode.values()));\n", "System.out.println(FileListMode.valueOf(\"ALL\"));\n", "System.out.println(FileListMode.valueOf(\"invalid\"));\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["`values()` returns a new cloned array at each invocation\n", "so don't call it inside a loop :)\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["## Enum are classes\n", "Unlike in C where enums are integers, enum in Java are full objects\n", "so they can have fields, constructors and methods defined after a semicolon\n", "at the end of the list of the instances\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["enum FileListMode {\n", "  ALL,\n", "  NORMAL,\n", "  DIRECTORY,  // trailing comma is allowed\n", "  ;           // ends of the instances\n", "  public String shortName() {\n", "    return name().toLowerCase().substring(0, 3);\n", "  }  \n", "}\n", "System.out.println(FileListMode.NORMAL.shortName());\n", "System.out.println(FileListMode.DIRECTORY.shortName());\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["### Enum constructors\n", "You can add fields if you want to associate specific values to the enum instances\n", "By example to convert from bits of an int to a set of modifier.\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["enum Modifier {\n", "  PUBLIC(1), FINAL(2), STATIC(4)\n", "  ;\n", "  private final int value;\n", "  private Modifier(int value) {\n", "    this.value = value;\n", "  }\n", "  // avoid to calls values() several times\n", "  private static final List<Modifier> MODIFIERS = List.of(values());\n", "  static int modifiersAsInt(Modifier... modifiers) {\n", "    return Arrays.stream(modifiers).map(m -> m.value).reduce(0, (a, b) -> a | b);\n", "  }\n", "  static Set<Modifier> intAsModifierSet(int modifiers) {\n", "    return MODIFIERS.stream().filter(m -> (modifiers & m.value) != 0).collect(Collectors.toSet());\n", "  }\n", "}\n", "var modifiers = Modifier.modifiersAsInt(Modifier.PUBLIC, Modifier.STATIC);\n", "System.out.println(\"int: \" + modifiers);\n", "var modifierSet = Modifier.intAsModifierSet(modifiers);\n", "System.out.println(\"set: \" + modifierSet);\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["The implementation of `intAsModifierSet` can be a little more efficient, see below\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["## Enum with abstract methods\n", "An enum can have abstract methods, in that case, all instances have to implement the missing method bodies\n", "using the same syntax as the anonymous class one\n", "In that case, the compiler generates one anonymous class per enum instance.\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["interface FilePredicate {\n", "  boolean test(Path path) throws IOException;\n", "}\n", "enum FileListMode implements FilePredicate {\n", "  ALL {\n", "    public boolean test(Path path) throws IOException {\n", "      return true;\n", "    }\n", "  },\n", "  NORMAL {\n", "    public boolean test(Path path) throws IOException {\n", "      return !Files.isHidden(path);\n", "    }\n", "  },\n", "  DIRECTORY {\n", "    public boolean test(Path path) throws IOException {\n", "      return NORMAL.test(path) && Files.isDirectory(path);\n", "    }\n", "  }\n", "}\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["It can be used to list the files of a directory in a way that\n", "depend on the mode. If you don't understand the cast in the for loop\n", "see chapter 'iteration'\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["void printAllPath(Path directory, FileListMode mode) throws IOException {\n", "  try(var stream = Files.list(directory)) {\n", "    for(var path: (Iterable<Path>)stream::iterator) {\n", "      if (mode.test(path)) {\n", "        System.out.println(path);\n", "      }\n", "    }\n", "  }\n", "}\n", "printAllPath(Path.of(\".\"), FileListMode.DIRECTORY);\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["### Use delegation, not inheritance\n", "The implementation above uses inheritance where it should use delegation\n", "Here is a better implementation delegating each implementation to a lambda.\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["enum FileListMode {\n", "  ALL(path -> true),\n", "  NORMAL(path -> !Files.isHidden(path)),\n", "  DIRECTORY(path -> NORMAL.test(path) && Files.isDirectory(path))\n", "  ;\n", "  private final FilePredicate predicate;\n", "  FileListMode(FilePredicate predicate) {\n", "    this.predicate = predicate;\n", "  }\n", "  public boolean test(Path path) throws IOException {\n", "    return predicate.test(path);\n", "  }\n", "}\n", "printAllPath(Path.of(\".\"), FileListMode.DIRECTORY);\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["## EnumSet and EnumMap\n", "There are one implementations of set (respectively map) specific if all values\n", "comes from the same enum because in that case ordinal() is a perfect hash function\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["so a EnumSet is implemented\n", "- using only one long if there is less than 64 enum instances\n", "- using an array of longs if there are more instances\n", "because there are two implementations, you have to use factory methods\n", "that takes the enum class to get an instance of the set\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["var emptySet = EnumSet.noneOf(Modifier.class);\n", "var enumSet = EnumSet.of(Modifier.PUBLIC, Modifier.FINAL);\n", "System.out.println(enumSet);\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["and EnumMap is implemented as an array of values, the index being the value of ordinal()\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["var enumMap = new EnumMap<>(Map.of(Modifier.PUBLIC, \"private\", Modifier.FINAL, \"final\"));\n", "System.out.println(enumMap);\n"]
}
],
  "metadata": {
    "kernelspec": {
      "display_name": "Java",
      "language": "java",
      "name": "java"
    },
    "language_info": {
      "codemirror_mode": "java",
      "file_extension": ".java",
      "mimetype": "text/x-java-source",
      "name": "Java",
      "pygments_lexer": "java",
      "version": "15"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 2
}