ScrollingArray Package

Overview

The org.scrollingArray package provides a set of Java classes for generating combinations from arrays or lists. The core functionality is provided by the ScrollingArray class, which generates index combinations, and is extended by CombinatorialArray and CombinatorialArrayList to produce combinations of elements from arrays and lists, respectively. This package is useful for applications requiring combinatorial iterations, such as data analysis, algorithm testing, or permutation-based computations.

Author: Joe McVerry
License: Apache License, Version 2.0
Version: 2025-06-20
Copyright: © 2025 Joe McVerry

Features

• Generate combinations of fixed or variable sizes from arrays (CombinatorialArray) or lists (CombinatorialArrayList).
• Support for combinations with or without repetition via the ScrollingArray class.
• Generic type support for flexible element types.
• Comprehensive JUnit 5 test suite to ensure reliability and correctness.
• Simple and intuitive API for iterating through combinations.

Package Structure

• Core Classes:
• ScrollingArray: Generates index combinations of a specified size from a given range, with optional repetition.
• CombinatorialArray<T>: Produces combinations of elements from an array, supporting fixed or variable combination sizes.
• CombinatorialArrayList<T>: Produces combinations of elements from a list, supporting fixed or variable combination sizes.
• Sample Application:
• Count3of4: Demonstrates usage of CombinatorialArray and CombinatorialArrayList with example inputs.
• Test Classes:
• TestScrollingArray: Tests ScrollingArray for index combinations.
• TestSimpleArrayTest: Tests CombinatorialArray for invalid sizes and single-element combinations.
• TestSimpleArrayListTest: Tests CombinatorialArrayList for invalid sizes and single-element combinations.
• TestSingleCountsOf3and4Arrays: Tests CombinatorialArray for fixed-size combinations.
• TestSingleCountsOf3and4ArrayLists: Tests CombinatorialArrayList for fixed-size combinations.
• TestMultipleCountsOf3and4Arrays: Tests CombinatorialArray for variable-size combinations.
• TestMultipleCountsOf3and4ArrayLists: Tests CombinatorialArrayList for variable-size combinations.

Installation

1. Clone or Download:

2. Clone the repository or download the source code containing the org.scrollingArray package.
   bash git clone <repository-url>

3. Dependencies:

4. Java 9 or higher (due to List.of usage in tests).
5. JUnit 5 (org.junit.jupiter:junit-jupiter:5.x.x) for running tests.

6. Add JUnit to your project using a build tool like Maven or Gradle:
   xml <!-- Maven --> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter</artifactId> <version>5.10.2</version> <scope>test</scope> </dependency>

7. Build:

8. Use a build tool (e.g., Maven, Gradle) or compile manually with javac.
9. Ensure the package is included in your classpath.

Usage

Example: Generating Combinations with CombinatorialArrayList

import org.scrollingArray.CombinatorialArrayList;
import java.util.ArrayList;
import java.util.List;

public class Example {
    public static void main(String[] args) {
        List<String> input = new ArrayList<>(List.of("One", "Two", "Three", "Four"));
        CombinatorialArrayList<String> combinator = new CombinatorialArrayList<>(input, 2);

        int count = 0;
        do {
            List<String> combination = combinator.getNewList();
            System.out.printf("Combination %d: %s%n", count++, combination);
        } while (combinator.scroll());
    }
}

Output:

Combination 0: [One, Two]
Combination 1: [One, Three]
Combination 2: [One, Four]
Combination 3: [Two, Three]
Combination 4: [Two, Four]
Combination 5: [Three, Four]

Example: Generating Variable-Size Combinations with CombinatorialArray

import org.scrollingArray.CombinatorialArray;

public class Example {
    public static void main(String[] args) {
        String[] input = {"A", "B", "C"};
        CombinatorialArray<String> combinator = new CombinatorialArray<>(input, 1, 3);

        int count = 0;
        do {
            String[] combination = combinator.getNewArray();
            System.out.printf("Combination %d: %s%n", count++, java.util.Arrays.toString(combination));
        } while (combinator.scroll());
    }
}

Output:

Combination 0: [A]
Combination 1: [B]
Combination 2: [C]
Combination 3: [A, B]
Combination 4: [A, C]
Combination 5: [B, C]
Combination 6: [A, B, C]

Running Tests

1. Ensure JUnit 5 is configured in your project.
2. Run the test classes using your IDE, Maven, or Gradle:
   bash mvn test
3. All tests should pass, verifying the correctness of the combination generation logic.

API Reference

ScrollingArray

• Constructor: ScrollingArray(int combinationSize, int totalSize, boolean repeatAllPositions)
• Methods:
• int[] getArray(): Returns the current combination of indices.
• boolean scroll(): Advances to the next combination, returning true if more combinations exist.

CombinatorialArray<T>

• Constructors:
• CombinatorialArray(T[] originalArray, int combinationSize)
• CombinatorialArray(T[] originalArray, int combinationSize, int maxCombinations)
• Methods:
• T[] getNewArray(): Returns the current combination as an array.
• boolean scroll(): Advances to the next combination, increasing size if needed.

CombinatorialArrayList<T>

• Constructors:
• CombinatorialArrayList(List<T> originalList, int combinationSize)
• CombinatorialArrayList(List<T> originalList, int combinationSize, int maxCombinations)
• Methods:
• List<T> getNewList(): Returns the current combination as a list.
• boolean scroll(): Advances to the next combination, increasing size if needed.

Contributing

Contributions are welcome! Please follow these steps:
1. Fork the repository.
2. Create a feature branch (git checkout -b feature/new-feature).
3. Commit your changes (git commit -m 'Add new feature').
4. Push to the branch (git push origin feature/new-feature).
5. Open a pull request.

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Contact

For questions or feedback, contact Joe McVerry at [usacoder @ gmail]