From 016467bd4a4cf240f3a146187818d0a06e515752 Mon Sep 17 00:00:00 2001
From: "Steven G. Johnson" <stevenj@alum.mit.edu>
Date: Thu, 5 Dec 2013 22:36:29 -0500
Subject: [PATCH] allow scale(b,A) or scale(A,b) when b is a scalar as well as
 a vector, don't restrict scale unnecessarily to arrays of numbers (e.g.
 scaling arrays of arrays should work), and improve documentation for scale\!

---
 base/linalg/generic.jl |  8 +++++---
 doc/stdlib/linalg.rst  | 29 +++++++++++++++++------------
 2 files changed, 22 insertions(+), 15 deletions(-)

diff --git a/base/linalg/generic.jl b/base/linalg/generic.jl
index 1aaabdfb70dde..0d47dd708cd48 100644
--- a/base/linalg/generic.jl
+++ b/base/linalg/generic.jl
@@ -1,13 +1,15 @@
 ## linalg.jl: Some generic Linear Algebra definitions
 
-scale{T<:Number}(X::AbstractArray{T}, s::Number) = scale!(copy(X), s)
+scale(X::AbstractArray, s::Number) = scale!(copy(X), s)
+scale(s::Number, X::AbstractArray) = scale!(copy(X), s)
 
-function scale!{T<:Number}(X::AbstractArray{T}, s::Number)
+function scale!(X::AbstractArray, s::Number)
     for i in 1:length(X)
-        X[i] *= s
+        @inbounds X[i] *= s
     end
     X
 end
+scale!(s::Number, X::AbstractArray) = scale!(X, s)
 
 cross(a::AbstractVector, b::AbstractVector) = [a[2]*b[3]-a[3]*b[2], a[3]*b[1]-a[1]*b[3], a[1]*b[2]-a[2]*b[1]]
 
diff --git a/doc/stdlib/linalg.rst b/doc/stdlib/linalg.rst
index 6a884a6c4e6f6..c49abcb5d1a76 100644
--- a/doc/stdlib/linalg.rst
+++ b/doc/stdlib/linalg.rst
@@ -247,23 +247,28 @@ Linear algebra functions in Julia are largely implemented by calling functions f
 
    Construct a diagonal matrix and place ``v`` on the ``k``-th diagonal.
 
-.. function:: scale(A, B)
+.. function:: scale(A, b), scale(b, A)
 
-   ``scale(A::Array, B::Number)`` scales all values in ``A`` with ``B``.
-   Note: In cases where the array is big enough, ``scale`` can be much
-   faster than ``A .* B``, due to the use of BLAS.
+   Scale an array ``A`` by a scalar ``b``, returning a new array.
 
-   ``scale(A::Matrix, B::Vector)`` is the same as multiplying with a
-   diagonal matrix on the right, and scales the columns of ``A`` with
-   the values in ``B``.
+   If ``A`` is a matrix and ``b`` is a vector, then ``scale!(A,b)``
+   scales each column ``i`` of ``A`` by ``b[i]`` (similar to
+   ``A*diagm(b)``), while ``scale!(b,A)`` scales each row ``i`` of
+   ``A`` by ``b[i]`` (similar to ``diagm(b)*A``), returning a new array.
 
-   ``scale(A::Vector, B::Matrix)`` is the same as multiplying with a
-   diagonal matrix on the left, and scales the rows of ``B`` with the
-   values in ``A``.
+   Note: for large ``A``, ``scale`` can be much faster than ``A .* b`` or
+   ``b .* A``, due to the use of BLAS.
 
-.. function:: scale!(A, B)
+.. function:: scale!(A, b), scale!(b, A)
 
-   ``scale!(A,B)`` overwrites the input array with the scaled result.
+   Scale an array ``A`` by a scalar ``b``, similar to ``scale`` but
+   overwriting ``A`` in-place.
+
+   If ``A`` is a matrix and ``b`` is a vector, then ``scale!(A,b)``
+   scales each column ``i`` of ``A`` by ``b[i]`` (similar to
+   ``A*diagm(b)``), while ``scale!(b,A)`` scales each row ``i`` of
+   ``A`` by ``b[i]`` (similar to ``diagm(b)*A``), again operating in-place
+   on ``A``.
 
 .. function:: symmetrize!(A[, UL::Char])