Stream: ideas

Topic: Num builtin doc tags

Ricardo Valero de la Rosa (Feb 22 2024 at 03:04):

Hi!
Any thoughts on adding a tagging system to the docs? It'd be nice for quickly spotting function details in the Num builtin module like signatures, constants, predicates, etc.
Also, what about having separate builtins for Int and Frac, and not just Num?
Wouldn't Frac.div and Int.divCeil be more intuitive?

Norbert Hajagos (Feb 22 2024 at 09:23):

Hi! I think it is great that there is only 1 Num namespace containing all the numeric functions. It simplifies the language. The type checker tells me that it expects a Frac or an Int for div and divCeil, so I can't make mistakes based on that. Also, I think this would be confusing to a beginner Frac.div 9 3. My first reaction is that "But 9 and 3 are not fractions!". But it may be just me, coming from langs where you would have to write Frac.div 9.0 3.0 to do this.

Anton (Feb 23 2024 at 08:52):

Any thoughts on adding a tagging system to the docs? It'd be nice for quickly spotting function details in the Num builtin module like signatures, constants, predicates, etc.

Hi @Ricardo Valero de la Rosa :)
Can you elaborate on this? Would you like visual indicators of what's what in the left sidebar or do you have something else in mind?

Ricardo Valero de la Rosa (Feb 24 2024 at 06:10):

Visual indicators or able to filter them.

This isn't an exhaustive list but here's more or less what I think.

- Num
  <!-- predicates -->
  - isLt
  - isGt
  - isLte
  - isGte
  - isZero
  - isPositive
  - isNegative
  <!-- functions -->
  - compare
  - abs
  - absDiff
  - neg
  - add
  - sub
  - mul
  - min
  - max
  - addSaturated
  - addChecked
  - subSaturated
  - subChecked
  - mulSaturated
  - mulChecked
  <!-- conversions -->
  - toStr
  - toFrac
  - toF32
  - toF64
  - toF32Checked
  - toF64Checked
  - Int
    <!-- predicates -->
    - isEven
    - isOdd
    - isMultipleOf
    <!-- functions -->
    - divCeil
    - divCeilChecked
    - divTrunc
    - divTruncChecked
    - rem
    - remChecked
    - powInt
    - addWrap
    - subWrap
    - mulWrap
    <!-- conversions -->
    - toI8
    - toI16
    - toI32
    - toI64
    - toI128
    - toU8
    - toU16
    - toU32
    - toU64
    - toU128
    - toI8Checked
    - toI16Checked
    - toI32Checked
    - toI64Checked
    - toI128Checked
    - toU8Checked
    - toU16Checked
    - toU32Checked
    - toU64Checked
    - toU128Checked
    <!-- constants -->
    - minI8
    - maxI8
    - minU8
    - maxU8
    - minI16
    - maxI16
    - minU16
    - maxU16
    - minI32
    - maxI32
    - minU32
    - maxU32
    - minI64
    - maxI64
    - minU64
    - maxU64
    - minI128
    - maxI128
    - minU128
    - maxU128
  - Frac
    <!-- predicates -->
    - isApproxEq
    - isNaN
    - isInfinite
    - isFinite
    <!-- functions -->
    - sin
    - cos
    - tan
    - asin
    - acos
    - atan
    - sqrt
    - sqrtChecked
    - log
    - logChecked
    - div
    - divChecked
    - pow
    <!-- conversions -->
    - round
    - floor
    - ceiling
    <!-- constants -->
    - e
    - pi
    - tau
    - minF32
    - maxF32
    - minF64
    - maxF64

So when I search in the docs for example:
What conversions can I do with a Frac?
The result I'd get is: round, floor and ceiling

I hope I explained myself.

Ricardo Valero de la Rosa (Feb 24 2024 at 06:27):

Maybe something more flexible like filtering by signature? Idk
Examples:
constants : Frac *
predicates : ANY -> Bool
conversions : Frac * -> NOT Frac
fns :Frac a -> Frac a, : Frac a -> Result (Frac a) [ANY], : Frac a, Frac a -> Frac a

Anton (Feb 24 2024 at 10:42):

I'm in favor of implementing both :)

Anton (Feb 24 2024 at 10:42):

For the visual indicators I think we need to experiment a bit for the best UI/UX. We should perhaps only show them once the list of functions/types/constants exceeds a certain length.

Anton (Feb 24 2024 at 10:42):

I'm curious to see what other people think

Brendan Hansknecht (Feb 24 2024 at 16:07):

I think the idea of at a minimum grouping the functions such that they are ordered by those categories. With a good ui, I think this would be awesome

Anton (Feb 26 2024 at 13:56):

I made #6540 and #6541 for these features.

Last updated: Jun 16 2026 at 16:19 UTC