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 (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 (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 | ∉, ∌ |