"and", "or", bitwise or shortcircuit, what we get searching docs

I am teaching some programming using Julia, and I faced a common student mistake which I think is justified from what we get when searching the docs. If we search “and or Julia” on google, we get, first, this page:

“Mathematical Operations and Elementary Functions…”

which defines bitwise “and” and “or”. These bitwise functions do not behave as a normal user would expect from an and:

julia> 1 == 1 & 2 == 2
false

(because 1 & 2 takes precedence).

The second page, which is

“Control flow”

defines “Short circuit evaluation”, and then the “&&” and “||” operators, which actually behave as we would expect from “and” and “or”. But that page does not mention that those are the “and” and “or” we would generally want:

julia> 1 == 1 && 2 == 2
true

Thus, I think that the control-flow section would benefit from a very clear explanation that && and || are the operators that behave as and and or operators in other languages (i. e. Python).

(if I had a single saying on the clarity of the Julia syntax, it would be to define and and or as synonyms of && and ||).

Edit: Also there are no “help” entries for “and” and “or”:

help?> and
search: tand rand randn expanduser atand asind significand append! LinearIndices transcode lastindex eachindex

Couldn't find and
Perhaps you meant rand, tand, ans, any, end, randn, asind, atand, any!, Any, tan, tanh, abs, all, Cmd, Inf or bind
  No documentation found.

  Binding and does not exist.

help?> or
search: OrdinalRange for xor sort Core sort! foreach sortperm normpath sortperm! sortslices error export import

Couldn't find or
Perhaps you meant xor, for, Core, sort, one, cos, cot, eof, log, mod, IO, do, X, x, y, !, !=, %, &, ', *, +, - or /
  No documentation found.

  Binding or does not exist.

7 Likes

You can make a PR to the docs, to change most of what you mention.

Yes, regrettable. Something similar to:

julia> (1 == 1) & (2 == 2)
true

