Class IntInterval

java.lang.Object

cloud.opencode.base.collections.IntInterval

All Implemented Interfaces:

Serializable, Iterable<Integer>

public final class IntInterval
extends Object
implements Iterable<Integer>, Serializable

IntInterval - Immutable, zero-allocation integer range with O(1) random access IntInterval - 零分配的不可变整数区间，支持 O(1) 随机访问

Represents a closed range of integers [from, to] with a given step, similar to Python's range() but with inclusive endpoints. No backing array is allocated; all values are computed on demand.

表示一个闭区间整数范围 [from, to]，具有给定步长， 类似于 Python 的 range() 但端点均包含在内。 不分配底层数组，所有值按需计算。

Features | 主要功能:

• Zero-allocation: no backing array - 零分配：无底层数组
• O(1) size, get, contains - O(1) 的 size、get、contains
• Inclusive endpoints (like Eclipse Collections) - 闭区间端点（类似 Eclipse Collections）
• Auto-detected direction for ascending/descending ranges - 自动检测升序/降序方向
• IntStream integration - IntStream 集成

Usage Examples | 使用示例:

// Ascending range - 升序区间
IntInterval range = IntInterval.fromTo(1, 5); // [1, 2, 3, 4, 5]

// Descending range (auto-detected) - 降序区间（自动检测）
IntInterval desc = IntInterval.fromTo(5, 1); // [5, 4, 3, 2, 1]

// Custom step - 自定义步长
IntInterval stepped = IntInterval.fromToBy(1, 10, 3); // [1, 4, 7, 10]

// For-each loop - for-each 循环
for (int i : IntInterval.oneTo(10)) {
    System.out.println(i);
}

// IntStream - IntStream
int sum = IntInterval.oneTo(100).stream().sum();

Performance | 性能特性:

• size: O(1) - size: O(1)
• get: O(1) - get: O(1)
• contains: O(1) - contains: O(1)
• toArray / toList: O(n) - toArray / toList: O(n)

Security | 安全性:

• Thread-safe: Yes (immutable) - 线程安全: 是（不可变）
• Overflow-safe: Uses long arithmetic internally - 溢出安全：内部使用 long 运算

Since:

JDK 25, opencode-base-collections V1.0.3

Author:

Leon Soo www.LeonSoo.com

See Also:

• OpenCode.cloud
• Serialized Form

Method Summary

Modifier and Type	Method	Description
IntInterval	by(int newStep)	Return a new interval with the same range but a different step.
boolean	contains(int value)	Check if this interval contains the given value.
boolean	equals(Object o)
void	forEach(IntConsumer action)	Perform the given action for each element (primitive, no boxing).
static IntInterval	fromTo(int from, int to)	Create an interval from from to to (inclusive) with auto-detected step.
static IntInterval	fromToBy(int from, int to, int step)	Create an interval from from to to (inclusive) with an explicit step.
int	get(int index)	Return the element at the given index (O(1)).
int	getFirst()	Return the first element of this interval.
int	getLast()	Return the last element of this interval.
int	hashCode()
boolean	isEmpty()	Check if this interval is empty.
Iterator<Integer>	iterator()	Return a PrimitiveIterator.OfInt over the elements.
static IntInterval	oneTo(int to)	Create an interval from 1 to to (inclusive).
IntInterval	reversed()	Return a reversed interval.
int	size()	Return the number of elements in this interval.
IntStream	stream()	Return an IntStream over the elements of this interval.
int[]	toArray()	Convert this interval to an int array.
List<Integer>	toList()	Convert this interval to a List of Integer.
String	toString()	Return a string representation such as "IntInterval[1..10 step 1]".
static IntInterval	zeroTo(int to)	Create an interval from 0 to to (inclusive).

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface Iterable

forEach, spliterator

Method Details

fromTo

public static IntInterval fromTo(int from,
 int to)

Create an interval from from to to (inclusive) with auto-detected step. 创建从 from 到 to（闭区间）的区间，自动检测步长。

Step is 1 if from <= to, otherwise -1.

如果 from <= to 则步长为 1，否则为 -1。

Parameters:

from - the start value (inclusive) | 起始值（包含）

to - the end value (inclusive) | 结束值（包含）

Returns:

the interval | 区间

fromToBy

public static IntInterval fromToBy(int from,
 int to,
 int step)

