2024/4/15

Guava Collection Utilities: Maps, Multisets, Multimaps, Tables

Maps

    @Test
    public void maps() {
        Map<String, Integer> left = ImmutableMap.of("a", 1, "b", 2, "c", 3);
        Map<String, Integer> right = ImmutableMap.of("b", 2, "c", 4, "d", 5);
        MapDifference<String, Integer> diff = Maps.difference(left, right);

        // 兩個 map 都有出現的 key-value pair
        Map<String, Integer> entriesInCommon = diff.entriesInCommon(); // {"b" => 2}
        assertEquals("{b=2}", entriesInCommon.toString());

        // 有相同的 key,不同的 values
        Map<String, MapDifference.ValueDifference<Integer>> entriesDiffering = diff.entriesDiffering(); // {"c" => (3, 4)}
        assertEquals("{c=(3, 4)}", entriesDiffering.toString());

        // 出現在 left,沒有出現在 right 的 key-value pair
        Map<String, Integer> entriesOnlyOnLeft = diff.entriesOnlyOnLeft(); // {"a" => 1}
        assertEquals("{a=1}", entriesOnlyOnLeft.toString());
        // 出現在 right,沒有出現在 left
        Map<String, Integer> entriesOnlyOnRight = diff.entriesOnlyOnRight(); // {"d" => 5}
        assertEquals("{d=5}", entriesOnlyOnRight.toString());
    }

uniqueIndex

    @Test
    public void maps_uniqueIndex() {
        // nickname屬性能唯一確定一個WebUser
        ArrayList<User> users = Lists.newArrayList(new User(1,"one"),new User(2,"two"),new User(3,"three"),new User(4,"four"));
        // 以 name 為 key,User為值的map
        ImmutableMap<String, User> map = Maps.uniqueIndex(users,new com.google.common.base.Function<User, String>() {
            @Override
            public String apply(User user) {
                return user.getName();
            }
        });
        System.out.println("map:" + map);
        System.out.println("name:" + map.get("two").getName());

        assertEquals("{one=User(id=1,name=one), two=User(id=2,name=two), three=User(id=3,name=three), four=User(id=4,name=four)}", map.toString());
    }
    class User {
        private int id;
        private String name;

        public User(int id, String name) {
            this.id = id;
            this.name = name;
        }

        public String getName() {
            return this.name;
        }

        public String toString() {
            return "User(id="+id+",name="+name+")";
        }
    }

Multisets

    @Test
    public void multisets() {
        Multiset<String> multiset1 = HashMultiset.create();
        multiset1.add("a", 2);

        Multiset<String> multiset2 = HashMultiset.create();
        multiset2.add("a", 5);

        // returns true: all unique elements are contained,
        boolean containsAll = multiset1.containsAll(multiset2);
        assertTrue(containsAll);

        // containsOccurrences(Multiset sup, Multiset sub)
        // if sub.count(o) <= sup.count(o) for all o  -> return true
        // even though multiset1.count("a") == 2 < multiset2.count("a") == 5
        // supCountA=2, subCountA=5
        // System.out.println("multiset1 CountA="+multiset1.count("a")+", multiset2 CountA="+multiset2.count("a"));
        boolean containsOccurrences = Multisets.containsOccurrences(multiset1, multiset2); // returns false
        assertFalse(containsOccurrences);

        // retainOccurrences(Multiset removeFrom, Multiset toRetain)
        // 確保 removeFrom.count(o) <= toRetain.count(o) for all o
        boolean retainOccurrences = Multisets.retainOccurrences(multiset1, multiset2);
        assertFalse(retainOccurrences);
        System.out.println("multiset1 CountA="+multiset1.count("a")+", multiset2 CountA="+multiset2.count("a"));

        // intersection of two multisets
        Multiset<String> intersection = Multisets.intersection(multiset1, multiset2);
        assertEquals(2, intersection.count("a"));

        // removeOccurrences(Multiset removeFrom, Multiset toRemove)
        // 自 removeFrom 中,移除 toRemove 的 element 出現的次數
        Multisets.removeOccurrences(multiset2, multiset1); // multiset2 now contains 3 occurrences of "a"
        assertEquals(3, multiset2.count("a"));

        // 移除 multiset2 中所有的元素
        multiset2.removeAll(multiset1); // removes all occurrences of "a" from multiset2, even though multiset1.count("a") == 2
        assertTrue(multiset2.isEmpty()); // returns true


        Multiset<String> multiset = HashMultiset.create();
        multiset.add("a", 3);
        multiset.add("b", 5);
        multiset.add("c", 1);

        // 次數從大到小的順序,排列 multiset
        ImmutableMultiset<String> highestCountFirst = Multisets.copyHighestCountFirst(multiset);
        assertEquals("[b x 5, a x 3, c]", highestCountFirst.toString());
    }

