StatProfilerHTML.jl report
Generated on Thu, 21 Dec 2023 12:59:22
File source code
Line Exclusive Inclusive Code
1 # This file is a part of Julia. License is MIT: https://julialang.org/license
2
3 ## integer arithmetic ##
4
5 # The tuples and types that do not include 128 bit sizes are necessary to handle
6 # certain issues on 32-bit machines, and also to simplify promotion rules, as
7 # they are also used elsewhere where Int128/UInt128 support is separated out,
8 # such as in hashing2.jl
9
10 const BitSigned32_types = (Int8, Int16, Int32)
11 const BitUnsigned32_types = (UInt8, UInt16, UInt32)
12 const BitInteger32_types = (BitSigned32_types..., BitUnsigned32_types...)
13
14 const BitSigned64_types = (BitSigned32_types..., Int64)
15 const BitUnsigned64_types = (BitUnsigned32_types..., UInt64)
16 const BitInteger64_types = (BitSigned64_types..., BitUnsigned64_types...)
17
18 const BitSigned_types = (BitSigned64_types..., Int128)
19 const BitUnsigned_types = (BitUnsigned64_types..., UInt128)
20 const BitInteger_types = (BitSigned_types..., BitUnsigned_types...)
21
22 const BitSignedSmall_types = Int === Int64 ? ( Int8, Int16, Int32) : ( Int8, Int16)
23 const BitUnsignedSmall_types = Int === Int64 ? (UInt8, UInt16, UInt32) : (UInt8, UInt16)
24 const BitIntegerSmall_types = (BitSignedSmall_types..., BitUnsignedSmall_types...)
25
26 const BitSigned32 = Union{BitSigned32_types...}
27 const BitUnsigned32 = Union{BitUnsigned32_types...}
28 const BitInteger32 = Union{BitInteger32_types...}
29
30 const BitSigned64 = Union{BitSigned64_types...}
31 const BitUnsigned64 = Union{BitUnsigned64_types...}
32 const BitInteger64 = Union{BitInteger64_types...}
33
34 const BitSigned = Union{BitSigned_types...}
35 const BitUnsigned = Union{BitUnsigned_types...}
36 const BitInteger = Union{BitInteger_types...}
37
38 const BitSignedSmall = Union{BitSignedSmall_types...}
39 const BitUnsignedSmall = Union{BitUnsignedSmall_types...}
40 const BitIntegerSmall = Union{BitIntegerSmall_types...}
41
42 const BitSigned64T = Union{Type{Int8}, Type{Int16}, Type{Int32}, Type{Int64}}
43 const BitUnsigned64T = Union{Type{UInt8}, Type{UInt16}, Type{UInt32}, Type{UInt64}}
44
45 const BitIntegerType = Union{map(T->Type{T}, BitInteger_types)...}
46
47 # >> this use of `unsigned` is defined somewhere else << the docstring should migrate there
48 """
49 unsigned(T::Integer)
50
51 Convert an integer bitstype to the unsigned type of the same size.
52 # Examples
53 ```jldoctest
54 julia> unsigned(Int16)
55 UInt16
56 julia> unsigned(UInt64)
57 UInt64
58 ```
59 """ unsigned
60
61 """
62 signed(T::Integer)
63
64 Convert an integer bitstype to the signed type of the same size.
65 # Examples
66 ```jldoctest
67 julia> signed(UInt16)
68 Int16
69 julia> signed(UInt64)
70 Int64
71 ```
72 """
73 signed(::Type{Bool}) = Int
74 signed(::Type{UInt8}) = Int8
75 signed(::Type{UInt16}) = Int16
76 signed(::Type{UInt32}) = Int32
77 signed(::Type{UInt64}) = Int64
78 signed(::Type{UInt128}) = Int128
79 signed(::Type{T}) where {T<:Signed} = T
80
81 ## integer comparisons ##
82
83 9 (3 %) 9 (3 %)
9 (3 %) samples spent in <
9 (100 %) (ex.), 9 (100 %) (incl.) when called from macro expansion line 75
(<)(x::T, y::T) where {T<:BitSigned} = slt_int(x, y)
84
85 (-)(x::BitInteger) = neg_int(x)
86 (-)(x::T, y::T) where {T<:BitInteger} = sub_int(x, y)
87 13 (5 %) 13 (5 %)
13 (5 %) samples spent in +
13 (100 %) (ex.), 13 (100 %) (incl.) when called from macro expansion line 78
(+)(x::T, y::T) where {T<:BitInteger} = add_int(x, y)
88 (*)(x::T, y::T) where {T<:BitInteger} = mul_int(x, y)
89
90 negate(x) = -x
91 negate(x::Unsigned) = -convert(Signed, x)
92 #widenegate(x) = -convert(widen(signed(typeof(x))), x)
93
94 inv(x::Integer) = float(one(x)) / float(x)
95 (/)(x::T, y::T) where {T<:Integer} = float(x) / float(y)
96 # skip promotion for system integer types
97 (/)(x::BitInteger, y::BitInteger) = float(x) / float(y)
98
99 """
100 isodd(x::Number) -> Bool
101
102 Return `true` if `x` is an odd integer (that is, an integer not divisible by 2), and `false` otherwise.
103
104 !!! compat "Julia 1.7"
105 Non-`Integer` arguments require Julia 1.7 or later.
106
107 # Examples
108 ```jldoctest
109 julia> isodd(9)
110 true
111
112 julia> isodd(10)
113 false
114 ```
115 """
116 isodd(n::Number) = isreal(n) && isodd(real(n))
117 isodd(n::Real) = isinteger(n) && !iszero(rem(Integer(n), 2))
118
119 """
120 iseven(x::Number) -> Bool
121
122 Return `true` if `x` is an even integer (that is, an integer divisible by 2), and `false` otherwise.
123
124 !!! compat "Julia 1.7"
125 Non-`Integer` arguments require Julia 1.7 or later.
126
127 # Examples
128 ```jldoctest
129 julia> iseven(9)
130 false
131
132 julia> iseven(10)
133 true
134 ```
135 """
136 iseven(n::Number) = isreal(n) && iseven(real(n))
137 iseven(n::Real) = isinteger(n) && iszero(rem(Integer(n), 2))
138
139 signbit(x::Integer) = x < 0
140 signbit(x::Unsigned) = false
141
142 flipsign(x::T, y::T) where {T<:BitSigned} = flipsign_int(x, y)
143 flipsign(x::BitSigned, y::BitSigned) = flipsign_int(promote(x, y)...) % typeof(x)
144
145 flipsign(x::Signed, y::Float16) = flipsign(x, bitcast(Int16, y))
146 flipsign(x::Signed, y::Float32) = flipsign(x, bitcast(Int32, y))
147 flipsign(x::Signed, y::Float64) = flipsign(x, bitcast(Int64, y))
148 flipsign(x::Signed, y::Real) = flipsign(x, -oftype(x, signbit(y)))
149
150 copysign(x::Signed, y::Signed) = flipsign(x, x ⊻ y)
151 copysign(x::Signed, y::Float16) = copysign(x, bitcast(Int16, y))
152 copysign(x::Signed, y::Float32) = copysign(x, bitcast(Int32, y))
153 copysign(x::Signed, y::Float64) = copysign(x, bitcast(Int64, y))
154 copysign(x::Signed, y::Real) = copysign(x, -oftype(x, signbit(y)))
155
156 """
157 abs(x)
158
159 The absolute value of `x`.
160
161 When `abs` is applied to signed integers, overflow may occur,
162 resulting in the return of a negative value. This overflow occurs only
163 when `abs` is applied to the minimum representable value of a signed
164 integer. That is, when `x == typemin(typeof(x))`, `abs(x) == x < 0`,
165 not `-x` as might be expected.
166
167 See also: [`abs2`](@ref), [`unsigned`](@ref), [`sign`](@ref).
168
169 # Examples
170 ```jldoctest
171 julia> abs(-3)
172 3
173
174 julia> abs(1 + im)
175 1.4142135623730951
176
177 julia> abs.(Int8[-128 -127 -126 0 126 127]) # overflow at typemin(Int8)
178 1×6 Matrix{Int8}:
179 -128 127 126 0 126 127
180
181 julia> maximum(abs, [1, -2, 3, -4])
182 4
183 ```
184 """
185 function abs end
186
187 abs(x::Unsigned) = x
188 abs(x::Signed) = flipsign(x,x)
189
190 ~(n::Integer) = -n-1
191
192 """
193 unsigned(x)
194
195 Convert a number to an unsigned integer. If the argument is signed, it is reinterpreted as
196 unsigned without checking for negative values.
197
198 See also: [`signed`](@ref), [`sign`](@ref), [`signbit`](@ref).
199
200 # Examples
201 ```jldoctest
202 julia> unsigned(-2)
203 0xfffffffffffffffe
204
205 julia> unsigned(Int8(2))
206 0x02
207
208 julia> typeof(ans)
209 UInt8
210
211 julia> signed(unsigned(-2))
212 -2
213 ```
214 """
215 unsigned(x) = x % typeof(convert(Unsigned, zero(x)))
216 unsigned(x::BitSigned) = reinterpret(typeof(convert(Unsigned, zero(x))), x)
217
218 """
219 signed(x)
220
221 Convert a number to a signed integer. If the argument is unsigned, it is reinterpreted as
222 signed without checking for overflow.
223
224 See also: [`unsigned`](@ref), [`sign`](@ref), [`signbit`](@ref).
225 """
226 signed(x) = x % typeof(convert(Signed, zero(x)))
227 signed(x::BitUnsigned) = reinterpret(typeof(convert(Signed, zero(x))), x)
228
229 div(x::BitSigned, y::Unsigned) = flipsign(signed(div(unsigned(abs(x)), y)), x)
230 div(x::Unsigned, y::BitSigned) = unsigned(flipsign(signed(div(x, unsigned(abs(y)))), y))
231
232 rem(x::BitSigned, y::Unsigned) = flipsign(signed(rem(unsigned(abs(x)), y)), x)
233 rem(x::Unsigned, y::BitSigned) = rem(x, unsigned(abs(y)))
234
235 function divrem(x::BitSigned, y::Unsigned)
236 q, r = divrem(unsigned(abs(x)), y)
237 flipsign(signed(q), x), flipsign(signed(r), x)
238 end
239
240 function divrem(x::Unsigned, y::BitSigned)
241 q, r = divrem(x, unsigned(abs(y)))
242 unsigned(flipsign(signed(q), y)), r
243 end
244
245
246 """
247 mod(x, y)
248 rem(x, y, RoundDown)
249
250 The reduction of `x` modulo `y`, or equivalently, the remainder of `x` after floored
251 division by `y`, i.e. `x - y*fld(x,y)` if computed without intermediate rounding.
252
253 The result will have the same sign as `y`, and magnitude less than `abs(y)` (with some
254 exceptions, see note below).
255
256 !!! note
257
258 When used with floating point values, the exact result may not be representable by the
259 type, and so rounding error may occur. In particular, if the exact result is very
260 close to `y`, then it may be rounded to `y`.
261
262 See also: [`rem`](@ref), [`div`](@ref), [`fld`](@ref), [`mod1`](@ref), [`invmod`](@ref).
263
264 ```jldoctest
265 julia> mod(8, 3)
266 2
267
268 julia> mod(9, 3)
269 0
270
271 julia> mod(8.9, 3)
272 2.9000000000000004
273
274 julia> mod(eps(), 3)
275 2.220446049250313e-16
276
277 julia> mod(-eps(), 3)
278 3.0
279
280 julia> mod.(-5:5, 3)'
281 1×11 adjoint(::Vector{Int64}) with eltype Int64:
282 1 2 0 1 2 0 1 2 0 1 2
283 ```
284 """
285 function mod(x::T, y::T) where T<:Integer
286 y == -1 && return T(0) # avoid potential overflow in fld
287 return x - fld(x, y) * y
288 end
289 mod(x::BitSigned, y::Unsigned) = rem(y + unsigned(rem(x, y)), y)
290 mod(x::Unsigned, y::Signed) = rem(y + signed(rem(x, y)), y)
291 mod(x::T, y::T) where {T<:Unsigned} = rem(x, y)
292
293 # Don't promote integers for div/rem/mod since there is no danger of overflow,
294 # while there is a substantial performance penalty to 64-bit promotion.
295 div(x::T, y::T) where {T<:BitSigned64} = checked_sdiv_int(x, y)
296 rem(x::T, y::T) where {T<:BitSigned64} = checked_srem_int(x, y)
297 div(x::T, y::T) where {T<:BitUnsigned64} = checked_udiv_int(x, y)
298 rem(x::T, y::T) where {T<:BitUnsigned64} = checked_urem_int(x, y)
299
300 ## integer bitwise operations ##
301
302 """
303 ~(x)
304
305 Bitwise not.
306
307 See also: [`!`](@ref), [`&`](@ref), [`|`](@ref).
308
309 # Examples
310 ```jldoctest
311 julia> ~4
312 -5
313
314 julia> ~10
315 -11
316
317 julia> ~true
318 false
319 ```
320 """
321 (~)(x::BitInteger) = not_int(x)
322
323 """
324 x & y
325
326 Bitwise and. Implements [three-valued logic](https://en.wikipedia.org/wiki/Three-valued_logic),
327 returning [`missing`](@ref) if one operand is `missing` and the other is `true`. Add parentheses for
328 function application form: `(&)(x, y)`.
329
330 See also: [`|`](@ref), [`xor`](@ref), [`&&`](@ref).
331
332 # Examples
333 ```jldoctest
334 julia> 4 & 10
335 0
336
337 julia> 4 & 12
338 4
339
340 julia> true & missing
341 missing
342
343 julia> false & missing
344 false
345 ```
346 """
347 (&)(x::T, y::T) where {T<:BitInteger} = and_int(x, y)
348
349 """
350 x | y
351
352 Bitwise or. Implements [three-valued logic](https://en.wikipedia.org/wiki/Three-valued_logic),
353 returning [`missing`](@ref) if one operand is `missing` and the other is `false`.
354
355 See also: [`&`](@ref), [`xor`](@ref), [`||`](@ref).
356
357 # Examples
358 ```jldoctest
359 julia> 4 | 10
360 14
361
362 julia> 4 | 1
363 5
364
365 julia> true | missing
366 true
367
368 julia> false | missing
369 missing
370 ```
371 """
372 (|)(x::T, y::T) where {T<:BitInteger} = or_int(x, y)
373 xor(x::T, y::T) where {T<:BitInteger} = xor_int(x, y)
374
375 """
376 bswap(n)
377
378 Reverse the byte order of `n`.
379
380 (See also [`ntoh`](@ref) and [`hton`](@ref) to convert between the current native byte order and big-endian order.)
381
382 # Examples
383 ```jldoctest
384 julia> a = bswap(0x10203040)
385 0x40302010
386
387 julia> bswap(a)
388 0x10203040
389
390 julia> string(1, base = 2)
391 "1"
392
393 julia> string(bswap(1), base = 2)
394 "100000000000000000000000000000000000000000000000000000000"
395 ```
396 """
397 bswap(x::Union{Int8, UInt8, Bool}) = x
398 bswap(x::Union{Int16, UInt16, Int32, UInt32, Int64, UInt64, Int128, UInt128}) =
399 bswap_int(x)
400
401 """
402 count_ones(x::Integer) -> Integer
403
404 Number of ones in the binary representation of `x`.
405
406 # Examples
407 ```jldoctest
408 julia> count_ones(7)
409 3
410
411 julia> count_ones(Int32(-1))
412 32
413 ```
414 """
415 count_ones(x::BitInteger) = (ctpop_int(x) % Int)::Int
416
417 """
418 leading_zeros(x::Integer) -> Integer
419
420 Number of zeros leading the binary representation of `x`.
421
422 # Examples
423 ```jldoctest
424 julia> leading_zeros(Int32(1))
425 31
426 ```
427 """
428 leading_zeros(x::BitInteger) = (ctlz_int(x) % Int)::Int
429
430 """
431 trailing_zeros(x::Integer) -> Integer
432
433 Number of zeros trailing the binary representation of `x`.
434
435 # Examples
436 ```jldoctest
437 julia> trailing_zeros(2)
438 1
439 ```
440 """
441 trailing_zeros(x::BitInteger) = (cttz_int(x) % Int)::Int
442
443 """
444 count_zeros(x::Integer) -> Integer
445
446 Number of zeros in the binary representation of `x`.
447
448 # Examples
449 ```jldoctest
450 julia> count_zeros(Int32(2 ^ 16 - 1))
451 16
452
453 julia> count_zeros(-1)
454 0
455 ```
456 """
457 count_zeros(x::Integer) = count_ones(~x)
458
459 """
460 leading_ones(x::Integer) -> Integer
461
462 Number of ones leading the binary representation of `x`.
463
464 # Examples
465 ```jldoctest
466 julia> leading_ones(UInt32(2 ^ 32 - 2))
467 31
468 ```
469 """
470 leading_ones(x::Integer) = leading_zeros(~x)
471
472 """
473 trailing_ones(x::Integer) -> Integer
474
475 Number of ones trailing the binary representation of `x`.
476
477 # Examples
478 ```jldoctest
479 julia> trailing_ones(3)
480 2
481 ```
482 """
483 trailing_ones(x::Integer) = trailing_zeros(~x)
484
485 """
486 top_set_bit(x::Integer) -> Integer
487
488 The number of bits in `x`'s binary representation, excluding leading zeros.
489
490 Equivalently, the position of the most significant set bit in `x`'s binary
491 representation, measured from the least significant side.
492
493 Negative `x` are only supported when `x::BitSigned`.
494
495 See also: [`ndigits0z`](@ref), [`ndigits`](@ref).
496
497 # Examples
498 ```jldoctest
499 julia> Base.top_set_bit(4)
500 3
501
502 julia> Base.top_set_bit(0)
503 0
504
505 julia> Base.top_set_bit(-1)
506 64
507 ```
508 """
509 top_set_bit(x::BitInteger) = 8sizeof(x) - leading_zeros(x)
510
511 ## integer comparisons ##
512
513 (< )(x::T, y::T) where {T<:BitUnsigned} = ult_int(x, y)
514 3 (1 %) 3 (1 %)
3 (1 %) samples spent in <=
3 (100 %) (ex.), 3 (100 %) (incl.) when called from in line 1439
(<=)(x::T, y::T) where {T<:BitSigned} = sle_int(x, y)
515 (<=)(x::T, y::T) where {T<:BitUnsigned} = ule_int(x, y)
516
517 ==(x::BitSigned, y::BitUnsigned) = (x >= 0) & (unsigned(x) == y)
518 ==(x::BitUnsigned, y::BitSigned ) = (y >= 0) & (x == unsigned(y))
519 <( x::BitSigned, y::BitUnsigned) = (x < 0) | (unsigned(x) < y)
520 <( x::BitUnsigned, y::BitSigned ) = (y >= 0) & (x < unsigned(y))
521 <=(x::BitSigned, y::BitUnsigned) = (x < 0) | (unsigned(x) <= y)
522 <=(x::BitUnsigned, y::BitSigned ) = (y >= 0) & (x <= unsigned(y))
523
524 ## integer shifts ##
525
526 # unsigned shift counts always shift in the same direction
527 >>(x::BitSigned, y::BitUnsigned) = ashr_int(x, y)
528 >>(x::BitUnsigned, y::BitUnsigned) = lshr_int(x, y)
529 <<(x::BitInteger, y::BitUnsigned) = shl_int(x, y)
530 >>>(x::BitInteger, y::BitUnsigned) = lshr_int(x, y)
531 # signed shift counts can shift in either direction
532 # note: this early during bootstrap, `>=` is not yet available
533 # note: we only define Int shift counts here; the generic case is handled later
534 >>(x::BitInteger, y::Int) =
535 ifelse(0 <= y, x >> unsigned(y), x << unsigned(-y))
536 <<(x::BitInteger, y::Int) =
537 ifelse(0 <= y, x << unsigned(y), x >> unsigned(-y))
538 >>>(x::BitInteger, y::Int) =
539 ifelse(0 <= y, x >>> unsigned(y), x << unsigned(-y))
540
541 for to in BitInteger_types, from in (BitInteger_types..., Bool)
542 if !(to === from)
543 if Core.sizeof(to) < Core.sizeof(from)
544 @eval rem(x::($from), ::Type{$to}) = trunc_int($to, x)
545 elseif from === Bool
546 @eval rem(x::($from), ::Type{$to}) = convert($to, x)
547 elseif Core.sizeof(from) < Core.sizeof(to)
548 if from <: Signed
549 @eval rem(x::($from), ::Type{$to}) = sext_int($to, x)
550 else
551 @eval rem(x::($from), ::Type{$to}) = convert($to, x)
552 end
553 else
554 @eval rem(x::($from), ::Type{$to}) = bitcast($to, x)
555 end
556 end
557 end
558
559 ## integer bitwise rotations ##
560
561 """
562 bitrotate(x::Base.BitInteger, k::Integer)
563
564 `bitrotate(x, k)` implements bitwise rotation.
565 It returns the value of `x` with its bits rotated left `k` times.
566 A negative value of `k` will rotate to the right instead.
567
568 !!! compat "Julia 1.5"
569 This function requires Julia 1.5 or later.
570
571 See also: [`<<`](@ref), [`circshift`](@ref), [`BitArray`](@ref).
572
573 ```jldoctest
574 julia> bitrotate(UInt8(114), 2)
575 0xc9
576
577 julia> bitstring(bitrotate(0b01110010, 2))
578 "11001001"
579
580 julia> bitstring(bitrotate(0b01110010, -2))
581 "10011100"
582
583 julia> bitstring(bitrotate(0b01110010, 8))
584 "01110010"
585 ```
586 """
587 bitrotate(x::T, k::Integer) where {T <: BitInteger} =
588 (x << ((sizeof(T) << 3 - 1) & k)) | (x >>> ((sizeof(T) << 3 - 1) & -k))
589
590 # @doc isn't available when running in Core at this point.
591 # Tuple syntax for documentation two function signatures at the same time
592 # doesn't work either at this point.
593 if nameof(@__MODULE__) === :Base
594 for fname in (:mod, :rem)
595 @eval @doc """
596 rem(x::Integer, T::Type{<:Integer}) -> T
597 mod(x::Integer, T::Type{<:Integer}) -> T
598 %(x::Integer, T::Type{<:Integer}) -> T
599
600 Find `y::T` such that `x` ≡ `y` (mod n), where n is the number of integers representable
601 in `T`, and `y` is an integer in `[typemin(T),typemax(T)]`.
602 If `T` can represent any integer (e.g. `T == BigInt`), then this operation corresponds to
603 a conversion to `T`.
604
605 # Examples
606 ```jldoctest
607 julia> x = 129 % Int8
608 -127
609
610 julia> typeof(x)
611 Int8
612
613 julia> x = 129 % BigInt
614 129
615
616 julia> typeof(x)
617 BigInt
618 ```
619 """ $fname(x::Integer, T::Type{<:Integer})
620 end
621 end
622
623 rem(x::T, ::Type{T}) where {T<:Integer} = x
624 rem(x::Signed, ::Type{Unsigned}) = x % unsigned(typeof(x))
625 rem(x::Unsigned, ::Type{Signed}) = x % signed(typeof(x))
626 rem(x::Integer, T::Type{<:Integer}) = convert(T, x) # `x % T` falls back to `convert`
627 rem(x::Integer, ::Type{Bool}) = ((x & 1) != 0)
628 mod(x::Integer, ::Type{T}) where {T<:Integer} = rem(x, T)
629
630 unsafe_trunc(::Type{T}, x::Integer) where {T<:Integer} = rem(x, T)
631
632 """
633 trunc([T,] x)
634 trunc(x; digits::Integer= [, base = 10])
635 trunc(x; sigdigits::Integer= [, base = 10])
636
637 `trunc(x)` returns the nearest integral value of the same type as `x` whose absolute value
638 is less than or equal to the absolute value of `x`.
639
640 `trunc(T, x)` converts the result to type `T`, throwing an `InexactError` if the value is
641 not representable.
642
643 Keywords `digits`, `sigdigits` and `base` work as for [`round`](@ref).
644
645 See also: [`%`](@ref rem), [`floor`](@ref), [`unsigned`](@ref), [`unsafe_trunc`](@ref).
646
647 # Examples
648 ```jldoctest
649 julia> trunc(2.22)
650 2.0
651
652 julia> trunc(-2.22, digits=1)
653 -2.2
654
655 julia> trunc(Int, -2.22)
656 -2
657 ```
658 """
659 function trunc end
660
661 """
662 floor([T,] x)
663 floor(x; digits::Integer= [, base = 10])
664 floor(x; sigdigits::Integer= [, base = 10])
665
666 `floor(x)` returns the nearest integral value of the same type as `x` that is less than or
667 equal to `x`.
668
669 `floor(T, x)` converts the result to type `T`, throwing an `InexactError` if the value is
670 not representable.
671
672 Keywords `digits`, `sigdigits` and `base` work as for [`round`](@ref).
673 """
674 function floor end
675
676 """
677 ceil([T,] x)
678 ceil(x; digits::Integer= [, base = 10])
679 ceil(x; sigdigits::Integer= [, base = 10])
680
681 `ceil(x)` returns the nearest integral value of the same type as `x` that is greater than or
682 equal to `x`.
683
684 `ceil(T, x)` converts the result to type `T`, throwing an `InexactError` if the value is not
685 representable.
686
687 Keywords `digits`, `sigdigits` and `base` work as for [`round`](@ref).
688 """
689 function ceil end
690
691 round(::Type{T}, x::Integer) where {T<:Integer} = convert(T, x)
692 trunc(::Type{T}, x::Integer) where {T<:Integer} = convert(T, x)
693 floor(::Type{T}, x::Integer) where {T<:Integer} = convert(T, x)
694 ceil(::Type{T}, x::Integer) where {T<:Integer} = convert(T, x)
695
696 ## integer construction ##
697
698 """
699 @int128_str str
700
701 Parse `str` as an [`Int128`](@ref).
702 Throw an `ArgumentError` if the string is not a valid integer.
703
704 # Examples
705 ```jldoctest
706 julia> int128"123456789123"
707 123456789123
708
709 julia> int128"123456789123.4"
710 ERROR: LoadError: ArgumentError: invalid base 10 digit '.' in "123456789123.4"
711 [...]
712 ```
713 """
714 macro int128_str(s)
715 return parse(Int128, s)
716 end
717
718 """
719 @uint128_str str
720
721 Parse `str` as an [`UInt128`](@ref).
722 Throw an `ArgumentError` if the string is not a valid integer.
723
724 # Examples
725 ```
726 julia> uint128"123456789123"
727 0x00000000000000000000001cbe991a83
728
729 julia> uint128"-123456789123"
730 ERROR: LoadError: ArgumentError: invalid base 10 digit '-' in "-123456789123"
731 [...]
732 ```
733 """
734 macro uint128_str(s)
735 return parse(UInt128, s)
736 end
737
738 """
739 @big_str str
740
741 Parse a string into a [`BigInt`](@ref) or [`BigFloat`](@ref),
742 and throw an `ArgumentError` if the string is not a valid number.
743 For integers `_` is allowed in the string as a separator.
744
745 # Examples
746 ```jldoctest
747 julia> big"123_456"
748 123456
749
750 julia> big"7891.5"
751 7891.5
752
753 julia> big"_"
754 ERROR: ArgumentError: invalid number format _ for BigInt or BigFloat
755 [...]
756 ```
757 """
758 macro big_str(s)
759 message = "invalid number format $s for BigInt or BigFloat"
760 throw_error = :(throw(ArgumentError($message)))
761 if '_' in s
762 # remove _ in s[2:end-1]
763 bf = IOBuffer(maxsize=lastindex(s))
764 c = s[1]
765 print(bf, c)
766 is_prev_underscore = (c == '_')
767 is_prev_dot = (c == '.')
768 for c in SubString(s, 2, lastindex(s)-1)
769 c != '_' && print(bf, c)
770 c == '_' && is_prev_dot && return throw_error
771 c == '.' && is_prev_underscore && return throw_error
772 is_prev_underscore = (c == '_')
773 is_prev_dot = (c == '.')
774 end
775 print(bf, s[end])
776 s = String(take!(bf))
777 end
778 n = tryparse(BigInt, s)
779 n === nothing || return n
780 n = tryparse(BigFloat, s)
781 n === nothing || return n
782 return throw_error
783 end
784
785 ## integer promotions ##
786
787 # with different sizes, promote to larger type
788 promote_rule(::Type{Int16}, ::Union{Type{Int8}, Type{UInt8}}) = Int16
789 promote_rule(::Type{Int32}, ::Union{Type{Int16}, Type{Int8}, Type{UInt16}, Type{UInt8}}) = Int32
790 promote_rule(::Type{Int64}, ::Union{Type{Int16}, Type{Int32}, Type{Int8}, Type{UInt16}, Type{UInt32}, Type{UInt8}}) = Int64
791 promote_rule(::Type{Int128}, ::Union{Type{Int16}, Type{Int32}, Type{Int64}, Type{Int8}, Type{UInt16}, Type{UInt32}, Type{UInt64}, Type{UInt8}}) = Int128
792 promote_rule(::Type{UInt16}, ::Union{Type{Int8}, Type{UInt8}}) = UInt16
793 promote_rule(::Type{UInt32}, ::Union{Type{Int16}, Type{Int8}, Type{UInt16}, Type{UInt8}}) = UInt32
794 promote_rule(::Type{UInt64}, ::Union{Type{Int16}, Type{Int32}, Type{Int8}, Type{UInt16}, Type{UInt32}, Type{UInt8}}) = UInt64
795 promote_rule(::Type{UInt128}, ::Union{Type{Int16}, Type{Int32}, Type{Int64}, Type{Int8}, Type{UInt16}, Type{UInt32}, Type{UInt64}, Type{UInt8}}) = UInt128
796 # with mixed signedness and same size, Unsigned wins
797 promote_rule(::Type{UInt8}, ::Type{Int8} ) = UInt8
798 promote_rule(::Type{UInt16}, ::Type{Int16} ) = UInt16
799 promote_rule(::Type{UInt32}, ::Type{Int32} ) = UInt32
800 promote_rule(::Type{UInt64}, ::Type{Int64} ) = UInt64
801 promote_rule(::Type{UInt128}, ::Type{Int128}) = UInt128
802
803 ## traits ##
804
805 """
806 typemin(T)
807
808 The lowest value representable by the given (real) numeric DataType `T`.
809
810 See also: [`floatmin`](@ref), [`typemax`](@ref), [`eps`](@ref).
811
812 # Examples
813 ```jldoctest
814 julia> typemin(Int8)
815 -128
816
817 julia> typemin(UInt32)
818 0x00000000
819
820 julia> typemin(Float16)
821 -Inf16
822
823 julia> typemin(Float32)
824 -Inf32
825
826 julia> nextfloat(-Inf32) # smallest finite Float32 floating point number
827 -3.4028235f38
828 ```
829 """
830 function typemin end
831
832 """
833 typemax(T)
834
835 The highest value representable by the given (real) numeric `DataType`.
836
837 See also: [`floatmax`](@ref), [`typemin`](@ref), [`eps`](@ref).
838
839 # Examples
840 ```jldoctest
841 julia> typemax(Int8)
842 127
843
844 julia> typemax(UInt32)
845 0xffffffff
846
847 julia> typemax(Float64)
848 Inf
849
850 julia> typemax(Float32)
851 Inf32
852
853 julia> floatmax(Float32) # largest finite Float32 floating point number
854 3.4028235f38
855 ```
856 """
857 function typemax end
858
859 typemin(::Type{Int8 }) = Int8(-128)
860 typemax(::Type{Int8 }) = Int8(127)
861 typemin(::Type{UInt8 }) = UInt8(0)
862 typemax(::Type{UInt8 }) = UInt8(255)
863 typemin(::Type{Int16 }) = Int16(-32768)
864 typemax(::Type{Int16 }) = Int16(32767)
865 typemin(::Type{UInt16}) = UInt16(0)
866 typemax(::Type{UInt16}) = UInt16(65535)
867 typemin(::Type{Int32 }) = Int32(-2147483648)
868 typemax(::Type{Int32 }) = Int32(2147483647)
869 typemin(::Type{UInt32}) = UInt32(0)
870 typemax(::Type{UInt32}) = UInt32(4294967295)
871 typemin(::Type{Int64 }) = -9223372036854775808
872 typemax(::Type{Int64 }) = 9223372036854775807
873 typemin(::Type{UInt64}) = UInt64(0)
874 typemax(::Type{UInt64}) = 0xffffffffffffffff
875 @eval typemin(::Type{UInt128}) = $(convert(UInt128, 0))
876 @eval typemax(::Type{UInt128}) = $(bitcast(UInt128, convert(Int128, -1)))
877 @eval typemin(::Type{Int128} ) = $(convert(Int128, 1) << 127)
878 @eval typemax(::Type{Int128} ) = $(bitcast(Int128, typemax(UInt128) >> 1))
879
880
881 widen(::Type{Int8}) = Int16
882 widen(::Type{Int16}) = Int32
883 widen(::Type{Int32}) = Int64
884 widen(::Type{Int64}) = Int128
885 widen(::Type{UInt8}) = UInt16
886 widen(::Type{UInt16}) = UInt32
887 widen(::Type{UInt32}) = UInt64
888 widen(::Type{UInt64}) = UInt128
889
890 # a few special cases,
891 # Int64*UInt64 => Int128
892 # |x|<=2^(k-1), |y|<=2^k-1 => |x*y|<=2^(2k-1)-1
893 widemul(x::Signed,y::Unsigned) = widen(x) * signed(widen(y))
894 widemul(x::Unsigned,y::Signed) = signed(widen(x)) * widen(y)
895 # multplication by Bool doesn't require widening
896 widemul(x::Bool,y::Bool) = x * y
897 widemul(x::Bool,y::Number) = x * y
898 widemul(x::Number,y::Bool) = x * y
899
900
901 ## wide multiplication, Int128 multiply and divide ##
902
903 if Core.sizeof(Int) == 4
904 function widemul(u::Int64, v::Int64)
905 local u0::UInt64, v0::UInt64, w0::UInt64
906 local u1::Int64, v1::Int64, w1::UInt64, w2::Int64, t::UInt64
907
908 u0 = u & 0xffffffff; u1 = u >> 32
909 v0 = v & 0xffffffff; v1 = v >> 32
910 w0 = u0 * v0
911 t = reinterpret(UInt64, u1) * v0 + (w0 >>> 32)
912 w2 = reinterpret(Int64, t) >> 32
913 w1 = u0 * reinterpret(UInt64, v1) + (t & 0xffffffff)
914 hi = u1 * v1 + w2 + (reinterpret(Int64, w1) >> 32)
915 lo = w0 & 0xffffffff + (w1 << 32)
916 return Int128(hi) << 64 + Int128(lo)
917 end
918
919 function widemul(u::UInt64, v::UInt64)
920 local u0::UInt64, v0::UInt64, w0::UInt64
921 local u1::UInt64, v1::UInt64, w1::UInt64, w2::UInt64, t::UInt64
922
923 u0 = u & 0xffffffff; u1 = u >>> 32
924 v0 = v & 0xffffffff; v1 = v >>> 32
925 w0 = u0 * v0
926 t = u1 * v0 + (w0 >>> 32)
927 w2 = t >>> 32
928 w1 = u0 * v1 + (t & 0xffffffff)
929 hi = u1 * v1 + w2 + (w1 >>> 32)
930 lo = w0 & 0xffffffff + (w1 << 32)
931 return UInt128(hi) << 64 + UInt128(lo)
932 end
933
934 function *(u::Int128, v::Int128)
935 u0 = u % UInt64; u1 = Int64(u >> 64)
936 v0 = v % UInt64; v1 = Int64(v >> 64)
937 lolo = widemul(u0, v0)
938 lohi = widemul(reinterpret(Int64, u0), v1)
939 hilo = widemul(u1, reinterpret(Int64, v0))
940 t = reinterpret(UInt128, hilo) + (lolo >>> 64)
941 w1 = reinterpret(UInt128, lohi) + (t & 0xffffffffffffffff)
942 return Int128(lolo & 0xffffffffffffffff) + reinterpret(Int128, w1) << 64
943 end
944
945 function *(u::UInt128, v::UInt128)
946 u0 = u % UInt64; u1 = UInt64(u>>>64)
947 v0 = v % UInt64; v1 = UInt64(v>>>64)
948 lolo = widemul(u0, v0)
949 lohi = widemul(u0, v1)
950 hilo = widemul(u1, v0)
951 t = hilo + (lolo >>> 64)
952 w1 = lohi + (t & 0xffffffffffffffff)
953 return (lolo & 0xffffffffffffffff) + UInt128(w1) << 64
954 end
955
956 function _setbit(x::UInt128, i)
957 # faster version of `return x | (UInt128(1) << i)`
958 j = i >> 5
959 y = UInt128(one(UInt32) << (i & 0x1f))
960 if j == 0
961 return x | y
962 elseif j == 1
963 return x | (y << 32)
964 elseif j == 2
965 return x | (y << 64)
966 elseif j == 3
967 return x | (y << 96)
968 end
969 return x
970 end
971
972 function divrem(x::UInt128, y::UInt128)
973 iszero(y) && throw(DivideError())
974 if (x >> 64) % UInt64 == 0
975 if (y >> 64) % UInt64 == 0
976 # fast path: upper 64 bits are zero, so we can fallback to UInt64 division
977 q64, x64 = divrem(x % UInt64, y % UInt64)
978 return UInt128(q64), UInt128(x64)
979 else
980 # this implies y>x, so
981 return zero(UInt128), x
982 end
983 end
984 n = leading_zeros(y) - leading_zeros(x)
985 q = zero(UInt128)
986 ys = y << n
987 while n >= 0
988 # ys == y * 2^n
989 if ys <= x
990 x -= ys
991 q = _setbit(q, n)
992 if (x >> 64) % UInt64 == 0
993 # exit early, similar to above fast path
994 if (y >> 64) % UInt64 == 0
995 q64, x64 = divrem(x % UInt64, y % UInt64)
996 q |= q64
997 x = UInt128(x64)
998 end
999 return q, x
1000 end
1001 end
1002 ys >>>= 1
1003 n -= 1
1004 end
1005 return q, x
1006 end
1007
1008 function div(x::Int128, y::Int128)
1009 (x == typemin(Int128)) & (y == -1) && throw(DivideError())
1010 return Int128(div(BigInt(x), BigInt(y)))::Int128
1011 end
1012 div(x::UInt128, y::UInt128) = divrem(x, y)[1]
1013
1014 function rem(x::Int128, y::Int128)
1015 return Int128(rem(BigInt(x), BigInt(y)))::Int128
1016 end
1017
1018 function rem(x::UInt128, y::UInt128)
1019 iszero(y) && throw(DivideError())
1020 if (x >> 64) % UInt64 == 0
1021 if (y >> 64) % UInt64 == 0
1022 # fast path: upper 64 bits are zero, so we can fallback to UInt64 division
1023 return UInt128(rem(x % UInt64, y % UInt64))
1024 else
1025 # this implies y>x, so
1026 return x
1027 end
1028 end
1029 n = leading_zeros(y) - leading_zeros(x)
1030 ys = y << n
1031 while n >= 0
1032 # ys == y * 2^n
1033 if ys <= x
1034 x -= ys
1035 if (x >> 64) % UInt64 == 0
1036 # exit early, similar to above fast path
1037 if (y >> 64) % UInt64 == 0
1038 x = UInt128(rem(x % UInt64, y % UInt64))
1039 end
1040 return x
1041 end
1042 end
1043 ys >>>= 1
1044 n -= 1
1045 end
1046 return x
1047 end
1048
1049 function mod(x::Int128, y::Int128)
1050 return Int128(mod(BigInt(x), BigInt(y)))::Int128
1051 end
1052 else
1053 *(x::T, y::T) where {T<:Union{Int128,UInt128}} = mul_int(x, y)
1054
1055 div(x::Int128, y::Int128) = checked_sdiv_int(x, y)
1056 div(x::UInt128, y::UInt128) = checked_udiv_int(x, y)
1057
1058 rem(x::Int128, y::Int128) = checked_srem_int(x, y)
1059 rem(x::UInt128, y::UInt128) = checked_urem_int(x, y)
1060 end
1061
1062 # issue #15489: since integer ops are unchecked, they shouldn't check promotion
1063 for op in (:+, :-, :*, :&, :|, :xor)
1064 @eval function $op(a::Integer, b::Integer)
1065 T = promote_typeof(a, b)
1066 aT, bT = a % T, b % T
1067 not_sametype((a, b), (aT, bT))
1068 return $op(aT, bT)
1069 end
1070 end
1071
1072 const _mask1_uint128 = (UInt128(0x5555555555555555) << 64) | UInt128(0x5555555555555555)
1073 const _mask2_uint128 = (UInt128(0x3333333333333333) << 64) | UInt128(0x3333333333333333)
1074 const _mask4_uint128 = (UInt128(0x0f0f0f0f0f0f0f0f) << 64) | UInt128(0x0f0f0f0f0f0f0f0f)
1075
1076 """
1077 bitreverse(x)
1078
1079 Reverse the order of bits in integer `x`. `x` must have a fixed bit width,
1080 e.g. be an `Int16` or `Int32`.
1081
1082 !!! compat "Julia 1.5"
1083 This function requires Julia 1.5 or later.
1084
1085 # Examples
1086 ```jldoctest
1087 julia> bitreverse(0x8080808080808080)
1088 0x0101010101010101
1089
1090 julia> reverse(bitstring(0xa06e)) == bitstring(bitreverse(0xa06e))
1091 true
1092 ```
1093 """
1094 function bitreverse(x::BitInteger)
1095 # TODO: consider using llvm.bitreverse intrinsic
1096 z = unsigned(x)
1097 mask1 = _mask1_uint128 % typeof(z)
1098 mask2 = _mask2_uint128 % typeof(z)
1099 mask4 = _mask4_uint128 % typeof(z)
1100 z = ((z & mask1) << 1) | ((z >> 1) & mask1)
1101 z = ((z & mask2) << 2) | ((z >> 2) & mask2)
1102 z = ((z & mask4) << 4) | ((z >> 4) & mask4)
1103 return bswap(z) % typeof(x)
1104 end