Create an interval from from to to (inclusive) with an explicit step. 创建从 from 到 to（闭区间）的区间，使用显式步长。

Parameters:

from - the start value (inclusive) | 起始值（包含）

to - the end value (inclusive) | 结束值（包含）

step - the step (must not be zero, must match direction) | 步长（不能为零，必须与方向匹配）

Returns:

the interval | 区间

Throws:

IllegalArgumentException - if step is zero or conflicts with direction | 如果步长为零或与方向冲突

zeroTo

public static IntInterval zeroTo(int to)

Create an interval from 0 to to (inclusive). 创建从 0 到 to（闭区间）的区间。

Parameters:

to - the end value (inclusive) | 结束值（包含）

Returns:

the interval [0..to] | 区间 [0..to]

oneTo

public static IntInterval oneTo(int to)

Create an interval from 1 to to (inclusive). 创建从 1 到 to（闭区间）的区间。

Parameters:

to - the end value (inclusive) | 结束值（包含）

Returns:

the interval [1..to] | 区间 [1..to]

contains

public boolean contains(int value)

Check if this interval contains the given value. 检查此区间是否包含给定值。

Parameters:

value - the value to check | 要检查的值

Returns:

true if the value is in this interval | 如果值在此区间中则返回 true

size

public int size()

Return the number of elements in this interval. 返回此区间中的元素数量。

Returns:

the size | 大小

get

public int get(int index)

Return the element at the given index (O(1)). 返回给定索引处的元素 (O(1))。

Parameters:

index - the zero-based index | 从零开始的索引

Returns:

the element at the index | 索引处的元素

Throws:

IndexOutOfBoundsException - if index is out of bounds | 如果索引越界

getFirst

public int getFirst()

Return the first element of this interval. 返回此区间的第一个元素。

Returns:

the first element | 第一个元素

Throws:

NoSuchElementException - if the interval is empty | 如果区间为空

getLast

public int getLast()

Return the last element of this interval. 返回此区间的最后一个元素。

The last element is the largest value v such that v = from + k * step and v does not exceed to.

最后一个元素是满足 v = from + k * step 且 v 不超过 to 的最大值。

Returns:

the last element | 最后一个元素

Throws:

NoSuchElementException - if the interval is empty | 如果区间为空

isEmpty

public boolean isEmpty()

Check if this interval is empty. 检查此区间是否为空。

Returns:

true if the interval has no elements | 如果区间没有元素则返回 true

by

public IntInterval by(int newStep)

Return a new interval with the same range but a different step. 返回具有相同范围但不同步长的新区间。

Parameters:

newStep - the new step | 新步长

Returns:

a new interval with the new step | 使用新步长的新区间

Throws:

IllegalArgumentException - if the new step is zero or conflicts with direction | 如果新步长为零或与方向冲突

reversed

public IntInterval reversed()

Return a reversed interval. 返回反转的区间。

The reversed interval starts at getLast() and ends at from, with the negated step.

反转区间从 getLast() 开始到 from 结束，步长取反。

Returns:

the reversed interval | 反转的区间

toArray

public int[] toArray()

Convert this interval to an int array. 将此区间转换为 int 数组。

Returns:

an array containing all elements | 包含所有元素的数组

toList

public List<Integer> toList()

Convert this interval to a List of Integer. 将此区间转换为 Integer 的 List。

Returns:

an unmodifiable list containing all elements | 包含所有元素的不可修改列表

stream

public IntStream stream()

Return an IntStream over the elements of this interval. 返回此区间元素上的 IntStream。

Returns:

an IntStream | IntStream

iterator

public Iterator<Integer> iterator()

Return a PrimitiveIterator.OfInt over the elements. 返回元素上的 PrimitiveIterator.OfInt。

Specified by:

iterator in interface Iterable<Integer>

Returns:

a primitive int iterator | 原始 int 迭代器

forEach

public void forEach(IntConsumer action)

Perform the given action for each element (primitive, no boxing). 对每个元素执行给定操作（原始类型，无装箱）。

Parameters:

action - the action to perform | 要执行的操作

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Return a string representation such as "IntInterval[1..10 step 1]". 返回字符串表示，如 "IntInterval[1..10 step 1]"。

Overrides:

toString in class Object

Returns:

string representation | 字符串表示