Multimaps

    @Test
    public void mutlimaps() {
        ImmutableSet<String> digits = ImmutableSet.of(
                "zero", "one", "two", "three", "four",
                "five", "six", "seven", "eight", "nine");
        Function<String, Integer> lengthFunction = new Function<String, Integer>() {
            public Integer apply(String string) {
                return string.length();
            }
        };
        //  Multimaps.index(Iterable, Function)
        // 以 Function apply 的結果分類,將相同字串長度的元素,放在一起
        ImmutableListMultimap<Integer, String> digitsByLength = Multimaps.index(digits, lengthFunction);
        /*
         * digitsByLength maps:
         *  3 => {"one", "two", "six"}
         *  4 => {"zero", "four", "five", "nine"}
         *  5 => {"three", "seven", "eight"}
         */
        assertEquals("{4=[zero, four, five, nine], 3=[one, two, six], 5=[three, seven, eight]}", digitsByLength.toString());

        ////////
        //  Multimaps.invertFrom(Multimap toInvert, Multimap dest)
        //  如果要得到 Immutablemiltimap 就呼叫 ImmutableMultimap.inverse()
        ArrayListMultimap<String, Integer> multimap = ArrayListMultimap.create();
        multimap.putAll("b", Ints.asList(2, 4, 6));
        multimap.putAll("a", Ints.asList(4, 2, 1));
        multimap.putAll("c", Ints.asList(2, 5, 3));

        TreeMultimap<Integer, String> inverse = Multimaps.invertFrom(multimap, TreeMultimap.<Integer, String>create());
        // note that we choose the implementation, so if we use a TreeMultimap, we get results in order
        /*
         * inverse maps:
         *  1 => {"a"}
         *  2 => {"a", "b", "c"}
         *  3 => {"c"}
         *  4 => {"a", "b"}
         *  5 => {"c"}
         *  6 => {"b"}
         */
        assertEquals("{1=[a], 2=[a, b, c], 3=[c], 4=[a, b], 5=[c], 6=[b]}", inverse.toString());

        /////
        // forMap(Map)  將 Map 轉換為 SetMultimap
        // 特別適合用在 Multimaps.invertFrom
        Map<String, Integer> map = ImmutableMap.of("a", 1, "b", 1, "c", 2);
        SetMultimap<String, Integer> multimap2 = Multimaps.forMap(map);
        // multimap maps ["a" => {1}, "b" => {1}, "c" => {2}]
        Multimap<Integer, String> inverse2 = Multimaps.invertFrom(multimap2, HashMultimap.<Integer, String> create());
        // inverse maps [1 => {"a", "b"}, 2 => {"c"}]
        assertEquals("{1=[a, b], 2=[c]}", inverse2.toString());
    }

Tables

    @Test
    public void tables() {
        // Tables.newCustomTable(Map, Supplier<Map>)
        Table<String, Character, Integer> table = Tables.newCustomTable(
                Maps.<String, Map<Character, Integer>>newLinkedHashMap(),
                new Supplier<Map<Character, Integer>>() {
                    public Map<Character, Integer> get() {
                        return Maps.newLinkedHashMap();
                    }
                });
        table.put("a", 'x', 1);
        table.put("a", 'y', 2);
        table.put("a", 'z', 3);
        table.put("b", 'x', 4);
        table.put("b", 'y', 5);
        table.put("b", 'z', 6);
        assertEquals("{a={x=1, y=2, z=3}, b={x=4, y=5, z=6}}", table.toString());

        // transpose 轉置矩陣
        assertEquals("{x={a=1, b=4}, y={a=2, b=5}, z={a=3, b=6}}", Tables.transpose(table).toString());
    }

References

CollectionUtilitiesExplained · google/guava Wiki · GitHub

2024/4/8

Guava Collection Utilities: Lists, Sets

Guava 在 Collection interfaces 有對應的 utility class,這些 utilities 是 static method,可直接使用。

Interface JDK or Guava? Corresponding Guava utility class
Collection JDK Collections2
List JDK Lists
Set JDK Sets
SortedSet JDK Sets
Map JDK Maps
SortedMap JDK Maps
Queue JDK Queues
Multiset Guava Multisets
Multimap Guava Multimaps
BiMap Guava Maps
Table Guava Tables

Static Contructor

    @Test
    public void static_constructor() {
        //JDK 的 list 必須建立後再加入元素
        List<String> list = new ArrayList<>();
        list.add("item1");
        list.add("item2");

        // Guava 在建立物件時,可直接填寫 init data
        Set<String> sets = Sets.newHashSet("alpha", "beta", "gamma");
        List<String> list2 = Lists.newArrayList("alpha", "beta", "gamma");

        // Guava 在 init 時,可直接設定 size
        List<String> exactly100 = Lists.newArrayListWithCapacity(100);
        List<String> approx100 = Lists.newArrayListWithExpectedSize(100);
        Set<String> approx100Set = Sets.newHashSetWithExpectedSize(100);

        // Guava 新的 Collection 類別,不提供 constructor,而是提供一個 factory method: create
        Multiset<String> multiset = HashMultiset.create();
    }

Iteratables

Iterables 封裝了 Iterable,提供 fluent 語法

    @Test
    public void iterables() {
        //// concat
        //// concat 可將兩個 collections 連接在一起
        Iterable<Integer> concatenated = Iterables.concat(
                Ints.asList(1, 2, 3),
                Ints.asList(5, 5, 6));
        // concatenated has elements 1, 2, 3, 4, 5, 6
        assertEquals("[1, 2, 3, 5, 5, 6]", concatenated.toString());

        //// concat 在不同類別的 list,不能連接在一起
//        Iterable<Integer> concatenated2 = Iterables.concat(
//                Ints.asList(1, 2, 3),
//                Lists.newArrayList("alpha", "beta", "gamma"));

        //// getFirst: first element, 第二個參數是 預設值
        //// getLast: last element, 失敗時會 throw NoSuchElementException
        Integer firstElement = Iterables.getFirst(concatenated, null);
        Integer lastAdded = Iterables.getLast(concatenated);
        assertEquals(firstElement.intValue(), 1);
        assertEquals(lastAdded.intValue(), 6);

        /// getOnlyElement: the only element in Iterable
        Iterable<Integer> iterable2 = () -> Arrays.asList(100).iterator();
        Iterable<Integer> iterable3 = Collections.singleton(200);
        Exception exception = assertThrows(IllegalArgumentException.class, () -> {
            Integer theElement = Iterables.getOnlyElement(concatenated);
        });
        assertEquals(Iterables.getOnlyElement(iterable2).intValue(), 100);

        //// frequency:  查詢某個 element 出現的次數
        assertEquals(2, Iterables.frequency(concatenated, 5));

        //// partition:  分割成多個 Iterable
        Iterable<List<Integer>> list = Iterables.partition(concatenated, 2);
//        System.out.println("list="+ list);
        assertEquals("[[1, 2], [3, 5], [5, 6]]", list.toString());
        assertEquals("[1, 2]", Iterables.getFirst(list, null).toString());
    }

