Lots of documentation + test fixes, updates

algebird-core/src/main/scala/com/twitter/algebird/First.scala

@@ -0,0 +1,43 @@
+/*
+Copyright 2016 Twitter, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+package com.twitter.algebird
+
+/**
+ * First tracks the "most recent" item by the order in which items
+ * are seen.
+ */
+case class First[@specialized(Int, Long, Float, Double) +T](get: T) {
+  def +[U >: T](r: First[U]): First[U] = this
+}
+
+object First extends FirstInstances {
+  def aggregator[T]: FirstAggregator[T] = FirstAggregator()
+}
+
+private[algebird] sealed abstract class FirstInstances {
+  implicit def semigroup[T]: Semigroup[First[T]] = new Semigroup[First[T]] {
+    def plus(l: First[T], r: First[T]): First[T] = l
+
+    override def sumOption(iter: TraversableOnce[First[T]]): Option[First[T]] =
+      if (iter.isEmpty) None else Some(iter.toIterator.next)
+  }
+}
+
+case class FirstAggregator[T]() extends Aggregator[T, T, T] {
+  def prepare(v: T) = v
+  val semigroup: Semigroup[T] = Semigroup.from { (l: T, r: T) => l }
+  def present(v: T) = v
+}

algebird-core/src/main/scala/com/twitter/algebird/Last.scala

@@ -0,0 +1,38 @@
+/*
+Copyright 2016 Twitter, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+package com.twitter.algebird
+
+/**
+ * Last tracks the "most recent" item by the order in which items are
+ * seen.
+ */
+case class Last[@specialized(Int, Long, Float, Double) +T](get: T) {
+  def +[U >: T](r: Last[U]): Last[U] = r
+}
+
+object Last extends LastInstances {
+  def aggregator[T]: LastAggregator[T] = LastAggregator()
+}
+
+private[algebird] sealed abstract class LastInstances {
+  implicit def semigroup[T]: Semigroup[Last[T]] = Semigroup.from { (l, r) => r }
+}
+
+case class LastAggregator[T]() extends Aggregator[T, T, T] {
+  def prepare(v: T) = v
+  val semigroup: Semigroup[T] = Semigroup.from { (l: T, r: T) => r }
+  def present(v: T) = v
+}

algebird-core/src/main/scala/com/twitter/algebird/Max.scala