can sometimes be useful as an optimization (while can also be slower, so shouldn’t be the default. I guess the precedence came from C, and maybe it could be changed so the former works, in Julia 2.0 (not earlier, as a breaking change). Short circuit evaluation control-flow “operators”, should be the first you should find in the docs, and be your default, and I agree, would be nice for the help system in the REPL (I’m just not sure how easy to add, given how it’s implemented).

I note:

help?> &&

works, and

help?> &
search: & &&

  x & y

  Bitwise and. Implements three-valued logic [..]

but neither point to the other, and they probably should.

About adding and, or, it’s been discussed (is a breaking change too), both as synonym, and with slightly different semantics (my proposal).

I’m just curious, who are you teaching Julia?

Googling as you did I actually got: https://docs.julialang.org/en/v1/manual/control-flow/ then number two the page you got. And yes, searching for “and” or “or” in the Docs search isn’t helpful…

2 Likes

Why would that be breaking?

Chemistry students, at the University of Campinas (Brazil)

4 Likes

It would be breaking because current code can already have used it as variable names (they are not reserved names) and such code would break if they started to be parsed as operators.

5 Likes

I am not sure who qualifies as a “normal” user, and how you happen to know their expectations. But since you mention Python, note that

>>> 1 == 1 & 2 == 2
False

Perhaps they are abnormal too?

Sure, if you somehow expect them to be called “and” and “or”. But in Julia they aren’t. Since they don’t exist, they have no help entries.

Generally, the manual should not be a transition guide from Python (or C, Matlab, R, …). We have a separate chapter in the manual for that purpose.

5 Likes

When I think about it, it’s maybe technically NOT breaking (if you’re clever with parsing, EDIT: apparently that’s still a problem), I was just going by my proposal labeled like such, but as already stated you can e.g. do:

julia> or = 1  # yes, a horrible variable name, you would want to disallow this, but you COULD not do that.
1

julia> var1 or var2  # already a syntax error, so not breaking at least this
ERROR: syntax: extra token "or" after end of expression
Stacktrace:
 [1] top-level scope
   @ none:1

If you allow the former, then having either (or both!) var1 or var2 be the “or” variable would be very confusing:

julia> if or or var2
2 Likes

I meant comparing to this:

>>> 1 == 1 and 2 == 2
True

I think in this case is common language and logic, not another programming language.

1 Like

While I agree that and and or are more readable, && and || are used in C, C++, Java and many other C-like languages. So it probably is missing from the docs because whoever wrote it thought this was common knowledge. I made a PR to improve it.

Funny, to me google returns the Control Flow page first and Mathematical Operations and Elementary Functions second.

2 Likes

Anyway, I am not saying that it is very important to have and and or as && and ||, although that would be cute.

What I am saying is that the docs and the help pages lead to confusion, and there is no mention anywhere that && and || is what we should most commonly use for conditionals where we logically would use and and or.

2 Likes

You are forgetting about whitespace sensitive contexts like in array expressions or macros. So for example [a or b] would parse as a single element vector instead of 3 hcatted ones like it does currently. That’s why I’m sceptical about adding further word operators, since they make it more difficult to tell what’s actually going on.

6 Likes

But note that Python’s and is && in Julia, so you already have that.

There is nothing “logical” in calling that operator and as opposed to &&. Various languages have different conventions, you cannot derive this from first principles. At least not spelling them out is consistent (cf 1 + 1 vs 1 plus 1).

We would, if we were using another programming language that uses these operators. Again, you appeal to “logic”, but these are (arbitrary) syntactic decisions.

In any case, this is unlikely to change now (unless, of course, we all go Zen).

2 Likes

Off-topic: Have you taught other languages (which?) [to beginners]? Did it go better or worse? Why did you choose Julia, is it about the language, or mostly about some package[s]?

I’m thinking Julia could be good for beginners, after you get over some small issues like this, shared by many other languages. I assume chemistry students are in many cases (not all) new to programming (if not, this likely wouldn’t be an issue for you).

1 Like

I insist, I am not suggesting that we should add those keywords, if that is complicated. I just think that would have been nice.

But I am not comparing programming languages here. I am just saying that if a new user searches the docs it might start using & where && is the correct thing to use. And that is because in common language “and” is “and”, and what we get from the docs is:

In the expression a && b, the subexpressionbis only evaluated ifaevaluates totrue .

or

x & y bitwise and

the english word and is in the second definition, not in the first. Related to this:

This in particular is not a big problem, if we warn the students soon enough. Other small things (which other languages share), are slightly more confusing, for example the difference between single name assignment and copying.

Yes, these students are VERY beginners, they commonly never had any contact with any other programming language. I have used Fortran and Python before. I want to teach them how to solve the dynamics of chemical kinetics and some particle simulations, and I do not use almost any package (except Plots). I usually teach them how to implement the loops explicitly for solving coupled differential equations, and only at the end of the course I show them how to feed packages with efficient implementations of the same concepts.

It has been a nice experience using Julia for that.

3 Likes

One issue has been package installation. I have to teach them in a student computer laboratory, and the students have limited storage space. Installing Julia and a few packages takes GBs of disk, and that is not possible. Installing Julia in a shared environment has been an issue.

1 Like

I am not sure why you think that:

  1. searching the docs with ?and will turn up nothing, as that is not a keyword or operator in Julia,

  2. the docstrings of & and | point out that these are bitwise operators in the first sentence, and even have examples to this effect.

Sure, that’s why the docs use the words “bitwise” and “short-circuiting boolean” before each “and” in the docstrings.

I am genuinely puzzled how confusion could arise.

1 Like

Well, to be truth, I still do not understand what bitwise is and where ever we would use that. And I have programmed for 20 years now, and developed some popular packages in my domain. I am teaching computer programming to people who don’t know in advance what an ASCII file is and start coding in Word. “Short-circuit boolean” also does not mean anything to most people, particularly for non-fluent-english speakers.

4 Likes

I would also add that searching for “and” in the docs doesn’t give any link to &, &&, control flow, or bitwise operators at all. But there were many threads criticising julia docs search already :slight_smile:

Personally I always have to resort to google search in julia docs. The content is great and very useful, the search - not so much.

7 Likes

That’s possible! Given enough disk space… :slight_smile: Anyway, you could look into Juliabox (at was a free solution, then paid, still is?), I see the website(s) are gone, but he software still exists, and could be installed at your institution. It’s at least a hosted environment, I guess the storage for packages was (to some degree only?) shared.

For a Julia cluster/HPC, I doubt each node (pre)compiles and stores its own packages. I assume the precompilation needs to only be done once, so maybe some shared disk for all students it possible (even allowing non-shared packages?), just to save space. [I believe HPC nodes do some redundant work when they load precompiled packages, as there compilation step is not fully finished, I however think that part is only in memory.]

2 Likes

It is documented in detail, with examples:

https://docs.julialang.org/en/v1/manual/control-flow/#Short-Circuit-Evaluation

Generally, programming (like all fields or specialties) is full of terminology that is not self-explanatory, regardless of one’s native language. Expecting everything to be self-explanatory is a somewhat unusual approach to learning.

2 Likes

Yes, “Short-circuit” is a CompSci term (or actually taken from electrical engineering), just something you need to know happens, it’s simple. But it means kind of that e.g. “&&” is not “and” as in English in general (and even if people think it might be better, wouldn’t be to people in e.g. Brazil). There are other issues with “or” in English meaning “||” or xor (either, or), so best to get used to that, and I kind of support not having “and” and “or” for it.

Bitwise however means you do for each corresponding bit; and in the context of & and | if there’s only one bit (true or false; as in a condition in an if statement) you get the meaning of “and” and “or” what you would really want it to mean (w/o short-circuiting).

Bitwise & and | (on many bits), is useful, I guess mostly outside your domain (e.g. in crypto, and for graphics when it was black-and-white)? E.g. if you have many flags in one integer. It’s a rather low-level concept, was/is used to conserve memory for flags. I wouldn’t worry to much about it.

It’s a bit dangerous in C and C++ for control flow, but shouldn’t be in Julia, except for the precedense. It’s rarely used as very low-level optimization.

2 Likes