Iterables 提供跟 Collection 類似的一些 methods

    @Test
    public void iterables_collection_like() {
        // Iterables 提供這些類似 Collection 的 methods
        // 1. addAll
        // 2. contains
        // 3. removeAll
        // 4. retainAll
        // 5. size
        // 6. toArray
        // 7. isEmpty
        // 8. get
        // 9. toString
        ArrayList<Integer> list1 = Lists.newArrayList(1, 2);
        ArrayList<Integer> list2 = Lists.newArrayList(100, 101);
        boolean changed = Iterables.addAll( list1 , list2);
        assertTrue( changed );
        assertEquals("[1, 2, 100, 101]", list1.toString());

        assertTrue( list1.contains(2) );
        assertEquals(list1.size(), 4);
        assertFalse( list1.isEmpty() );

        assertEquals(1, list1.get(0).intValue());
    }

FluentIterable 有幾個 method,可產生 immutable collection

Result Type Method
ImmutableList toList()
ImmutableList toSortedList()
ImmutableSet toSet()
ImmutableSortedSet toSortedSet()
ImmutableMultiset toMultiset()
ImmutableMap toMap()
    @Test
    public void FluentIterable_immutable() {
        // FluentIterable
        ImmutableList<String> list1 =
                FluentIterable.from( Arrays.asList(1,2,3) )
                .transform( Functions.toStringFunction() )
                .limit(10)
                .toList();
        assertEquals( 3, list1.size());
    }

Lists

    @Test
    public void lists() {
        List<Integer> countUp = Ints.asList(1, 2, 3);

        // Lists.reverse: reverse a list
        List<Integer> countDown = Lists.reverse(countUp); // {3, 2, 1}
        // 將 list 以 size 分割成多個 sublist
        List<List<Integer>> parts = Lists.partition(countUp, 2); // {{1, 2}, {3}}

        assertEquals("[1, 2, 3]", countUp.toString());
        assertEquals("[3, 2, 1]", countDown.toString());
        assertEquals("[[1, 2], [3]]", parts.toString());

        // Lists 可產生 ArrayList 及 LinkedList
        // Lists.newArrayList()
        // Lists.newLinkedList()
        List<Integer> list1 = Lists.newArrayList(1,3,2,4);
        List<Integer> list2 = Lists.newLinkedList(Ints.asList(1, 3, 2));
        assertEquals("[1, 3, 2, 4]", list1.toString());
        assertEquals("[1, 3, 2]", list2.toString());

        // 透過 Collections.max 找到最大的元素, Collections.min 最小的元素
        int maxElement = Collections.max(Arrays.asList(1,3,2,4));
        int minElement = Collections.min(Arrays.asList(1,3,2,4));
        assertEquals(4, maxElement);
        assertEquals(1, minElement);
    }

Sets

    @Test
    public void sets() {
        Set<String> set1 = ImmutableSet.of("a", "b", "c");
        Set<String> set2 = ImmutableSet.of("b", "c", "d");

        // 聯集 union of two sets
        Set<String> union1 = Sets.union(set1, set2);
        // 回傳 SetView,可再轉換為 immutable set 使用
        Sets.SetView<String> union2 = Sets.union(set1, set2);
        ImmutableSet<String> immutableSet = union2.immutableCopy();
        assertEquals("[a, b, c, d]", union1.toString());
        assertEquals("[a, b, c, d]", immutableSet.toString());

        // 交集 intersection of two sets
        Sets.SetView<String> intersection = Sets.intersection(set1, set2);
        // I can use intersection as a Set directly, but copying it can be more efficient if I use it a lot.
        assertEquals("[b, c]", intersection.toString());

        // 差集 difference
        Set<String> diff = Sets.difference(set1, set2);
        assertEquals("[a]", diff.toString());

        // symmetricDifference
        Set<String> diff2 = Sets.symmetricDifference(set1, set2);
        assertEquals("[a, d]", diff2.toString());

        // cartesianProduct: Cartesian Product 笛卡兒積
        Set<List<String>> product = Sets.cartesianProduct(set1, set2);
        assertEquals("[[a, b], [a, c], [a, d], [b, b], [b, c], [b, d], [c, b], [c, c], [c, d]]", product.toString());

        // powerSet: 找到所有可能的 subsets
        Set<Set<String>> powerset = Sets.powerSet(set1);
        assertTrue(powerset.contains(ImmutableSet.of("a")));
        assertTrue(powerset.contains(ImmutableSet.of("b")));
        assertTrue(powerset.contains(ImmutableSet.of("a", "b")));
        assertTrue(powerset.contains(ImmutableSet.of("a", "b", "c")));
        assertEquals(8, powerset.size());
    }

References

CollectionUtilitiesExplained · google/guava Wiki · GitHub

2024/4/1

Guava Collection: BiMap, Table, ClassToInstanceMap, RangeSet, RangeMap

BiMap

JDK 的方式,只能用兩個 Maps 分別儲存,並自己維護同步資料

BiMap 就是 Map<K,V>

  • 提供 inverse(),可取得 Map<V, K>

  • 為了提供 inverse(),values 必須要唯一,values() 可得到 Set

    @Test
    public void biMap() {
        // JDK 的方式,兩個 Map 獨立
        Map<String, Integer> nameToId = Maps.newHashMap();
        Map<Integer, String> idToName = Maps.newHashMap();
        nameToId.put("Bob", 42);
        idToName.put(42, "Bob");

        BiMap<String, Integer> userIdNameBiMap = HashBiMap.create();
        userIdNameBiMap.put("Bob", 42);
        userIdNameBiMap.put("Alice", 43);
        System.out.println("");
        System.out.println("userIdNameBiMap: "+userIdNameBiMap);
        String userForId = userIdNameBiMap.inverse().get(42);
        System.out.println("user 42 ForId: "+userForId);

//        userIdNameBiMap: {Bob=42, Alice=43}
//        user 42 ForId: Bob
    }

implementations