@@ -0,0 +1,111 @@
+/*
+Copyright 2016 Twitter, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+package com.twitter.algebird
+
+import scala.annotation.tailrec
+
+// To use the MaxSemigroup wrap your item in Max
+case class Max[@specialized(Int, Long, Float, Double) +T](get: T) {
+  def max[U >: T](r: Max[U])(implicit ord: Ordering[U]): Max[U] =
+    Max.ordering.max(this, r)
+  def +[U >: T](r: Max[U])(implicit ord: Ordering[U]): Max[U] = max(r)
+}
+
+object Max extends MaxInstances {
+  def aggregator[T](implicit ord: Ordering[T]): MaxAggregator[T] = MaxAggregator()(ord)
+}
+
+private[algebird] sealed abstract class MaxInstances {
+  implicit def equiv[T](implicit eq: Equiv[T]): Equiv[Max[T]] = Equiv.by(_.get)
+
+  implicit def semigroup[T](implicit ord: Ordering[T]): Semigroup[Max[T]] =
+    Semigroup.from[Max[T]] { (l, r) => if (ord.gteq(l.get, r.get)) l else r }
+
+  implicit def ordering[T](implicit ord: Ordering[T]): Ordering[Max[T]] =
+    Ordering.by(_.get)
+
+  // Zero should have the property that it <= all T
+  def monoid[T](zero: => T)(implicit ord: Ordering[T]): Monoid[Max[T]] =
+    Monoid.from(Max(zero)) { (l, r) => if (ord.gteq(l.get, r.get)) l else r }
+
+  implicit def intMonoid: Monoid[Max[Int]] = monoid(Int.MinValue)
+  implicit def longMonoid: Monoid[Max[Long]] = monoid(Long.MinValue)
+  implicit def doubleMonoid: Monoid[Max[Double]] = monoid(Double.MinValue)
+  implicit def floatMonoid: Monoid[Max[Float]] = monoid(Float.MinValue)
+
+  // These have a lower bound, but not an upperbound, so the Max forms a monoid:
+  implicit def stringMonoid: Monoid[Max[String]] = monoid("")
+
+  implicit def listMonoid[T: Ordering]: Monoid[Max[List[T]]] = monoid[List[T]](Nil)(
+    new Ordering[List[T]] {
+      @tailrec
+      final override def compare(left: List[T], right: List[T]): Int = {
+        (left, right) match {
+          case (Nil, Nil) => 0
+          case (Nil, _) => -1
+          case (_, Nil) => 1
+          case (lh :: lt, rh :: rt) =>
+            val c = Ordering[T].compare(lh, rh)
+            if (c == 0) compare(lt, rt) else c
+        }
+      }
+    })
+
+  // TODO: Replace with
+  // scala.collection.mutable.MutableMethods.iteratorCompare when we
+  // merge with cats.
+  def iteratorCompare[T](xs: Iterator[T], ys: Iterator[T])(implicit ord: Ordering[T]): Int = {
+    while (true) {
+      if (xs.hasNext) {
+        if (ys.hasNext) {
+          val x = xs.next
+          val y = ys.next
+          val cmp = ord.compare(x, y)
+          if (cmp != 0) return cmp
+        } else {
+          return 1
+        }
+      } else {
+        return if (ys.hasNext) -1 else 0
+      }
+    }
+    0
+  }
+
+  implicit def vectorMonoid[T: Ordering]: Monoid[Max[Vector[T]]] =
+    monoid[Vector[T]](Vector.empty[T])(
+      new Ordering[Vector[T]] {
+        def compare(l: Vector[T], r: Vector[T]): Int = {
+          if (l eq r) 0
+          else iteratorCompare(l.iterator, r.iterator)
+        }
+      })
+
+  implicit def streamMonoid[T: Ordering]: Monoid[Max[Stream[T]]] =
+    monoid[Stream[T]](Stream.empty[T])(
+      new Ordering[Stream[T]] {
+        def compare(l: Stream[T], r: Stream[T]): Int = {
+          if (l eq r) 0
+          else iteratorCompare(l.iterator, r.iterator)
+        }
+      })
+}
+
+case class MaxAggregator[T](implicit ord: Ordering[T]) extends Aggregator[T, T, T] {
+  def prepare(v: T) = v
+  val semigroup = Semigroup.from { (l: T, r: T) => ord.max(l, r) }
+  def present(v: T) = v
+}

algebird-core/src/main/scala/com/twitter/algebird/Min.scala

@@ -0,0 +1,52 @@
+/*
+Copyright 2016 Twitter, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+package com.twitter.algebird
+
+// To use the MinSemigroup wrap your item in a Min object
+case class Min[@specialized(Int, Long, Float, Double) +T](get: T) {
+  def min[U >: T](r: Min[U])(implicit ord: Ordering[U]): Min[U] =
+    Min.ordering.min(this, r)
+  def +[U >: T](r: Min[U])(implicit ord: Ordering[U]): Min[U] = min(r)
+}
+
+object Min extends MinInstances {
+  def aggregator[T](implicit ord: Ordering[T]): MinAggregator[T] = MinAggregator()(ord)
+}
+
+private[algebird] sealed abstract class MinInstances {
+  implicit def equiv[T](implicit eq: Equiv[T]): Equiv[Min[T]] = Equiv.by(_.get)
+
+  // Zero should have the property that it >= all T
+  def monoid[T](zero: => T)(implicit ord: Ordering[T]): Monoid[Min[T]] =
+    Monoid.from(Min(zero)) { (l, r) => if (ord.lteq(l.get, r.get)) l else r }
+
+  implicit def semigroup[T](implicit ord: Ordering[T]): Semigroup[Min[T]] =
+    Semigroup.from[Min[T]] { (l, r) => if (ord.lteq(l.get, r.get)) l else r }
+
+  implicit def ordering[T](implicit ord: Ordering[T]): Ordering[Min[T]] =
+    Ordering.by(_.get)
+
+  implicit def intMonoid: Monoid[Min[Int]] = monoid(Int.MaxValue)
+  implicit def longMonoid: Monoid[Min[Long]] = monoid(Long.MaxValue)
+  implicit def doubleMonoid: Monoid[Min[Double]] = monoid(Double.MaxValue)
+  implicit def floatMonoid: Monoid[Min[Float]] = monoid(Float.MaxValue)
+}
+
+case class MinAggregator[T](implicit ord: Ordering[T]) extends Aggregator[T, T, T] {
+  def prepare(v: T) = v
+  val semigroup = Semigroup.from { (l: T, r: T) => ord.min(l, r) }
+  def present(v: T) = v
+}

algebird-test/src/main/scala/com/twitter/algebird/BaseProperties.scala

@@ -36,6 +36,9 @@ object BaseProperties {
 
   def defaultEq[T](t0: T, t1: T) = t0 == t1
 
+  def approxEq(eps: Double)(f1: Double, f2: Double) =
+    (scala.math.abs(f1 - f2) / scala.math.abs(f2)) < eps
+
   trait HigherEq[M[_]] {
     def apply[T](m: M[T], n: M[T]): Boolean
   }