Integer literals are undocumented

[sarna]

New syntax literals were added in janet-lang/janet@872b39c (thanks @sogaiu), but never documented. They seem to be the same as the ones from the int module:

repl:5:> (= 123:u (int/u64 123))
true
repl:6:> (= -123:s (int/s64 -123))
true

So.. are they boxed, or not? My guess would be yes, based on functions used like janet_wrap_u64. Are they then Janet primitive types that should be mentioned on the main datatypes page, or are they just abstract types in a module that happens to be in core? I don't know enough to document them myself, hence this issue and not a PR.

[veqqq]

https://janet-lang.org/spork/api/tarray.html used to be in the Janet compiler itself before being moved out. I've been adding (like 30 math) operations on top. Being able to add type info in Janet directly would be interesting for the API itself...

Could we... expand this usage, perhaps? E.g. have a way of giving an array of uint8 numbers? Or is that not desirable? (Can be done from a library but hmhmhm, curious to see it already in the core! I will experiment.)

We can e.g. give [1 2 3]:n which the interpret returns as:
(1 2 3)
:n

[sogaiu]

They seem to be the same as the ones from the int module

IIUC, for :u and :s, yes:

(type 1:s)
# =>
:core/s64

(type 1:u)
# =>
:core/u64

For :n though:

(type 1:n)
# =>
:number

Are they then Janet primitive types that should be mentioned on the main datatypes page

If you decide to try them out, one idea is that we revisit this issue after you've gotten a sense of them. May be it would be clearer what to do then?

or are they just abstract types in a module that happens to be in core?

I believe this PR might provide some background.

[sogaiu]

@veqqq I'm not sure how your comment relates to this issue. Any hints?

[veqqq]

The first commit says:

This also leaves open a syntax for other number types such as bignums, ratios, decimals, etc.

Exploring, I discovered we can e.g. input/have parsed (edit: without breaking the interpreter/parser): [1 2 3]:n or {:a 1}:lol so it actually expands possible syntaxes a lot, if we determine it's a worthwhile pathway to encourage (via documentation, commits adding further features etc.) Libraries can also utilize it profitably, I suspect.

Now, (def a 2:s) gives a the value <core/s64 2> and trying to use the array literal like (def b [1 2 3]:u) leads to a parsing error. But

[sogaiu]

Thanks for the clarification.

I don't follow what you mean though by:

discovered we can e.g. input/have parsed: [1 2 3]:n or {:a 1}:lol

The first returns two things here, a tuple and a keyword:

$ janet
Janet 1.41.3-dev-c0b32d4e linux/x64/gcc - '(doc)' for help
repl:1:> [1 2 3]:n
(1 2 3)
:n

If that wasn't so clear, possibly this will help:

$ janet
Janet 1.41.3-dev-c0b32d4e linux/x64/gcc - '(doc)' for help
repl:1:> (type [1 2 3]:n)
error: arity mismatch, expected 1, got 2
  in type [src/core/corelib.c] on line 575
  in thunk [repl] (tail call) on line 1, column 1

So to summarize, I think parsing results in two pieces.

I got the sense you might have had the impression that you get one thing back but I don't think that's the case. Or may be I misunderstood your prose?

[sogaiu]

It seems I misunderstood the intent of the prose.

My initial impression is I would prefer not to have Janet extended in the suggested way, but it's not my call...and perhaps this discussion might be better placed elsewhere so it's easier to find later?

[veqqq]

https://github.com/janet-lang/janet/blob/c0b32d4e3798d0ceaf4131e642e59602a31ce151/src/core/vm.c#L1641-L1653 is useful for understanding the above, e.g. that you can just use + on these boxed numbers.

[sogaiu]

To spell this out a bit more:

(type (+ 1:s -1:s))
# =>
:core/s64

IIUC, the way this works is that + ends up being handled by the vm main loop - may be JOP_ADD_IMMEDIATE or JOP_ADD. One of those calls janet_mcall and the other janet_binop_call [1]. In either case, I think corresponding methods implemented in inttypes.c are called. Those can be found by starting to look around here.

The description above may be off a bit, but I think that's more or less how it fits together.

---

Based on:

(disasm (fn [] (+ 1:s -1:s)) :bytecode)
# =>
@[(ldc 1 0) (ldc 2 1) (add 0 1 2) (ret 0)]

ATM, it seems more likely that it's JOP_ADD -> vm_binop -> _vm_binop -> janet_binop_call.

---

[1] Via the vm_binop_immediate / _vm_binop macros.