Key-Value Map Impl Value-Key Map Impl Corresponding BiMap
HashMap HashMap HashBiMap
ImmutableMap ImmutableMap ImmutableBiMap
EnumMap EnumMap EnumBiMap
EnumMap HashMap EnumHashBiMap

Table

ref: Guide to Guava Table | Baeldung

    @Test
    public void table_create() {
        // HashBasedTable.create()
        // 內部使用 LinkedHashMap
        Table<String, String, Integer> universityCourseSeatTable
                = HashBasedTable.create();
        // 內部使用 TreeMap,natural ordering
        Table<String, String, Integer> universityCourseSeatTableOrdered
                = TreeBasedTable.create();

        // table size 固定時,可使用 ArrayTable
        List<String> universityRowTable
                = Lists.newArrayList("Mumbai", "Harvard");
        List<String> courseColumnTables
                = Lists.newArrayList("Chemical", "IT", "Electrical");
        Table<String, String, Integer> universityCourseSeatTableArrayTable
                = ArrayTable.create(universityRowTable, courseColumnTables);

        // ImmutableTable: immutable table
        Table<String, String, Integer> universityCourseSeatTableImmutable
                = ImmutableTable.<String, String, Integer> builder()
                .put("Mumbai", "Chemical", 120).build();
    }

    @Test
    public void table_using() {
        Table<String, String, Integer> universityCourseSeatTable
                = HashBasedTable.create();
        universityCourseSeatTable.put("Mumbai", "Chemical", 120);
        universityCourseSeatTable.put("Mumbai", "IT", 60);
        universityCourseSeatTable.put("Harvard", "Electrical", 60);
        universityCourseSeatTable.put("Harvard", "IT", 120);

        // get 可取得 row, col  對應的資料
        int seatCount = universityCourseSeatTable.get("Mumbai", "IT");
        Integer seatCountForNoEntry = universityCourseSeatTable.get("Oxford", "IT");
        assertEquals(seatCount, 60);
        assertNull(seatCountForNoEntry);

        ////////////
        // containsXXX  可判斷是否存在
        // 1. row key
        // 2. col key
        // 3. row, col
        // 4 value
        boolean entryIsPresent
                = universityCourseSeatTable.contains("Mumbai", "IT");
        boolean courseIsPresent
                = universityCourseSeatTable.containsColumn("IT");
        boolean universityIsPresent
                = universityCourseSeatTable.containsRow("Mumbai");
        boolean seatCountIsPresent
                = universityCourseSeatTable.containsValue(60);

        assertTrue(entryIsPresent);
        assertTrue(courseIsPresent);
        assertTrue(universityIsPresent);
        assertTrue(seatCountIsPresent);


        ///////
        // 由 col 取得 row, value 的 Map
        Map<String, Integer> universitySeatMap
                = universityCourseSeatTable.column("IT");

        assertEquals(universitySeatMap.size(), 2);
        assertEquals(universitySeatMap.get("Mumbai").intValue(), 60);
        assertEquals(universitySeatMap.get("Harvard").intValue(), 120);

        /////
        // columnMap  取得  Map<UniversityName, Map<CoursesOffered, SeatAvailable>>
        Map<String, Map<String, Integer>> courseKeyUniversitySeatMap
                = universityCourseSeatTable.columnMap();

        assertEquals(courseKeyUniversitySeatMap.size(), 3);
        assertEquals(courseKeyUniversitySeatMap.get("IT").size(), 2);
        assertEquals(courseKeyUniversitySeatMap.get("Electrical").size(), 1);
        assertEquals(courseKeyUniversitySeatMap.get("Chemical").size(), 1);

        ///////
        // 由 row 取得 col, value 的 Map
        Map<String, Integer> courseSeatMap
                = universityCourseSeatTable.row("Mumbai");

        assertEquals(courseSeatMap.size(), 2);
        assertEquals(courseSeatMap.get("IT").intValue(), 60);
        assertEquals(courseSeatMap.get("Chemical").intValue(), 120);

        //////
        // rowKeySet:  row keys
        // columnKeySet:  col keys
        Set<String> universitySet = universityCourseSeatTable.rowKeySet();
        assertEquals(universitySet.size(), 2);
        Set<String> courseSet = universityCourseSeatTable.columnKeySet();
        assertEquals(courseSet.size(), 3);

        /////////
        // remove 會回傳既有的 value 後,移除該 row, col 的 value
        Integer seatCount2 = universityCourseSeatTable.remove("Mumbai", "IT");
        Integer seatCount3 = universityCourseSeatTable.remove("Mumbai", "IT");

        assertEquals(seatCount2.intValue(), 60);
        assertNull(seatCount3);
    }

ClassToInstanceMap

ClassToInstanceMap 是一種特殊的 Map,可確保 keys, values 都是 B 的子類別

ClassToInstanceMap extends Map 介面,並增加兩個 methods: T getInstance(Class) and T putInstance(Class, T) ,這兩個 method 有做型別檢查,並避免 casting

    @Test
    public void create() {
        // 產生 ImmutableClassToInstanceMap

        // 1. using the of() method to create an empty map
        ImmutableClassToInstanceMap map1 = ImmutableClassToInstanceMap.of();

        // 2. using the of(Class<T> type, T value) method to create a single entry map
        ImmutableClassToInstanceMap map2 = ImmutableClassToInstanceMap.of(Save.class, new Save());

        // 3. copyOf()  複製另一個 ImmutableClassToInstanceMap
        ImmutableClassToInstanceMap map3 = ImmutableClassToInstanceMap.copyOf(map2);

        // 4. builder
        ImmutableClassToInstanceMap map4 = ImmutableClassToInstanceMap
                .<Action>builder()
                .put(Save.class, new Save())
                .put(Delete.class, new Delete())
                .build();

        ////////
        // MutableClassToInstanceMap
        // 1. create()
        MutableClassToInstanceMap mmap1 = MutableClassToInstanceMap.create();

        // 2. create(Map<Class<? extends B>, B> backingMap)
        MutableClassToInstanceMap mmap2 = MutableClassToInstanceMap.create(new HashMap());
    }
    interface Action {

    }
    class Save implements Action {
    }

    class Delete implements Action {
    }

    @Test
    public void using() {
        // 增加兩個 method 到 Map interface
        MutableClassToInstanceMap map = MutableClassToInstanceMap
                .create();
        map.put(Save.class, new Save());
        map.put(Delete.class, new Delete());

        // 1. <T extends B> T getInstance(Class<T> type):
        Action saveAction = (Action) map.get(Save.class);
        Delete deleteAction = (Delete) map.getInstance(Delete.class);

        // 2. <T extends B> T putInstance(Class<T> type, @Nullable T value):
        Action newOpen = (Action) map.put(Save.class, new Save());
        Delete newDelete = (Delete) map.putInstance(Delete.class, new Delete());
    }

RangeSet

a set comprising of zero or more non-empty, disconnected ranges

最基本實作 RangeSet 的類別為 TreeRangeSet

    @Test
    public void create() {
        // 1. 直接用 create 產生一個空的 RangeSet
        RangeSet<Integer> numberRangeSet = TreeRangeSet.create();

        // 2. create 時,加上一個 List of Range 參數
        List<Range<Integer>> numberList = Arrays.asList(Range.closed(0, 2));
        RangeSet<Integer> numberRangeSet2 = TreeRangeSet.create(numberList);

        // ImmutableRangeSet 的 builder 產生 ImmutableRangeSet
        //        ImmutableRangeSet.Builder<Integer> builder = ImmutableRangeSet.builder();
        RangeSet<Integer> numberRangeSet3
                = new ImmutableRangeSet.Builder<Integer>().add(Range.closed(0, 2)).build();
    }

    @Test
    public void add_remove_range() {
        // add/remove range
        RangeSet<Integer> numberRangeSet = TreeRangeSet.create();

        numberRangeSet.add(Range.closed(0, 2));
        numberRangeSet.add(Range.closed(3, 5));
        numberRangeSet.add(Range.closed(6, 8));
        numberRangeSet.add(Range.closed(9, 15));
        numberRangeSet.remove(Range.closed(3, 5));
        numberRangeSet.remove(Range.closed(7, 10));

        assertTrue(numberRangeSet.contains(1));
        assertFalse(numberRangeSet.contains(9));
        assertTrue(numberRangeSet.contains(12));
    }

    @Test
    public void range_span() {
        RangeSet<Integer> numberRangeSet = TreeRangeSet.create();

        numberRangeSet.add(Range.closed(0, 2));
        numberRangeSet.add(Range.closed(3, 5));
        numberRangeSet.add(Range.closed(6, 8));
        Range<Integer> experienceSpan = numberRangeSet.span();

        assertEquals(0, experienceSpan.lowerEndpoint().intValue());
        assertEquals(8, experienceSpan.upperEndpoint().intValue());
    }

    @Test
    public void subrange() {
        RangeSet<Integer> numberRangeSet = TreeRangeSet.create();

        numberRangeSet.add(Range.closed(0, 2));
        numberRangeSet.add(Range.closed(3, 5));
        numberRangeSet.add(Range.closed(6, 8));
        RangeSet<Integer> numberSubRangeSet
                = numberRangeSet.subRangeSet(Range.closed(4, 14));

        assertFalse(numberSubRangeSet.contains(3));
        assertFalse(numberSubRangeSet.contains(14));
        assertTrue(numberSubRangeSet.contains(7));
    }

    @Test
    public void complement() {
        RangeSet<Integer> numberRangeSet = TreeRangeSet.create();

        numberRangeSet.add(Range.closed(0, 2));
        numberRangeSet.add(Range.closed(3, 5));
        numberRangeSet.add(Range.closed(6, 8));
        RangeSet<Integer> numberRangeComplementSet
                = numberRangeSet.complement();

        assertTrue(numberRangeComplementSet.contains(-1000));
        assertFalse(numberRangeComplementSet.contains(2));
        assertFalse(numberRangeComplementSet.contains(3));
        assertTrue(numberRangeComplementSet.contains(1000));
    }

    @Test
    public void intersect() {
        RangeSet<Integer> numberRangeSet = TreeRangeSet.create();

        numberRangeSet.add(Range.closed(0, 2));
        numberRangeSet.add(Range.closed(3, 10));
        numberRangeSet.add(Range.closed(15, 18));

        assertTrue(numberRangeSet.intersects(Range.closed(4, 17)));
        assertFalse(numberRangeSet.intersects(Range.closed(19, 200)));
    }

RangeMap

mapping 不連續非空的 ranges 到非 null 的 values

