What does binding numbers from the docs mean?

,
1

Careful when you bind to JavaScript numbers! Long ones might be truncated. Bind JS number (especially Dates) as float instead.

Just started learning ReScript and going through the docs. Now this might just be because English isn’t my native language, but I don’t understand the quote above. Could I get a clarification on what “bind JS number (especially Dates) as float” actually means?

Perhaps we could add a short example in the docs?

1 Like
2

In OCaml (so likely Rescript as well), ints have a much smaller range than JavaScript numbers, so floats will be safer to bind to their JS counterparts:

  • OCaml int range: −1073741824 to 1073741823. 0
    1662824498
  • JS number range: -9007199254740991 to 9007199254740991 1 2
  • OCaml float range: I couldn’t actually find the mix/max here but presumably much larger than JS’s range.

The reference to dates refers to epoch time 3. Using the time right now as a reference: 1662824498 in epoch time exceeds the OCaml/Rescript int range above, so if you were doing date math and passing data to/from JS, you’d be better off using a float on the rescript side.

1 Like
3

Can you clarify which part is confusing? The ‘bind’ part or the ‘JS number (especially Dates) as float’ part?

4

To add onto the earlier answers here, ReScript’s ints are limited to 32-bits.

Say you have some big number that doesn’t fit into 32 bits (like a timestamp), and you pass it from JS to ReScript as an int, do something with it, and then pass it back to JS, the number you get back will be different from what you expect because the number gets truncated to 32 bits.

Therefore when you have really big numbers like timestamps that can exceed 32 bits you should represent them as floats in ReScript. For smaller numbers ints are fine.

2 Likes
5

Thanks for the replies! Much appeciated.

@yawaramin , yes the paragraph about binding to Dates is unclear to me. I guess the text makes an assumption that the reader would know what the author means, instead of making sure that the meaning is clear.

That’s why I felt that examples are always handy as further context.

Another way to put it could be,

“Be careful when you bind to JavaScript numbers! Since ReScript ints have a much smaller range than JavaScript numbers, data might get lost. It’s much safer to bind as float in cases of large numbers. Be extra mindful of this when binding to JavaScript Dates and their epoch time.”

4 Likes
6

“Be careful when you bind to JavaScript numbers! Since ReScript ints have a much smaller range than JavaScript numbers, data might get lost. It’s much safer to bind as float in cases of large numbers. Be extra mindful of this when binding to JavaScript Dates and their epoch time.”

This is nice!

The documentation site is on github here https://github.com/rescript-association/rescript-lang.org/blob/master/pages/docs/manual/latest/primitive-types.mdx, feel free to submit a PR to update it!

1 Like
7

Done and done :slight_smile:

Thanks for the feedback

2 Likes