BiMap

Why have a bimap? A bimap (or "bidirectional map") is a map that preserves the uniqueness of its values as well as that of its keys. This constraint enables bimaps to support an "inverse view", which is another bimap containing the same entries as this bimap but with reversed keys and values. That means it is not possible to insert an entry that has a value that is already a value in another entry, because then it would not be possible to invert the bimap. However, this can be overridden with a force put function, in which case the existing entry will be silently overwritten.
A duplicate key is acceptable input, in that case the insertion operation for the bimap will simply overwrite the existing entry.

For example, assigning people social security numbers would be an application of a bimap. For every person there can be only one SSN, and every SSN can be owned by only one person. However, it must be possible to assign a person a new SSN that is not used currently by simply overwriting the old one for the same person.

In JavaTools a bimap can simply be created with JBiMap[]. It then has to be filled with elements afterwards.

"bimap_1.gif"

"bimap_2.gif"

However, it's also possible to create a new bimap and supply initial values during creation:

"bimap_3.gif"

"bimap_4.gif"

This constructs the inverse bimap:

"bimap_5.gif"

"bimap_6.gif"

"bimap_7.gif"

1 2
2 4
3 6
4 8

"bimap_8.gif"

2 1
4 2
6 3
8 4

JBiMapSize[] returns the number of elements in the bimap, and JBiMapIsEmpty[] shows if the bimap is empty:

"bimap_9.gif"

"bimap_10.gif"

"bimap_11.gif"

"bimap_12.gif"

A new element is added to the bimap with JBiMapPut[]:

"bimap_13.gif"

"bimap_14.gif"

1 2
2 4
3 6
4 8
15 20

It is not permitted to insert an entry for which the value exists already in the bimap for another entry.

"bimap_15.gif"

"bimap_16.gif"

"bimap_17.gif"

"bimap_18.gif"

1 2
2 4
3 6
4 8
15 20

"bimap_19.gif"

"bimap_20.gif"

A value is retrieved from the bimap through its key:

"bimap_21.gif"

"bimap_22.gif"

"bimap_23.gif"

The type of elements that can be put in a bimap can be anything: Integer, Real, String, or even List:

"bimap_24.gif"

"bimap_25.gif"

"bimap_26.gif"

"bimap_27.gif"

"bimap_28.gif"

hello 555
16 33.44
1 2
2 4
3 6
4 8
22 {3,4,77.88}
a range {1,2,3,4,5}
15 20

"bimap_29.gif"

"bimap_30.gif"

This means that even lists can be valid keys in a bimap.

"bimap_31.gif"

{3,4,77.88} 22
2 1
{1,2,3,4,5} a range
4 2
20 15
6 3
8 4
555 hello
33.44 16

"bimap_32.gif"

"bimap_33.gif"

If JBiMapPut[] is used with a {key,value} pair and the key exists already in the bimap, the value of that entry will be overwritten with the new value, and JBiMapPut[] returns the value of the overwritten entry.

"bimap_34.gif"

"bimap_35.gif"

"bimap_36.gif"

hello 555
16 33.44
1 2
2 4
3 67
4 8
22 {3,4,77.88}
a range {1,2,3,4,5}
15 20

"bimap_37.gif"

"bimap_38.gif"

You can use JBiMapForcePut[] if you want to force the entry to be added to the bimap, in which case JBiMapForcePut[] silently removes the other entry having the same value to ensure there are no duplicate values in the bimap, to preserve invertibility.

This attempt fails, because 67 is already a value in the bimap for the key 3.

"bimap_39.gif"

"bimap_40.gif"

"bimap_41.gif"

Here we force the insertion of the 67 with a new key 55:

"bimap_42.gif"

"bimap_43.gif"

hello 555
16 33.44
1 2
2 4
55 67
4 8
22 {3,4,77.88}
a range {1,2,3,4,5}
15 20

The bimap remains invertible.

"bimap_44.gif"

"bimap_45.gif"

"bimap_46.gif"

{3,4,77.88} 22
2 1
{1,2,3,4,5} a range
4 2
20 15
67 55
8 4
555 hello
33.44 16

"bimap_47.gif"

"bimap_48.gif"

With JBiMapRemove[]we can remove an entry that is in the bimap, returning the value of the entry that was removed:

"bimap_49.gif"

"bimap_50.gif"

"bimap_51.gif"

hello 555
16 33.44
1 2
55 67
4 8
22 {3,4,77.88}
a range {1,2,3,4,5}
15 20

"bimap_52.gif"

"bimap_53.gif"

With JBiMapContainsKey[] we can see if the bimap contains a particular key:

"bimap_54.gif"

"bimap_55.gif"

"bimap_56.gif"

"bimap_57.gif"

"bimap_58.gif"

"bimap_59.gif"

With JBiMapContainsValue[] we can see if the bimap contains a particular value:

"bimap_60.gif"

"bimap_61.gif"

"bimap_62.gif"

"bimap_63.gif"

JBiMapPutAll[] adds all elements to the bimap, if possible (no duplicate values permitted):

"bimap_64.gif"

"bimap_65.gif"

"bimap_66.gif"

34 44
35 45
1 2
32 42
33 43
4 8
15 20
a range {1,2,3,4,5}
hello 555
16 33.44
55 67
22 {3,4,77.88}
31 41
30 40

"bimap_67.gif"

"bimap_68.gif"

Note that JBiMapPutAll[]adds all elements in the list to the bimap individually, whereas JBiMapPut[] adds all elements in the list to the bimap as one list element:

"bimap_69.gif"

"bimap_70.gif"

"bimap_71.gif"

34 44
35 45
1 2
32 42
33 43
4 8
15 20
a range {1,2,3,4,5}
hello 555
16 33.44
55 67
22 {3,4,77.88}
key101 101
31 41
key100 100
30 40

"bimap_72.gif"

"bimap_73.gif"

"bimap_74.gif"

"bimap_75.gif"

34 44
key100-101 {100,101}
35 45
1 2
32 42
33 43
4 8
15 20
a range {1,2,3,4,5}
hello 555
16 33.44
55 67
22 {3,4,77.88}
key101 101
31 41
key100 100
30 40

"bimap_76.gif"

"bimap_77.gif"

The bimap is cleared or emptied with JBiMapClear[].

"bimap_78.gif"

"bimap_79.gif"

"bimap_80.gif"

"bimap_81.gif"

"bimap_82.gif"

"bimap_83.gif"

The data stored in the bimap can be any valid Mathematica expression, not just Integer, Real, or String. In the following example we use integers as keys, plots as values, then we invert the bimap, so that the plots become the keys ("indices") and the integers become the values.

"bimap_84.gif"

"bimap_85.gif"

"bimap_86.gif"

"bimap_87.gif"

"bimap_88.gif"

"bimap_89.gif"

1 "bimap_90.gif"
2 "bimap_91.gif"
3 "bimap_92.gif"
4 "bimap_93.gif"
5 "bimap_94.gif"

"bimap_95.gif"

"bimap_96.gif"

"bimap_97.gif"

"bimap_98.gif" 3
"bimap_99.gif" 4
"bimap_100.gif" 5
"bimap_101.gif" 1
"bimap_102.gif" 2

"bimap_103.gif"

"bimap_104.gif"

Of course a bimap could also be implemented in Mathematica, but the key point is that with JavaTools the bimap is completely stored in the JVM and NOT in the Mathematica kernel.

"bimap_105.gif"

"bimap_106.gif"

"bimap_107.gif"

"bimap_108.gif"

Spikey Created with Wolfram Mathematica 7.0