-
Notifications
You must be signed in to change notification settings - Fork 10
/
rootdoc.txt
173 lines (131 loc) · 7.52 KB
/
rootdoc.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
== The Mango library ==
This is the documentation for the Mango library.
The purpose of the Mango library is to provide [[https://code.google.com/p/guava-libraries/ Guava]] (Google's core libraries) functionalities to Scala. This is primarily achieved through wrappers around Guava classes and converter between Java and Scala.
Also the package structure is intended to mirror the one from Guava.
However there are differences from the Guava libraries:
- Whenever `null` is in Guava to indicate the absence of a value we use `Option`
- Mango is more restrictive when passing `null` as arguments to library functions. The recommendation is to never use `null` at all.
- In rare cases the method names are changed to conform to the Scala standard library
- The Mango library uses Type Classes when appropriate
This is a beta version of the library. Many modules are not published yet because they are either not implemented, the test coverage is too low or the documentation is not complete. We publish these modules as soon as they are ready.
== Downloading ==
Mango is programmed against `guava-18.0` (and is compatible to all guava versions >= 15.0) using Scala 2.11. If you want to run the tests you will also need the `guava-testlib-18.0`.
To use the Mango library in [[http://www.scala-sbt.org/ sbt]] add the following dependency to your project file:
{{{
resolvers ++= Seq(
"Sonatype Snapshots" at "http://oss.sonatype.org/content/repositories/snapshots",
"Sonatype Releases" at "http://oss.sonatype.org/content/repositories/releases"
)
libraryDependencies += "org.feijoas" %% "mango" % "0.12"
}}}
== Examples ==
==== Suppliers ====
{{{
import org.feijoas.mango.common.base.Suppliers._
// a supplier is just a function () => T
val supplier = () => 3 //> supplier : () => Int
//= function0
// convert to a Guava supplier
val gSupplier = supplier.asJava //> gSupplier : com.google.common.base.Supplier[Int]
//= AsGuavaSupplier(function0)
// create s supplier that memoize its return
// value for 10 seconds
val memSupplier = memoizeWithExpiration(supplier, 10, TimeUnit.SECONDS)
//> memSupplier : () => Int
//= Suppliers.memoizeWithExpiration(function0, 10, SECONDS)
}}}
==== Caches ====
{{{
import java.util.concurrent.TimeUnit
import org.feijoas.mango.common.cache._
// the function to cache
val expensiveFnc = (str: String) => str.length //> expensiveFnc : String => Int
// create a cache with a maximum size of 100 and
// exiration time of 10 minutes
val cache = CacheBuilder.newBuilder()
.maximumSize(100)
.expireAfterWrite(10, TimeUnit.MINUTES)
.build(expensiveFnc) //> cache : LoadingCache[String,Int]
cache("MyString") //> res0: Int = 8
}}}
==== BloomFilter & Funnel ====
{{{
import org.feijoas.mango.common.hash.Funnel._
import org.feijoas.mango.common.hash.BloomFilter._
// A Funnel describes how to decompose a particular object type into primitive field values.
// For example, if we had
case class Person(id: Integer, firstName: String, lastName: String, birthYear: Int)
// our Funnel might look like
implicit val personFunnel = new Funnel[Person] {
override def funnel(person: Person, into: PrimitiveSink) = {
into
.putInt(person.id)
.putString(person.firstName, Charsets.UTF_8)
.putString(person.lastName, Charsets.UTF_8)
.putInt(person.birthYear)
}
}
val friends: BloomFilter[Person] = BloomFilter.create(500, 0.01)
friendsList.foreach { case p: Person => friends.put(p) }
// much later
if (friends.mightContain(dude)) {
// the probability that dude reached this place if he isn't a friend is 1%
// we might, for example, start asynchronously loading things for dude while we do a more expensive exact check
}
}}}
==== Range, RangeSet & RangeMap ====
{{{
import org.feijoas.mango.common.collect.Bound._
import org.feijoas.mango.common.collect._
import math.Ordering.Int
val range = Range.atLeast(6) // Range[Int,math.Ordering.Int.type] = [6..inf)
// Pattern match using extractor
range match {
case Range(FiniteBound(lower, lowerType), InfiniteBound) => ...
}
// immutable range set:
val rangeSet = RangeSet(Range.open(1, 3), Range.closed(4, 9)) // {(1,3), [4,9]}
val subSet = rangeSet.subRangeSet(Range.closed(2, 6)) // union view {[2,3), [4,6]}
// mutable range set:
val mutableRangeSet = mutable.RangeSet(Range.closed(1, 10)) // {[1, 10]}
mutableRangeSet += Range.closedOpen(11, 15) // disconnected range: {[1, 10], [11, 15)}
mutableRangeSet += Range.closedOpen(15, 20) // connected range; {[1, 10], [11, 20)}
mutableRangeSet += Range.openClosed(0, 0) // empty range; {[1, 10], [11, 20)}
mutableRangeSet -= Range.open(5, 10) // splits [1, 10]; {[1, 5], [10, 10], [11, 20)}
// mutable range map
val rangeMap = mutable.RangeMap(Range.open(3, 7) -> "1") //Map((3..7) -> 1)
rangeMap += Range.closed(9, 10) -> "2" // Map((3..7) -> 1, [9..10] -> 2)
rangeMap += Range.closed(12, 16) -> "3" // Map((3..7) -> 1, [9..10] -> 2, [12..16] -> 3)
val sub = rangeMap.subRangeMap(Range.closed(5, 11)) // Map([5..7) -> 1, [9..10] -> 2)
sub.put(Range.closed(7, 9), "4") // sub = Map([5..7) -> 1, [7..9] -> 4, (9..10] -> 2)
// rangeMap = Map((3..7) -> 1, [7..9] -> 4, (9..10] -> 2, [12..16] -> 3)
}}}
See the individual packages for more examples and documentation.
== Converter ==
Conversions to and from the Guava libraries are done with the `.asJava` and `.asScala` methods respectively. These methods are imported together with the utility functions of the class. For example:
{{{
// import converter for com.google.common.base.Function
import org.feijoas.mango.common.base.Functions._
val fnc = (str: String)=> str.length //> fnc : String => Int = function1
fnc.asJava //> res0: com.google.common.base.Function[String,Int]
//= AsGuavaFunction(function1)
}}}
== Build ==
Just clone the git repository and build Mango in the following way:
{{{
sbt update
sbt compile
}}}
Don't forget to test
{{
sbt test
}}
== Help ==
Besides this Scaladoc there is an excelent user guide [[https://code.google.com/p/guava-libraries/wiki/GuavaExplained Guava Explained]] which should be sufficient for almost all questions.
- Mango-Guava conversions: [[#org.feijoas.mango.common.base.Functions Functions]], [[#org.feijoas.mango.common.base.Optional Optional]], [[#org.feijoas.mango.common.base.Predicates Predicates]], [[#org.feijoas.mango.common.base.Suppliers Suppliers]], [[#org.feijoas.mango.common.util.concurrent.Futures Futures]]
- [[#org.feijoas.mango.common.base.Preconditions Preconditions]]: Test preconditions for your methods more easily.
- [[#org.feijoas.mango.common.cache.CacheBuilder Caches]]: Local caching, done right, and supporting a wide variety of expiration behaviors.
- [[#org.feijoas.mango.common.collect.Range Ranges]]: RangeSets/RangeMaps query, merge and manipulate ranges
- [[#org.feijoas.mango.common.primitives Primitives]]: Unsigned Int, Long and Byte
== License ==
[[http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0]]