godotengine / godotengine/godot-docs

Clarify rounding for `snapped*` functions

Open Beginner friendly
#12,113 0 comments 0 reactions 0 assignees View on GitHub
area:class reference
Dominant language
reStructuredText
Stars
5.7k
Forks
3.8k
Avg merge
1d 20h
Merged PRs (30d)
25

Description

## Your Godot version:
4.7

## Issue description (describe via experience):

I look at `round`:
> Rounds x to the nearest whole number, with halfway cases rounded away from 0.
- `roundf(-0.5) # -1.0` yep, further from zero.
- `roundf(0.5) # 1.0` further from zero, all good here.

Then I look at `snapped` and its derivatives:

> Returns the multiple of step that is the closest to x. This can also be used to [**ROUND**] a floating-point number to an arbitrary number of decimals.

There's no mention of how it rounds a number, but it used the word "round" so I figure behaviour matches `round` a.k.a. "away from zero".
- `snappedf(0.5, 1.0) # 1.0` yep, further from zero.
- `snappedf(-0.5, 1.0) # 0.0` oh?
- `snappedf(-0.5, -1.0) # -1.0` it's based on the step, maybe?

Looking at the implementation, I see how this occurs (even if I don't know the reasoning behind the implementation).

```cpp
double Math::snapped(double p_value, double p_step) {
if (p_step != 0) {
p_value = Math::floor(p_value / p_step + 0.5) * p_step;
}
return p_value;
}
```

So I've pieced it together, but it required digging into the C++ which shouldn't be a requirement.

### Solution

Document that halfway cases are rounded up for a positive `step` and down for a negative `step`

## URL to the documentation page (if already existing):

https://docs.godotengine.org/en/stable/classes/class_%40globalscope.html#class-globalscope-method-snapped

### Related Code:
[implementation: math_funcs.cpp](
https://github.com/godotengine/godot/blob/d7c45b19ccf6ddadc73d1c8423cd2848f59de437/core/math/math_funcs.cpp#L121-L126)

[docs: GlobalScope.xml](https://github.com/godotengine/godot/blob/d7c45b19ccf6ddadc73d1c8423cd2848f59de437/doc/classes/%40GlobalScope.xml#L1272-L1314)

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with doc/classes/@GlobalScope.xml and review the snapped and related snapped* entries linked in the issue. Clarify the documented halfway-case behavior for positive and negative steps, then verify the generated GlobalScope documentation renders the updated wording.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
88/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.