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:

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:

# 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.

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