基本實作為TreeRangeMap

    @Test
    public void create() {
        // 用 TreeRangeMap 的 create 產生 mutable RangeMap
        RangeMap<Integer, String> experienceRangeDesignationMap = TreeRangeMap.create();

        // ImmutableRangeMap.Builder 產生 ImmutableRangeMap
        RangeMap<Integer, String> experienceRangeDesignationMap2 =
                new ImmutableRangeMap.Builder<Integer, String>()
                        .put(Range.closed(0, 2), "Junior")
                        .build();
    }

    @Test
    public void query_within_range() {
        RangeMap<Integer, String> experienceRangeDesignationMap
                = TreeRangeMap.create();

        experienceRangeDesignationMap.put(
                Range.closed(0, 2), "Junior");
        experienceRangeDesignationMap.put(
                Range.closed(3, 5), "Senior");
        experienceRangeDesignationMap.put(
                Range.closed(6, 8),  "College");
        experienceRangeDesignationMap.put(
                Range.closed(9, 15), "Research");

        assertEquals("College",
                experienceRangeDesignationMap.get(6));
        assertEquals("Research",
                experienceRangeDesignationMap.get(15));

        assertNull(experienceRangeDesignationMap.get(30));
    }

    @Test
    public void remove_rage() {
        RangeMap<Integer, String> experienceRangeDesignationMap
                = TreeRangeMap.create();

        experienceRangeDesignationMap.put(
                Range.closed(0, 2), "Junior");
        experienceRangeDesignationMap.put(
                Range.closed(3, 5), "Senior");
        experienceRangeDesignationMap.put(
                Range.closed(6, 8),  "College");
        experienceRangeDesignationMap.put(
                Range.closed(9, 15), "Research");

        experienceRangeDesignationMap.remove(Range.closed(9, 15));
        experienceRangeDesignationMap.remove(Range.closed(1, 4));

        assertNull(experienceRangeDesignationMap.get(9));
        assertEquals("Junior",
                experienceRangeDesignationMap.get(0));
        assertEquals("Senior",
                experienceRangeDesignationMap.get(5));
        assertNull(experienceRangeDesignationMap.get(1));
    }

    @Test
    public void span() {
        RangeMap<Integer, String> experienceRangeDesignationMap
                = TreeRangeMap.create();

        experienceRangeDesignationMap.put(
                Range.closed(0, 2), "Junior");
        experienceRangeDesignationMap.put(
                Range.closed(3, 5), "Senior");
        experienceRangeDesignationMap.put(
                Range.closed(6, 8),  "College");
        experienceRangeDesignationMap.put(
                Range.closed(9, 15), "Research");

        Range<Integer> experienceSpan = experienceRangeDesignationMap.span();

        assertEquals(0, experienceSpan.lowerEndpoint().intValue());
        assertEquals(15, experienceSpan.upperEndpoint().intValue());
    }

    @Test
    public void subRageMap() {
        RangeMap<Integer, String> experienceRangeDesignationMap
                = TreeRangeMap.create();

        experienceRangeDesignationMap.put(
                Range.closed(0, 2), "Junior");
        experienceRangeDesignationMap.put(
                Range.closed(3, 5), "Senior");
        experienceRangeDesignationMap.put(
                Range.closed(6, 8),  "College");
        experienceRangeDesignationMap.put(
                Range.closed(9, 15), "Research");

        RangeMap<Integer, String> experiencedSubRangeDesignationMap
                = experienceRangeDesignationMap.subRangeMap(Range.closed(4, 14));

        assertNull(experiencedSubRangeDesignationMap.get(3));
        assertTrue(experiencedSubRangeDesignationMap.asMapOfRanges().values()
                .containsAll(Arrays.asList("Senior", "College", "Research")));
    }

2024/3/25

Guava Collection Multiset Multimap

New Collection Type

ref: NewCollectionTypesExplained · google/guava Wiki · GitHub

ref: 【Guava 教學】(7)Multiset、Multimap 與 BiMap

Multiset

多重集合(Multiset)是集合(Set)概念的推廣(Generalization),Set 裡面相同元素只能出現一次,Multiet 多重集合則允許相同元素出現多次,元素在集合中有重複次數(Occurrence)的概念,多重集合又稱為 Bag。

Guava 提供 Multiset,可方便地計算每一個元素發生的次數,且能 iterate 每一個元素。換句話說,Multiset 有兩個功能

  1. 類似沒有順序的 ArrayList

    • add(E) 新增一個元素

    • iterator() 迭代每一個元素

    • size()

  2. 類似 Map<E, Integer>,儲存元素及數量

    • count(Object) 計算某個元素的數量

    • entrySet() 回傳 Set<Multiset.Entry> ,類似 Map 的 entrySet

    • elementSet() 回傳 Set ,包含所有不同的 elements,類似 Map 的 keySet()

    @Test
    public void jdk_word_count() {
        List<String> words = Arrays.asList("one", "two", "three", "one", "three");
        Map<String, Integer> counts = new HashMap<>();
        for(String word : words) {
            Integer count = counts.get(word);
            if (count == null) {
                counts.put(word, 1);
            } else {
                counts.put(word, count + 1);
            }
        }
        System.out.println(counts); // {two=1, one=2, three=2}

        Map<String, List<String>> wordBag = new HashMap<>();
        for(String word : words) {
            List<String> repeatedWds = wordBag.get(word);
            if(repeatedWds == null) {
                repeatedWds = new ArrayList<>();
                wordBag.put(word, repeatedWds);
            }
            repeatedWds.add(word);
        }
        // {one=[one, one], two=[two], three=[three, three]}
        System.out.println(wordBag);
    }

    @Test
    public void guava_multiset_word_count() {
        List<String> words = Arrays.asList("one", "two", "three", "one", "three");
        Multiset<String> wordBag = HashMultiset.create(words);

        System.out.println("");
        // [two, one x 2, three x 2]
        System.out.println(wordBag);

//        Element: one, Occurrence(s): 2
//        Element: two, Occurrence(s): 1
//        Element: three, Occurrence(s): 2
        for (Multiset.Entry<String> entry : wordBag.entrySet())
        {
            System.out.println("Element: "+entry.getElement() +", Occurrence(s): " + entry.getCount());
        }
        for(String word : wordBag) {
            // 可直接使用 words 裡面的每一個元素
            System.out.print(word);
        }
    }

Guava 提供的 Multiset implementation,可對應到 JDK map implementation

Map Corresponding Multiset Supports null elements
HashMap HashMultiset Yes
TreeMap TreeMultiset Yes
LinkedHashMap LinkedHashMultiset Yes
ConcurrentHashMap ConcurrentHashMultiset No
ImmutableMap ImmutableMultiset No

