RangeInt: Thư viện Python giúp quản lý số nguyên có giới hạn thông minh hơn

Bạn đã bao giờ viết những dòng code như thế này chưa?

hp -= 10
if hp < 0:
    hp = 0

Hoặc như thế này?

volume += 5
if volume > 100:
    volume = 100

Chúng ta đều đã từng làm vậy. Đó là những đoạn code mẫu (boilerplate) làm rối logic của bạn mỗi khi cần một con số phải nằm trong một giới hạn nhất định. RangeInt sẽ giải quyết vấn đề này.

Nếu bạn muốn xem ngay kho lưu trữ, hãy truy cập GitHub.

RangeInt là gì?

RangeInt là một kiểu dữ liệu số tự động "kẹp" (clamp) giá trị của nó trong một khoảng [min, max]. Mọi phép tính số học, mọi phép gán hay thay đổi giá trị — tất cả đều được giới hạn một cách âm thầm. Không còn các câu lệnh if, không còn kiểm tra thủ công.

Bạn có thể cài đặt thư viện này qua pip:

pip install rangeint

Cơ bản về cách sử dụng

from rangeint import RangeInt

hp = RangeInt(100, 0, 100)

hp -= 999
print(hp)  # 0 — không bao giờ thấp hơn min
hp += 9999
print(hp)  # 100 — không bao giờ cao hơn max

Nó hoạt động minh bạch như một con số bình thường:

print(int(hp))      # 100
print(float(hp))    # 100.0
print(hp == 100)    # True
print(hp > 50)      # True

Ví dụ thực tế

Phát triển Game — chỉ số người chơi

hp      = RangeInt(100, 0, 100)
stamina = RangeInt(100, 0, 100)
ammo    = RangeInt(30,  0, 30)

hp      -= 45   # 55
stamina -= 200  # 0  — đã được kẹp, không bị âm
ammo    -= 999  # 0  — đã được kẹp, không bị âm

Giao diện người dùng (UI) — thanh âm lượng

volume = RangeInt(50, 0, 100)

volume += 80   # 100 — sẽ không vượt quá max
volume -= 200  # 0   — sẽ không bị âm

Hoạt ảnh — theo dõi tiến trình

progress = RangeInt(0, 0, 100)
progress += 10   # 10
progress += 10   # 20

Nội suy tuyến tính (Lerp) và Định vị tương đối

RangeInt hỗ trợ tuyệt vời việc làm việc với các giá trị dưới dạng vị trí tương đối — rất hữu ích cho hoạt ảnh, thanh trượt và nội suy.

relative() — tôi đang ở đâu trong khoảng?

hp = RangeInt(75, 0, 100)
hp.relative()  # 0.75 — tôi đã đi được 75% chặng đường

lerp_to() — nhảy đến một vị trí

progress = RangeInt(0, 0, 200)
progress.lerp_to(0.5)   # 100.0 — nhảy đến điểm giữa
progress.lerp_to(1.0)   # 200.0 — nhảy đến max

nudge_percentage() — dịch chuyển một tỷ lệ

volume = RangeInt(50, 0, 100)
volume.nudge_percentage(0.1)   # +10% của khoảng → 60
volume.nudge_percentage(-0.2)  # -20% của khoảng → 40

Callback ngưỡng (Threshold Callbacks)

Đây là nơi RangeInt trở nên thú vị. Bạn có thể đăng ký các hàm sẽ tự động kích hoạt khi giá trị vượt qua một ngưỡng nhất định.

hp = RangeInt(100, 0, 100)

hp.on_percentage(0.25, lambda: print("Máu nguy cấp!"), directional="down", through=True)
hp.on_percentage(0.0,  lambda: print("Bạn đã chết!"),        directional="down", through=False)

hp -= 80   # in ra "Máu nguy cấp!"
hp -= 20   # in ra "Bạn đã chết!"

Tham số directional kiểm soát khi nào callback được kích hoạt:

• "down" — chỉ kích hoạt khi đi xuống qua ngưỡng
• "up" — chỉ kích hoạt khi đi lên qua ngưỡng
• "both" — kích hoạt theo cả hai hướng

Tham số through quyết định việc kích hoạt callback khi giá trị rơi đúng vào ngưỡng hay khi đi ngang qua nó.

Các phương thức tiện ích khác

edge_check() — có đang ở biên không?

hp = RangeInt(0, 0, 100)
hp.edge_check("min")  # True
hp.edge_check("max")  # False

is_between() — kiểm tra khoảng tương đối

hp = RangeInt(50, 0, 100)
hp.is_between(0.25, 0.75)  # True — ở nửa giữa
hp.is_between(0.75, 1.0)   # False

set_range() — cập nhật giới hạn ngay lập tức

hp = RangeInt(80, 0, 100)
hp.set_range(0, 50)   # giá trị được kẹp lại thành 50

Mọi toán tử đều hoạt động

RangeInt hỗ trợ mọi toán tử số học và so sánh mà bạn mong đợi:

hp = RangeInt(50, 0, 100)

hp + 30    # RangeInt(80)
hp - 999   # RangeInt(0)   — đã kẹp
hp * 2     # RangeInt(100) — đã kẹp
hp / 2     # RangeInt(25)

hp += 10
hp -= 5
hp *= 2
hp /= 2

10 + hp    # hoạt động
3  * hp    # hoạt động
-hp        # hoạt động
abs(hp)    # hoạt động

Cài đặt

pip install rangeint

from rangeint import RangeInt

hp = RangeInt(100, 0, 100)

Mã nguồn và các vấn đề được báo cáo tại GitHub. Các Pull Request và phản hồi đều được hoan nghênh — đặc biệt nếu bạn tìm thấy một trường hợp sử dụng mà tôi chưa nghĩ đến!

Tôi đã xây dựng thư viện này vì tôi liên tục viết những đoạn code kẹp giá trị lặp lại trong mọi dự án. Hy vọng nó giúp bạn tiết kiệm được những rắc rối tương tự.