Java Range Fun(ctions)

A lightweight Java implementation of Python's range function, but with better naming.

Usage

You can find source, javadoc, and binary jars at Maven Central, under the groupId "xyz.jmburns", and the artifactId "rangefun". The latest version is 3.0.0. Using that, you can add the dependency to you project, just like any other.

For example, with Gradle:

repositories {
   mavenCentral()
}

dependencies {
   compile 'xyz.jmburns:rangefun:3.0.0'
}

Also, feel free to copy the source code and include it in your own project, under the terms of the License.

Description

This library provides a lightweight, iterable Progression class, representing a series of integers. The class's main purpose is in for-each loops, but can also be used to build an array of integers, or check if an integer is within a certain range, among other things.

All methods of the Progression class (and its Iterator) are lazily-evaluated, so all Progression instances -- large and small -- are guaranteed to have the same (small) memory footprint, and a similar performance impact.

Also, the class has well-behaved hashCode, equals, compareTo implementations, so instances can be safely stored in Collection and Map instances.

Examples

The best demonstration of the library is in the tests. However, for the sake of "readme-completeness", I've compiled some small examples of what's possible.

Progression Creation

Note: All creation of xyz.jmburns.rangefun.Progression instances is done via static factory methods in the xyz.jmburns.rangefun.Progressions "API" class. Those static methods are intended to be statically imported for enhanced readability.

Basic range of x to y, inclusive:

range(x, y)

Generates: x, x + 1, x + 2, ..., y

Progression of x to no further than y, with a custom step of z:

progression(x, y, z)

Generates: x, x + z, x + 2*z, ...

Range of all the indices of an array:

indices(array)

Generates: 0, 1, 2, ..., array.length - 1

Range of all the indices of an array, backwards:

indices(array).reverse()

Generates: array.length - 1, array.length - 2, ..., 0

Progression of x to y with a custom step of z, backwards:

progression(x, y, z).reverse()

Or, simply:

progression(y, x, z) //y can be higher than x, and z does not have to be negative

Generates: y, y - z, y - 2*z, ...

A simple count from 0 to y, exclusive:

count(y)

Generates: 0, 1, 2, ..., y - 1

Progression Usage

Checking if a integer is within a range:

range(1, 5).contains(3)

Will evaluate to true.

Generating an array of integers:

progression(1, 25, 5).toArray()

Will evaluate to an array of 1, 6, 11, 16, 21.

Finding the length of a progression:

progression(1, 25, 5).length()

Will evaluate to 5.

Finding the integer in a progression at a specific index, counting from zero:

progression(1, 25, 5).get(2)

Will evaluate to 11.

And finally, a practical example. Copying over an array.

for (int i : indices(source)) {
   destination[i] = source[i];
}

Beautiful, no?

Features

• Lazy evaluation
• Well-behaved hashCode, equals, compareTo implementations, for storage in maps and collections
• Ability to easily iterate backwards
• Convenience method to generate ranges for arrays
• Ability to generate a range of long values (Possibly coming soon)
• Ability to generate a range of double values (Possibly coming soon)

Feedback

Suggestions, bug reports, and pull requests are all welcome and appreciated. You are also welcome to send me an email at dev (AT) rangefun.xyz if you feel the need to do so.

Licensing

Copyright 2017 Jacques Burns

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.