TreeMultiset 有實作 SortedMultiset 介面,該 interface 可快速取得 sub-multiset,ex:

    @Test
    public void guava_submultiset_word_count() {
        List<String> words = Arrays.asList("one", "two", "three", "one", "three");
        TreeMultiset<String> wordBag = TreeMultiset.create(words);

        SortedMultiset<String> subWordBag = wordBag.subMultiset("one", BoundType.CLOSED, "two", BoundType.OPEN);
        System.out.println("");
        // [two, one x 2, three x 2]
        System.out.println(wordBag);
        // [one x 2, three x 2]
        // 根據 String 的排序,取得比 "two" 比較後還小的那些元素集合
        // TreeMultiset 裡面的元素都有排序過
        System.out.println(subWordBag);

        //Element: one, Occurrence(s): 2
        //Element: three, Occurrence(s): 2
        for (SortedMultiset.Entry<String> entry : subWordBag.entrySet())
        {
            System.out.println("Element: "+entry.getElement() +", Occurrence(s): " + entry.getCount());
        }
        for(String word : subWordBag) {
            // 可直接使用 subWordBag 裡面的每一個元素
            // one one three three
            System.out.print(word+" ");
        }
    }

Multimap

ref: Guava Multimap類 - Guava教學

在 java 只有提供 Map<K, List<V>> or Map<K, Set<V>>

在 Guava 以 Multimap 提供 keys 對應到任意資料結構的一個介面

Multimap 有一個 asMap() ,會回傳 Map<K, Collection<V>>

比較常用的是 ListMultimap / SetMutimap,比較少直接使用 Multimap interface


Construction & Modify

雖然可以直接用 ListMultimap / SetMutimap 的 create() 產生 Multimap,但比較建議使用 MultimapBuilder 產生

    @Test
    public void construction() {
        List<String> tolist = Arrays.asList("to1@domain");
        List<String> cclist = Arrays.asList("cc1@domain", "cc2@domain");
        List<String> bcclist = Arrays.asList("bcc1@domain", "bcc2@domain");

        // 使用 MultimapBuilder
        // creates a ListMultimap with tree keys and array list values
        ListMultimap<String, List<String>> treeListMultimap =
                MultimapBuilder.treeKeys().arrayListValues().build();
        treeListMultimap.put("to", tolist);
        treeListMultimap.put("cc", cclist);
        treeListMultimap.put("bcc", bcclist);
        System.out.println("treeListMultimap:");
        // {bcc=[[bcc1@domain, bcc2@domain]], cc=[[cc1@domain, cc2@domain]], to=[[to1@domain]]}
        System.out.println(treeListMultimap);

        // 直接使用 create()
        Multimap<String,List<String>> treeListMultimap2 = ArrayListMultimap.create();
        treeListMultimap2.put("to", tolist);
        treeListMultimap2.put("cc", cclist);
        treeListMultimap2.put("bcc", bcclist);

        // creates a SetMultimap with hash keys and enum set values
        SetMultimap<String, Grade> hashEnumMultimap =
                MultimapBuilder.hashKeys().enumSetValues(Grade.class).build();
        hashEnumMultimap.put("Alice", Grade.A);
        hashEnumMultimap.put("Bruce", Grade.B);

        System.out.println("hashEnumMultimap:");
        // {Bruce=[B], Alice=[A]}
        System.out.println(hashEnumMultimap);
    }
    public enum Grade {
        A, B, C, D, F, INCOMPLETE
    }

    @Test
    public void modify() {
        System.out.println("");

        List<String> tolist = Arrays.asList("to1@domain");
        List<String> cclist = Arrays.asList("cc1@domain", "cc2@domain");
        List<String> bcclist = Arrays.asList("bcc1@domain", "bcc2@domain");

        // 使用 MultimapBuilder
        // creates a ListMultimap with tree keys and array list values
        ListMultimap<String, List<String>> treeListMultimap =
                MultimapBuilder.treeKeys().arrayListValues().build();
        treeListMultimap.put("to", tolist);
        treeListMultimap.put("cc", cclist);
        treeListMultimap.put("bcc", bcclist);
        // treeListMultimap: {bcc=[[bcc1@domain, bcc2@domain]], cc=[[cc1@domain, cc2@domain]], to=[[to1@domain]]}
        System.out.println("treeListMultimap: "+ treeListMultimap);
        treeListMultimap.removeAll("cc");

        // treeListMultimap2 after removeAll: {bcc=[[bcc1@domain, bcc2@domain]], to=[[to1@domain]]}
        System.out.println("treeListMultimap2 after removeAll: "+ treeListMultimap);

        List<String> tolist2 = Arrays.asList("to2@domain");
        treeListMultimap.put("to", tolist2);
        // treeListMultimap2 put new key/value: {bcc=[[bcc1@domain, bcc2@domain]], to=[[to1@domain], [to2@domain]]}
        System.out.println("treeListMultimap2 put new key/value: "+ treeListMultimap);

        treeListMultimap.clear();
        treeListMultimap.put("to", tolist2);
        // treeListMultimap2: {to=[[to2@domain]]}
        System.out.println("treeListMultimap2: "+ treeListMultimap);
    }

views

    @Test
    public void views() {
        System.out.println("");

        List<String> tolist = Arrays.asList("to1@domain");
        List<String> cclist = Arrays.asList("cc1@domain", "cc2@domain");
        List<String> bcclist = Arrays.asList("bcc1@domain", "bcc2@domain");

        // 使用 MultimapBuilder
        // creates a ListMultimap with tree keys and array list values
        ListMultimap<String, List<String>> treeListMultimap =
                MultimapBuilder.treeKeys().arrayListValues().build();
        treeListMultimap.put("to", tolist);
        treeListMultimap.put("cc", cclist);
        treeListMultimap.put("bcc", bcclist);
        // treeListMultimap: {bcc=[[bcc1@domain, bcc2@domain]], cc=[[cc1@domain, cc2@domain]], to=[[to1@domain]]}
        System.out.println("treeListMultimap: "+ treeListMultimap);

        // asMap:  views any Multimap<K, V> as a Map<K, Collection<V>>
        Map<String, Collection<List<String>>> tomap = treeListMultimap.asMap();
        // asMap: {bcc=[[bcc1@domain, bcc2@domain]], cc=[[cc1@domain, cc2@domain]], to=[[to1@domain]]}
        System.out.println("asMap: "+ tomap);

        // entries():  views the Collection<Map.Entry<K, V>>
        // entries: [bcc=[bcc1@domain, bcc2@domain], cc=[cc1@domain, cc2@domain], to=[to1@domain]]
        Collection<Map.Entry<String, List<String>>> entries = treeListMultimap.entries();
        System.out.println("entries: "+ entries);

        // keySet: views the distinct keys in the Multimap as a Set
        // keySet: [bcc, cc, to]
        Set<String> keySet = treeListMultimap.keySet();
        System.out.println("keySet: "+ keySet);

        // keys: views the keys of the Multimap as a Multiset
        // keysMultiset: [bcc, cc, to]
        Multiset<String> keysMultiset = treeListMultimap.keys();
        System.out.println("keysMultiset: "+ keysMultiset);

        // values: views all the values in the Multimap as a "flattened" Collection<V>
        // values: [[bcc1@domain, bcc2@domain], [cc1@domain, cc2@domain], [to1@domain]]
        Collection<List<String>> values = treeListMultimap.values();
        System.out.println("values: "+ values);
    }

