Skip to content

Commit

Permalink
"Named arguments" -> "Keyword arguments"
Browse files Browse the repository at this point in the history
  • Loading branch information
staticfloat committed Nov 10, 2013
1 parent 3933141 commit 6d1a5f3
Show file tree
Hide file tree
Showing 4 changed files with 19 additions and 20 deletions.
17 changes: 8 additions & 9 deletions doc/manual/functions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -396,40 +396,39 @@ multiple method definitions with different numbers of arguments
(see :ref:`man-methods`).


Named Arguments
Keyword Arguments
---------------

Some functions need a large number of arguments, or have a large number of
behaviors. Remembering how to call such functions can be difficult. Named
arguments, also called keyword arguments, can make these complex interfaces
easier to use and extend by allowing arguments to be identified by name
instead of only by position.
behaviors. Remembering how to call such functions can be difficult. Keyword
arguments can make these complex interfaces easier to use and extend by
allowing arguments to be identified by name instead of only by position.

For example, consider a function ``plot`` that
plots a line. This function might have many options, for controlling line
style, width, color, and so on. If it accepts named arguments, a possible
style, width, color, and so on. If it accepts keyword arguments, a possible
call might look like ``plot(x, y, width=2)``, where we have chosen to
specify only line width. Notice that this serves two purposes. The call is
easier to read, since we can label an argument with its meaning. It also
becomes possible to pass any subset of a large number of arguments, in
any order.

Functions with named arguments are defined using a semicolon in the
Functions with keyword arguments are defined using a semicolon in the
signature::

function plot(x, y; style="solid", width=1, color="black")
###
end

Extra named arguments can be collected using ``...``, as in varargs
Extra keyword arguments can be collected using ``...``, as in varargs
functions::

function f(x; args...)
###
end

Inside ``f``, ``args`` will be a collection of ``(key,value)`` tuples,
where each ``key`` is a symbol. Such collections can be passed as named
where each ``key`` is a symbol. Such collections can be passed as keyword
arguments using a semicolon in a call, ``f(x; k...)``. Dictionaries
can be used for this purpose.

Expand Down
6 changes: 3 additions & 3 deletions doc/manual/methods.rst
Original file line number Diff line number Diff line change
Expand Up @@ -441,7 +441,7 @@ can also constrain type parameters of methods::
The ``same_type_numeric`` function behaves much like the ``same_type``
function defined above, but is only defined for pairs of numbers.

Note on Optional and Named Arguments
Note on Optional and keyword Arguments
------------------------------------

As mentioned briefly in :ref:`man-functions`, optional arguments are
Expand All @@ -456,9 +456,9 @@ translates to the following three methods::
f(a) = f(a,2)
f() = f(1,2)

Named arguments behave quite differently from ordinary positional arguments.
Keyword arguments behave quite differently from ordinary positional arguments.
In particular, they do not participate in method dispatch. Methods are
dispatched based only on positional arguments, with named arguments processed
dispatched based only on positional arguments, with keyword arguments processed
after the matching method is identified.

.. [Clarke61] Arthur C. Clarke, *Profiles of the Future* (1961): Clarke's Third Law.
Expand Down
14 changes: 7 additions & 7 deletions doc/manual/performance-tips.rst
Original file line number Diff line number Diff line change
Expand Up @@ -103,24 +103,24 @@ Here, we happened to know that the first element of ``a`` would be an
will raise a run-time error if the value is not of the expected type,
potentially catching certain bugs earlier.

Declare types of named arguments
Declare types of keyword arguments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Named arguments can have declared types::
Keyword arguments can have declared types::

function with_named(x; name::Int = 1)
function with_keyword(x; name::Int = 1)
...
end

Functions are specialized on the types of named arguments, so these
Functions are specialized on the types of keyword arguments, so these
declarations will not affect performance of code inside the function.
However, they will reduce the overhead of calls to the function that
include named arguments.
include keyword arguments.

Functions with named arguments have near-zero overhead for call sites
Functions with keyword arguments have near-zero overhead for call sites
that pass only positional arguments.

Passing dynamic lists of named arguments, as in ``f(x; names...)``,
Passing dynamic lists of keyword arguments, as in ``f(x; keywords...)``,
can be slow and should be avoided in performance-sensitive code.

Break functions into multiple definitions
Expand Down
2 changes: 1 addition & 1 deletion doc/stdlib/profile.rst
Original file line number Diff line number Diff line change
Expand Up @@ -215,7 +215,7 @@ Let's discuss these arguments in order:
@profile Profile.print(STDOUT, data) # Prints the previous results
Profile.print() # Prints results from Profile.print()

- The first named argument, ``format``, was introduced above. The
- The first keyword argument, ``format``, was introduced above. The
possible choices are ``:tree`` and ``:flat``.
- ``C``, if set to ``true``, allows you to see even the calls to C
code. Try running the introductory example with ``Profile.print(C =
Expand Down

0 comments on commit 6d1a5f3

Please sign in to comment.