StatProfilerHTML.jl report
Generated on tor 10 okt 2019 11:38:33
File source code
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 const (>:)(@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 canonical total order. Values that are
136 normally unordered, such as `NaN`, are ordered in an arbitrary but consistent fashion.
137 [`missing`](@ref) values are ordered last.
138
139 This is the default comparison used by [`sort`](@ref).
140
141 # Implementation
142 Non-numeric types with a canonical total order should implement this function.
143 Numeric types only need to implement it if they have special values such as `NaN`.
144 Types with a canonical partial order should implement [`<`](@ref).
145 """
146 function isless end
147
148 isless(x::AbstractFloat, y::AbstractFloat) = (!isnan(x) & (isnan(y) | signless(x, y))) | (x < y)
149 isless(x::Real, y::AbstractFloat) = (!isnan(x) & (isnan(y) | signless(x, y))) | (x < y)
150 isless(x::AbstractFloat, y::Real ) = (!isnan(x) & (isnan(y) | signless(x, y))) | (x < y)
151
152
153 function ==(T::Type, S::Type)
154 @_pure_meta
155 T<:S && S<:T
156 end
157 function !=(T::Type, S::Type)
158 @_pure_meta
159 !(T == S)
160 end
161 ==(T::TypeVar, S::Type) = false
162 ==(T::Type, S::TypeVar) = false
163
164 ## comparison fallbacks ##
165
166 """
167 !=(x, y)
168 ≠(x,y)
169
170 Not-equals comparison operator. Always gives the opposite answer as [`==`](@ref).
171
172 # Implementation
173 New types should generally not implement this, and rely on the fallback definition
174 `!=(x,y) = !(x==y)` instead.
175
176 # Examples
177 ```jldoctest
178 julia> 3 != 2
179 true
180
181 julia> "foo" ≠ "foo"
182 false
183 ```
184 """
185 !=(x, y) = !(x == y)
186 const ≠ = !=
187
188 """
189 ===(x,y) -> Bool
190 ≡(x,y) -> Bool
191
192 Determine whether `x` and `y` are identical, in the sense that no program could distinguish
193 them. First the types of `x` and `y` are compared. If those are identical, mutable objects
194 are compared by address in memory and immutable objects (such as numbers) are compared by
195 contents at the bit level. This function is sometimes called "egal".
196 It always returns a `Bool` value.
197
198 # Examples
199 ```jldoctest
200 julia> a = [1, 2]; b = [1, 2];
201
202 julia> a == b
203 true
204
205 julia> a === b
206 false
207
208 julia> a === a
209 true
210 ```
211 """
212 ===
213 const ≡ = ===
214
215 """
216 !==(x, y)
217 ≢(x,y)
218
219 Always gives the opposite answer as [`===`](@ref).
220
221 # Examples
222 ```jldoctest
223 julia> a = [1, 2]; b = [1, 2];
224
225 julia> a ≢ b
226 true
227
228 julia> a ≢ a
229 false
230 ```
231 """
232 !==(@nospecialize(x), @nospecialize(y)) = !(x === y)
233 const ≢ = !==
234
235 """
236 <(x, y)
237
238 Less-than comparison operator. Falls back to [`isless`](@ref).
239 Because of the behavior of floating-point NaN values, this operator implements
240 a partial order.
241
242 # Implementation
243 New numeric types with a canonical partial order should implement this function for
244 two arguments of the new type.
245 Types with a canonical total order should implement [`isless`](@ref) instead.
246 (x < y) | (x == y)
247
248 # Examples
249 ```jldoctest
250 julia> 'a' < 'b'
251 true
252
253 julia> "abc" < "abd"
254 true
255
256 julia> 5 < 3
257 false
258 ```
259 """
260 <(x, y) = isless(x, y)
261
262 """
263 >(x, y)
264
265 Greater-than comparison operator. Falls back to `y < x`.
266
267 # Implementation
268 Generally, new types should implement [`<`](@ref) instead of this function,
269 and rely on the fallback definition `>(x, y) = y < x`.
270
271 # Examples
272 ```jldoctest
273 julia> 'a' > 'b'
274 false
275
276 julia> 7 > 3 > 1
277 true
278
279 julia> "abc" > "abd"
280 false
281
282 julia> 5 > 3
283 true
284 ```
285 """
286 1 (2.38%)
1 (2.38%) samples spent in >
0 (ex.), 1 (100.00%) (incl.) when called from unsafe_write line 407
1 (100.00%) samples spent calling <
>(x, y) = y < x
287
288 """
289 <=(x, y)
290 ≤(x,y)
291
292 Less-than-or-equals comparison operator. Falls back to `(x < y) | (x == y)`.
293
294 # Examples
295 ```jldoctest
296 julia> 'a' <= 'b'
297 true
298
299 julia> 7 ≤ 7 ≤ 9
300 true
301
302 julia> "abc" ≤ "abc"
303 true
304
305 julia> 5 <= 3
306 false
307 ```
308 """
309 <=(x, y) = (x < y) | (x == y)
310 const ≤ = <=
311
312 """
313 >=(x, y)
314 ≥(x,y)
315
316 Greater-than-or-equals comparison operator. Falls back to `y <= x`.
317
318 # Examples
319 ```jldoctest
320 julia> 'a' >= 'b'
321 false
322
323 julia> 7 ≥ 7 ≥ 3
324 true
325
326 julia> "abc" ≥ "abc"
327 true
328
329 julia> 5 >= 3
330 true
331 ```
332 """
333 >=(x, y) = (y <= x)
334 const ≥ = >=
335
336 # this definition allows Number types to implement < instead of isless,
337 # which is more idiomatic:
338 isless(x::Real, y::Real) = x<y
339
340 """
341 ifelse(condition::Bool, x, y)
342
343 Return `x` if `condition` is `true`, otherwise return `y`. This differs from `?` or `if` in
344 that it is an ordinary function, so all the arguments are evaluated first. In some cases,
345 using `ifelse` instead of an `if` statement can eliminate the branch in generated code and
346 provide higher performance in tight loops.
347
348 # Examples
349 ```jldoctest
350 julia> ifelse(1 > 2, 1, 2)
351 2
352 ```
353 """
354 ifelse
355
356 """
357 cmp(x,y)
358
359 Return -1, 0, or 1 depending on whether `x` is less than, equal to, or greater than `y`,
360 respectively. Uses the total order implemented by `isless`.
361
362 # Examples
363 ```jldoctest
364 julia> cmp(1, 2)
365 -1
366
367 julia> cmp(2, 1)
368 1
369
370 julia> cmp(2+im, 3-im)
371 ERROR: MethodError: no method matching isless(::Complex{Int64}, ::Complex{Int64})
372 [...]
373 ```
374 """
375 cmp(x, y) = isless(x, y) ? -1 : ifelse(isless(y, x), 1, 0)
376
377 """
378 cmp(<, x, y)
379
380 Return -1, 0, or 1 depending on whether `x` is less than, equal to, or greater than `y`,
381 respectively. The first argument specifies a less-than comparison function to use.
382 """
383 cmp(<, x, y) = (x < y) ? -1 : ifelse(y < x, 1, 0)
384
385 # cmp returns -1, 0, +1 indicating ordering
386 cmp(x::Integer, y::Integer) = ifelse(isless(x, y), -1, ifelse(isless(y, x), 1, 0))
387
388 """
389 max(x, y, ...)
390
391 Return the maximum of the arguments. See also the [`maximum`](@ref) function
392 to take the maximum element from a collection.
393
394 # Examples
395 ```jldoctest
396 julia> max(2, 5, 1)
397 5
398 ```
399 """
400 max(x, y) = ifelse(isless(y, x), x, y)
401
402 """
403 min(x, y, ...)
404
405 Return the minimum of the arguments. See also the [`minimum`](@ref) function
406 to take the minimum element from a collection.
407
408 # Examples
409 ```jldoctest
410 julia> min(2, 5, 1)
411 1
412 ```
413 """
414 min(x,y) = ifelse(isless(y, x), y, x)
415
416 """
417 minmax(x, y)
418
419 Return `(min(x,y), max(x,y))`. See also: [`extrema`](@ref) that returns `(minimum(x), maximum(x))`.
420
421 # Examples
422 ```jldoctest
423 julia> minmax('c','b')
424 ('b', 'c')
425 ```
426 """
427 minmax(x,y) = isless(y, x) ? (y, x) : (x, y)
428
429 """
430 extrema(itr) -> Tuple
431
432 Compute both the minimum and maximum element in a single pass, and return them as a 2-tuple.
433
434 # Examples
435 ```jldoctest
436 julia> extrema(2:10)
437 (2, 10)
438
439 julia> extrema([9,pi,4.5])
440 (3.141592653589793, 9.0)
441 ```
442 """
443 extrema(itr) = _extrema_itr(itr)
444
445 function _extrema_itr(itr)
446 y = iterate(itr)
447 y === nothing && throw(ArgumentError("collection must be non-empty"))
448 (v, s) = y
449 vmin = vmax = v
450 while true
451 y = iterate(itr, s)
452 y === nothing && break
453 (x, s) = y
454 vmax = max(x, vmax)
455 vmin = min(x, vmin)
456 end
457 return (vmin, vmax)
458 end
459
460 extrema(x::Real) = (x, x)
461
462 ## definitions providing basic traits of arithmetic operators ##
463
464 """
465 identity(x)
466
467 The identity function. Returns its argument.
468
469 # Examples
470 ```jldoctest
471 julia> identity("Well, what did you expect?")
472 "Well, what did you expect?"
473 ```
474 """
475 identity(x) = x
476
477 +(x::Number) = x
478 *(x::Number) = x
479 (&)(x::Integer) = x
480 (|)(x::Integer) = x
481 xor(x::Integer) = x
482
483 const ⊻ = xor
484
485 # foldl for argument lists. expand recursively up to a point, then
486 # switch to a loop. this allows small cases like `a+b+c+d` to be inlined
487 # efficiently, without a major slowdown for `+(x...)` when `x` is big.
488 afoldl(op,a) = a
489 afoldl(op,a,b) = op(a,b)
490 afoldl(op,a,b,c...) = afoldl(op, op(a,b), c...)
491 function afoldl(op,a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,qs...)
492 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)
493 for x in qs; y = op(y,x); end
494 y
495 end
496
497 for op in (:+, :*, :&, :|, :xor, :min, :max, :kron)
498 @eval begin
499 # note: these definitions must not cause a dispatch loop when +(a,b) is
500 # not defined, and must only try to call 2-argument definitions, so
501 # that defining +(a,b) is sufficient for full functionality.
502 ($op)(a, b, c, xs...) = afoldl($op, ($op)(($op)(a,b),c), xs...)
503 # a further concern is that it's easy for a type like (Int,Int...)
504 # to match many definitions, so we need to keep the number of
505 # definitions down to avoid losing type information.
506 end
507 end
508
509 """
510 \\(x, y)
511
512 Left division operator: multiplication of `y` by the inverse of `x` on the left. Gives
513 floating-point results for integer arguments.
514
515 # Examples
516 ```jldoctest
517 julia> 3 \\ 6
518 2.0
519
520 julia> inv(3) * 6
521 2.0
522
523 julia> A = [4 3; 2 1]; x = [5, 6];
524
525 julia> A \\ x
526 2-element Array{Float64,1}:
527 6.5
528 -7.0
529
530 julia> inv(A) * x
531 2-element Array{Float64,1}:
532 6.5
533 -7.0
534 ```
535 """
536 \(x,y) = adjoint(adjoint(y)/adjoint(x))
537
538 # Core <<, >>, and >>> take either Int or UInt as second arg. Signed shift
539 # counts can shift in either direction, and are translated here to unsigned
540 # counts. Integer datatypes only need to implement the unsigned version.
541
542 """
543 <<(x, n)
544
545 Left bit shift operator, `x << n`. For `n >= 0`, the result is `x` shifted left
546 by `n` bits, filling with `0`s. This is equivalent to `x * 2^n`. For `n < 0`,
547 this is equivalent to `x >> -n`.
548
549 # Examples
550 ```jldoctest
551 julia> Int8(3) << 2
552 12
553
554 julia> bitstring(Int8(3))
555 "00000011"
556
557 julia> bitstring(Int8(12))
558 "00001100"
559 ```
560 See also [`>>`](@ref), [`>>>`](@ref).
561 """
562 function <<(x::Integer, c::Integer)
563 @_inline_meta
564 typemin(Int) <= c <= typemax(Int) && return x << (c % Int)
565 (x >= 0 || c >= 0) && return zero(x)
566 oftype(x, -1)
567 end
568 <<(x::Integer, c::Unsigned) = c <= typemax(UInt) ? x << (c % UInt) : zero(x)
569 <<(x::Integer, c::Int) = c >= 0 ? x << unsigned(c) : x >> unsigned(-c)
570
571 """
572 >>(x, n)
573
574 Right bit shift operator, `x >> n`. For `n >= 0`, the result is `x` shifted
575 right by `n` bits, where `n >= 0`, filling with `0`s if `x >= 0`, `1`s if `x <
576 0`, preserving the sign of `x`. This is equivalent to `fld(x, 2^n)`. For `n <
577 0`, this is equivalent to `x << -n`.
578
579 # Examples
580 ```jldoctest
581 julia> Int8(13) >> 2
582 3
583
584 julia> bitstring(Int8(13))
585 "00001101"
586
587 julia> bitstring(Int8(3))
588 "00000011"
589
590 julia> Int8(-14) >> 2
591 -4
592
593 julia> bitstring(Int8(-14))
594 "11110010"
595
596 julia> bitstring(Int8(-4))
597 "11111100"
598 ```
599 See also [`>>>`](@ref), [`<<`](@ref).
600 """
601 function >>(x::Integer, c::Integer)
602 @_inline_meta
603 1 (2.38%)
1 (2.38%) samples spent in >>
0 (ex.), 1 (100.00%) (incl.) when called from digitgen line 92
1 (100.00%) samples spent calling >>
typemin(Int) <= c <= typemax(Int) && return x >> (c % Int)
604 (x >= 0 || c < 0) && return zero(x)
605 oftype(x, -1)
606 end
607 >>(x::Integer, c::Unsigned) = c <= typemax(UInt) ? x >> (c % UInt) : zero(x)
608 >>(x::Integer, c::Int) = c >= 0 ? x >> unsigned(c) : x << unsigned(-c)
609
610 """
611 >>>(x, n)
612
613 Unsigned right bit shift operator, `x >>> n`. For `n >= 0`, the result is `x`
614 shifted right by `n` bits, where `n >= 0`, filling with `0`s. For `n < 0`, this
615 is equivalent to `x << -n`.
616
617 For [`Unsigned`](@ref) integer types, this is equivalent to [`>>`](@ref). For
618 [`Signed`](@ref) integer types, this is equivalent to `signed(unsigned(x) >> n)`.
619
620 # Examples
621 ```jldoctest
622 julia> Int8(-14) >>> 2
623 60
624
625 julia> bitstring(Int8(-14))
626 "11110010"
627
628 julia> bitstring(Int8(60))
629 "00111100"
630 ```
631
632 [`BigInt`](@ref)s are treated as if having infinite size, so no filling is required and this
633 is equivalent to [`>>`](@ref).
634
635 See also [`>>`](@ref), [`<<`](@ref).
636 """
637 function >>>(x::Integer, c::Integer)
638 @_inline_meta
639 typemin(Int) <= c <= typemax(Int) ? x >>> (c % Int) : zero(x)
640 end
641 >>>(x::Integer, c::Unsigned) = c <= typemax(UInt) ? x >>> (c % UInt) : zero(x)
642 >>>(x::Integer, c::Int) = c >= 0 ? x >>> unsigned(c) : x << unsigned(-c)
643
644 # fallback div, fld, and cld implementations
645 # NOTE: C89 fmod() and x87 FPREM implicitly provide truncating float division,
646 # so it is used here as the basis of float div().
647 div(x::T, y::T) where {T<:Real} = convert(T,round((x-rem(x,y))/y))
648
649 """
650 fld(x, y)
651
652 Largest integer less than or equal to `x/y`.
653
654 # Examples
655 ```jldoctest
656 julia> fld(7.3,5.5)
657 1.0
658 ```
659 """
660 fld(x::T, y::T) where {T<:Real} = convert(T,round((x-mod(x,y))/y))
661
662 """
663 cld(x, y)
664
665 Smallest integer larger than or equal to `x/y`.
666
667 # Examples
668 ```jldoctest
669 julia> cld(5.5,2.2)
670 3.0
671 ```
672 """
673 cld(x::T, y::T) where {T<:Real} = convert(T,round((x-modCeil(x,y))/y))
674 #rem(x::T, y::T) where {T<:Real} = convert(T,x-y*trunc(x/y))
675 #mod(x::T, y::T) where {T<:Real} = convert(T,x-y*floor(x/y))
676 modCeil(x::T, y::T) where {T<:Real} = convert(T,x-y*ceil(x/y))
677
678 # operator alias
679
680 """
681 rem(x, y)
682 %(x, y)
683
684 Remainder from Euclidean division, returning a value of the same sign as `x`, and smaller in
685 magnitude than `y`. This value is always exact.
686
687 # Examples
688 ```jldoctest
689 julia> x = 15; y = 4;
690
691 julia> x % y
692 3
693
694 julia> x == div(x, y) * y + rem(x, y)
695 true
696 ```
697 """
698 rem
699 const % = rem
700
701 """
702 div(x, y)
703 ÷(x, y)
704
705 The quotient from Euclidean division. Computes `x/y`, truncated to an integer.
706
707 # Examples
708 ```jldoctest
709 julia> 9 ÷ 4
710 2
711
712 julia> -5 ÷ 3
713 -1
714 ```
715 """
716 div
717 const ÷ = div
718
719 """
720 mod1(x, y)
721
722 Modulus after flooring division, returning a value `r` such that `mod(r, y) == mod(x, y)`
723 in the range ``(0, y]`` for positive `y` and in the range ``[y,0)`` for negative `y`.
724
725 See also: [`fld1`](@ref), [`fldmod1`](@ref).
726
727 # Examples
728 ```jldoctest
729 julia> mod1(4, 2)
730 2
731
732 julia> mod1(4, 3)
733 1
734 ```
735 """
736 mod1(x::T, y::T) where {T<:Real} = (m = mod(x, y); ifelse(m == 0, y, m))
737
738
739 """
740 fld1(x, y)
741
742 Flooring division, returning a value consistent with `mod1(x,y)`
743
744 See also: [`mod1`](@ref), [`fldmod1`](@ref).
745
746 # Examples
747 ```jldoctest
748 julia> x = 15; y = 4;
749
750 julia> fld1(x, y)
751 4
752
753 julia> x == fld(x, y) * y + mod(x, y)
754 true
755
756 julia> x == (fld1(x, y) - 1) * y + mod1(x, y)
757 true
758 ```
759 """
760 fld1(x::T, y::T) where {T<:Real} = (m = mod1(x, y); fld(x + y - m, y))
761 function fld1(x::T, y::T) where T<:Integer
762 d = div(x, y)
763 return d + (!signbit(x ⊻ y) & (d * y != x))
764 end
765
766 """
767 fldmod1(x, y)
768
769 Return `(fld1(x,y), mod1(x,y))`.
770
771 See also: [`fld1`](@ref), [`mod1`](@ref).
772 """
773 fldmod1(x, y) = (fld1(x, y), mod1(x, y))
774
775
776 """
777 widen(x)
778
779 If `x` is a type, return a "larger" type, defined so that arithmetic operations
780 `+` and `-` are guaranteed not to overflow nor lose precision for any combination
781 of values that type `x` can hold.
782
783 For fixed-size integer types less than 128 bits, `widen` will return a type with
784 twice the number of bits.
785
786 If `x` is a value, it is converted to `widen(typeof(x))`.
787
788 # Examples
789 ```jldoctest
790 julia> widen(Int32)
791 Int64
792
793 julia> widen(1.5f0)
794 1.5
795 ```
796 """
797 widen(x::T) where {T} = convert(widen(T), x)
798 widen(x::Type{T}) where {T} = throw(MethodError(widen, (T,)))
799
800 # function pipelining
801
802 """
803 |>(x, f)
804
805 Applies a function to the preceding argument. This allows for easy function chaining.
806
807 # Examples
808 ```jldoctest
809 julia> [1:5;] |> x->x.^2 |> sum |> inv
810 0.01818181818181818
811 ```
812 """
813 |>(x, f) = f(x)
814
815 # function composition
816
817 """
818 f ∘ g
819
820 Compose functions: i.e. `(f ∘ g)(args...)` means `f(g(args...))`. The `∘` symbol can be
821 entered in the Julia REPL (and most editors, appropriately configured) by typing `\\circ<tab>`.
822
823 # Examples
824 ```jldoctest
825 julia> map(uppercase∘first, ["apple", "banana", "carrot"])
826 3-element Array{Char,1}:
827 'A'
828 'B'
829 'C'
830 ```
831 """
832 ∘(f, g) = (x...)->f(g(x...))
833
834
835 """
836 !f::Function
837
838 Predicate function negation: when the argument of `!` is a function, it returns a
839 function which computes the boolean negation of `f`.
840
841 # Examples
842 ```jldoctest
843 julia> str = "∀ ε > 0, ∃ δ > 0: |x-y| < δ ⇒ |f(x)-f(y)| < ε"
844 "∀ ε > 0, ∃ δ > 0: |x-y| < δ ⇒ |f(x)-f(y)| < ε"
845
846 julia> filter(isletter, str)
847 "εδxyδfxfyε"
848
849 julia> filter(!isletter, str)
850 "∀ > 0, ∃ > 0: |-| < ⇒ |()-()| < "
851 ```
852 """
853 !(f::Function) = (x...)->!f(x...)
854
855 """
856 Fix1(f, x)
857
858 A type representing a partially-applied version of the two-argument function
859 `f`, with the first argument fixed to the value "x". In other words,
860 `Fix1(f, x)` behaves similarly to `y->f(x, y)`.
861 """
862 struct Fix1{F,T} <: Function
863 f::F
864 x::T
865
866 Fix1(f::F, x::T) where {F,T} = new{F,T}(f, x)
867 Fix1(f::Type{F}, x::T) where {F,T} = new{Type{F},T}(f, x)
868 end
869
870 (f::Fix1)(y) = f.f(f.x, y)
871
872 """
873 Fix2(f, x)
874
875 A type representing a partially-applied version of the two-argument function
876 `f`, with the second argument fixed to the value "x". In other words,
877 `Fix2(f, x)` behaves similarly to `y->f(y, x)`.
878 """
879 struct Fix2{F,T} <: Function
880 f::F
881 x::T
882
883 Fix2(f::F, x::T) where {F,T} = new{F,T}(f, x)
884 Fix2(f::Type{F}, x::T) where {F,T} = new{Type{F},T}(f, x)
885 end
886
887 (f::Fix2)(y) = f.f(y, f.x)
888
889 """
890 isequal(x)
891
892 Create a function that compares its argument to `x` using [`isequal`](@ref), i.e.
893 a function equivalent to `y -> isequal(y, x)`.
894
895 The returned function is of type `Base.Fix2{typeof(isequal)}`, which can be
896 used to implement specialized methods.
897 """
898 isequal(x) = Fix2(isequal, x)
899
900 """
901 ==(x)
902
903 Create a function that compares its argument to `x` using [`==`](@ref), i.e.
904 a function equivalent to `y -> y == x`.
905
906 The returned function is of type `Base.Fix2{typeof(==)}`, which can be
907 used to implement specialized methods.
908 """
909 ==(x) = Fix2(==, x)
910
911 """
912 splat(f)
913
914 Defined as
915 ```julia
916 splat(f) = args->f(args...)
917 ```
918 i.e. given a function returns a new function that takes one argument and splats
919 its argument into the original function. This is useful as an adaptor to pass
920 a multi-argument function in a context that expects a single argument, but
921 passes a tuple as that single argument.
922
923 # Example usage:
924 ```jldoctest
925 julia> map(splat(+), zip(1:3,4:6))
926 3-element Array{Int64,1}:
927 5
928 7
929 9
930 ```
931 """
932 splat(f) = args->f(args...)
933
934 ## in & contains
935
936 """
937 in(x)
938
939 Create a function that checks whether its argument is [`in`](@ref) `x`, i.e.
940 a function equivalent to `y -> y in x`.
941
942 The returned function is of type `Base.Fix2{typeof(in)}`, which can be
943 used to implement specialized methods.
944 """
945 in(x) = Fix2(in, x)
946
947 function in(x, itr)
948 anymissing = false
949 for y in itr
950 v = (y == x)
951 if ismissing(v)
952 anymissing = true
953 elseif v
954 return true
955 end
956 end
957 return anymissing ? missing : false
958 end
959
960 const ∈ = in
961 ∋(itr, x) = ∈(x, itr)
962 ∉(x, itr) = !∈(x, itr)
963 ∌(itr, x) = !∋(itr, x)
964
965 """
966 in(item, collection) -> Bool
967 ∈(item, collection) -> Bool
968 ∋(collection, item) -> Bool
969
970 Determine whether an item is in the given collection, in the sense that it is
971 [`==`](@ref) to one of the values generated by iterating over the collection.
972 Returns a `Bool` value, except if `item` is [`missing`](@ref) or `collection`
973 contains `missing` but not `item`, in which case `missing` is returned
974 ([three-valued logic](https://en.wikipedia.org/wiki/Three-valued_logic),
975 matching the behavior of [`any`](@ref) and [`==`](@ref)).
976
977 Some collections follow a slightly different definition. For example,
978 [`Set`](@ref)s check whether the item [`isequal`](@ref) to one of the elements.
979 [`Dict`](@ref)s look for `key=>value` pairs, and the key is compared using
980 [`isequal`](@ref). To test for the presence of a key in a dictionary,
981 use [`haskey`](@ref) or `k in keys(dict)`. For these collections, the result
982 is always a `Bool` and never `missing`.
983
984 # Examples
985 ```jldoctest
986 julia> a = 1:3:20
987 1:3:19
988
989 julia> 4 in a
990 true
991
992 julia> 5 in a
993 false
994
995 julia> missing in [1, 2]
996 missing
997
998 julia> 1 in [2, missing]
999 missing
1000
1001 julia> 1 in [1, missing]
1002 true
1003
1004 julia> missing in Set([1, 2])
1005 false
1006 ```
1007 """
1008 in, ∋
1009
1010 """
1011 ∉(item, collection) -> Bool
1012 ∌(collection, item) -> Bool
1013
1014 Negation of `∈` and `∋`, i.e. checks that `item` is not in `collection`.
1015
1016 # Examples
1017 ```jldoctest
1018 julia> 1 ∉ 2:4
1019 true
1020
1021 julia> 1 ∉ 1:3
1022 false
1023 ```
1024 """
1025 ∉, ∌