empty? should be documented more clearly.

[amano-kenji]

repl:1:> (doc empty?)


    function
    boot.janet on line 117, column 1

    (empty? xs)

    Check if xs is empty.

What? Define empty. I thought nil was empty.

[kenaryn]

nil is derived from latin nihil which approximately stands for "no thing". There is no thing (pun intended) like emptyness. Even the cosmic void is filled with reversed Kasimir force (formerly known as dark matter then more recently as dark energy).

I think the Janet doc means "Check if xs has a null valence ( from latin ne ullus, "not one") if I were to use array theory terminology.
I know Janet is not based on Array paradigm (unlike a language like Nial) so perhaps Check if xs has a zero dimensionality could be adopted in stead...

... or even "Check if xs has a null length".

[amano-kenji]

Define xs.

[oneness]

xs in janet (in version 1.34 that I verified) means iterables. While I agree docs could be improved, I really like Janets error reporting, which is self explanatory.

[sogaiu]

It is true that it's not spelled out explicitly what xs represents all of the time.

For reference, this seems to be the case in the docstrings for the following as well: %, %=, *, *=, +, -, /, <, <=, =, >=, array/insert, array/push, band, bor, buffer, buffer/push, buffer/push-at, buffer/push-byte, buffer/push-string, buffer/push-word, bxor, compare<, compare<=, compare=, compare>, compare>=, distinct, div, eprin, eprinf, eprint, eprintf, geomean, last, mean, mod, not=, prin, prinf, print, printf, product, string, sum, symbol, tuple/brackets, xprin, xprinf, xprint, and xprintf.

[sogaiu]

I've gone over the list above and based on each of the corresponding docstrings, I don't think it's unclear what xs (or in one case ns) means for the following:

• % %= * *= + - / < <= = >=
• array/insert array/push
• band bor bxor
• buffer buffer/push buffer/push-at buffer/push-byte buffer/push-string buffer/push-word
• compare< compare<= compare= compare> compare>=
• div mod
• eprin eprinf eprint eprintf
• not=
• prin prinf print printf
• string
• symbol
• tuple/brackets
• xprin xprinf xprint xprintf

FWIW, these all have have signatures that contain & xs (or & ns) and I think the docstring content gives enough context for one to arrive at an appropriate interpretation.

---

For geomean, mean, product, sum, distinct I think a straight-forward interpretation would include xs covering at least an indexed type (so arrays and tuples) [1].

---

For last, the docstring explicitly mentions "indexed data structure" and there is only one argument, so deducing that xs is supposed to be an indexed data structure seems reasonable to me.

---

[1] All of the implementations have bits that refer to each, so whatever works with each may work -- though there is no claim of this in the docstring so I would stick with indexed types to be on the same side, YMMV.

Update: There are examples of usages of product and sum that suggest that use with a struct or table is intentional (at least for those two):

• sum example
• product example

[sogaiu]

For reference, AFAICT, empty? was added in this commit (2018-11) (to see the details likely one will need to click on "load diff" for core.janet) and originally was a check to see if the return value of calling length on something returned 0:

(defn empty? "Check if xs is empty." [xs] (= 0 (length xs)))

In 2021-01, in this commit a change was made to not use length but instead check the return value of next:

(defn empty? "Check if xs is empty." [xs] (= nil (next xs nil)))

In either case I think there is a hint in the commit message from the latter commit about intent:

This lets them be more generic and implemented over a wider range of data types, such as fibers.

That the type of thing xs can be is not specified may be a deliberate design decision. Originally it seems empty? could be used on any xs that length [1] could handle and now it depends on something that next [1] can be meaningfully called on.

---

[1] For the built-in types, length (via janet_lengthv) and next (via janet_next_impl) can be called on almost exactly the same set of things. The one difference ATM is that next works for fibers, but length doesn't, which seems consistent with the content of the commit message above.