dart2js cps: Introduce some built-in operators in type propagation.

pkg/compiler/lib/src/cps_ir/builtin_operator.dart

+// Copyright (c) 2015, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+library builtin_operator;
+// This is shared by the CPS and Tree IRs.
+// Both cps_ir_nodes and tree_ir_nodes import and reexport this file.

[sra1, 2015/06/10 21:07:37]

re-export

[asgerf, 2015/06/11 11:16:40]

Done.

+
+/// An operator supported natively in the CPS and Tree IRs using the
+/// `ApplyBuiltinOperator` instructions.
+///
+/// These operators are pure in the sense that they cannot throw, diverge,
+/// have observable side-effects, return new objects, nor depend on any
+/// mutable state.
+///
+/// Most operators place restrictions on the values that may be given as
+/// argument; their behaviour is unspecified if those requirements are violated.

[sra1, 2015/06/10 21:07:37]

Many of these operators implement Dart operators.
Where this is true, say so in the comment.

Many of these operators correspond directly to JavaScript operators.
Where this is true, say so in the comment.

For example, in JavaScript we can use === to implement Dart a==b and
identical(a,b) when both a and b are strings or when one is a string and the
other is a string or (Dart) null (implemented as either JS null or undefined).

[asgerf, 2015/06/11 11:16:40]

If you are referring to the bitwise operators using Dart semantics instead of
JS, then yes, I agree. I'll clarify.

I'm a bit wary of using the correspondence to JS operators as a way of
specifying behavior, but I guess it's ok for the numeric operators.

+enum BuiltinOperator {
+  NumPlus, NumMinus, NumMultiply, NumAnd, NumOr, NumXor,

[sra1, 2015/06/10 21:07:37]

"NumPlus" and "NumMultiply" are inconsistent.
One might read "2+2" as "two plus two" but the operation is addition, giving the
verb "to add".
Add/Subtract/Multiply, not Plus/Minus/Times

[asgerf, 2015/06/11 11:16:40]

Done.

+  NumLt, NumLe, NumGt, NumGe,

[sra1, 2015/06/10 21:07:37]

Generally format the enum elements all on one line or one per line.

[asgerf, 2015/06/11 11:16:40]

Done.

+
+  /// Returns true if the two arguments are the same value (with some
+  /// caveats regarding NaN and +/-0).

[sra1, 2015/06/10 21:07:37]

Either explain the caveats or reference where they are explained.

[asgerf, 2015/06/11 11:16:40]

Done.

+  ///
+  /// At most one of the arguments may be null.
+  StrictEq,
+
+  /// Negated version of [StrictEq]. Introduced by [LogicalRewriter] in Tree IR.
+  StrictNeq,
+
+  /// Returns true if the two arguments are both null or are the same string,
+  /// boolean, or number (with some caveats regarding NaN and +/- zero).
+  ///
+  /// One of the following must hold:
+  /// - At least one argument is null.

[sra1, 2015/06/10 21:07:37]

is null, or may be null?

[asgerf, 2015/06/11 11:16:40]

Is null.

+  /// - Arguments are both strings, or both booleans, or both numbers.

[sra1, 2015/06/10 21:07:37]

If this holds, you would use StrictEq, no?

Perhaps you mean arguments are both (string or null), or both (boolean or null),
...

[asgerf, 2015/06/11 11:16:40]

The two bullet points are disjunctive; only one needs to be satisfied.

If we know the second criterion holds, then StrictEq would work, but we might
not know which criterion is satisfied at runtime (it could alternate with each
evaluation).

I initially wrote a comment similar to yours above, but changed it because that
spec does not allow us to compare arbitrary Dart objects against null.

I know seems easier to just say "this is JS ==" but that just pushes the problem
into optimizations, whose code would then get flooded with comments explaining
why it is safe to do so and so.

+  LooseEq,
+
+  /// Negated version of [LooseEq]. Introduced by [LogicalRewriter] in Tree IR.
+  LooseNeq,

[sra1, 2015/06/10 21:07:37]

We prefer words.
'eq' is not a word, so I would use 'equals'.

LooseNeq -> LooseNotEquals etc

NumGe -> NumGreaterOrEquals

[asgerf, 2015/06/11 11:16:40]

Readability will degrade tremendously if we do this, because lines will have to
be split everywhere.

+
+  /// Returns true if the argument is false, +0. -0, NaN, the empty string,
+  /// or null.

[sra1, 2015/06/10 21:07:37]

'Falsy' is a JavaScript concept, so also 'undefined'.

[asgerf, 2015/06/11 11:16:40]

It don't think it matters where the word "falsy" comes from.

I was on the fence about whether to mention 'undefined' here, but ultimately
decided against it.

The operators are specified in terms of the values manipulated by the IR, and
the IR has no notion of 'undefined' as a separate value. If we start to say
'undefined' here, it would be inconsistent with all the other places where we
just say 'null'.

I've added a comment on the enum itself clarifying that "null" always means Dart
null.

If we ever beef up the type inference to distinguish null from undefined, and
introduce operators that specialize based on this knowledge, then we might have
to qualify each mention of null as 'Dart null' or 'JS null', but right now there
is no need.

+  IsFalsy
+}