Hello Roman, Thanks for your feedback. These are good questions and I realize that not enough documentation on the concept or usage of polymaps is provided, so my next step will be to expand the Haddock documentation to include a detailed explanation of the concept and how to use the Relation data type and the Storage typeclass. As far as what a polymap actually is, the example I've used to describe to concept to a couple of people is as follows. I'll briefly explain a couple of concepts first. A unidirectional map--or just map for short--is a data structure holding a number of keys of some type and an identical number of values of some other type, forming a bijection between the keys and values. The data structure stores the keys and values in such a way so as to allow values to be looked up by their corresponding keys; in other words, each key maps to the corresponding value. To illustrate this mapping: A==>B A bidirectional map is similar to a map with the difference that each value also maps back to its corresponding key, allowing two-way (bidirectional) mapping between the keys and values. In the case of a bimap, it may be more useful to refer to both the keys and values as a set of keys on one of the sides of the bimap. To illustrate this mapping: A<=>B Or to illustrate more consistently for the illustration following this one: A---B A 3-sided map builds on these concepts, applying them to three sides as opposed to two (left and right), creating a relational mapping between three different sets of keys where each side maps to every other side. To illustrate this mapping: A---B | / | / |/ C Similarly, a 4-sided map is illustrated as: A---B |\ /| | X | |/ \| C---D A polymap essentially generalizes these previous examples as an n-sided map, allowing values to looked up by any of their of corresponding keys on one of the sides of the polymap. I hope this clears things up somewhat with respect to what a polymap is. I'll be adding Haddock explaining all of this as well as Storage and Relation and the definitions in Data.PolyMap.Nat as soon as I get the chance. Apologies for my awful ASCII illustrations. On 25/09/2015 07:42, Roman Cheplyaka wrote:
(moving from haskell@ to haskell-cafe@)
Hi David,
As someone who is not familiar with the concept of polygonal maps, I find this package severely underdocumented.
What is a polymap? Why would I want to use one? What is storage and how should I choose it?
The example clears it up a bit, but it could also use more prose. And perhaps there could be a more motivated example (showing how polymap solves an actual problem).
On 09/24/2015 09:53 PM, David Farrell wrote:
I'm excited to announce the first release of a package I've been working on over the last week called polymap, a library providing type-safe polygonal maps whose sides are defined by a kindlist of types zipped with a storage type for each side. I've tried to match the interface exposed by the containers package as closely as possible. For example:
import Data.Set (Set) import Data.PolyMap.Nat (first, second, third) import qualified Data.PolyMap as PM
mEmpty :: PM.PolyMap '[ '(String, Set), '(Int, Set) ] mEmpty = PM.empty
mOne :: PM.SimplePolyMap '[String, Int] Set mOne = PM.singleton ("one", length "one")
main = do print mEmpty -- empty PolyMap print mOne -- PolyMap with one Relation print mTwo -- PolyMapwith two Relations print (PM.member first "one" mTwo) -- True print (PM.notMember first "asdf" mTwo) -- True --print (PM.notMember second "asdf" mTwo) -- will not typecheck --print (PM.notMember third "asdf" mTwo) -- will not typecheck print (PM.lookup first "two" mTwo) -- second Relation of PolyMap where mTwo = PM.insert ("two", length "two") mOne
This is a short usage example of most of the functions currently written for polymap. There's still a long way to go both in terms of exposed functions and in terms of efficiency and such, but I felt it prudent to make a public release of my work so far as I feel it's reached a stage where it could be beneficial to others. Note that GHC 7.10 (base >=4.8, GHC extensions) is required.
Git Repository: https://github.com/shockkolate/hs-polymap
Issue Tracker: https://github.com/shockkolate/hs-polymap
Hackage: https://hackage.haskell.org/package/polymap
The code is licensed under the Unlicense license--that is to say, the code is released into the public domain for the benefit of others.
I'd love to hear any feedback/suggestions/improvements/anything you want to say about polymap over the mailing list (which may be more suited to the haskell-cafe mailing list; I don't know) or in #haskell on Freenode (I'm usually in there as Shockk).
N.B. Version 0.1.0.0 of the package will not build due to the use of a function in containers that has been submitted as a pull request but does not exist yet/at all. _______________________________________________ Haskell mailing list Haskell@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell