65 lines
2 KiB
Markdown
Vendored
65 lines
2 KiB
Markdown
Vendored
# mruby-compar-ext
|
|
|
|
Comparable module extension.
|
|
|
|
This mrbgem adds the `clamp` method to the `Comparable` module.
|
|
|
|
## `Comparable#clamp`
|
|
|
|
The `clamp` method restricts a value to a given range.
|
|
|
|
**Syntax:**
|
|
|
|
```ruby
|
|
obj.clamp(min, max) -> obj
|
|
obj.clamp(range) -> obj
|
|
```
|
|
|
|
**Description:**
|
|
|
|
- In the `(min, max)` form, it returns:
|
|
- `min` if `obj <=> min` is less than zero.
|
|
- `max` if `obj <=> max` is greater than zero.
|
|
- `obj` otherwise.
|
|
- In the `(range)` form, it returns:
|
|
- `range.begin` if `obj <=> range.begin` is less than zero.
|
|
- `range.end` if `obj <=> range.end` is greater than zero (and `range.end` is not `nil` and the range is inclusive).
|
|
- `obj` otherwise.
|
|
- If `range.begin` is `nil`, it is considered smaller than `obj`.
|
|
- If `range.end` is `nil`, it is considered greater than `obj`.
|
|
|
|
**Examples:**
|
|
|
|
```ruby
|
|
# Using min and max arguments
|
|
12.clamp(0, 100) #=> 12
|
|
523.clamp(0, 100) #=> 100
|
|
-3.123.clamp(0, 100) #=> 0
|
|
|
|
'd'.clamp('a', 'f') #=> 'd'
|
|
'z'.clamp('a', 'f') #=> 'f'
|
|
|
|
# Using a Range argument
|
|
12.clamp(0..100) #=> 12
|
|
523.clamp(0..100) #=> 100
|
|
-3.123.clamp(0..100) #=> 0
|
|
|
|
'd'.clamp('a'..'f') #=> 'd'
|
|
'z'.clamp('a'..'f') #=> 'f'
|
|
|
|
# Using ranges with nil begin or end
|
|
-20.clamp(0..) #=> 0
|
|
523.clamp(..100) #=> 100
|
|
```
|
|
|
|
**Error Handling:**
|
|
|
|
- Raises an `ArgumentError` if an exclusive range (e.g., `0...100`) is provided as the `range` argument when `range.end` is not `nil`.
|
|
- Raises an `ArgumentError` if `min` and `max` arguments cannot be compared (e.g., a `String` and an `Integer`).
|
|
- Raises an `ArgumentError` if the `min` argument is greater than the `max` argument.
|
|
|
|
```ruby
|
|
100.clamp(0...100) # ArgumentError: cannot clamp with an exclusive range
|
|
10.clamp("a", "z") # ArgumentError: comparison of String with String failed (depending on mruby version, may also be other errors if types are incompatible)
|
|
100.clamp(10, 0) # ArgumentError: min argument must be smaller than max argument
|
|
```
|