Number Methods GitHub issue

• Overview
  • • Numeric literals
• • Arithmetic
• • Comparison
• • Testing
• Rounding
  • • Midpoint rule
  • • Examples
• • Bitwise
• • Math
• • Conversion
• • Iteration
• • Open Questions

Overview GitHub issue

{"vibecode": {
    "section": "overview",
    "type": "number",
    "unified": true,
    "notes": ["single_class_for_integers_and_floats",
        "integer_only_methods_raise_if_called_on_float"]
}}

Caspian uses a single Number class for all numeric values, integer and floating-point alike. Methods that only make sense for integers (such as even? and odd?) are defined on Number but raise an error if called on a non-integer value.

Numeric literals GitHub issue

Underscores in numeric literals are ignored by the lexer. Use them freely as digit separators for readability:

1_000_000       # same as 1000000
3.141_592_653   # same as 3.141592653
0xFF_FF         # same as 0xFFFF

Leading and trailing underscores are invalid. Double underscores are allowed.

Arithmetic GitHub issue

{"vibecode": {
    "section": "arithmetic",
    "operators": ["+", "-", "*", "/", "%", "**"],
    "returns": "Number"
}}

Comparison GitHub issue

{"vibecode": {
    "section": "comparison",
    "operators": ["==", "!=", "<", "<=", ">", ">="],
    "returns": "Boolean"
}}

Testing GitHub issue

{"vibecode": {
    "section": "testing",
    "methods": ["zero?", "positive?", "negative?", "integer?", "even?", "odd?",
        "finite?", "infinite?", "nan?"],
    "returns": "Boolean",
    "notes": ["even_and_odd_raise_if_not_integer", "finite_infinite_nan_for_float_safety"]
}}

Rounding GitHub issue

{"vibecode": {
    "section": "rounding",
    "methods": ["round", "round_up", "round_down"],
    "param": "multiple",
    "param_default": 1,
    "midpoint_rule": "half_away_from_zero",
    "notes": ["multiple_must_be_nonzero", "passing_0_raises_error"]
}}

All rounding methods operate on multiples. The multiple parameter specifies the step to round to. If omitted, it defaults to 1.

multiple must be a non-zero number. Passing 0 raises an error.

Midpoint rule GitHub issue

When a value falls exactly halfway between two multiples, Caspian rounds half away from zero:

5.round(multiple:10)   -> 10
-5.round(multiple:10)  -> -10

Examples GitHub issue

$foo = 2.5

$foo.round                    -> 3
$foo.round(multiple: 10)      -> 0
$foo.round_up(multiple: 10)   -> 10
$foo.round_down(multiple: 10) -> 0

$foo = 12.25

$foo.round(multiple: 0.2)     -> 12.2 or 12.4 (midpoint rule applies)
$foo.round_up(multiple: 0.2)  -> 12.4
$foo.round_down(multiple: 0.2) -> 12.2

$foo = -2.5

$foo.round                    -> -3
$foo.round(multiple: 10)      -> 0
$foo.round_up(multiple: 10)   -> 0
$foo.round_down(multiple: 10) -> -10

Bitwise GitHub issue

{"vibecode": {
    "section": "bitwise",
    "method": "bitwise",
    "returns": "Bitwise object",
    "notes": ["see_bitwise_md_for_full_api"]
}}

Math GitHub issue

{"vibecode": {
    "section": "math",
    "methods": ["abs", "square_root", "√"],
    "returns": "Number",
    "notes": ["sqrt_symbol_is_alias_for_square_root"]
}}

Conversion GitHub issue

{"vibecode": {
    "section": "conversion",
    "methods": ["to_string", "to_integer"],
    "notes": ["to_integer_truncates_toward_zero"]
}}

Iteration GitHub issue

Numeric iteration helpers (.times, .upto, .downto) live in loops.md § Numeric iteration helpers.

Open Questions GitHub issue

• Should sqrt of a negative number raise an error or return a special value?
• Should to_string accept a format argument (e.g. number of decimal places)?
• Floating-point precision: implementations should account for floating-point representation limits, particularly in rounding operations with small multiples.