# Exercise: Self-Documenting Code
#
# Well-named words with clear stack effects document themselves.
#
# The secret to elegant stack code: when manipulation gets complex,
# CREATE HELPER WORDS. Small words are the documentation.
#
# BAD - complex stack juggling:
#   : clamp ( value min max -- clamped )
#       rot 2dup < [ nip 2dup > [ drop ] [ nip ] if ] [ drop nip ] if
#   ;
#
# GOOD - factored into meaningful pieces:
#   : min ( a b -- smaller ) ... ;
#   : max ( a b -- larger )  ... ;
#   : clamp ( value min max -- clamped )
#       # Now clamp becomes beautiful!
#   ;
#
# Your task: Implement `clamp` that restricts a value to a range.
# clamp ( value min max -- clamped )
#   - If value < min, return min
#   - If value > max, return max
#   - Otherwise, return value
#
# HINT: Create min and max helper words first. Then clamp nearly
# writes itself with just a few stack operations.
# When done, delete the marker line below.

# I AM NOT DONE

: min ( Int Int -- Int )
    # Your code here
    drop
;

: max ( Int Int -- Int )
    # Your code here
    drop
;

: clamp ( Int Int Int -- Int )
    # value min max
    # With good helpers, this becomes elegant!
    # Your code here
    drop drop drop 0
;

: test-documentation ( -- )
    15 0 10 clamp
    # Do not edit below this line
    10 test.assert-eq   # 15 clamped to 0-10 is 10

    5 0 10 clamp
    5 test.assert-eq    # 5 is already in range

    -3 0 10 clamp
    0 test.assert-eq    # -3 clamped to 0-10 is 0
;