implementations

建議使用  MultimapBuilder 不是直接 create()

Implementation Keys behave like... Values behave like..
ArrayListMultimap HashMap ArrayList
HashMultimap HashMap HashSet
LinkedListMultimap * LinkedHashMap``* LinkedList``*
LinkedHashMultimap** LinkedHashMap LinkedHashSet
TreeMultimap TreeMap TreeSet
ImmutableListMultimap ImmutableMap ImmutableList
ImmutableSetMultimap ImmutableMap ImmutableSet

2024/3/18

Guava Collection 1 Immutable Collections

Immutable Collections

ref: ImmutableCollectionsExplained · google/guava Wiki · GitHub

collection 的資料不一定需要隨時可以修改,如果可以任意修改,反而在某些時候,會造成問題。

  1. 不能修改的 collection,將資料傳給 untrusted libraries 使用,也不會被 library 任意修改資料

  2. thread-safe,再多執行緒環境共用資料時,可避免同時修改發生問題

  3. 可節省 time, space

JDK 也有提供 Collections.unmodifiableXXX methods,但還是有可能有以下問題

  1. unwieldy and verbose: 使用時必須要在每一個地方,都先產生一份

  2. unsafe: 只有在沒有其他地方,有儲存原本 collection 的 reference 時,這個 collection 才會是 immutable

  3. inefficient: 資料結構還是跟原本 mutable collection 一樣,所以還是會有 concurrent modification check, 額外耗費的 space ...

    @Test
    public void jdk_unmodifiableMethod() {
        List list = new ArrayList();
        list.add("item1");
        list.add("item2");

        List unmodifiableList = Collections.unmodifiableList(list);

        Exception exception = assertThrows(UnsupportedOperationException.class, () -> {
            unmodifiableList.add("item3");;
        });

        assertEquals(exception.getClass().getName(), "java.lang.UnsupportedOperationException");
        String actualMessage = exception.getMessage();
        assertNull(actualMessage);

        // 如果修改原本的 list,還是會影響到 unmodifiableList
        list.add("item3");
        assertEquals(unmodifiableList.size(), 3);
    }

    @Test
    public void guava_immutable() {
        List<String> stringArrayList = Lists.newArrayList("item1","item2");
        ImmutableList<String> immutableList = ImmutableList.copyOf(stringArrayList);

        Exception exception = assertThrows(UnsupportedOperationException.class, () -> {
            immutableList.add("item3");
        });

        assertEquals(exception.getClass().getName(), "java.lang.UnsupportedOperationException");
        String actualMessage = exception.getMessage();
        assertNull(actualMessage);

        // 如果修改原本的 list,不會影響到 immutableList
        stringArrayList.add("item3");
        assertEquals(stringArrayList.size(), 3);
        assertEquals(immutableList.size(), 2);
    }

Guava immutable collection 不能使用 null values,因為大部分的 code,都是必須要有值

產生 ImmutableXXX collection 的方法:

  1. 使用 copyOf method ex: ImmutableSet.copyOf(set)

  2. 使用 of method ex: ImmutableSet.of("a", "b", "c") or ImmutableMap.of("a", 1, "b", 2)

  3. 使用 Builder

    @Test
    public void immutableCollection() {
        // copyOf
        List<String> stringArrayList = Lists.newArrayList("item1","item2");
        ImmutableList<String> immutableList = ImmutableList.copyOf(stringArrayList);

        // of
        ImmutableSet.of("a", "b", "c", "a", "d", "b");

        // Builder
        Color color1 = new Color(0, 0, 255);
        Color color2 = new Color(0, 255, 0);
        ImmutableSet<Color> colors = ImmutableSet.of(color1, color2);

        ImmutableSet<Color> newcolors =
                ImmutableSet.<Color>builder()
                        .addAll(colors)
                        .add(new Color(0, 191, 255))
                        .build();
    }

所有 immutable collections 都有透過 asList() 產生的 ImmutableList 的 view。

    @Test
    public void asList() {
        ImmutableSet<String> set = ImmutableSet.of("a", "b", "c", "a", "d", "b");

        String item0 = set.asList().get(0);
        assertEquals(item0, "a");
    }
Interface JDK or Guava? Immutable Version
Collection JDK ImmutableCollection
List JDK ImmutableList
Set JDK ImmutableSet
SortedSet/NavigableSet JDK ImmutableSortedSet
Map JDK ImmutableMap
SortedMap JDK ImmutableSortedMap
Multiset Guava ImmutableMultiset
SortedMultiset Guava ImmutableSortedMultiset
Multimap Guava ImmutableMultimap
ListMultimap Guava ImmutableListMultimap
SetMultimap Guava ImmutableSetMultimap
BiMap Guava ImmutableBiMap
ClassToInstanceMap Guava ImmutableClassToInstanceMap
Table Guava ImmutableTable