Deprecate $ as bitwise xor, replace by xor(), as discussed in #18696 (

#18977)

* Deprecate $ for xor() (#18696)

This includes:
 - occurrances of $ (as infix operator) and $= in base
 - occurances of $ in test
 - the definition in the manual
 - the entry in REPL help

This commit does not introduce an alternative,
that will happen in the next commit.

* Add ⊻ as alternative to xor, and `⊻=` as alternative to `$=`.

Please note that `⊻=` is in the add-dots group in the parser, preparing for `.⊻=`.
However, this commit does not implement `.⊻` yet, this should happen in
a separate commit with `.&` and `.|` together.

* Add deprecation comment in show.jl and deprecation item in NEWS.md

NEWS.md

@@ -68,6 +68,8 @@ Deprecated or removed
 
   * `num` and `den` have been deprecated in favor of `numerator` and `denominator` respectively ([#19233]).
 
+  * infix operator `$` has been deprecated in favor of infix `⊻` or function `xor()` ([#18977]).
+
 Julia v0.5.0 Release Notes
 ==========================
 

base/arraymath.jl

@@ -66,7 +66,7 @@ promote_array_type{S<:Integer}(::typeof(./), ::Type{S}, ::Type{Bool}, T::Type) =
 promote_array_type{S<:Integer}(::typeof(.\), ::Type{S}, ::Type{Bool}, T::Type) = T
 promote_array_type{S<:Integer}(F, ::Type{S}, ::Type{Bool}, T::Type) = T
 
-for f in (:+, :-, :div, :mod, :&, :|, :$)
+for f in (:+, :-, :div, :mod, :&, :|, :xor)
     @eval ($f)(A::AbstractArray, B::AbstractArray) =
         _elementwise($f, promote_eltype_op($f, A, B), A, B)
 end
@@ -89,7 +89,7 @@ function _elementwise{T}(op, ::Type{T}, A::AbstractArray, B::AbstractArray)
     return F
 end
 
-for f in (:.+, :.-, :.*, :./, :.\, :.^, :.÷, :.%, :.<<, :.>>, :div, :mod, :rem, :&, :|, :$)
+for f in (:.+, :.-, :.*, :./, :.\, :.^, :.÷, :.%, :.<<, :.>>, :div, :mod, :rem, :&, :|, :xor)
     @eval begin
         function ($f){T}(A::Number, B::AbstractArray{T})
             R = promote_op($f, typeof(A), T)

base/associative.jl

@@ -251,7 +251,7 @@ const hasha_seed = UInt === UInt64 ? 0x6d35bb51952d5539 : 0x952d5539
 function hash(a::Associative, h::UInt)
     h = hash(hasha_seed, h)
     for (k,v) in a
-        h $= hash(k, hash(v))
+        h ⊻= hash(k, hash(v))
     end
     return h
 end

base/bitarray.jl

@@ -1333,12 +1333,12 @@ function (|)(B::BitArray, x::Bool)
 end
 (|)(x::Bool, B::BitArray) = B | x
 
-function ($)(B::BitArray, x::Bool)
+function xor(B::BitArray, x::Bool)
     x ? ~B : copy(B)
 end
-($)(x::Bool, B::BitArray) = B $ x
+xor(x::Bool, B::BitArray) = xor(B, x)
 
-for f in (:&, :|, :$)
+for f in (:&, :|, :xor)
     @eval begin
         function ($f)(A::BitArray, B::BitArray)
             F = BitArray(promote_shape(size(A),size(B))...)
@@ -2006,10 +2006,10 @@ map!(::typeof(identity), dest::BitArray, A::BitArray) = copy!(dest, A)
 
 for (T, f) in ((:(Union{typeof(&), typeof(*), typeof(min)}), :(&)),
                (:(Union{typeof(|), typeof(max)}),            :(|)),
-               (:(Union{typeof($), typeof(!=)}),             :($)),
+               (:(Union{typeof(xor), typeof(!=)}),           :xor),
                (:(Union{typeof(>=), typeof(^)}),             :((p, q) -> p | ~q)),
                (:(typeof(<=)),                               :((p, q) -> ~p | q)),
-               (:(typeof(==)),                               :((p, q) -> ~(p $ q))),
+               (:(typeof(==)),                               :((p, q) -> ~xor(p, q))),
                (:(typeof(<)),                                :((p, q) -> ~p & q)),
                (:(typeof(>)),                                :((p, q) -> p & ~q)))
     @eval map(::$T, A::BitArray, B::BitArray) = bit_map!($f, similar(A), A, B)
@@ -2058,12 +2058,12 @@ transpose(B::BitVector) = reshape(copy(B), 1, length(B))
 # http://www.hackersdelight.org/hdcodetxt/transpose8.c.txt
 function transpose8x8(x::UInt64)
     y = x
-    t = (y $ (y >>> 7)) & 0x00aa00aa00aa00aa
-    y = y $ t $ (t << 7)
-    t = (y $ (y >>> 14)) & 0x0000cccc0000cccc
-    y = y $ t $ (t << 14)
-    t = (y $ (y >>> 28)) & 0x00000000f0f0f0f0
-    return y $ t $ (t << 28)
+    t = xor(y, y >>> 7) & 0x00aa00aa00aa00aa
+    y = xor(y, t, t << 7)
+    t = xor(y, y >>> 14) & 0x0000cccc0000cccc
+    y = xor(y, t, t << 14)
+    t = xor(y, y >>> 28) & 0x00000000f0f0f0f0
+    return xor(y, t, t << 28)
 end
 
 function form_8x8_chunk(Bc::Vector{UInt64}, i1::Int, i2::Int, m::Int, cgap::Int, cinc::Int, nc::Int, msk8::UInt64)

base/bool.jl

@@ -23,7 +23,7 @@ end
 (~)(x::Bool) = !x
 (&)(x::Bool, y::Bool) = box(Bool,and_int(unbox(Bool,x),unbox(Bool,y)))
 (|)(x::Bool, y::Bool) = box(Bool,or_int(unbox(Bool,x),unbox(Bool,y)))
-($)(x::Bool, y::Bool) = (x!=y)
+xor(x::Bool, y::Bool) = (x!=y)
 
 >>(x::Bool, c::Unsigned) = Int(x) >> c
 <<(x::Bool, c::Unsigned) = Int(x) << c

base/broadcast.jl

@@ -498,9 +498,9 @@ function broadcast_bitarrays(scalarf, bitf, A::AbstractArray{Bool}, B::AbstractA
     return F
 end
 
-biteq(a::UInt64, b::UInt64) = ~a $ b
+biteq(a::UInt64, b::UInt64) = ~a ⊻ b
 bitlt(a::UInt64, b::UInt64) = ~a & b
-bitneq(a::UInt64, b::UInt64) = a $ b
+bitneq(a::UInt64, b::UInt64) = a ⊻ b
 bitle(a::UInt64, b::UInt64) = ~a | b
 
 .==(A::AbstractArray{Bool}, B::AbstractArray{Bool}) = broadcast_bitarrays(==, biteq, A, B)

base/c.jl

@@ -187,24 +187,24 @@ function transcode(::Type{UInt16}, src::Vector{UInt8})
                 push!(dst, a)
                 a = b; continue
             elseif a < 0xe0 # 2-byte UTF-8
-                push!(dst, 0x3080 $ (UInt16(a) << 6) $ b)
+                push!(dst, xor(0x3080, UInt16(a) << 6, b))
             elseif i < n # 3/4-byte character
                 c = src[i += 1]
                 if -64 <= (c % Int8) # invalid UTF-8 (non-continuation)
                     push!(dst, a, b)
                     a = c; continue
                 elseif a < 0xf0 # 3-byte UTF-8
-                    push!(dst, 0x2080 $ (UInt16(a) << 12) $ (UInt16(b) << 6) $ c)
+                    push!(dst, xor(0x2080, UInt16(a) << 12, UInt16(b) << 6, c))
                 elseif i < n
                     d = src[i += 1]
                     if -64 <= (d % Int8) # invalid UTF-8 (non-continuation)
                         push!(dst, a, b, c)
                         a = d; continue
                     elseif a == 0xf0 && b < 0x90 # overlong encoding
-                        push!(dst, 0x2080 $ (UInt16(b) << 12) $ (UInt16(c) << 6) $ d)
+                        push!(dst, xor(0x2080, UInt16(b) << 12, UInt16(c) << 6, d))
                     else # 4-byte UTF-8
                         push!(dst, 0xe5b8 + (UInt16(a) << 8) + (UInt16(b) << 2) + (c >> 4),
-                                   0xdc80 $ (UInt16(c & 0xf) << 6) $ d)
+                                   xor(0xdc80, UInt16(c & 0xf) << 6, d))
                     end
                 else # too short
                     push!(dst, a, b, c)
@@ -273,7 +273,7 @@ function transcode(::Type{UInt8}, src::Vector{UInt16})
                 a += 0x2840
                 dst[j += 1] = 0xf0 | ((a >> 8) % UInt8)
                 dst[j += 1] = 0x80 | ((a % UInt8) >> 2)
-                dst[j += 1] = 0xf0 $ ((((a % UInt8) << 4) & 0x3f) $ (b >> 6) % UInt8)
+                dst[j += 1] = xor(0xf0, ((a % UInt8) << 4) & 0x3f, (b >> 6) % UInt8)
                 dst[j += 1] = 0x80 | ((b % UInt8) & 0x3f)
             else
                 dst[j += 1] = 0xe0 | ((a >> 12) % UInt8)

base/char.jl

@@ -33,7 +33,7 @@ in(x::Char, y::Char) = x == y
 isless(x::Char, y::Char) = UInt32(x) < UInt32(y)
 
 const hashchar_seed = 0xd4d64234
-hash(x::Char, h::UInt) = hash_uint64(((UInt64(x)+hashchar_seed)<<32) $ UInt64(h))
+hash(x::Char, h::UInt) = hash_uint64(((UInt64(x)+hashchar_seed)<<32) ⊻ UInt64(h))
 
 -(x::Char, y::Char) = Int(x) - Int(y)
 -(x::Char, y::Integer) = Char(Int32(x) - Int32(y))

base/combinatorics.jl

@@ -73,7 +73,7 @@ function isperm(A)
     n = length(A)
     used = falses(n)
     for a in A
-        (0 < a <= n) && (used[a] $= true) || return false
+        (0 < a <= n) && (used[a] ⊻= true) || return false
     end
     true
 end

base/complex.jl

@@ -161,8 +161,8 @@ const hash_0_imag = hash(0, h_imag)
 
 function hash(z::Complex, h::UInt)
     # TODO: with default argument specialization, this would be better:
-    # hash(real(z), h $ hash(imag(z), h $ h_imag) $ hash(0, h $ h_imag))
-    hash(real(z), h $ hash(imag(z), h_imag) $ hash_0_imag)
+    # hash(real(z), h ⊻ hash(imag(z), h ⊻ h_imag) ⊻ hash(0, h ⊻ h_imag))
+    hash(real(z), h ⊻ hash(imag(z), h_imag) ⊻ hash_0_imag)
 end
 
 ## generic functions of complex numbers ##

base/dSFMT.jl

@@ -115,19 +115,19 @@ function dsfmt_jump_add!(dest::Vector{UInt64}, src::Vector{UInt64})
     while i <= N-diff
         j = i*2-1
         p = j + diff*2
-        dest[j]   $= src[p]
-        dest[j+1] $= src[p+1]
+        dest[j]   ⊻= src[p]
+        dest[j+1] ⊻= src[p+1]
         i += 1
     end
     while i <= N
         j = i*2-1
         p = j + (diff - N)*2
-        dest[j]   $= src[p]
-        dest[j+1] $= src[p+1]
+        dest[j]   ⊻= src[p]
+        dest[j+1] ⊻= src[p+1]
         i += 1
     end
-    dest[N*2+1] $= src[N*2+1]
-    dest[N*2+2] $= src[N*2+2]
+    dest[N*2+1] ⊻= src[N*2+1]
+    dest[N*2+2] ⊻= src[N*2+2]
     return dest
 end
 
@@ -148,10 +148,10 @@ function dsfmt_jump_next_state!(mts::Vector{UInt64})
     t1 = mts[a+1]
     L0 = mts[u]
     L1 = mts[u+1]
-    mts[u]   = (t0 << SL1) $ (L1 >> 32) $ (L1 << 32) $ mts[b]
-    mts[u+1] = (t1 << SL1) $ (L0 >> 32) $ (L0 << 32) $ mts[b+1]
-    mts[a]   = (mts[u]   >> SR) $ (mts[u]   & MSK1) $ t0
-    mts[a+1] = (mts[u+1] >> SR) $ (mts[u+1] & MSK2) $ t1
+    mts[u]   = xor(t0 << SL1, L1 >> 32, L1 << 32, mts[b])
+    mts[u+1] = xor(t1 << SL1, L0 >> 32, L0 << 32, mts[b+1])
+    mts[a]   = xor(mts[u]   >> SR, mts[u]   & MSK1, t0)
+    mts[a+1] = xor(mts[u+1] >> SR, mts[u+1] & MSK2, t1)
 
     mts[end] = (mts[end] + 2) % (N*2)
     return mts

base/deprecated.jl

@@ -303,7 +303,7 @@ for (Fun, func) in [(:IdFun, :identity),
                     (:ConjFun, :conj),
                     (:AndFun, :&),
                     (:OrFun, :|),
-                    (:XorFun, :$),
+                    (:XorFun, :xor),
                     (:AddFun, :+),
                     (:DotAddFun, :.+),
                     (:SubFun, :-),
@@ -1022,6 +1022,13 @@ end))
 
 @deprecate ipermutedims(A::AbstractArray,p) permutedims(A, invperm(p))
 
+# 18696
+function ($)(x, y)
+    depwarn("`x \$ y` is deprecated.  use `xor(x, y)` or `x ⊻ y` instead.", :$)
+    xor(x, y)
+end
+export $
+
 @deprecate is (===)
 
 

base/docs/helpdb/Base.jl

@@ -3340,8 +3340,9 @@ Compute the Dawson function (scaled imaginary error function) of `x`, defined by
 dawson
 
 """
-    \$(x, y)
+    xor(x, y)
+    ⊻(x, y)
 
 Bitwise exclusive or.
 """
-Base.:$(x, y)
+Base.xor(x, y)

base/exports.jl

@@ -205,7 +205,8 @@ export
     !==,
     ≡,
     ≢,
-    $,
+    xor,
+    ⊻,
     %,
     ÷,
     &,

base/fastmath.jl

@@ -153,7 +153,7 @@ mul_fast{T<:FloatTypes}(x::T, y::T, zs::T...) =
     cmp_fast{T<:FloatTypes}(x::T, y::T) = ifelse(x==y, 0, ifelse(x<y, -1, +1))
     function mod_fast{T<:FloatTypes}(x::T, y::T)
         r = rem(x,y)
-        ifelse((r > 0) $ (y > 0), r+y, r)
+        ifelse((r > 0) ⊻ (y > 0), r+y, r)
     end
 end
 

base/float.jl

@@ -361,7 +361,7 @@ _default_type(T::Union{Type{Real},Type{AbstractFloat}}) = Float64
 ## floating point arithmetic ##
 -(x::Float64) = box(Float64,neg_float(unbox(Float64,x)))
 -(x::Float32) = box(Float32,neg_float(unbox(Float32,x)))
--(x::Float16) = reinterpret(Float16, reinterpret(UInt16,x) $ 0x8000)
+-(x::Float16) = reinterpret(Float16, reinterpret(UInt16,x) ⊻ 0x8000)
 
 for op in (:+,:-,:*,:/,:\,:^)
     @eval ($op)(a::Float16, b::Float16) = Float16(($op)(Float32(a), Float32(b)))
@@ -400,7 +400,7 @@ function mod{T<:AbstractFloat}(x::T, y::T)
     r = rem(x,y)
     if r == 0
         copysign(r,y)
-    elseif (r > 0) $ (y > 0)
+    elseif (r > 0) ⊻ (y > 0)
         r+y
     else
         r
@@ -531,7 +531,7 @@ const hx_NaN = hx(UInt64(0), NaN, UInt(0  ))
 
 hash(x::UInt64,  h::UInt) = hx(x, Float64(x), h)
 hash(x::Int64,   h::UInt) = hx(reinterpret(UInt64,abs(x)), Float64(x), h)
-hash(x::Float64, h::UInt) = isnan(x) ? (hx_NaN $ h) : hx(box(UInt64,fptoui(unbox(Float64,abs(x)))), x, h)
+hash(x::Float64, h::UInt) = isnan(x) ? (hx_NaN ⊻ h) : hx(box(UInt64,fptoui(unbox(Float64,abs(x)))), x, h)
 
 hash(x::Union{Bool,Int8,UInt8,Int16,UInt16,Int32,UInt32}, h::UInt) = hash(Int64(x), h)
 hash(x::Float32, h::UInt) = hash(Float64(x), h)
@@ -577,7 +577,7 @@ function nextfloat(f::Union{Float16,Float32,Float64}, d::Integer)
         fu = fumax
     else
         du = da % U
-        if fneg $ dneg
+        if fneg ⊻ dneg
             if du > fu
                 fu = min(fumax, du - fu)
                 fneg = !fneg

base/gmp.jl

@@ -4,7 +4,7 @@ module GMP
 
 export BigInt
 
-import Base: *, +, -, /, <, <<, >>, >>>, <=, ==, >, >=, ^, (~), (&), (|), ($),
+import Base: *, +, -, /, <, <<, >>, >>>, <=, ==, >, >=, ^, (~), (&), (|), xor,
              binomial, cmp, convert, div, divrem, factorial, fld, gcd, gcdx, lcm, mod,
              ndigits, promote_rule, rem, show, isqrt, string, powermod,
              sum, trailing_zeros, trailing_ones, count_ones, base, tryparse_internal,
@@ -194,7 +194,7 @@ function convert{T<:Signed}(::Type{T}, x::BigInt)
     else
         0 <= n <= cld(sizeof(T),sizeof(Limb)) || throw(InexactError())
         y = x % T
-        (x.size > 0) $ (y > 0) && throw(InexactError()) # catch overflow
+        (x.size > 0) ⊻ (y > 0) && throw(InexactError()) # catch overflow
         y
     end
 end
@@ -249,7 +249,7 @@ promote_rule{T<:Integer}(::Type{BigInt}, ::Type{T}) = BigInt
 for (fJ, fC) in ((:+, :add), (:-,:sub), (:*, :mul),
                  (:fld, :fdiv_q), (:div, :tdiv_q), (:mod, :fdiv_r), (:rem, :tdiv_r),
                  (:gcd, :gcd), (:lcm, :lcm),
-                 (:&, :and), (:|, :ior), (:$, :xor))
+                 (:&, :and), (:|, :ior), (:xor, :xor))
     @eval begin
         function ($fJ)(x::BigInt, y::BigInt)
             z = BigInt()
@@ -279,7 +279,7 @@ function invmod(x::BigInt, y::BigInt)
 end
 
 # More efficient commutative operations
-for (fJ, fC) in ((:+, :add), (:*, :mul), (:&, :and), (:|, :ior), (:$, :xor))
+for (fJ, fC) in ((:+, :add), (:*, :mul), (:&, :and), (:|, :ior), (:xor, :xor))
     @eval begin
         function ($fJ)(a::BigInt, b::BigInt, c::BigInt)
             z = BigInt()

base/hashing.jl

@@ -14,34 +14,34 @@ hash(x::ANY, h::UInt) = 3*object_id(x) - h
 function hash_64_64(n::UInt64)
     local a::UInt64 = n
     a = ~a + a << 21
-    a =  a $ a >> 24
+    a =  a ⊻ a >> 24
     a =  a + a << 3 + a << 8
-    a =  a $ a >> 14
+    a =  a ⊻ a >> 14
     a =  a + a << 2 + a << 4
-    a =  a $ a >> 28
+    a =  a ⊻ a >> 28
     a =  a + a << 31
     return a
 end
 
 function hash_64_32(n::UInt64)
     local a::UInt64 = n
     a = ~a + a << 18
-    a =  a $ a >> 31
+    a =  a ⊻ a >> 31
     a =  a * 21
-    a =  a $ a >> 11
+    a =  a ⊻ a >> 11
     a =  a + a << 6
-    a =  a $ a >> 22
+    a =  a ⊻ a >> 22
     return a % UInt32
 end
 
 function hash_32_32(n::UInt32)
     local a::UInt32 = n
     a = a + 0x7ed55d16 + a << 12
-    a = a $ 0xc761c23c $ a >> 19
+    a = a ⊻ 0xc761c23c ⊻ a >> 19
     a = a + 0x165667b1 + a << 5
-    a = a + 0xd3a2646c $ a << 9
+    a = a + 0xd3a2646c ⊻ a << 9
     a = a + 0xfd7046c5 + a << 3
-    a = a $ 0xb55a4f09 $ a >> 16
+    a = a ⊻ 0xb55a4f09 ⊻ a >> 16
     return a
 end