docs reference

[[ceil]]

Ceil

By Goblin Docs ~ 9 min read

ceil rounds a number upward to the nearest whole number.

Overview

Use ceil when a partial amount must be counted as the next whole amount:

boxes_needed | 4.2^

:say(boxes_needed)  /// 5

boxes_needed | 4.2^

:say(boxes_needed)  /// 5

If the number is already whole, it stays unchanged.

Ceiling Operator

^ is Goblin's postfix ceiling operator:

4.567^  /// 5

4.567^  /// 5

Place it immediately after the number or numeric expression:

boxes_needed | 4.2^
average | (total / count)^

boxes_needed | 4.2^
average | (total / count)^

The similar _ operator performs Floor, not ceiling:

4.567^  /// 5 - ceiling
4.567_  /// 4 - floor

4.567^  /// 5 - ceiling
4.567_  /// 4 - floor

The ^ operator returns a float.

Method Style

Call ceil directly on a number:

pages | 12.1.ceil

:say(pages)  /// 13

pages | 12.1.ceil

:say(pages)  /// 13

The method form does not need parentheses.

The equivalent free-call form is:

pages | ceil(12.1)

pages | ceil(12.1)

Both forms behave the same way.

The named forms preserve the numeric family of the input: integers remain integers and big numbers remain big numbers. This differs from the ^ operator, which returns a float.

Rounding Upward

ceil rounds toward positive infinity:

4.2.ceil   /// 5
4.8.ceil   /// 5

4.2.ceil   /// 5
4.8.ceil   /// 5

For negative numbers, upward means moving closer to positive infinity:

(-4.2).ceil  /// -4
(-4.8).ceil  /// -4

(-4.2).ceil  /// -4
(-4.8).ceil  /// -4

Use Floor when you need to round downward instead.

Whole Numbers

An integer is already whole, so ceil returns it unchanged:

12.ceil  /// 12

12.ceil  /// 12

The result remains an integer.

Number Types

ceil accepts integers, floats, percentages, and big numbers.

Input	Result
integer	The same integer.
float	A whole-valued float.
percentage	A whole-valued float.
big number	A whole-valued big number.

"19.25".big.ceil  /// a big number with value 20

"19.25".big.ceil  /// a big number with value 20

The postfix ^ operator accepts numeric values but converts its result to a float:

12^  /// 12 as a float

12^  /// 12 as a float

Ceil, Floor, and Round

The three common rounding operations choose whole values differently:

value | 4.6

value.ceil   /// 5
value.floor  /// 4
value.round  /// 5

value | 4.6

value.ceil   /// 5
value.floor  /// 4
value.round  /// 5

ceil always rounds upward.
floor always rounds downward.
round chooses the nearest whole number.

Signature

number^
number.ceil
ceil(number)

number^
number.ceil
ceil(number)

Argument	Type	Description
`number`	numeric	The integer, float, percentage, or big number to round upward.

The ^ operator returns a float. The named ceil forms return a whole numeric value whose exact type depends on the input type.

Errors

ceil requires exactly one value:

ceil()
/// error: R0301 wrong-arity

ceil()
/// error: R0301 wrong-arity

The value must be numeric:

"4.2".ceil
/// error: R0200 numeric-expected

"4.2".ceil
/// error: R0200 numeric-expected

The operator has the same numeric requirement:

"4.2"^
/// error: R0201 type-mismatch

"4.2"^
/// error: R0201 type-mismatch

Convert numeric text before rounding it:

"4.2".float.ceil  /// 5

"4.2".float.ceil  /// 5