| Line | Exclusive | Inclusive | Code |
|---|---|---|---|
| 1 | # This file is a part of Julia. License is MIT: https://julialang.org/license | ||
| 2 | |||
| 3 | ## types ## | ||
| 4 | |||
| 5 | """ | ||
| 6 | <:(T1, T2) | ||
| 7 | |||
| 8 | Subtype operator: returns `true` if and only if all values of type `T1` are | ||
| 9 | also of type `T2`. | ||
| 10 | |||
| 11 | # Examples | ||
| 12 | ```jldoctest | ||
| 13 | julia> Float64 <: AbstractFloat | ||
| 14 | true | ||
| 15 | |||
| 16 | julia> Vector{Int} <: AbstractArray | ||
| 17 | true | ||
| 18 | |||
| 19 | julia> Matrix{Float64} <: Matrix{AbstractFloat} | ||
| 20 | false | ||
| 21 | ``` | ||
| 22 | """ | ||
| 23 | (<:) | ||
| 24 | |||
| 25 | """ | ||
| 26 | >:(T1, T2) | ||
| 27 | |||
| 28 | Supertype operator, equivalent to `T2 <: T1`. | ||
| 29 | """ | ||
| 30 | (>:)(@nospecialize(a), @nospecialize(b)) = (b <: a) | ||
| 31 | |||
| 32 | """ | ||
| 33 | supertype(T::DataType) | ||
| 34 | |||
| 35 | Return the supertype of DataType `T`. | ||
| 36 | |||
| 37 | # Examples | ||
| 38 | ```jldoctest | ||
| 39 | julia> supertype(Int32) | ||
| 40 | Signed | ||
| 41 | ``` | ||
| 42 | """ | ||
| 43 | function supertype(T::DataType) | ||
| 44 | @_pure_meta | ||
| 45 | T.super | ||
| 46 | end | ||
| 47 | |||
| 48 | function supertype(T::UnionAll) | ||
| 49 | @_pure_meta | ||
| 50 | UnionAll(T.var, supertype(T.body)) | ||
| 51 | end | ||
| 52 | |||
| 53 | ## generic comparison ## | ||
| 54 | |||
| 55 | """ | ||
| 56 | ==(x, y) | ||
| 57 | |||
| 58 | Generic equality operator. Falls back to [`===`](@ref). | ||
| 59 | Should be implemented for all types with a notion of equality, based on the abstract value | ||
| 60 | that an instance represents. For example, all numeric types are compared by numeric value, | ||
| 61 | ignoring type. Strings are compared as sequences of characters, ignoring encoding. | ||
| 62 | For collections, `==` is generally called recursively on all contents, | ||
| 63 | though other properties (like the shape for arrays) may also be taken into account. | ||
| 64 | |||
| 65 | This operator follows IEEE semantics for floating-point numbers: `0.0 == -0.0` and | ||
| 66 | `NaN != NaN`. | ||
| 67 | |||
| 68 | The result is of type `Bool`, except when one of the operands is [`missing`](@ref), | ||
| 69 | in which case `missing` is returned | ||
| 70 | ([three-valued logic](https://en.wikipedia.org/wiki/Three-valued_logic)). | ||
| 71 | For collections, `missing` is returned if at least one of the operands contains | ||
| 72 | a `missing` value and all non-missing values are equal. | ||
| 73 | Use [`isequal`](@ref) or [`===`](@ref) to always get a `Bool` result. | ||
| 74 | |||
| 75 | # Implementation | ||
| 76 | New numeric types should implement this function for two arguments of the new type, and | ||
| 77 | handle comparison to other types via promotion rules where possible. | ||
| 78 | |||
| 79 | [`isequal`](@ref) falls back to `==`, so new methods of `==` will be used by the | ||
| 80 | [`Dict`](@ref) type to compare keys. If your type will be used as a dictionary key, it | ||
| 81 | should therefore also implement [`hash`](@ref). | ||
| 82 | """ | ||
| 83 | ==(x, y) = x === y | ||
| 84 | |||
| 85 | """ | ||
| 86 | isequal(x, y) | ||
| 87 | |||
| 88 | Similar to [`==`](@ref), except for the treatment of floating point numbers | ||
| 89 | and of missing values. `isequal` treats all floating-point `NaN` values as equal | ||
| 90 | to each other, treats `-0.0` as unequal to `0.0`, and [`missing`](@ref) as equal | ||
| 91 | to `missing`. Always returns a `Bool` value. | ||
| 92 | |||
| 93 | # Implementation | ||
| 94 | The default implementation of `isequal` calls `==`, so a type that does not involve | ||
| 95 | floating-point values generally only needs to define `==`. | ||
| 96 | |||
| 97 | `isequal` is the comparison function used by hash tables (`Dict`). `isequal(x,y)` must imply | ||
| 98 | that `hash(x) == hash(y)`. | ||
| 99 | |||
| 100 | This typically means that types for which a custom `==` or `isequal` method exists must | ||
| 101 | implement a corresponding `hash` method (and vice versa). Collections typically implement | ||
| 102 | `isequal` by calling `isequal` recursively on all contents. | ||
| 103 | |||
| 104 | Scalar types generally do not need to implement `isequal` separate from `==`, unless they | ||
| 105 | represent floating-point numbers amenable to a more efficient implementation than that | ||
| 106 | provided as a generic fallback (based on `isnan`, `signbit`, and `==`). | ||
| 107 | |||
| 108 | # Examples | ||
| 109 | ```jldoctest | ||
| 110 | julia> isequal([1., NaN], [1., NaN]) | ||
| 111 | true | ||
| 112 | |||
| 113 | julia> [1., NaN] == [1., NaN] | ||
| 114 | false | ||
| 115 | |||
| 116 | julia> 0.0 == -0.0 | ||
| 117 | true | ||
| 118 | |||
| 119 | julia> isequal(0.0, -0.0) | ||
| 120 | false | ||
| 121 | ``` | ||
| 122 | """ | ||
| 123 | isequal(x, y) = x == y | ||
| 124 | |||
| 125 | signequal(x, y) = signbit(x)::Bool == signbit(y)::Bool | ||
| 126 | signless(x, y) = signbit(x)::Bool & !signbit(y)::Bool | ||
| 127 | |||
| 128 | isequal(x::AbstractFloat, y::AbstractFloat) = (isnan(x) & isnan(y)) | signequal(x, y) & (x == y) | ||
| 129 | isequal(x::Real, y::AbstractFloat) = (isnan(x) & isnan(y)) | signequal(x, y) & (x == y) | ||
| 130 | isequal(x::AbstractFloat, y::Real ) = (isnan(x) & isnan(y)) | signequal(x, y) & (x == y) | ||
| 131 | |||
| 132 | """ | ||
| 133 | isless(x, y) | ||
| 134 | |||
| 135 | Test whether `x` is less than `y`, according to a fixed total order. | ||
| 136 | `isless` is not defined on all pairs of values `(x, y)`. However, if it | ||
| 137 | is defined, it is expected to satisfy the following: | ||
| 138 | - If `isless(x, y)` is defined, then so is `isless(y, x)` and `isequal(x, y)`, | ||
| 139 | and exactly one of those three yields `true`. | ||
| 140 | - The relation defined by `isless` is transitive, i.e., | ||
| 141 | `isless(x, y) && isless(y, z)` implies `isless(x, z)`. | ||
| 142 | |||
| 143 | Values that are normally unordered, such as `NaN`, | ||
| 144 | are ordered in an arbitrary but consistent fashion. | ||
| 145 | [`missing`](@ref) values are ordered last. | ||
| 146 | |||
| 147 | This is the default comparison used by [`sort`](@ref). | ||
| 148 | |||
| 149 | # Implementation | ||
| 150 | Non-numeric types with a total order should implement this function. | ||
| 151 | Numeric types only need to implement it if they have special values such as `NaN`. | ||
| 152 | Types with a partial order should implement [`<`](@ref). | ||
| 153 | """ | ||
| 154 | function isless end | ||
| 155 | |||
| 156 | isless(x::AbstractFloat, y::AbstractFloat) = (!isnan(x) & (isnan(y) | signless(x, y))) | (x < y) | ||
| 157 | isless(x::Real, y::AbstractFloat) = (!isnan(x) & (isnan(y) | signless(x, y))) | (x < y) | ||
| 158 | isless(x::AbstractFloat, y::Real ) = (!isnan(x) & (isnan(y) | signless(x, y))) | (x < y) | ||
| 159 | |||
| 160 | |||
| 161 | function ==(T::Type, S::Type) | ||
| 162 | @_pure_meta | ||
| 163 | return ccall(:jl_types_equal, Cint, (Any, Any), T, S) != 0 | ||
| 164 | end | ||
| 165 | function !=(T::Type, S::Type) | ||
| 166 | @_pure_meta | ||
| 167 | return !(T == S) | ||
| 168 | end | ||
| 169 | ==(T::TypeVar, S::Type) = false | ||
| 170 | ==(T::Type, S::TypeVar) = false | ||
| 171 | |||
| 172 | ## comparison fallbacks ## | ||
| 173 | |||
| 174 | """ | ||
| 175 | !=(x, y) | ||
| 176 | ≠(x,y) | ||
| 177 | |||
| 178 | Not-equals comparison operator. Always gives the opposite answer as [`==`](@ref). | ||
| 179 | |||
| 180 | # Implementation | ||
| 181 | New types should generally not implement this, and rely on the fallback definition | ||
| 182 | `!=(x,y) = !(x==y)` instead. | ||
| 183 | |||
| 184 | # Examples | ||
| 185 | ```jldoctest | ||
| 186 | julia> 3 != 2 | ||
| 187 | true | ||
| 188 | |||
| 189 | julia> "foo" ≠ "foo" | ||
| 190 | false | ||
| 191 | ``` | ||
| 192 | """ | ||
| 193 | !=(x, y) = !(x == y) | ||
| 194 | const ≠ = != | ||
| 195 | |||
| 196 | """ | ||
| 197 | ===(x,y) -> Bool | ||
| 198 | ≡(x,y) -> Bool | ||
| 199 | |||
| 200 | Determine whether `x` and `y` are identical, in the sense that no program could distinguish | ||
| 201 | them. First the types of `x` and `y` are compared. If those are identical, mutable objects | ||
| 202 | are compared by address in memory and immutable objects (such as numbers) are compared by | ||
| 203 | contents at the bit level. This function is sometimes called "egal". | ||
| 204 | It always returns a `Bool` value. | ||
| 205 | |||
| 206 | # Examples | ||
| 207 | ```jldoctest | ||
| 208 | julia> a = [1, 2]; b = [1, 2]; | ||
| 209 | |||
| 210 | julia> a == b | ||
| 211 | true | ||
| 212 | |||
| 213 | julia> a === b | ||
| 214 | false | ||
| 215 | |||
| 216 | julia> a === a | ||
| 217 | true | ||
| 218 | ``` | ||
| 219 | """ | ||
| 220 | === | ||
| 221 | const ≡ = === | ||
| 222 | |||
| 223 | """ | ||
| 224 | !==(x, y) | ||
| 225 | ≢(x,y) | ||
| 226 | |||
| 227 | Always gives the opposite answer as [`===`](@ref). | ||
| 228 | |||
| 229 | # Examples | ||
| 230 | ```jldoctest | ||
| 231 | julia> a = [1, 2]; b = [1, 2]; | ||
| 232 | |||
| 233 | julia> a ≢ b | ||
| 234 | true | ||
| 235 | |||
| 236 | julia> a ≢ a | ||
| 237 | false | ||
| 238 | ``` | ||
| 239 | """ | ||
| 240 | !==(@nospecialize(x), @nospecialize(y)) = !(x === y) | ||
| 241 | const ≢ = !== | ||
| 242 | |||
| 243 | """ | ||
| 244 | <(x, y) | ||
| 245 | |||
| 246 | Less-than comparison operator. Falls back to [`isless`](@ref). | ||
| 247 | Because of the behavior of floating-point NaN values, this operator implements | ||
| 248 | a partial order. | ||
| 249 | |||
| 250 | # Implementation | ||
| 251 | New numeric types with a canonical partial order should implement this function for | ||
| 252 | two arguments of the new type. | ||
| 253 | Types with a canonical total order should implement [`isless`](@ref) instead. | ||
| 254 | (x < y) | (x == y) | ||
| 255 | |||
| 256 | # Examples | ||
| 257 | ```jldoctest | ||
| 258 | julia> 'a' < 'b' | ||
| 259 | true | ||
| 260 | |||
| 261 | julia> "abc" < "abd" | ||
| 262 | true | ||
| 263 | |||
| 264 | julia> 5 < 3 | ||
| 265 | false | ||
| 266 | ``` | ||
| 267 | """ | ||
| 268 | 589 (71 %) |
589 (71 %)
samples spent in <
241 (41 %) (incl.) when called from isless line 7 348 (59 %) (incl.) when called from > line 294
10 (2 %)
samples spent calling
isless
<(x, y) = isless(x, y)
32 (5 %) samples spent calling isless 9 (2 %) samples spent calling isless 53 (9 %) samples spent calling isless 123 (21 %) samples spent calling isless 36 (6 %) samples spent calling isless 56 (10 %) samples spent calling isless 256 (43 %) samples spent calling isless 14 (2 %) samples spent calling isless |
|
| 269 | |||
| 270 | """ | ||
| 271 | >(x, y) | ||
| 272 | |||
| 273 | Greater-than comparison operator. Falls back to `y < x`. | ||
| 274 | |||
| 275 | # Implementation | ||
| 276 | Generally, new types should implement [`<`](@ref) instead of this function, | ||
| 277 | and rely on the fallback definition `>(x, y) = y < x`. | ||
| 278 | |||
| 279 | # Examples | ||
| 280 | ```jldoctest | ||
| 281 | julia> 'a' > 'b' | ||
| 282 | false | ||
| 283 | |||
| 284 | julia> 7 > 3 > 1 | ||
| 285 | true | ||
| 286 | |||
| 287 | julia> "abc" > "abd" | ||
| 288 | false | ||
| 289 | |||
| 290 | julia> 5 > 3 | ||
| 291 | true | ||
| 292 | ``` | ||
| 293 | """ | ||
| 294 | 357 (43 %) |
357 (43 %)
samples spent in >
>(x, y) = y < x
348 (97 %) (incl.) when called from #1 line 73 9 (3 %) (incl.) when called from isless line 18 |
|
| 295 | |||
| 296 | """ | ||
| 297 | <=(x, y) | ||
| 298 | ≤(x,y) | ||
| 299 | |||
| 300 | Less-than-or-equals comparison operator. Falls back to `(x < y) | (x == y)`. | ||
| 301 | |||
| 302 | # Examples | ||
| 303 | ```jldoctest | ||
| 304 | julia> 'a' <= 'b' | ||
| 305 | true | ||
| 306 | |||
| 307 | julia> 7 ≤ 7 ≤ 9 | ||
| 308 | true | ||
| 309 | |||
| 310 | julia> "abc" ≤ "abc" | ||
| 311 | true | ||
| 312 | |||
| 313 | julia> 5 <= 3 | ||
| 314 | false | ||
| 315 | ``` | ||
| 316 | """ | ||
| 317 | <=(x, y) = (x < y) | (x == y) | ||
| 318 | const ≤ = <= | ||
| 319 | |||
| 320 | """ | ||
| 321 | >=(x, y) | ||
| 322 | ≥(x,y) | ||
| 323 | |||
| 324 | Greater-than-or-equals comparison operator. Falls back to `y <= x`. | ||
| 325 | |||
| 326 | # Examples | ||
| 327 | ```jldoctest | ||
| 328 | julia> 'a' >= 'b' | ||
| 329 | false | ||
| 330 | |||
| 331 | julia> 7 ≥ 7 ≥ 3 | ||
| 332 | true | ||
| 333 | |||
| 334 | julia> "abc" ≥ "abc" | ||
| 335 | true | ||
| 336 | |||
| 337 | julia> 5 >= 3 | ||
| 338 | true | ||
| 339 | ``` | ||
| 340 | """ | ||
| 341 | >=(x, y) = (y <= x) | ||
| 342 | const ≥ = >= | ||
| 343 | |||
| 344 | # this definition allows Number types to implement < instead of isless, | ||
| 345 | # which is more idiomatic: | ||
| 346 | isless(x::Real, y::Real) = x<y | ||
| 347 | |||
| 348 | """ | ||
| 349 | ifelse(condition::Bool, x, y) | ||
| 350 | |||
| 351 | Return `x` if `condition` is `true`, otherwise return `y`. This differs from `?` or `if` in | ||
| 352 | that it is an ordinary function, so all the arguments are evaluated first. In some cases, | ||
| 353 | using `ifelse` instead of an `if` statement can eliminate the branch in generated code and | ||
| 354 | provide higher performance in tight loops. | ||
| 355 | |||
| 356 | # Examples | ||
| 357 | ```jldoctest | ||
| 358 | julia> ifelse(1 > 2, 1, 2) | ||
| 359 | 2 | ||
| 360 | ``` | ||
| 361 | """ | ||
| 362 | ifelse | ||
| 363 | |||
| 364 | """ | ||
| 365 | cmp(x,y) | ||
| 366 | |||
| 367 | Return -1, 0, or 1 depending on whether `x` is less than, equal to, or greater than `y`, | ||
| 368 | respectively. Uses the total order implemented by `isless`. | ||
| 369 | |||
| 370 | # Examples | ||
| 371 | ```jldoctest | ||
| 372 | julia> cmp(1, 2) | ||
| 373 | -1 | ||
| 374 | |||
| 375 | julia> cmp(2, 1) | ||
| 376 | 1 | ||
| 377 | |||
| 378 | julia> cmp(2+im, 3-im) | ||
| 379 | ERROR: MethodError: no method matching isless(::Complex{Int64}, ::Complex{Int64}) | ||
| 380 | [...] | ||
| 381 | ``` | ||
| 382 | """ | ||
| 383 | cmp(x, y) = isless(x, y) ? -1 : ifelse(isless(y, x), 1, 0) | ||
| 384 | |||
| 385 | """ | ||
| 386 | cmp(<, x, y) | ||
| 387 | |||
| 388 | Return -1, 0, or 1 depending on whether `x` is less than, equal to, or greater than `y`, | ||
| 389 | respectively. The first argument specifies a less-than comparison function to use. | ||
| 390 | """ | ||
| 391 | cmp(<, x, y) = (x < y) ? -1 : ifelse(y < x, 1, 0) | ||
| 392 | |||
| 393 | # cmp returns -1, 0, +1 indicating ordering | ||
| 394 | cmp(x::Integer, y::Integer) = ifelse(isless(x, y), -1, ifelse(isless(y, x), 1, 0)) | ||
| 395 | |||
| 396 | """ | ||
| 397 | max(x, y, ...) | ||
| 398 | |||
| 399 | Return the maximum of the arguments. See also the [`maximum`](@ref) function | ||
| 400 | to take the maximum element from a collection. | ||
| 401 | |||
| 402 | # Examples | ||
| 403 | ```jldoctest | ||
| 404 | julia> max(2, 5, 1) | ||
| 405 | 5 | ||
| 406 | ``` | ||
| 407 | """ | ||
| 408 | max(x, y) = ifelse(isless(y, x), x, y) | ||
| 409 | |||
| 410 | """ | ||
| 411 | min(x, y, ...) | ||
| 412 | |||
| 413 | Return the minimum of the arguments. See also the [`minimum`](@ref) function | ||
| 414 | to take the minimum element from a collection. | ||
| 415 | |||
| 416 | # Examples | ||
| 417 | ```jldoctest | ||
| 418 | julia> min(2, 5, 1) | ||
| 419 | 1 | ||
| 420 | ``` | ||
| 421 | """ | ||
| 422 | min(x,y) = ifelse(isless(y, x), y, x) | ||
| 423 | |||
| 424 | """ | ||
| 425 | minmax(x, y) | ||
| 426 | |||
| 427 | Return `(min(x,y), max(x,y))`. See also: [`extrema`](@ref) that returns `(minimum(x), maximum(x))`. | ||
| 428 | |||
| 429 | # Examples | ||
| 430 | ```jldoctest | ||
| 431 | julia> minmax('c','b') | ||
| 432 | ('b', 'c') | ||
| 433 | ``` | ||
| 434 | """ | ||
| 435 | minmax(x,y) = isless(y, x) ? (y, x) : (x, y) | ||
| 436 | |||
| 437 | """ | ||
| 438 | extrema(itr) -> Tuple | ||
| 439 | |||
| 440 | Compute both the minimum and maximum element in a single pass, and return them as a 2-tuple. | ||
| 441 | |||
| 442 | # Examples | ||
| 443 | ```jldoctest | ||
| 444 | julia> extrema(2:10) | ||
| 445 | (2, 10) | ||
| 446 | |||
| 447 | julia> extrema([9,pi,4.5]) | ||
| 448 | (3.141592653589793, 9.0) | ||
| 449 | ``` | ||
| 450 | """ | ||
| 451 | extrema(itr) = _extrema_itr(identity, itr) | ||
| 452 | |||
| 453 | """ | ||
| 454 | extrema(f, itr) -> Tuple | ||
| 455 | |||
| 456 | Compute both the minimum and maximum of `f` applied to each element in `itr` and return | ||
| 457 | them as a 2-tuple. Only one pass is made over `itr`. | ||
| 458 | |||
| 459 | !!! compat "Julia 1.2" | ||
| 460 | This method requires Julia 1.2 or later. | ||
| 461 | |||
| 462 | # Examples | ||
| 463 | ```jldoctest | ||
| 464 | julia> extrema(sin, 0:π) | ||
| 465 | (0.0, 0.9092974268256817) | ||
| 466 | ``` | ||
| 467 | """ | ||
| 468 | extrema(f, itr) = _extrema_itr(f, itr) | ||
| 469 | |||
| 470 | function _extrema_itr(f, itr) | ||
| 471 | y = iterate(itr) | ||
| 472 | y === nothing && throw(ArgumentError("collection must be non-empty")) | ||
| 473 | (v, s) = y | ||
| 474 | vmin = vmax = f(v) | ||
| 475 | while true | ||
| 476 | y = iterate(itr, s) | ||
| 477 | y === nothing && break | ||
| 478 | (x, s) = y | ||
| 479 | fx = f(x) | ||
| 480 | vmax = max(fx, vmax) | ||
| 481 | vmin = min(fx, vmin) | ||
| 482 | end | ||
| 483 | return (vmin, vmax) | ||
| 484 | end | ||
| 485 | |||
| 486 | extrema(x::Real) = (x, x) | ||
| 487 | extrema(f, x::Real) = (y = f(x); (y, y)) | ||
| 488 | |||
| 489 | ## definitions providing basic traits of arithmetic operators ## | ||
| 490 | |||
| 491 | """ | ||
| 492 | identity(x) | ||
| 493 | |||
| 494 | The identity function. Returns its argument. | ||
| 495 | |||
| 496 | # Examples | ||
| 497 | ```jldoctest | ||
| 498 | julia> identity("Well, what did you expect?") | ||
| 499 | "Well, what did you expect?" | ||
| 500 | ``` | ||
| 501 | """ | ||
| 502 | identity(x) = x | ||
| 503 | |||
| 504 | +(x::Number) = x | ||
| 505 | *(x::Number) = x | ||
| 506 | (&)(x::Integer) = x | ||
| 507 | (|)(x::Integer) = x | ||
| 508 | xor(x::Integer) = x | ||
| 509 | |||
| 510 | const ⊻ = xor | ||
| 511 | |||
| 512 | # foldl for argument lists. expand recursively up to a point, then | ||
| 513 | # switch to a loop. this allows small cases like `a+b+c+d` to be inlined | ||
| 514 | # efficiently, without a major slowdown for `+(x...)` when `x` is big. | ||
| 515 | afoldl(op,a) = a | ||
| 516 | afoldl(op,a,b) = op(a,b) | ||
| 517 | afoldl(op,a,b,c...) = afoldl(op, op(a,b), c...) | ||
| 518 | function afoldl(op,a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,qs...) | ||
| 519 | y = op(op(op(op(op(op(op(op(op(op(op(op(op(op(op(a,b),c),d),e),f),g),h),i),j),k),l),m),n),o),p) | ||
| 520 | for x in qs; y = op(y,x); end | ||
| 521 | y | ||
| 522 | end | ||
| 523 | |||
| 524 | for op in (:+, :*, :&, :|, :xor, :min, :max, :kron) | ||
| 525 | @eval begin | ||
| 526 | # note: these definitions must not cause a dispatch loop when +(a,b) is | ||
| 527 | # not defined, and must only try to call 2-argument definitions, so | ||
| 528 | # that defining +(a,b) is sufficient for full functionality. | ||
| 529 | 137 (16 %) | ($op)(a, b, c, xs...) = afoldl($op, ($op)(($op)(a,b),c), xs...) | |
| 530 | # a further concern is that it's easy for a type like (Int,Int...) | ||
| 531 | # to match many definitions, so we need to keep the number of | ||
| 532 | # definitions down to avoid losing type information. | ||
| 533 | end | ||
| 534 | end | ||
| 535 | |||
| 536 | """ | ||
| 537 | \\(x, y) | ||
| 538 | |||
| 539 | Left division operator: multiplication of `y` by the inverse of `x` on the left. Gives | ||
| 540 | floating-point results for integer arguments. | ||
| 541 | |||
| 542 | # Examples | ||
| 543 | ```jldoctest | ||
| 544 | julia> 3 \\ 6 | ||
| 545 | 2.0 | ||
| 546 | |||
| 547 | julia> inv(3) * 6 | ||
| 548 | 2.0 | ||
| 549 | |||
| 550 | julia> A = [4 3; 2 1]; x = [5, 6]; | ||
| 551 | |||
| 552 | julia> A \\ x | ||
| 553 | 2-element Array{Float64,1}: | ||
| 554 | 6.5 | ||
| 555 | -7.0 | ||
| 556 | |||
| 557 | julia> inv(A) * x | ||
| 558 | 2-element Array{Float64,1}: | ||
| 559 | 6.5 | ||
| 560 | -7.0 | ||
| 561 | ``` | ||
| 562 | """ | ||
| 563 | \(x,y) = adjoint(adjoint(y)/adjoint(x)) | ||
| 564 | |||
| 565 | # Core <<, >>, and >>> take either Int or UInt as second arg. Signed shift | ||
| 566 | # counts can shift in either direction, and are translated here to unsigned | ||
| 567 | # counts. Integer datatypes only need to implement the unsigned version. | ||
| 568 | |||
| 569 | """ | ||
| 570 | <<(x, n) | ||
| 571 | |||
| 572 | Left bit shift operator, `x << n`. For `n >= 0`, the result is `x` shifted left | ||
| 573 | by `n` bits, filling with `0`s. This is equivalent to `x * 2^n`. For `n < 0`, | ||
| 574 | this is equivalent to `x >> -n`. | ||
| 575 | |||
| 576 | # Examples | ||
| 577 | ```jldoctest | ||
| 578 | julia> Int8(3) << 2 | ||
| 579 | 12 | ||
| 580 | |||
| 581 | julia> bitstring(Int8(3)) | ||
| 582 | "00000011" | ||
| 583 | |||
| 584 | julia> bitstring(Int8(12)) | ||
| 585 | "00001100" | ||
| 586 | ``` | ||
| 587 | See also [`>>`](@ref), [`>>>`](@ref). | ||
| 588 | """ | ||
| 589 | function <<(x::Integer, c::Integer) | ||
| 590 | @_inline_meta | ||
| 591 | typemin(Int) <= c <= typemax(Int) && return x << (c % Int) | ||
| 592 | (x >= 0 || c >= 0) && return zero(x) << 0 # for type stability | ||
| 593 | oftype(x, -1) | ||
| 594 | end | ||
| 595 | function <<(x::Integer, c::Unsigned) | ||
| 596 | @_inline_meta | ||
| 597 | if c isa UInt | ||
| 598 | throw(MethodError(<<, (x, c))) | ||
| 599 | end | ||
| 600 | c <= typemax(UInt) ? x << (c % UInt) : zero(x) << UInt(0) | ||
| 601 | end | ||
| 602 | <<(x::Integer, c::Int) = c >= 0 ? x << unsigned(c) : x >> unsigned(-c) | ||
| 603 | |||
| 604 | """ | ||
| 605 | >>(x, n) | ||
| 606 | |||
| 607 | Right bit shift operator, `x >> n`. For `n >= 0`, the result is `x` shifted | ||
| 608 | right by `n` bits, where `n >= 0`, filling with `0`s if `x >= 0`, `1`s if `x < | ||
| 609 | 0`, preserving the sign of `x`. This is equivalent to `fld(x, 2^n)`. For `n < | ||
| 610 | 0`, this is equivalent to `x << -n`. | ||
| 611 | |||
| 612 | # Examples | ||
| 613 | ```jldoctest | ||
| 614 | julia> Int8(13) >> 2 | ||
| 615 | 3 | ||
| 616 | |||
| 617 | julia> bitstring(Int8(13)) | ||
| 618 | "00001101" | ||
| 619 | |||
| 620 | julia> bitstring(Int8(3)) | ||
| 621 | "00000011" | ||
| 622 | |||
| 623 | julia> Int8(-14) >> 2 | ||
| 624 | -4 | ||
| 625 | |||
| 626 | julia> bitstring(Int8(-14)) | ||
| 627 | "11110010" | ||
| 628 | |||
| 629 | julia> bitstring(Int8(-4)) | ||
| 630 | "11111100" | ||
| 631 | ``` | ||
| 632 | See also [`>>>`](@ref), [`<<`](@ref). | ||
| 633 | """ | ||
| 634 | function >>(x::Integer, c::Integer) | ||
| 635 | @_inline_meta | ||
| 636 | if c isa UInt | ||
| 637 | throw(MethodError(>>, (x, c))) | ||
| 638 | end | ||
| 639 | typemin(Int) <= c <= typemax(Int) && return x >> (c % Int) | ||
| 640 | (x >= 0 || c < 0) && return zero(x) >> 0 | ||
| 641 | oftype(x, -1) | ||
| 642 | end | ||
| 643 | >>(x::Integer, c::Int) = c >= 0 ? x >> unsigned(c) : x << unsigned(-c) | ||
| 644 | |||
| 645 | """ | ||
| 646 | >>>(x, n) | ||
| 647 | |||
| 648 | Unsigned right bit shift operator, `x >>> n`. For `n >= 0`, the result is `x` | ||
| 649 | shifted right by `n` bits, where `n >= 0`, filling with `0`s. For `n < 0`, this | ||
| 650 | is equivalent to `x << -n`. | ||
| 651 | |||
| 652 | For [`Unsigned`](@ref) integer types, this is equivalent to [`>>`](@ref). For | ||
| 653 | [`Signed`](@ref) integer types, this is equivalent to `signed(unsigned(x) >> n)`. | ||
| 654 | |||
| 655 | # Examples | ||
| 656 | ```jldoctest | ||
| 657 | julia> Int8(-14) >>> 2 | ||
| 658 | 60 | ||
| 659 | |||
| 660 | julia> bitstring(Int8(-14)) | ||
| 661 | "11110010" | ||
| 662 | |||
| 663 | julia> bitstring(Int8(60)) | ||
| 664 | "00111100" | ||
| 665 | ``` | ||
| 666 | |||
| 667 | [`BigInt`](@ref)s are treated as if having infinite size, so no filling is required and this | ||
| 668 | is equivalent to [`>>`](@ref). | ||
| 669 | |||
| 670 | See also [`>>`](@ref), [`<<`](@ref). | ||
| 671 | """ | ||
| 672 | function >>>(x::Integer, c::Integer) | ||
| 673 | @_inline_meta | ||
| 674 | typemin(Int) <= c <= typemax(Int) ? x >>> (c % Int) : zero(x) >>> 0 | ||
| 675 | end | ||
| 676 | function >>>(x::Integer, c::Unsigned) | ||
| 677 | @_inline_meta | ||
| 678 | if c isa UInt | ||
| 679 | throw(MethodError(>>>, (x, c))) | ||
| 680 | end | ||
| 681 | c <= typemax(UInt) ? x >>> (c % UInt) : zero(x) >>> 0 | ||
| 682 | end | ||
| 683 | >>>(x::Integer, c::Int) = c >= 0 ? x >>> unsigned(c) : x << unsigned(-c) | ||
| 684 | |||
| 685 | # operator alias | ||
| 686 | |||
| 687 | """ | ||
| 688 | rem(x, y) | ||
| 689 | %(x, y) | ||
| 690 | |||
| 691 | Remainder from Euclidean division, returning a value of the same sign as `x`, and smaller in | ||
| 692 | magnitude than `y`. This value is always exact. | ||
| 693 | |||
| 694 | # Examples | ||
| 695 | ```jldoctest | ||
| 696 | julia> x = 15; y = 4; | ||
| 697 | |||
| 698 | julia> x % y | ||
| 699 | 3 | ||
| 700 | |||
| 701 | julia> x == div(x, y) * y + rem(x, y) | ||
| 702 | true | ||
| 703 | ``` | ||
| 704 | """ | ||
| 705 | rem | ||
| 706 | const % = rem | ||
| 707 | |||
| 708 | """ | ||
| 709 | div(x, y) | ||
| 710 | ÷(x, y) | ||
| 711 | |||
| 712 | The quotient from Euclidean division. Computes `x/y`, truncated to an integer. | ||
| 713 | |||
| 714 | # Examples | ||
| 715 | ```jldoctest | ||
| 716 | julia> 9 ÷ 4 | ||
| 717 | 2 | ||
| 718 | |||
| 719 | julia> -5 ÷ 3 | ||
| 720 | -1 | ||
| 721 | |||
| 722 | julia> 5.0 ÷ 2 | ||
| 723 | 2.0 | ||
| 724 | ``` | ||
| 725 | """ | ||
| 726 | div | ||
| 727 | const ÷ = div | ||
| 728 | |||
| 729 | """ | ||
| 730 | mod1(x, y) | ||
| 731 | |||
| 732 | Modulus after flooring division, returning a value `r` such that `mod(r, y) == mod(x, y)` | ||
| 733 | in the range ``(0, y]`` for positive `y` and in the range ``[y,0)`` for negative `y`. | ||
| 734 | |||
| 735 | See also: [`fld1`](@ref), [`fldmod1`](@ref). | ||
| 736 | |||
| 737 | # Examples | ||
| 738 | ```jldoctest | ||
| 739 | julia> mod1(4, 2) | ||
| 740 | 2 | ||
| 741 | |||
| 742 | julia> mod1(4, 3) | ||
| 743 | 1 | ||
| 744 | ``` | ||
| 745 | """ | ||
| 746 | mod1(x::T, y::T) where {T<:Real} = (m = mod(x, y); ifelse(m == 0, y, m)) | ||
| 747 | |||
| 748 | |||
| 749 | """ | ||
| 750 | fld1(x, y) | ||
| 751 | |||
| 752 | Flooring division, returning a value consistent with `mod1(x,y)` | ||
| 753 | |||
| 754 | See also: [`mod1`](@ref), [`fldmod1`](@ref). | ||
| 755 | |||
| 756 | # Examples | ||
| 757 | ```jldoctest | ||
| 758 | julia> x = 15; y = 4; | ||
| 759 | |||
| 760 | julia> fld1(x, y) | ||
| 761 | 4 | ||
| 762 | |||
| 763 | julia> x == fld(x, y) * y + mod(x, y) | ||
| 764 | true | ||
| 765 | |||
| 766 | julia> x == (fld1(x, y) - 1) * y + mod1(x, y) | ||
| 767 | true | ||
| 768 | ``` | ||
| 769 | """ | ||
| 770 | fld1(x::T, y::T) where {T<:Real} = (m = mod1(x, y); fld(x + y - m, y)) | ||
| 771 | function fld1(x::T, y::T) where T<:Integer | ||
| 772 | d = div(x, y) | ||
| 773 | return d + (!signbit(x ⊻ y) & (d * y != x)) | ||
| 774 | end | ||
| 775 | |||
| 776 | """ | ||
| 777 | fldmod1(x, y) | ||
| 778 | |||
| 779 | Return `(fld1(x,y), mod1(x,y))`. | ||
| 780 | |||
| 781 | See also: [`fld1`](@ref), [`mod1`](@ref). | ||
| 782 | """ | ||
| 783 | fldmod1(x, y) = (fld1(x, y), mod1(x, y)) | ||
| 784 | |||
| 785 | |||
| 786 | """ | ||
| 787 | widen(x) | ||
| 788 | |||
| 789 | If `x` is a type, return a "larger" type, defined so that arithmetic operations | ||
| 790 | `+` and `-` are guaranteed not to overflow nor lose precision for any combination | ||
| 791 | of values that type `x` can hold. | ||
| 792 | |||
| 793 | For fixed-size integer types less than 128 bits, `widen` will return a type with | ||
| 794 | twice the number of bits. | ||
| 795 | |||
| 796 | If `x` is a value, it is converted to `widen(typeof(x))`. | ||
| 797 | |||
| 798 | # Examples | ||
| 799 | ```jldoctest | ||
| 800 | julia> widen(Int32) | ||
| 801 | Int64 | ||
| 802 | |||
| 803 | julia> widen(1.5f0) | ||
| 804 | 1.5 | ||
| 805 | ``` | ||
| 806 | """ | ||
| 807 | widen(x::T) where {T} = convert(widen(T), x) | ||
| 808 | widen(x::Type{T}) where {T} = throw(MethodError(widen, (T,))) | ||
| 809 | |||
| 810 | # function pipelining | ||
| 811 | |||
| 812 | """ | ||
| 813 | |>(x, f) | ||
| 814 | |||
| 815 | Applies a function to the preceding argument. This allows for easy function chaining. | ||
| 816 | |||
| 817 | # Examples | ||
| 818 | ```jldoctest | ||
| 819 | julia> [1:5;] |> x->x.^2 |> sum |> inv | ||
| 820 | 0.01818181818181818 | ||
| 821 | ``` | ||
| 822 | """ | ||
| 823 | |>(x, f) = f(x) | ||
| 824 | |||
| 825 | # function composition | ||
| 826 | |||
| 827 | """ | ||
| 828 | f ∘ g | ||
| 829 | |||
| 830 | Compose functions: i.e. `(f ∘ g)(args...)` means `f(g(args...))`. The `∘` symbol can be | ||
| 831 | entered in the Julia REPL (and most editors, appropriately configured) by typing `\\circ<tab>`. | ||
| 832 | |||
| 833 | Function composition also works in prefix form: `∘(f, g)` is the same as `f ∘ g`. | ||
| 834 | The prefix form supports composition of multiple functions: `∘(f, g, h) = f ∘ g ∘ h` | ||
| 835 | and splatting `∘(fs...)` for composing an iterable collection of functions. | ||
| 836 | |||
| 837 | !!! compat "Julia 1.4" | ||
| 838 | Multiple function composition requires at least Julia 1.4. | ||
| 839 | |||
| 840 | !!! compat "Julia 1.5" | ||
| 841 | Composition of one function ∘(f) requires at least Julia 1.5. | ||
| 842 | |||
| 843 | # Examples | ||
| 844 | ```jldoctest | ||
| 845 | julia> map(uppercase∘first, ["apple", "banana", "carrot"]) | ||
| 846 | 3-element Array{Char,1}: | ||
| 847 | 'A': ASCII/Unicode U+0041 (category Lu: Letter, uppercase) | ||
| 848 | 'B': ASCII/Unicode U+0042 (category Lu: Letter, uppercase) | ||
| 849 | 'C': ASCII/Unicode U+0043 (category Lu: Letter, uppercase) | ||
| 850 | |||
| 851 | julia> fs = [ | ||
| 852 | x -> 2x | ||
| 853 | x -> x/2 | ||
| 854 | x -> x-1 | ||
| 855 | x -> x+1 | ||
| 856 | ]; | ||
| 857 | |||
| 858 | julia> ∘(fs...)(3) | ||
| 859 | 3.0 | ||
| 860 | ``` | ||
| 861 | """ | ||
| 862 | function ∘ end | ||
| 863 | ∘(f) = f | ||
| 864 | ∘(f, g) = (x...)->f(g(x...)) | ||
| 865 | ∘(f, g, h...) = ∘(f ∘ g, h...) | ||
| 866 | |||
| 867 | """ | ||
| 868 | !f::Function | ||
| 869 | |||
| 870 | Predicate function negation: when the argument of `!` is a function, it returns a | ||
| 871 | function which computes the boolean negation of `f`. | ||
| 872 | |||
| 873 | # Examples | ||
| 874 | ```jldoctest | ||
| 875 | julia> str = "∀ ε > 0, ∃ δ > 0: |x-y| < δ ⇒ |f(x)-f(y)| < ε" | ||
| 876 | "∀ ε > 0, ∃ δ > 0: |x-y| < δ ⇒ |f(x)-f(y)| < ε" | ||
| 877 | |||
| 878 | julia> filter(isletter, str) | ||
| 879 | "εδxyδfxfyε" | ||
| 880 | |||
| 881 | julia> filter(!isletter, str) | ||
| 882 | "∀ > 0, ∃ > 0: |-| < ⇒ |()-()| < " | ||
| 883 | ``` | ||
| 884 | """ | ||
| 885 | !(f::Function) = (x...)->!f(x...) | ||
| 886 | |||
| 887 | """ | ||
| 888 | Fix1(f, x) | ||
| 889 | |||
| 890 | A type representing a partially-applied version of the two-argument function | ||
| 891 | `f`, with the first argument fixed to the value "x". In other words, | ||
| 892 | `Fix1(f, x)` behaves similarly to `y->f(x, y)`. | ||
| 893 | """ | ||
| 894 | struct Fix1{F,T} <: Function | ||
| 895 | f::F | ||
| 896 | x::T | ||
| 897 | |||
| 898 | Fix1(f::F, x::T) where {F,T} = new{F,T}(f, x) | ||
| 899 | Fix1(f::Type{F}, x::T) where {F,T} = new{Type{F},T}(f, x) | ||
| 900 | end | ||
| 901 | |||
| 902 | (f::Fix1)(y) = f.f(f.x, y) | ||
| 903 | |||
| 904 | """ | ||
| 905 | Fix2(f, x) | ||
| 906 | |||
| 907 | A type representing a partially-applied version of the two-argument function | ||
| 908 | `f`, with the second argument fixed to the value "x". In other words, | ||
| 909 | `Fix2(f, x)` behaves similarly to `y->f(y, x)`. | ||
| 910 | """ | ||
| 911 | struct Fix2{F,T} <: Function | ||
| 912 | f::F | ||
| 913 | x::T | ||
| 914 | |||
| 915 | Fix2(f::F, x::T) where {F,T} = new{F,T}(f, x) | ||
| 916 | Fix2(f::Type{F}, x::T) where {F,T} = new{Type{F},T}(f, x) | ||
| 917 | end | ||
| 918 | |||
| 919 | (f::Fix2)(y) = f.f(y, f.x) | ||
| 920 | |||
| 921 | """ | ||
| 922 | isequal(x) | ||
| 923 | |||
| 924 | Create a function that compares its argument to `x` using [`isequal`](@ref), i.e. | ||
| 925 | a function equivalent to `y -> isequal(y, x)`. | ||
| 926 | |||
| 927 | The returned function is of type `Base.Fix2{typeof(isequal)}`, which can be | ||
| 928 | used to implement specialized methods. | ||
| 929 | """ | ||
| 930 | isequal(x) = Fix2(isequal, x) | ||
| 931 | |||
| 932 | """ | ||
| 933 | ==(x) | ||
| 934 | |||
| 935 | Create a function that compares its argument to `x` using [`==`](@ref), i.e. | ||
| 936 | a function equivalent to `y -> y == x`. | ||
| 937 | |||
| 938 | The returned function is of type `Base.Fix2{typeof(==)}`, which can be | ||
| 939 | used to implement specialized methods. | ||
| 940 | """ | ||
| 941 | ==(x) = Fix2(==, x) | ||
| 942 | |||
| 943 | """ | ||
| 944 | !=(x) | ||
| 945 | |||
| 946 | Create a function that compares its argument to `x` using [`!=`](@ref), i.e. | ||
| 947 | a function equivalent to `y -> y != x`. | ||
| 948 | The returned function is of type `Base.Fix2{typeof(!=)}`, which can be | ||
| 949 | used to implement specialized methods. | ||
| 950 | |||
| 951 | !!! compat "Julia 1.2" | ||
| 952 | This functionality requires at least Julia 1.2. | ||
| 953 | """ | ||
| 954 | !=(x) = Fix2(!=, x) | ||
| 955 | |||
| 956 | """ | ||
| 957 | >=(x) | ||
| 958 | |||
| 959 | Create a function that compares its argument to `x` using [`>=`](@ref), i.e. | ||
| 960 | a function equivalent to `y -> y >= x`. | ||
| 961 | The returned function is of type `Base.Fix2{typeof(>=)}`, which can be | ||
| 962 | used to implement specialized methods. | ||
| 963 | |||
| 964 | !!! compat "Julia 1.2" | ||
| 965 | This functionality requires at least Julia 1.2. | ||
| 966 | """ | ||
| 967 | >=(x) = Fix2(>=, x) | ||
| 968 | |||
| 969 | """ | ||
| 970 | <=(x) | ||
| 971 | |||
| 972 | Create a function that compares its argument to `x` using [`<=`](@ref), i.e. | ||
| 973 | a function equivalent to `y -> y <= x`. | ||
| 974 | The returned function is of type `Base.Fix2{typeof(<=)}`, which can be | ||
| 975 | used to implement specialized methods. | ||
| 976 | |||
| 977 | !!! compat "Julia 1.2" | ||
| 978 | This functionality requires at least Julia 1.2. | ||
| 979 | """ | ||
| 980 | <=(x) = Fix2(<=, x) | ||
| 981 | |||
| 982 | """ | ||
| 983 | >(x) | ||
| 984 | |||
| 985 | Create a function that compares its argument to `x` using [`>`](@ref), i.e. | ||
| 986 | a function equivalent to `y -> y > x`. | ||
| 987 | The returned function is of type `Base.Fix2{typeof(>)}`, which can be | ||
| 988 | used to implement specialized methods. | ||
| 989 | |||
| 990 | !!! compat "Julia 1.2" | ||
| 991 | This functionality requires at least Julia 1.2. | ||
| 992 | """ | ||
| 993 | >(x) = Fix2(>, x) | ||
| 994 | |||
| 995 | """ | ||
| 996 | <(x) | ||
| 997 | |||
| 998 | Create a function that compares its argument to `x` using [`<`](@ref), i.e. | ||
| 999 | a function equivalent to `y -> y < x`. | ||
| 1000 | The returned function is of type `Base.Fix2{typeof(<)}`, which can be | ||
| 1001 | used to implement specialized methods. | ||
| 1002 | |||
| 1003 | !!! compat "Julia 1.2" | ||
| 1004 | This functionality requires at least Julia 1.2. | ||
| 1005 | """ | ||
| 1006 | <(x) = Fix2(<, x) | ||
| 1007 | |||
| 1008 | """ | ||
| 1009 | splat(f) | ||
| 1010 | |||
| 1011 | Defined as | ||
| 1012 | ```julia | ||
| 1013 | splat(f) = args->f(args...) | ||
| 1014 | ``` | ||
| 1015 | i.e. given a function returns a new function that takes one argument and splats | ||
| 1016 | its argument into the original function. This is useful as an adaptor to pass | ||
| 1017 | a multi-argument function in a context that expects a single argument, but | ||
| 1018 | passes a tuple as that single argument. | ||
| 1019 | |||
| 1020 | # Example usage: | ||
| 1021 | ```jldoctest | ||
| 1022 | julia> map(Base.splat(+), zip(1:3,4:6)) | ||
| 1023 | 3-element Array{Int64,1}: | ||
| 1024 | 5 | ||
| 1025 | 7 | ||
| 1026 | 9 | ||
| 1027 | ``` | ||
| 1028 | """ | ||
| 1029 | splat(f) = args->f(args...) | ||
| 1030 | |||
| 1031 | ## in & contains | ||
| 1032 | |||
| 1033 | """ | ||
| 1034 | in(x) | ||
| 1035 | |||
| 1036 | Create a function that checks whether its argument is [`in`](@ref) `x`, i.e. | ||
| 1037 | a function equivalent to `y -> y in x`. | ||
| 1038 | |||
| 1039 | The returned function is of type `Base.Fix2{typeof(in)}`, which can be | ||
| 1040 | used to implement specialized methods. | ||
| 1041 | """ | ||
| 1042 | in(x) = Fix2(in, x) | ||
| 1043 | |||
| 1044 | function in(x, itr) | ||
| 1045 | anymissing = false | ||
| 1046 | for y in itr | ||
| 1047 | v = (y == x) | ||
| 1048 | if ismissing(v) | ||
| 1049 | anymissing = true | ||
| 1050 | elseif v | ||
| 1051 | return true | ||
| 1052 | end | ||
| 1053 | end | ||
| 1054 | return anymissing ? missing : false | ||
| 1055 | end | ||
| 1056 | |||
| 1057 | const ∈ = in | ||
| 1058 | ∋(itr, x) = ∈(x, itr) | ||
| 1059 | ∉(x, itr) = !∈(x, itr) | ||
| 1060 | ∌(itr, x) = !∋(itr, x) | ||
| 1061 | |||
| 1062 | """ | ||
| 1063 | in(item, collection) -> Bool | ||
| 1064 | ∈(item, collection) -> Bool | ||
| 1065 | ∋(collection, item) -> Bool | ||
| 1066 | |||
| 1067 | Determine whether an item is in the given collection, in the sense that it is | ||
| 1068 | [`==`](@ref) to one of the values generated by iterating over the collection. | ||
| 1069 | Returns a `Bool` value, except if `item` is [`missing`](@ref) or `collection` | ||
| 1070 | contains `missing` but not `item`, in which case `missing` is returned | ||
| 1071 | ([three-valued logic](https://en.wikipedia.org/wiki/Three-valued_logic), | ||
| 1072 | matching the behavior of [`any`](@ref) and [`==`](@ref)). | ||
| 1073 | |||
| 1074 | Some collections follow a slightly different definition. For example, | ||
| 1075 | [`Set`](@ref)s check whether the item [`isequal`](@ref) to one of the elements. | ||
| 1076 | [`Dict`](@ref)s look for `key=>value` pairs, and the key is compared using | ||
| 1077 | [`isequal`](@ref). To test for the presence of a key in a dictionary, | ||
| 1078 | use [`haskey`](@ref) or `k in keys(dict)`. For these collections, the result | ||
| 1079 | is always a `Bool` and never `missing`. | ||
| 1080 | |||
| 1081 | To determine whether an item is not in a given collection, see [`:∉`](@ref). | ||
| 1082 | You may also negate the `in` by doing `!(a in b)` which is logically similar to "not in". | ||
| 1083 | |||
| 1084 | # Examples | ||
| 1085 | ```jldoctest | ||
| 1086 | julia> a = 1:3:20 | ||
| 1087 | 1:3:19 | ||
| 1088 | |||
| 1089 | julia> 4 in a | ||
| 1090 | true | ||
| 1091 | |||
| 1092 | julia> 5 in a | ||
| 1093 | false | ||
| 1094 | |||
| 1095 | julia> missing in [1, 2] | ||
| 1096 | missing | ||
| 1097 | |||
| 1098 | julia> 1 in [2, missing] | ||
| 1099 | missing | ||
| 1100 | |||
| 1101 | julia> 1 in [1, missing] | ||
| 1102 | true | ||
| 1103 | |||
| 1104 | julia> missing in Set([1, 2]) | ||
| 1105 | false | ||
| 1106 | |||
| 1107 | julia> !(21 in a) | ||
| 1108 | true | ||
| 1109 | |||
| 1110 | julia> !(19 in a) | ||
| 1111 | false | ||
| 1112 | ``` | ||
| 1113 | """ | ||
| 1114 | in, ∋ | ||
| 1115 | |||
| 1116 | """ | ||
| 1117 | ∉(item, collection) -> Bool | ||
| 1118 | ∌(collection, item) -> Bool | ||
| 1119 | |||
| 1120 | Negation of `∈` and `∋`, i.e. checks that `item` is not in `collection`. | ||
| 1121 | |||
| 1122 | # Examples | ||
| 1123 | ```jldoctest | ||
| 1124 | julia> 1 ∉ 2:4 | ||
| 1125 | true | ||
| 1126 | |||
| 1127 | julia> 1 ∉ 1:3 | ||
| 1128 | false | ||
| 1129 | ``` | ||
| 1130 | """ | ||
| 1131 | ∉, ∌ |