- "body": "λ\r\n======\r\n[](https://travis-ci.org/palatable/lambda)\r\n[](http://search.maven.org/#search%7Cga%7C1%7Ccom.jnape.palatable.lambda)\r\n\r\nFunctional patterns for Java 8\r\n\r\nBackground\r\n----------\r\n\r\nLambda was born out of a desire to use some of the same canonical functions (e.g. `unfoldr`, `takeWhile`, `zipWith`) and functional patterns (e.g. `Functor` and friends) that are idiomatic in other languages and make them available for Java.\r\n\r\nSome things a user of lambda most likely values:\r\n\r\n- Lazy evaluation\r\n- Immutablility by design\r\n- Composition\r\n- Higher-level abstractions\r\n- Parametric polymorphism\r\n\r\nGenerally, everything that lambda produces is lazily-evaluated (except for terminal operations like `reduce`), immutable (except for `Iterator`s, since it's effectively impossible), composable (even between different arities, where possible), foundational (maximally contravariant), and parametrically type-checked (even where this adds unnecessary constraints due to a lack of higher-kinded types).\r\n\r\nAlthough the library is currently (very) small, these values should always be the driving forces behind future growth.\r\n\r\nInstallation\r\n------------\r\n\r\nAdd the following dependency to your:\r\n \r\n`pom.xml` ([Maven](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html)):\r\n \r\n```xml\r\n <dependency>\r\n <groupId>com.jnape.palatable</groupId>\r\n <artifactId>lambda</artifactId>\r\n <version>1.2</version>\r\n </dependency>\r\n```\r\n \r\n`build.gradle` ([Gradle](https://docs.gradle.org/current/userguide/dependency_management.html)):\r\n \r\n```gradle\r\n compile group: 'com.jnape.palatable', name: 'lambda', version: '1.2'\r\n```\r\n \r\n\r\nExamples\r\n--------\r\n\r\nFirst, the obligatory `map`/`filter`/`reduce` example:\r\n```Java\r\n Integer sumOfEvenIncrements =\r\n reduceLeft((x, y) -> x + y,\r\n filter(x -> x % 2 == 0,\r\n map(x -> x + 1, asList(1, 2, 3, 4, 5))));\r\n //-> 12\r\n```\r\n\r\nEvery function in lambda is [curried](https://www.wikiwand.com/en/Currying), so we could have also done this:\r\n```Java\r\n Fn1<Iterable<Integer>, Integer> sumOfEvenIncrementsFn =\r\n map((Integer x) -> x + 1)\r\n .then(filter(x -> x % 2 == 0))\r\n .then(reduceLeft((x, y) -> x + y));\r\n \r\n Integer sumOfEvenIncrements = sumOfEvenIncrementsFn.apply(asList(1, 2, 3, 4, 5));\r\n //-> 12\r\n```\r\n\r\nHow about the positive squares below 100:\r\n\r\n```Java\r\n Iterable<Integer> positiveSquaresBelow100 =\r\n takeWhile(x -> x < 100, map(x -> x * x, iterate(x -> x + 1, 1)));\r\n //-> [1, 4, 9, 16, 25, 36, 49, 64, 81]\r\n```\r\n\r\nWe could have also used `unfoldr`:\r\n\r\n```Java\r\n Iterable<Integer> positiveSquaresBelow100 = unfoldr(x -> {\r\n int square = x * x;\r\n return square < 100 ? Optional.of(tuple(square, x + 1)) : Optional.empty();\r\n }, 1);\r\n //-> [1, 4, 9, 16, 25, 36, 49, 64, 81]\r\n```\r\n\r\nWhat if we want the cross product of a domain and codomain:\r\n\r\n```Java\r\n Iterable<Tuple2<Integer, String>> crossProduct =\r\n take(10, cartesianProduct(asList(1, 2, 3), asList(\"a\", \"b\", \"c\")));\r\n //-> (1,\"a\"), (1,\"b\"), (1,\"c\"), (2,\"a\"), (2,\"b\"), (2,\"c\"), (3,\"a\"), (3,\"b\"), (3,\"c\")\r\n```\r\n\r\nLet's compose two functions:\r\n\r\n```Java\r\n Fn1<Integer, Integer> add = x -> x + 1;\r\n Fn1<Integer, Integer> subtract = x -> x -1;\r\n\r\n Fn1<Integer, Integer> noOp = add.then(subtract);\r\n // same as\r\n Fn1<Integer, Integer> alsoNoOp = subtract.fmap(add);\r\n```\r\n\r\nAnd partially apply some:\r\n\r\n```Java\r\n Fn2<Integer, Integer, Integer> add = (x, y) -> x + y;\r\n\r\n Fn1<Integer, Integer> add1 = add.apply(1);\r\n add1.apply(2);\r\n //-> 3\r\n```\r\n\r\nAnd have fun with 3s:\r\n\r\n```Java\r\n Iterable<Iterable<Integer>> multiplesOf3InGroupsOf3 =\r\n take(10, inGroupsOf(3, unfoldr(x -> Optional.of(tuple(x * 3, x + 1)), 1)));\r\n //-> [[3, 6, 9], [12, 15, 18], [21, 24, 27]]\r\n```\r\n\r\nCheck out [the tests](https://github.com/palatable/lambda/tree/master/src/test/java/com/jnape/palatable/lambda/functions/builtin) or [javadoc](https://palatable.github.io/lambda/javadoc) for more examples.\r\n\r\nADTs\r\n----\r\n\r\nIn addition to the functions above, lambda also supports a few first-class [algebraic data types](https://www.wikiwand.com/en/Algebraic_data_type).\r\n\r\n### Heterogeneous Lists (HLists)\r\n\r\nHLists are type-safe heterogeneous lists, meaning they can store elements of different types in the same list while facilitating certain type-safe interactions.\r\n\r\nThe following illustrates how the linear expansion of the recursive type signature for `HList` prevents ill-typed expressions:\r\n\r\n```Java\r\n HCons<Integer, HCons<String, HNil>> hList = HList.cons(1, HList.cons(\"foo\", HList.nil()));\r\n\r\n System.out.println(hList.head()); // prints 1\r\n System.out.println(hList.tail().head()); // prints \"foo\"\r\n\r\n HNil nil = hList.tail().tail();\r\n //nil.head() won't type-check\r\n```\r\n\r\n#### Tuples\r\n\r\nOne of the primary downsides to using `HList`s in Java is how quickly the type signature grows.\r\n\r\nTo address this, tuples in lambda are specializations of `HList`s up to 5 elements deep, with added support for index-based accessor methods.\r\n\r\n```Java\r\n HNil nil = HList.nil();\r\n SingletonHList<Integer> singleton = nil.cons(5);\r\n Tuple2<Integer, Integer> tuple2 = singleton.cons(4);\r\n Tuple3<Integer, Integer, Integer> tuple3 = tuple2.cons(3);\r\n Tuple4<Integer, Integer, Integer, Integer> tuple4 = tuple3.cons(2);\r\n Tuple5<Integer, Integer, Integer, Integer, Integer> tuple5 = tuple4.cons(1);\r\n\r\n System.out.println(tuple2._1()); // prints 4\r\n System.out.println(tuple5._5()); // prints 5\r\n```\r\n\r\nAdditionally, `HList` provides convenience static factory methods for directly constructing lists of up to 5 elements:\r\n\r\n```Java\r\n SingletonHList<Integer> singleton = HList.singletonHList(1);\r\n Tuple2<Integer, Integer> tuple2 = HList.tuple(1, 2);\r\n Tuple3<Integer, Integer, Integer> tuple3 = HList.tuple(1, 2, 3);\r\n Tuple4<Integer, Integer, Integer, Integer> tuple4 = HList.tuple(1, 2, 3, 4);\r\n Tuple5<Integer, Integer, Integer, Integer, Integer> tuple5 = HList.tuple(1, 2, 3, 4, 5);\r\n```\r\n\r\nFinally, all `Tuple*` classes are instances of both `Functor` and `Bifunctor`:\r\n\r\n```Java\r\n Tuple2<Integer, String> mappedTuple2 = tuple(1, 2).biMap(x -> x + 1, Object::toString);\r\n\r\n System.out.println(mappedTuple2._1()); // prints 2\r\n System.out.println(mappedTuple2._2()); // prints \"2\"\r\n\r\n Tuple3<String, Boolean, Integer> mappedTuple3 = tuple(\"foo\", true, 1).biMap(x -> !x, x -> x + 1);\r\n\r\n System.out.println(mappedTuple3._1()); // prints \"foo\"\r\n System.out.println(mappedTuple3._2()); // prints false\r\n System.out.println(mappedTuple3._3()); // prints 2\r\n```\r\n\r\n### Heterogeneous Maps\r\n\r\nHMaps are type-safe heterogeneous maps, meaning they can store mappings to different value types in the same map; however, whereas HLists encode value types in their type signatures, HMaps rely on the keys to encode the value type that they point to. \r\n\r\n```Java\r\n TypeSafeKey<String> stringKey = TypeSafeKey.typeSafeKey();\r\n TypeSafeKey<Integer> intKey = TypeSafeKey.typeSafeKey();\r\n HMap hmap = HMap.hMap(stringKey, \"string value\",\r\n intKey, 1);\r\n\r\n Optional<String> stringValue = hmap.get(stringKey); // Optional[\"string value\"]\r\n Optional<Integer> intValue = hmap.get(intKey); // Optional[1]\r\n Optional<Integer> anotherIntValue = hmap.get(anotherIntKey); // Optional.empty\r\n``` \r\n\r\n### Either\r\n\r\nBinary tagged unions are represented as `Either<L, R>`s, which resolve to one of two possible values: a `Left` value wrapping an `L`, or a `Right` value wrapping an `R` (typically an exceptional value or a successful value, respectively).\r\n\r\nRather than supporting explicit value unwrapping, `Either` supports many useful comprehensions to help facilitate type-safe interactions. For example, `Either#match` is used to resolve an `Either<L,R>` to a different type. \r\n\r\n```Java\r\n Either<String, Integer> right = Either.right(1);\r\n Either<String, Integer> left = Either.left(\"Head fell off\");\r\n\r\n Boolean successful = right.match(l -> false, r -> true);\r\n //-> true\r\n \r\n List<Integer> values = left.match(l -> Collections.emptyList(), Collections::singletonList);\r\n //-> [] \r\n```\r\n\r\nCheck out the tests for [more examples](https://github.com/palatable/lambda/blob/master/src/test/java/com/jnape/palatable/lambda/adt/EitherTest.java) of ways to interact with `Either`.\r\n\r\nLicense\r\n-------\r\n\r\n_lambda_ is part of [palatable](http://www.github.com/palatable), which is distributed under [The MIT License](http://choosealicense.com/licenses/mit/).\r\n",
0 commit comments