org.functionaljava:functionaljava

= Functional Java

image:https://travis-ci.org/functionaljava/functionaljava.svg?branch=master["Build Status", link="https://app.travis-ci.com/github/functionaljava/functionaljava"] image:https://codecov.io/gh/functionaljava/functionaljava/branch/master/graph/badge.svg["Code Coverage", link="https://codecov.io/gh/functionaljava/functionaljava"] image:https://badges.gitter.im/functionaljava/functionaljava.svg[link="https://gitter.im/functionaljava/functionaljava?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"]

image::http://www.functionaljava.org/img/logo-600x144.png[]

Functional Java is an open source library facilitating functional programming in Java. The library implements numerous basic and advanced programming abstractions that assist composition oriented development. Functional Java also serves as a platform for learning functional programming concepts by introducing these concepts using a familiar language.

The library is intended for use in production applications and is thoroughly tested using the technique of automated specification-based testing with ScalaCheck and Functional Java's quickcheck module. Functional Java is compiled with Java 8 targeting Java 7 bytecode. The use of lambdas within the project are back ported with the Retro Lambda library, supporting Java versions 6 to 8.

Functional Java provides abstractions for the following types:

• Basic Data Structures - total and partial functions, products, unit, option, unbiased and right biased unions (either and validation), void.
• Immutable Collections - array, list, vector, stream, set, map, priority queue, finger tree, heterogenous list, difference list.
• Other Abstractions - monoid, semigroup, natural, random number generator, reader, writer, state, input/output, parser, zipper, specification based testing (quickcheck), actors, optics (lens, prism, fold, traversal and others), concurrency and type conversion.

== URLs

Important URLs for the project are:

• Website, http://www.functionaljava.org
• Website repository, http://github.com/functionaljava/functionaljava.github.io
• Travis continuous integration build, https://app.travis-ci.com/github/functionaljava/functionaljava
• Sonatype repository, https://oss.sonatype.org/content/groups/public/org/functionaljava/
• Maven Central repository, https://mvnrepository.com/artifact/org.functionaljava/functionaljava

== Downloading

The recommended way to download and use the project is through your build tool.

The Functional Java artifact is published to Maven Central using the group org.functionaljava with three published artifacts:

• the core library (functionaljava or functionaljava_1.8 if you use Java 8+)
• Java 8 specific support (functionaljava-java8)
• property based testing (functionaljava-quickcheck or functionaljava-quickcheck_1.8 if you use Java 8+)

The latest stable version is 4.9. This can be added to your Gradle project by adding the dependencies:

compile "org.functionaljava:functionaljava:4.9" compile "org.functionaljava:functionaljava-java8:4.9" compile "org.functionaljava:functionaljava-quickcheck:4.9" compile "org.functionaljava:functionaljava-java-core:4.9"

and in Maven:

org.functionaljava functionaljava 4.9 org.functionaljava functionaljava-java8 4.9 org.functionaljava functionaljava-quickcheck 4.9 org.functionaljava functionaljava-java-core 4.9 ----

== Building

FunctionalJava uses the Retro Lambda project to backport Java 8 lambdas to Java 6 bytecode. This requires access to both JDK 6 and 8. The build system requires the environment variables JAVA6_HOME and JAVA8_HOME to refer to the appropriate directories.

Building is done using Gradle 6.8.3. In the root directory run:

./gradlew

This requires access to Java and will download the Gradle build tool and necessary dependencies and build FunctionalJava.

== Features

A more complete description of the features mentioned above are:

• Basic Data Structures ** Functions with arity 1 to 8 (fj.F). ** Functions with arity 0 to 8 that can produce exceptions (fj.Try). ** Functions with arity 0 to 8 that have a void return (fj.Effect). ** Functions with arity 0 to 8 that have a void return and can throw an exception (fj.TryEffect). ** Products with arity 1 to 8 (fj.P). ** Unit type (fj.Unit). ** Optional value - type-safe null (fj.data.Option). ** Disjoint union data type - compositional exception handling (fj.data.Either). ** Validation - right biased compositional exception handling (fj.data.Validation).
• Immutable Collections ** Array wrapper (fj.data.Array). ** Immutable, in-memory singly linked list (fj.data.List). ** Immutable lazy singly linked list (fj.data.Stream). ** A package (fj.data.fingertrees) providing 2-3 finger trees for a functional representation of persistent sequences, supporting access to the ends in amortized O(1) time. ** Type-safe heterogeneous list (fj.data.hlist) for lists of elements of differing types without sacrificing type-safety. ** Immutable set implementation using a red/black tree (fj.data.Set). ** Immutable multi-way tree - aka rose tree (fj.data.Tree). ** Immutable tree-map using a red/black tree implementation (fj.data.TreeMap). ** Immutable priority queue using finger trees (fj.data.PriorityQueue). ** Difference lists, a highly performant list.
• Other Abstractions ** Monoid (fj.Monoid). ** Semigroup (fj.Semigroup). ** Natural number data type (fj.data.Natural). ** Random number generator using a linear congruential generator (fj.LcgRng). ** Reader, Writer and State monads (fj.data.Reader,fj.data.Writer, fj.data.State). ** Input/Output monad for abstracting IO (fj.IO). ** Monadic parser combinators for writing parsers by combining smaller parsers using composition. ** Conversion of data types to/from standard Java types. ** Conversion between FunctionalJava and Java 8 specific types. ** Configurable equality and hash-code for HashMap and HashSet. ** Zipper implementations for streams and trees. ** Automated specification-based testing framework (fj.test). ** Fully operational Actors for parallel computations (fj.control.parallel) and layered abstractions such as parallel-map, map-reduce, parallel-zip. ** Optics for updating immutable data including lens, prism, iso, optional, traversal, getter, fold and setter. Inspired by the Scala Monocle library (https://github.com/julien-truffaut/Monocle) and the Haskell lens library (https://github.com/ekmett/lens). ** Void, a logically uninhabited type.

== License

link:etc/LICENCE[The Functional Java license] uses the BSD 3 license (3-clause license) available at https://en.wikipedia.org/wiki/BSD_licenses[].

== Release Notes

For release notes for each version, see the directory etc/release-notes.