1572

Committed 01 Feb 2026 09:55PM UTC coverage: 76.677% (-0.07%) from 76.749%

Build # 1572

Build Type

push

buildkite

Committed by

web-flow

Commit Message

docs: clarify 'using A, B' semantics (#60856)

Resolves #36090

Run Details

62889 of 82018 relevant lines covered (76.68%)

23269256.38 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

96.71

/base/abstractarraymath.jl

# This file is a part of Julia. License is MIT: https://julialang.org/license

 ## Basic functions ##

isreal(x::AbstractArray) = all(isreal,x)
iszero(x::AbstractArray) = all(iszero,x)
isreal(x::AbstractArray{<:Real}) = true

## Constructors ##

"""
    vec(a::AbstractArray)::AbstractVector

Reshape the array `a` as a one-dimensional column vector. Return `a` if it is
already an `AbstractVector`. The resulting array
shares the same underlying data as `a`, so it will only be mutable if `a` is
mutable, in which case modifying one will also modify the other.

# Examples
```jldoctest
julia> a = [1 2 3; 4 5 6]
2×3 Matrix{Int64}:
 1  2  3
 4  5  6

julia> vec(a)
6-element Vector{Int64}:
 1
 4
 2
 5
 3
 6

julia> vec(1:3)
1:3
```

See also [`reshape`](@ref), [`dropdims`](@ref).
"""
vec(a::AbstractArray) = reshape(a,length(a))
vec(a::AbstractVector) = a

_sub(::Tuple{}, ::Tuple{}) = ()
_sub(t::Tuple, ::Tuple{}) = t
_sub(t::Tuple, s::Tuple) = _sub(tail(t), tail(s))

"""
    dropdims(A; dims)

Return an array with the same data as `A`, but with the dimensions specified by
`dims` removed.

Repeated dimensions or numbers outside `1:ndims(A)` are forbidden.
Moreover `size(A,d)` must equal 1 for every `d` in `dims`.

The result shares the same underlying data as `A`, such that the
result is mutable if and only if `A` is mutable, and setting elements of one
alters the values of the other.

Inverse of [`insertdims`](@ref).
See also [`reshape`](@ref), [`vec`](@ref).

# Examples
```jldoctest
julia> a = reshape(Vector(1:4),(2,2,1,1))
2×2×1×1 Array{Int64, 4}:
[:, :, 1, 1] =
 1  3
 2  4

julia> b = dropdims(a; dims=3)
2×2×1 Array{Int64, 3}:
[:, :, 1] =
 1  3
 2  4

julia> b[1,1,1] = 5; a
2×2×1×1 Array{Int64, 4}:
[:, :, 1, 1] =
 5  3
 2  4
```
"""
dropdims(A; dims) = _dropdims(A, dims)
function _dropdims(A::AbstractArray, dims::Dims)
    for i in eachindex(dims)
        1 <= dims[i] <= ndims(A) || throw(ArgumentError("dropped dims must be in range 1:ndims(A)"))
        length(axes(A, dims[i])) == 1 || throw(ArgumentError("dropped dims must all be size 1"))
        for j = 1:i-1
            dims[j] == dims[i] && throw(ArgumentError("dropped dims must be unique"))
        end
    end
    ox = axes(A)
    ax = _foldoneto((ds, d) -> d in dims ? ds : (ds..., axes(A,d)), (), Val(ndims(A)))
    if isconcretetype(eltype(ox))
        # if all the axes are the same type, we can use the tail as the
        # axes of the result rather than extracting one at each index
        return reshape(A, ax::typeof(_sub(ox, dims)))
    else
        return reshape(A, ax)
    end
end
_dropdims(A::AbstractArray, dim::Integer) = _dropdims(A, (Int(dim),))

"""
    insertdims(A; dims)

Return an array with new singleton dimensions at every dimension in `dims`.

Repeated dimensions are forbidden and the largest entry in `dims` must be
less than or equal than `ndims(A) + length(dims)`.

The result shares the same underlying data as `A`, such that the
result is mutable if and only if `A` is mutable, and setting elements of one
alters the values of the other.

Inverse of [`dropdims`](@ref).
See also [`reshape`](@ref), [`vec`](@ref).

# Examples
```jldoctest
julia> x = [1 2 3; 4 5 6]
2×3 Matrix{Int64}:
 1  2  3
 4  5  6

julia> insertdims(x, dims=3)
2×3×1 Array{Int64, 3}:
[:, :, 1] =
 1  2  3
 4  5  6

julia> insertdims(x, dims=(1,2,5)) == reshape(x, 1, 1, 2, 3, 1)
true

julia> dropdims(insertdims(x, dims=(1,2,5)), dims=(1,2,5))
2×3 Matrix{Int64}:
 1  2  3
 4  5  6
```

!!! compat "Julia 1.12"
    Requires Julia 1.12 or later.
"""
insertdims(A; dims) = _insertdims(A, dims)
function _insertdims(A::AbstractArray{T, N}, dims::NTuple{M, Int}) where {T, N, M}
    for i in eachindex(dims)
        1 ≤ dims[i] || throw(ArgumentError("the smallest entry in dims must be ≥ 1."))
        dims[i] ≤ N+M || throw(ArgumentError("the largest entry in dims must be not larger than the dimension of the array and the length of dims added"))
        for j = 1:i-1
            dims[j] == dims[i] && throw(ArgumentError("inserted dims must be unique"))
        end
    end

    # acc is a tuple, where the first entry is the final shape
    # the second entry off acc is a counter for the axes of A
    inds= Base._foldoneto((acc, i) ->
                            i ∈ dims
                                ? ((acc[1]..., Base.OneTo(1)), acc[2])
                                : ((acc[1]..., axes(A, acc[2])), acc[2] + 1),
                            ((), 1), Val(N+M))
    new_shape = inds[1]
    return reshape(A, new_shape)
end
_insertdims(A::AbstractArray, dim::Integer) = _insertdims(A, (Int(dim),))



## Unary operators ##

"""
    conj!(A)

Transform an array to its complex conjugate in-place.

See also [`conj`](@ref).

# Examples
```jldoctest
julia> A = [1+im 2-im; 2+2im 3+im]
2×2 Matrix{Complex{Int64}}:
 1+1im  2-1im
 2+2im  3+1im

julia> conj!(A);

julia> A
2×2 Matrix{Complex{Int64}}:
 1-1im  2+1im
 2-2im  3-1im
```
"""
conj!(A::AbstractArray{<:Number}) = (@inbounds broadcast!(conj, A, A); A)
conj!(x::AbstractArray{<:Real}) = x
conj!(A::AbstractArray) = (foreach(conj!, A); A)

"""
    conj(A::AbstractArray)

Return an array containing the complex conjugate of each entry in array `A`.

Equivalent to `conj.(A)`, except that when `eltype(A) <: Real`
`A` is returned without copying, and that when `A` has zero dimensions,
a 0-dimensional array is returned (rather than a scalar).

# Examples
```jldoctest
julia> conj([1, 2im, 3 + 4im])
3-element Vector{Complex{Int64}}:
 1 + 0im
 0 - 2im
 3 - 4im

julia> conj(fill(2 - im))
0-dimensional Array{Complex{Int64}, 0}:
2 + 1im
```
"""
conj(A::AbstractArray) = broadcast_preserving_zero_d(conj, A)
conj(A::AbstractArray{<:Real}) = A

"""
    real(A::AbstractArray)

Return an array containing the real part of each entry in array `A`.

Equivalent to `real.(A)`, except that when `eltype(A) <: Real`
`A` is returned without copying, and that when `A` has zero dimensions,
a 0-dimensional array is returned (rather than a scalar).

# Examples
```jldoctest
julia> real([1, 2im, 3 + 4im])
3-element Vector{Int64}:
 1
 0
 3

julia> real(fill(2 - im))
0-dimensional Array{Int64, 0}:
2
```
"""
real(A::AbstractArray) = broadcast_preserving_zero_d(real, A)
real(A::AbstractArray{<:Real}) = A

"""
    imag(A::AbstractArray)

Return an array containing the imaginary part of each entry in array `A`.

Equivalent to `imag.(A)`, except that when `A` has zero dimensions,
a 0-dimensional array is returned (rather than a scalar).

# Examples
```jldoctest
julia> imag([1, 2im, 3 + 4im])
3-element Vector{Int64}:
 0
 2
 4

julia> imag(fill(2 - im))
0-dimensional Array{Int64, 0}:
-1
```
"""
imag(A::AbstractArray) = broadcast_preserving_zero_d(imag, A)
imag(A::AbstractArray{<:Real}) = zero(A)

"""
    reim(A::AbstractArray)

Return a tuple of two arrays containing respectively the real and the imaginary
part of each entry in `A`.

Equivalent to `(real.(A), imag.(A))`, except that when `eltype(A) <: Real`
`A` is returned without copying to represent the real part, and that when `A` has
zero dimensions, a 0-dimensional array is returned (rather than a scalar).

# Examples
```jldoctest
julia> reim([1, 2im, 3 + 4im])
([1, 0, 3], [0, 2, 4])

julia> reim(fill(2 - im))
(fill(2), fill(-1))
```
"""
reim(A::AbstractArray)

-(A::AbstractArray) = broadcast_preserving_zero_d(-, A)

+(x::AbstractArray{<:Number}) = x
*(x::AbstractArray{<:Number,2}) = x

# index A[:,:,...,i,:,:,...] where "i" is in dimension "d"

"""
    selectdim(A, d::Integer, i)

Return a view of all the data of `A` where the index for dimension `d` equals `i`.

Equivalent to `view(A,:,:,...,i,:,:,...)` where `i` is in position `d`.

See also [`eachslice`](@ref).

# Examples
```jldoctest
julia> A = [1 2 3 4; 5 6 7 8]
2×4 Matrix{Int64}:
 1  2  3  4
 5  6  7  8

julia> selectdim(A, 2, 3)
2-element view(::Matrix{Int64}, :, 3) with eltype Int64:
 3
 7

julia> selectdim(A, 2, 3:4)
2×2 view(::Matrix{Int64}, :, 3:4) with eltype Int64:
 3  4
 7  8
```
"""
@inline selectdim(A::AbstractArray, d::Integer, i) = _selectdim(A, d, i, _setindex(i, d, map(Slice, axes(A))...))
@noinline function _selectdim(A, d, i, idxs)
    d >= 1 || throw(ArgumentError("dimension must be ≥ 1, got $d"))
    nd = ndims(A)
    d > nd && (i == 1 || throw(BoundsError(A, (ntuple(Returns(Colon()),d-1)..., i))))
    return view(A, idxs...)
end

function circshift(a::AbstractArray, shiftamt::Real)
    circshift!(similar(a), a, (Integer(shiftamt),))
end
circshift(a::AbstractArray, shiftamt::DimsInteger) = circshift!(similar(a), a, shiftamt)
"""
    circshift(A, shifts)

Circularly shift, i.e. rotate, the data in `A`. The second argument is a tuple or
vector giving the amount to shift in each dimension, or an integer to shift only in the
first dimension.

The generated code is most efficient when the shift amounts are known at compile-time, i.e.,
compile-time constants.

See also [`circshift!`](@ref), [`circcopy!`](@ref), [`bitrotate`](@ref), [`<<`](@ref).

# Examples
```jldoctest
julia> b = reshape(Vector(1:16), (4,4))
4×4 Matrix{Int64}:
 1  5   9  13
 2  6  10  14
 3  7  11  15
 4  8  12  16

julia> circshift(b, (0,2))
4×4 Matrix{Int64}:
  9  13  1  5
 10  14  2  6
 11  15  3  7
 12  16  4  8

julia> circshift(b, (-1,0))
4×4 Matrix{Int64}:
 2  6  10  14
 3  7  11  15
 4  8  12  16
 1  5   9  13

julia> a = BitArray([true, true, false, false, true])
5-element BitVector:
 1
 1
 0
 0
 1

julia> circshift(a, 1)
5-element BitVector:
 1
 1
 1
 0
 0

julia> circshift(a, -1)
5-element BitVector:
 1
 0
 0
 1
 1

julia> x = (1, 2, 3, 4, 5)
(1, 2, 3, 4, 5)

julia> circshift(x, 4)
(2, 3, 4, 5, 1)

julia> z = (1, 'a', -7.0, 3)
(1, 'a', -7.0, 3)

julia> circshift(z, -1)
('a', -7.0, 3, 1)
```
"""
function circshift(a::AbstractArray, shiftamt)
    circshift!(similar(a), a, map(Integer, (shiftamt...,)))
end

## Other array functions ##

"""
    repeat(A::AbstractArray, counts::Integer...)

Construct an array by repeating array `A` a given number of times in each dimension, specified by `counts`.

See also [`fill`](@ref), [`Iterators.repeated`](@ref), [`Iterators.cycle`](@ref).

# Examples
```jldoctest
julia> repeat([1, 2, 3], 2)
6-element Vector{Int64}:
 1
 2
 3
 1
 2
 3

julia> repeat([1, 2, 3], 2, 3)
6×3 Matrix{Int64}:
 1  1  1
 2  2  2
 3  3  3
 1  1  1
 2  2  2
 3  3  3
```
"""
function repeat(A::AbstractArray, counts...)
    return repeat(A, outer=counts)
end

"""
    repeat(A::AbstractArray; inner=ntuple(Returns(1), ndims(A)), outer=ntuple(Returns(1), ndims(A)))

Construct an array by repeating the entries of `A`. The i-th element of `inner` specifies
the number of times that the individual entries of the i-th dimension of `A` should be
repeated. The i-th element of `outer` specifies the number of times that a slice along the
i-th dimension of `A` should be repeated. If `inner` or `outer` are omitted, no repetition
is performed.

# Examples
```jldoctest
julia> repeat(1:2, inner=2)
4-element Vector{Int64}:
 1
 1
 2
 2

julia> repeat(1:2, outer=2)
4-element Vector{Int64}:
 1
 2
 1
 2

julia> repeat([1 2; 3 4], inner=(2, 1), outer=(1, 3))
4×6 Matrix{Int64}:
 1  2  1  2  1  2
 1  2  1  2  1  2
 3  4  3  4  3  4
 3  4  3  4  3  4
```
"""
function repeat(A::AbstractArray; inner = nothing, outer = nothing)
    return _RepeatInnerOuter.repeat(A, inner=inner, outer=outer)
end

module _RepeatInnerOuter

function repeat(arr; inner=nothing, outer=nothing)
    check(arr, inner, outer)
    arr, inner, outer = resolve(arr, inner, outer)
    repeat_inner_outer(arr, inner, outer)
end

to_tuple(t::Tuple) = t
to_tuple(x::Integer) = (x,)
to_tuple(itr) = tuple(itr...)

function pad(a, b)
    N = max(length(a), length(b))
    Base.fill_to_length(a, 1, Val(N)), Base.fill_to_length(b, 1, Val(N))
end
function pad(a, b, c)
    N = max(max(length(a), length(b)), length(c))
    Base.fill_to_length(a, 1, Val(N)), Base.fill_to_length(b, 1, Val(N)), Base.fill_to_length(c, 1, Val(N))
end

function resolve(arr::AbstractArray{<:Any, N}, inner::NTuple{N, Any}, outer::NTuple{N,Any}) where {N}
    arr, inner, outer
end
function resolve(arr, inner, outer)
    dims, inner, outer = pad(size(arr), to_tuple(inner), to_tuple(outer))
    reshape(arr, dims), inner, outer
end
function resolve(arr, inner::Nothing, outer::Nothing)
    return arr, inner, outer
end
function resolve(arr, inner::Nothing, outer)
    dims, outer = pad(size(arr), to_tuple(outer))
    reshape(arr, dims), inner, outer
end
function resolve(arr, inner, outer::Nothing)
    dims, inner = pad(size(arr), to_tuple(inner))
    reshape(arr, dims), inner, outer
end

function check(arr, inner, outer)
    if inner !== nothing
        # TODO: Currently one based indexing is demanded for inner !== nothing,
        # but not for outer !== nothing. Decide for something consistent.
        Base.require_one_based_indexing(arr)
        if !all(n -> n isa Integer, inner)
            throw(ArgumentError("repeat requires integer counts, got inner = $inner"))
        end
        if any(<(0), inner)
            throw(ArgumentError("no inner repetition count may be negative; got $inner"))
        end
        if length(inner) < ndims(arr)
            throw(ArgumentError("number of inner repetitions ($(length(inner))) cannot be less than number of dimensions of input array ($(ndims(arr)))"))
        end
    end
    if outer !== nothing
        if !all(n -> n isa Integer, outer)
            throw(ArgumentError("repeat requires integer counts, got outer = $outer"))
        end
        if any(<(0), outer)
            throw(ArgumentError("no outer repetition count may be negative; got $outer"))
        end
        if (length(outer) < ndims(arr)) && (inner !== nothing)
            throw(ArgumentError("number of outer repetitions ($(length(outer))) cannot be less than number of dimensions of input array ($(ndims(arr)))"))
        end
    end
end

repeat_inner_outer(arr, inner::Nothing, outer::Nothing) = arr
repeat_inner_outer(arr, ::Nothing, outer) = repeat_outer(arr, outer)
repeat_inner_outer(arr, inner, ::Nothing) = repeat_inner(arr, inner)
repeat_inner_outer(arr, inner, outer) = repeat_outer(repeat_inner(arr, inner), outer)

function repeat_outer(a::AbstractMatrix, (m,n)::NTuple{2, Any})
    o, p = size(a,1), size(a,2)
    b = similar(a, o*m, p*n)
    for j=1:n
        d = (j-1)*p+1
        R = d:d+p-1
        for i=1:m
            c = (i-1)*o+1
            @inbounds b[c:c+o-1, R] = a
        end
    end
    return b
end

function repeat_outer(a::AbstractVector, (m,)::Tuple{Any})
    o = length(a)
    b = similar(a, o*m)
    for i=1:m
        c = (i-1)*o+1
        @inbounds b[c:c+o-1] = a
    end
    return b
end

function repeat_outer(arr::AbstractArray{<:Any,N}, dims::NTuple{N,Any}) where {N}
    insize  = size(arr)
    outsize = map(*, insize, dims)
    out = similar(arr, outsize)
    for I in CartesianIndices(arr)
        for J in CartesianIndices(dims)
            TIJ = map(Tuple(I), Tuple(J), insize) do i, j, d
                i + d * (j-1)
            end
            IJ = CartesianIndex(TIJ)
            @inbounds out[IJ] = arr[I]
        end
    end
    return out
end

function repeat_inner(arr, inner)
    outsize = map(*, size(arr), inner)
    out = similar(arr, outsize)
    for I in CartesianIndices(arr)
        for J in CartesianIndices(inner)
            TIJ = map(Tuple(I), Tuple(J), inner) do i, j, d
                (i-1) * d + j
            end
            IJ = CartesianIndex(TIJ)
            @inbounds out[IJ] = arr[I]
        end
    end
    return out
end

end#module

1	# This file is a part of Julia. License is MIT: https://julialang.org/license
2
3	## Basic functions ##
4
5	isreal(x::AbstractArray) = all(isreal,x)	4,086✔
6	iszero(x::AbstractArray) = all(iszero,x)	47,612✔
7	isreal(x::AbstractArray{<:Real}) = true	×
8
9	## Constructors ##
10
11	"""
12	vec(a::AbstractArray)::AbstractVector
13
14	Reshape the array `a` as a one-dimensional column vector. Return `a` if it is
15	already an `AbstractVector`. The resulting array
16	shares the same underlying data as `a`, so it will only be mutable if `a` is
17	mutable, in which case modifying one will also modify the other.
18
19	# Examples
20	```jldoctest
21	julia> a = [1 2 3; 4 5 6]
22	2×3 Matrix{Int64}:
23	1 2 3
24	4 5 6
25
26	julia> vec(a)
27	6-element Vector{Int64}:
28	1
29	4
30	2
31	5
32	3
33	6
34
35	julia> vec(1:3)
36	1:3
37	```
38
39	See also [`reshape`](@ref), [`dropdims`](@ref).
40	"""
41	vec(a::AbstractArray) = reshape(a,length(a))	10,678✔
42	vec(a::AbstractVector) = a	10,942✔
43
44	_sub(::Tuple{}, ::Tuple{}) = ()	×
45	_sub(t::Tuple, ::Tuple{}) = t	192✔
46	_sub(t::Tuple, s::Tuple) = _sub(tail(t), tail(s))	360✔
47
48	"""
49	dropdims(A; dims)
50
51	Return an array with the same data as `A`, but with the dimensions specified by
52	`dims` removed.
53
54	Repeated dimensions or numbers outside `1:ndims(A)` are forbidden.
55	Moreover `size(A,d)` must equal 1 for every `d` in `dims`.
56
57	The result shares the same underlying data as `A`, such that the
58	result is mutable if and only if `A` is mutable, and setting elements of one
59	alters the values of the other.
60
61	Inverse of [`insertdims`](@ref).
62	See also [`reshape`](@ref), [`vec`](@ref).
63
64	# Examples
65	```jldoctest
66	julia> a = reshape(Vector(1:4),(2,2,1,1))
67	2×2×1×1 Array{Int64, 4}:
68	[:, :, 1, 1] =
69	1 3
70	2 4
71
72	julia> b = dropdims(a; dims=3)
73	2×2×1 Array{Int64, 3}:
74	[:, :, 1] =
75	1 3
76	2 4
77
78	julia> b[1,1,1] = 5; a
79	2×2×1×1 Array{Int64, 4}:
80	[:, :, 1, 1] =
81	5 3
82	2 4
83	```
84	"""
85	dropdims(A; dims) = _dropdims(A, dims)	489✔
86	function _dropdims(A::AbstractArray, dims::Dims)	183✔
87	for i in eachindex(dims)	243✔
88	1 <= dims[i] <= ndims(A) \|\| throw(ArgumentError("dropped dims must be in range 1:ndims(A)"))	447✔
89	length(axes(A, dims[i])) == 1 \|\| throw(ArgumentError("dropped dims must all be size 1"))	438✔
90	for j = 1:i-1	408✔
91	dims[j] == dims[i] && throw(ArgumentError("dropped dims must be unique"))	288✔
92	end	366✔
93	end	582✔
94	ox = axes(A)	198✔
95	ax = _foldoneto((ds, d) -> d in dims ? ds : (ds..., axes(A,d)), (), Val(ndims(A)))	1,608✔
96	if isconcretetype(eltype(ox))	198✔
97	# if all the axes are the same type, we can use the tail as the
98	# axes of the result rather than extracting one at each index
99	return reshape(A, ax::typeof(_sub(ox, dims)))	192✔
100	else
101	return reshape(A, ax)	6✔
102	end
103	end
104	_dropdims(A::AbstractArray, dim::Integer) = _dropdims(A, (Int(dim),))	87✔
105
106	"""
107	insertdims(A; dims)
108
109	Return an array with new singleton dimensions at every dimension in `dims`.
110
111	Repeated dimensions are forbidden and the largest entry in `dims` must be
112	less than or equal than `ndims(A) + length(dims)`.
113
114	The result shares the same underlying data as `A`, such that the
115	result is mutable if and only if `A` is mutable, and setting elements of one
116	alters the values of the other.
117
118	Inverse of [`dropdims`](@ref).
119	See also [`reshape`](@ref), [`vec`](@ref).
120
121	# Examples
122	```jldoctest
123	julia> x = [1 2 3; 4 5 6]
124	2×3 Matrix{Int64}:
125	1 2 3
126	4 5 6
127
128	julia> insertdims(x, dims=3)
129	2×3×1 Array{Int64, 3}:
130	[:, :, 1] =
131	1 2 3
132	4 5 6
133
134	julia> insertdims(x, dims=(1,2,5)) == reshape(x, 1, 1, 2, 3, 1)
135	true
136
137	julia> dropdims(insertdims(x, dims=(1,2,5)), dims=(1,2,5))
138	2×3 Matrix{Int64}:
139	1 2 3
140	4 5 6
141	```
142
143	!!! compat "Julia 1.12"
144	Requires Julia 1.12 or later.
145	"""
146	insertdims(A; dims) = _insertdims(A, dims)	321✔
147	function _insertdims(A::AbstractArray{T, N}, dims::NTuple{M, Int}) where {T, N, M}	129✔
148	for i in eachindex(dims)	150✔
149	1 ≤ dims[i] \|\| throw(ArgumentError("the smallest entry in dims must be ≥ 1."))	345✔
150	dims[i] ≤ N+M \|\| throw(ArgumentError("the largest entry in dims must be not larger than the dimension of the array and the length of dims added"))	345✔
151	for j = 1:i-1	333✔
152	dims[j] == dims[i] && throw(ArgumentError("inserted dims must be unique"))	336✔
153	end	462✔
154	end	513✔
155
156	# acc is a tuple, where the first entry is the final shape
157	# the second entry off acc is a counter for the axes of A
158	inds= Base._foldoneto((acc, i) ->	1,224✔
159	i ∈ dims
160	? ((acc[1]..., Base.OneTo(1)), acc[2])
161	: ((acc[1]..., axes(A, acc[2])), acc[2] + 1),
162	((), 1), Val(N+M))
163	new_shape = inds[1]	126✔
164	return reshape(A, new_shape)	126✔
165	end
166	_insertdims(A::AbstractArray, dim::Integer) = _insertdims(A, (Int(dim),))	42✔
167
168
169
170	## Unary operators ##
171
172	"""
173	conj!(A)
174
175	Transform an array to its complex conjugate in-place.
176
177	See also [`conj`](@ref).
178
179	# Examples
180	```jldoctest
181	julia> A = [1+im 2-im; 2+2im 3+im]
182	2×2 Matrix{Complex{Int64}}:
183	1+1im 2-1im
184	2+2im 3+1im
185
186	julia> conj!(A);
187
188	julia> A
189	2×2 Matrix{Complex{Int64}}:
190	1-1im 2+1im
191	2-2im 3-1im
192	```
193	"""
194	conj!(A::AbstractArray{<:Number}) = (@inbounds broadcast!(conj, A, A); A)	361,134✔
195	conj!(x::AbstractArray{<:Real}) = x	9✔
196	conj!(A::AbstractArray) = (foreach(conj!, A); A)	6✔
197
198	"""
199	conj(A::AbstractArray)
200
201	Return an array containing the complex conjugate of each entry in array `A`.
202
203	Equivalent to `conj.(A)`, except that when `eltype(A) <: Real`
204	`A` is returned without copying, and that when `A` has zero dimensions,
205	a 0-dimensional array is returned (rather than a scalar).
206
207	# Examples
208	```jldoctest
209	julia> conj([1, 2im, 3 + 4im])
210	3-element Vector{Complex{Int64}}:
211	1 + 0im
212	0 - 2im
213	3 - 4im
214
215	julia> conj(fill(2 - im))
216	0-dimensional Array{Complex{Int64}, 0}:
217	2 + 1im
218	```
219	"""
220	conj(A::AbstractArray) = broadcast_preserving_zero_d(conj, A)	597✔
221	conj(A::AbstractArray{<:Real}) = A	522✔
222
223	"""
224	real(A::AbstractArray)
225
226	Return an array containing the real part of each entry in array `A`.
227
228	Equivalent to `real.(A)`, except that when `eltype(A) <: Real`
229	`A` is returned without copying, and that when `A` has zero dimensions,
230	a 0-dimensional array is returned (rather than a scalar).
231
232	# Examples
233	```jldoctest
234	julia> real([1, 2im, 3 + 4im])
235	3-element Vector{Int64}:
236	1
237	0
238	3
239
240	julia> real(fill(2 - im))
241	0-dimensional Array{Int64, 0}:
242	2
243	```
244	"""
245	real(A::AbstractArray) = broadcast_preserving_zero_d(real, A)	4,257✔
246	real(A::AbstractArray{<:Real}) = A	2,511✔
247
248	"""
249	imag(A::AbstractArray)
250
251	Return an array containing the imaginary part of each entry in array `A`.
252
253	Equivalent to `imag.(A)`, except that when `A` has zero dimensions,
254	a 0-dimensional array is returned (rather than a scalar).
255
256	# Examples
257	```jldoctest
258	julia> imag([1, 2im, 3 + 4im])
259	3-element Vector{Int64}:
260	0
261	2
262	4
263
264	julia> imag(fill(2 - im))
265	0-dimensional Array{Int64, 0}:
266	-1
267	```
268	"""
269	imag(A::AbstractArray) = broadcast_preserving_zero_d(imag, A)	2,658✔
270	imag(A::AbstractArray{<:Real}) = zero(A)	2,013✔
271
272	"""
273	reim(A::AbstractArray)
274
275	Return a tuple of two arrays containing respectively the real and the imaginary
276	part of each entry in `A`.
277
278	Equivalent to `(real.(A), imag.(A))`, except that when `eltype(A) <: Real`
279	`A` is returned without copying to represent the real part, and that when `A` has
280	zero dimensions, a 0-dimensional array is returned (rather than a scalar).
281
282	# Examples
283	```jldoctest
284	julia> reim([1, 2im, 3 + 4im])
285	([1, 0, 3], [0, 2, 4])
286
287	julia> reim(fill(2 - im))
288	(fill(2), fill(-1))
289	```
290	"""
291	reim(A::AbstractArray)
292
293	-(A::AbstractArray) = broadcast_preserving_zero_d(-, A)	8,534✔
294
295	+(x::AbstractArray{<:Number}) = x	18✔
296	*(x::AbstractArray{<:Number,2}) = x	3✔
297
298	# index A[:,:,...,i,:,:,...] where "i" is in dimension "d"
299
300	"""
301	selectdim(A, d::Integer, i)
302
303	Return a view of all the data of `A` where the index for dimension `d` equals `i`.
304
305	Equivalent to `view(A,:,:,...,i,:,:,...)` where `i` is in position `d`.
306
307	See also [`eachslice`](@ref).
308
309	# Examples
310	```jldoctest
311	julia> A = [1 2 3 4; 5 6 7 8]
312	2×4 Matrix{Int64}:
313	1 2 3 4
314	5 6 7 8
315
316	julia> selectdim(A, 2, 3)
317	2-element view(::Matrix{Int64}, :, 3) with eltype Int64:
318	3
319	7
320
321	julia> selectdim(A, 2, 3:4)
322	2×2 view(::Matrix{Int64}, :, 3:4) with eltype Int64:
323	3 4
324	7 8
325	```
326	"""
327	@inline selectdim(A::AbstractArray, d::Integer, i) = _selectdim(A, d, i, _setindex(i, d, map(Slice, axes(A))...))	129✔
328	@noinline function _selectdim(A, d, i, idxs)	129✔
329	d >= 1 \|\| throw(ArgumentError("dimension must be ≥ 1, got $d"))	135✔
330	nd = ndims(A)	123✔
331	d > nd && (i == 1 \|\| throw(BoundsError(A, (ntuple(Returns(Colon()),d-1)..., i))))	129✔
332	return view(A, idxs...)	117✔
333	end
334
335	function circshift(a::AbstractArray, shiftamt::Real)	423✔
336	circshift!(similar(a), a, (Integer(shiftamt),))	438✔
337	end
338	circshift(a::AbstractArray, shiftamt::DimsInteger) = circshift!(similar(a), a, shiftamt)	108✔
339	"""
340	circshift(A, shifts)
341
342	Circularly shift, i.e. rotate, the data in `A`. The second argument is a tuple or
343	vector giving the amount to shift in each dimension, or an integer to shift only in the
344	first dimension.
345
346	The generated code is most efficient when the shift amounts are known at compile-time, i.e.,
347	compile-time constants.
348
349	See also [`circshift!`](@ref), [`circcopy!`](@ref), [`bitrotate`](@ref), [`<<`](@ref).
350
351	# Examples
352	```jldoctest
353	julia> b = reshape(Vector(1:16), (4,4))
354	4×4 Matrix{Int64}:
355	1 5 9 13
356	2 6 10 14
357	3 7 11 15
358	4 8 12 16
359
360	julia> circshift(b, (0,2))
361	4×4 Matrix{Int64}:
362	9 13 1 5
363	10 14 2 6
364	11 15 3 7
365	12 16 4 8
366
367	julia> circshift(b, (-1,0))
368	4×4 Matrix{Int64}:
369	2 6 10 14
370	3 7 11 15
371	4 8 12 16
372	1 5 9 13
373
374	julia> a = BitArray([true, true, false, false, true])
375	5-element BitVector:
376	1
377	1
378	0
379	0
380	1
381
382	julia> circshift(a, 1)
383	5-element BitVector:
384	1
385	1
386	1
387	0
388	0
389
390	julia> circshift(a, -1)
391	5-element BitVector:
392	1
393	0
394	0
395	1
396	1
397
398	julia> x = (1, 2, 3, 4, 5)
399	(1, 2, 3, 4, 5)
400
401	julia> circshift(x, 4)
402	(2, 3, 4, 5, 1)
403
404	julia> z = (1, 'a', -7.0, 3)
405	(1, 'a', -7.0, 3)
406
407	julia> circshift(z, -1)
408	('a', -7.0, 3, 1)
409	```
410	"""
411	function circshift(a::AbstractArray, shiftamt)	3✔
412	circshift!(similar(a), a, map(Integer, (shiftamt...,)))	3✔
413	end
414
415	## Other array functions ##
416
417	"""
418	repeat(A::AbstractArray, counts::Integer...)
419
420	Construct an array by repeating array `A` a given number of times in each dimension, specified by `counts`.
421
422	See also [`fill`](@ref), [`Iterators.repeated`](@ref), [`Iterators.cycle`](@ref).
423
424	# Examples
425	```jldoctest
426	julia> repeat([1, 2, 3], 2)
427	6-element Vector{Int64}:
428	1
429	2
430	3
431	1
432	2
433	3
434
435	julia> repeat([1, 2, 3], 2, 3)
436	6×3 Matrix{Int64}:
437	1 1 1
438	2 2 2
439	3 3 3
440	1 1 1
441	2 2 2
442	3 3 3
443	```
444	"""
445	function repeat(A::AbstractArray, counts...)	397✔
446	return repeat(A, outer=counts)	901✔
447	end
448
449	"""
450	repeat(A::AbstractArray; inner=ntuple(Returns(1), ndims(A)), outer=ntuple(Returns(1), ndims(A)))
451
452	Construct an array by repeating the entries of `A`. The i-th element of `inner` specifies
453	the number of times that the individual entries of the i-th dimension of `A` should be
454	repeated. The i-th element of `outer` specifies the number of times that a slice along the
455	i-th dimension of `A` should be repeated. If `inner` or `outer` are omitted, no repetition
456	is performed.
457
458	# Examples
459	```jldoctest
460	julia> repeat(1:2, inner=2)
461	4-element Vector{Int64}:
462	1
463	1
464	2
465	2
466
467	julia> repeat(1:2, outer=2)
468	4-element Vector{Int64}:
469	1
470	2
471	1
472	2
473
474	julia> repeat([1 2; 3 4], inner=(2, 1), outer=(1, 3))
475	4×6 Matrix{Int64}:
476	1 2 1 2 1 2
477	1 2 1 2 1 2
478	3 4 3 4 3 4
479	3 4 3 4 3 4
480	```
481	"""
482	function repeat(A::AbstractArray; inner = nothing, outer = nothing)	1,129✔
483	return _RepeatInnerOuter.repeat(A, inner=inner, outer=outer)	1,153✔
484	end
485
486	module _RepeatInnerOuter
487
488	function repeat(arr; inner=nothing, outer=nothing)	2,085✔
489	check(arr, inner, outer)	2,221✔
490	arr, inner, outer = resolve(arr, inner, outer)	1,081✔
491	repeat_inner_outer(arr, inner, outer)	1,081✔
492	end
493
494	to_tuple(t::Tuple) = t	940✔
495	to_tuple(x::Integer) = (x,)	39✔
496	to_tuple(itr) = tuple(itr...)	27✔
497
498	function pad(a, b)	18✔
499	N = max(length(a), length(b))	964✔
500	Base.fill_to_length(a, 1, Val(N)), Base.fill_to_length(b, 1, Val(N))	964✔
501	end
502	function pad(a, b, c)	9✔
503	N = max(max(length(a), length(b)), length(c))	39✔
504	Base.fill_to_length(a, 1, Val(N)), Base.fill_to_length(b, 1, Val(N)), Base.fill_to_length(c, 1, Val(N))	39✔
505	end
506
507	function resolve(arr::AbstractArray{<:Any, N}, inner::NTuple{N, Any}, outer::NTuple{N,Any}) where {N}
508	arr, inner, outer	72✔
509	end
510	function resolve(arr, inner, outer)	9✔
511	dims, inner, outer = pad(size(arr), to_tuple(inner), to_tuple(outer))	39✔
512	reshape(arr, dims), inner, outer	39✔
513	end
514	function resolve(arr, inner::Nothing, outer::Nothing)
515	return arr, inner, outer	6✔
516	end
517	function resolve(arr, inner::Nothing, outer)	12✔
518	dims, outer = pad(size(arr), to_tuple(outer))	931✔
519	reshape(arr, dims), inner, outer	931✔
520	end
521	function resolve(arr, inner, outer::Nothing)	6✔
522	dims, inner = pad(size(arr), to_tuple(inner))	33✔
523	reshape(arr, dims), inner, outer	33✔
524	end
525
526	function check(arr, inner, outer)	126✔
527	if inner !== nothing	1,099✔
528	# TODO: Currently one based indexing is demanded for inner !== nothing,
529	# but not for outer !== nothing. Decide for something consistent.
530	Base.require_one_based_indexing(arr)	165✔
531	if !all(n -> n isa Integer, inner)	525✔
532	throw(ArgumentError("repeat requires integer counts, got inner = $inner"))	×
533	end
534	if any(<(0), inner)	423✔
535	throw(ArgumentError("no inner repetition count may be negative; got $inner"))	3✔
536	end
537	if length(inner) < ndims(arr)	156✔
538	throw(ArgumentError("number of inner repetitions ($(length(inner))) cannot be less than number of dimensions of input array ($(ndims(arr)))"))	6✔
539	end
540	end
541	if outer !== nothing	1,087✔
542	if !all(n -> n isa Integer, outer)	2,571✔
543	throw(ArgumentError("repeat requires integer counts, got outer = $outer"))	×
544	end
545	if any(<(0), outer)	2,347✔
546	throw(ArgumentError("no outer repetition count may be negative; got $outer"))	×
547	end
548	if (length(outer) < ndims(arr)) && (inner !== nothing)	1,048✔
549	throw(ArgumentError("number of outer repetitions ($(length(outer))) cannot be less than number of dimensions of input array ($(ndims(arr)))"))	6✔
550	end
551	end
552	end
553
554	repeat_inner_outer(arr, inner::Nothing, outer::Nothing) = arr	6✔
555	repeat_inner_outer(arr, ::Nothing, outer) = repeat_outer(arr, outer)	931✔
556	repeat_inner_outer(arr, inner, ::Nothing) = repeat_inner(arr, inner)	33✔
557	repeat_inner_outer(arr, inner, outer) = repeat_outer(repeat_inner(arr, inner), outer)	111✔
558
559	function repeat_outer(a::AbstractMatrix, (m,n)::NTuple{2, Any})	218✔
560	o, p = size(a,1), size(a,2)	218✔
561	b = similar(a, om, pn)	218✔
562	for j=1:n	218✔
563	d = (j-1)*p+1	403✔
564	R = d:d+p-1	409✔
565	for i=1:m	403✔
566	c = (i-1)*o+1	580✔
567	@inbounds b[c:c+o-1, R] = a	586✔
568	end	799✔
569	end	615✔
570	return b	218✔
571	end
572
573	function repeat_outer(a::AbstractVector, (m,)::Tuple{Any})	23✔
574	o = length(a)	800✔
575	b = similar(a, o*m)	800✔
576	for i=1:m	800✔
577	c = (i-1)*o+1	3,034,173✔
578	@inbounds b[c:c+o-1] = a	6,087,384✔
579	end	6,067,672✔
580	return b	800✔
581	end
582
583	function repeat_outer(arr::AbstractArray{<:Any,N}, dims::NTuple{N,Any}) where {N}	24✔
584	insize = size(arr)	24✔
585	outsize = map(*, insize, dims)	24✔
586	out = similar(arr, outsize)	24✔
587	for I in CartesianIndices(arr)	48✔
588	for J in CartesianIndices(dims)	588✔
589	TIJ = map(Tuple(I), Tuple(J), insize) do i, j, d	1,908✔
590	i + d * (j-1)	5,724✔
591	end
592	IJ = CartesianIndex(TIJ)	1,908✔
593	@inbounds out[IJ] = arr[I]	1,908✔
594	end	2,202✔
595	end	318✔
596	return out	24✔
597	end
598
599	function repeat_inner(arr, inner)	144✔
600	outsize = map(*, size(arr), inner)	144✔
601	out = similar(arr, outsize)	144✔
602	for I in CartesianIndices(arr)	234✔
603	for J in CartesianIndices(inner)	759✔
604	TIJ = map(Tuple(I), Tuple(J), inner) do i, j, d	948✔
605	(i-1) * d + j	1,980✔
606	end
607	IJ = CartesianIndex(TIJ)	948✔
608	@inbounds out[IJ] = arr[I]	948✔
609	end	1,359✔
610	end	576✔
611	return out	144✔
612	end
613
614	end#module

JuliaLang / julia / 1572

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous