update manual for tuple type change

[ci skip]

doc/manual/calling-c-and-fortran-code.rst

@@ -288,8 +288,8 @@ Syntax / Keyword Example Description
 ``type ...; end`` ``nothing`` "Singleton" :: a Leaf Type or Immutable with no fields.
 
 ``(...)`` or ``tuple(...)``` ``(1,2,3)`` "Tuple" :: an immutable data-structure similar to an
- anonymous immutable type, or a constant array. Its
- storage semantics are TBD.
+ anonymous immutable type, or a constant array.
+ Represented as either an array or a struct.
 
 ``typealias`` Not applicable here Type aliases, and other similar mechanisms of
  doing type indirection, are resolved to their base

doc/manual/functions.rst

@@ -304,6 +304,8 @@ You can also return multiple values via an explicit usage of the
 
 This has the exact same effect as the previous definition of ``foo``.
 
+.. _man-varargs-functions:
+
 Varargs Functions
 -----------------
 

doc/manual/interacting-with-julia.rst

@@ -69,7 +69,7 @@ In addition to function names, complete function calls may be entered to see whi
  help> AbstractString
  DataType : AbstractString
  supertype: Any
- subtypes : {DirectIndexString,GenericString,RepString,RevString{T<:AbstractString},RopeString,SubString{T<:AbstractString},UTF16String,UTF8String}
+ subtypes : Any[DirectIndexString,GenericString,RepString,RevString{T<:AbstractString},RopeString,SubString{T<:AbstractString},UTF16String,UTF8String]
 
 Help mode can be exited by pressing backspace at the beginning of the line.
 

doc/manual/performance-tips.rst

@@ -425,7 +425,7 @@ by ``1`` input vector::
 
  julia> fmt(f) = println(rpad(string(f)*": ", 14, ' '), @elapsed f(x))
 
- julia> map(fmt, {copy_cols, copy_rows, copy_col_row, copy_row_col});
+ julia> map(fmt, Any[copy_cols, copy_rows, copy_col_row, copy_row_col]);
  copy_cols: 0.331706323
  copy_rows: 1.799009911
  copy_col_row: 0.415630047
@@ -753,7 +753,7 @@ example::
  x::Float64
  y::UNION(INT64,FLOAT64)
  _var0::Float64
- _var3::(Int64,)
+ _var3::Tuple{Int64}
  _var4::UNION(INT64,FLOAT64)
  _var1::Float64
  _var2::Float64

doc/manual/types.rst

@@ -197,9 +197,9 @@ When no supertype is given, the default supertype is :obj:`Any` — a
 predefined abstract type that all objects are instances of and all types
 are subtypes of. In type theory, :obj:`Any` is commonly called "top"
 because it is at the apex of the type graph. Julia also has a predefined
-abstract "bottom" type, at the nadir of the type graph, which is called
-``None``. It is the exact opposite of :obj:`Any`: no object is an instance
-of ``None`` and all types are supertypes of ``None``.
+abstract "bottom" type, at the nadir of the type graph, which is written as
+``Union()``. It is the exact opposite of :obj:`Any`: no object is an instance
+of ``Union()`` and all types are supertypes of ``Union()``.
 
 Let's consider some of the abstract types that make up Julia's numerical
 hierarchy::
@@ -546,65 +546,7 @@ Thus a bits type is a :obj:`DataType` with nonzero size, but no field
 names. A composite type is a :obj:`DataType` that has field names or
 is empty (zero size).
 
-Every concrete value in the system is either an instance of some
-:obj:`DataType`, or is a tuple.
-
-Tuple Types
------------
-
-Tuples are an abstraction of the arguments of a function — without the
-function itself. The salient aspects of a function's arguments are their
-order and their types. The type of a tuple of values is the tuple of
-types of values:
-
-.. doctest::
-
- julia> typeof((1,"foo",2.5))
- (Int64,ASCIIString,Float64)
-
-Accordingly, a tuple of types can be used anywhere a type is expected:
-
-.. doctest::
-
- julia> (1,"foo",2.5) :: (Int64,AbstractString,Any)
- (1,"foo",2.5)
-
- julia> (1,"foo",2.5) :: (Int64,AbstractString,Float32)
- ERROR: type: typeassert: expected (Int64,AbstractString,Float32), got (Int64,ASCIIString,Float64)
-
-If one of the components of the tuple is not a type, however, you will
-get an error:
-
-.. doctest::
-
- julia> (1,"foo",2.5) :: (Int64,AbstractString,3)
- ERROR: type: typeassert: expected Type{T<:Top}, got (DataType,DataType,Int64)
-
-Note that the empty tuple ``()`` is its own type:
-
-.. doctest::
-
- julia> typeof(())
- ()
-
-Tuple types are *covariant* in their constituent types, which means
-that one tuple type is a subtype of another if elements of the first
-are subtypes of the corresponding elements of the second. For
-example:
-
-.. doctest::
-
- julia> (Int,AbstractString) <: (Real,Any)
- true
-
- julia> (Int,AbstractString) <: (Real,Real)
- false
-
- julia> (Int,AbstractString) <: (Real,)
- false
-
-Intuitively, this corresponds to the type of a function's arguments
-being a subtype of the function's signature (when the signature matches).
+Every concrete value in the system is an instance of some :obj:`DataType`.
 
 Type Unions
 -----------
@@ -626,18 +568,7 @@ instances of any of its argument types, constructed using the special
  ERROR: type: typeassert: expected Union(AbstractString,Int64), got Float64
 
 The compilers for many languages have an internal union construct for
-reasoning about types; Julia simply exposes it to the programmer. The
-union of no types is the "bottom" type, ``None``:
-
-.. doctest::
-
- julia> None
- Union()
-
-Recall from the `discussion above <#Any+and+None>`_ that ``None`` is the
-abstract type which is the subtype of all other types, and which no
-object is an instance of. ``None`` is therefore synonymous with a zero-argument
-``Union`` type, which has no argument types for objects to be instances of.
+reasoning about types; Julia simply exposes it to the programmer.
 
 .. _man-parametric-types:
 
@@ -978,6 +909,77 @@ type ``T`` is restricted to being a subtype of :class:`Integer`, and a ratio
 of integers represents a value on the real number line, so any
 :obj:`Rational` is an instance of the :obj:`Real` abstraction.
 
+Tuple Types
+~~~~~~~~~~~
+
+Tuples are an abstraction of the arguments of a function — without the
+function itself. The salient aspects of a function's arguments are their
+order and their types. Therefore a tuple type is similar to a
+parameterized immutable type where each parameter is the type
+of one field. For example, a 2-element tuple type resembles the following
+immutable type:
+
+ immutable Tuple2{A,B}
+ a::A
+ b::B
+ end
+
+However, there are three key differences:
+
+- Tuple types may have any number of parameters.
+- Tuple types are *covariant* in their parameters: ``Tuple{Int}`` is a subtype
+ of ``Tuple{Any}``. Therefore ``Tuple{Any}`` is considered an abstract type,
+ and tuple types are only concrete if their parameters are.
+- Tuples do not have field names; fields are only accessed by index.
+
+Tuple values are written with parentheses and commas. When a tuple is constructed,
+an appropriate tuple type is generated on demand:
+
+.. doctest::
+
+ julia> typeof((1,"foo",2.5))
+ Tuple{Int64,ASCIIString,Float64}
+
+Note the implications of covariance:
+
+.. doctest::
+
+ julia> Tuple{Int,AbstractString} <: Tuple{Real,Any}
+ true
+
+ julia> Tuple{Int,AbstractString} <: Tuple{Real,Real}
+ false
+
+ julia> Tuple{Int,AbstractString} <: Tuple{Real,}
+ false
+
+Intuitively, this corresponds to the type of a function's arguments
+being a subtype of the function's signature (when the signature matches).
+
+Vararg Tuple Types
+~~~~~~~~~~~~~~~~~~
+
+The last parameter of a tuple type can be the special type ``Vararg``,
+which denotes any number of trailing elements:
+
+.. doctest::
+
+ julia> isa(("1",), Tuple{String,Vararg{Int}})
+ true
+
+ julia> isa(("1",1), Tuple{String,Vararg{Int}})
+ true
+
+ julia> isa(("1",1,2), Tuple{String,Vararg{Int}})
+ true
+
+ julia> isa(("1",1,2,3.0), Tuple{String,Vararg{Int}})
+ false
+
+Notice that ``Vararg{T}`` matches zero or more elements of type ``T``.
+Vararg tuple types are used to represent the arguments accepted by varargs
+methods (see :ref:`man-varargs-functions`).
+
 .. _man-singleton-types:
 
 Singleton Types
@@ -1173,8 +1175,8 @@ objects, they also have types, and we can ask what their types are:
  julia> typeof(Union(Real,Float64,Rational))
  DataType
 
- julia> typeof((Rational,None))
- (DataType,UnionType)
+ julia> typeof(Union(Real,ASCIIString))
+ UnionType
 
 What if we repeat the process? What is the type of a type of a type?
 As it happens, types are all composite values and thus all have a type of
@@ -1188,30 +1190,7 @@ As it happens, types are all composite values and thus all have a type of
  julia> typeof(UnionType)
  DataType
 
-The reader may note that :obj:`DataType` shares with the empty tuple
-(see `above <#tuple-types>`_), the distinction of being its own type
-(i.e. a fixed point of the :func:`typeof` function). This leaves any number
-of tuple types recursively built with ``()`` and :obj:`DataType` as
-their only atomic values, which are their own type:
-
-.. doctest::
-
- julia> typeof(())
- ()
-
- julia> typeof(DataType)
- DataType
-
- julia> typeof(((),))
- ((),)
-
- julia> typeof((DataType,))
- (DataType,)
-
- julia> typeof(((),DataType))
- ((),DataType)
-
-All fixed points of :func:`typeof` are like this.
+:obj:`DataType` is its own type.
 
 Another operation that applies to some types is :func:`super`, which
 reveals a type's supertype.
@@ -1237,12 +1216,6 @@ If you apply :func:`super` to other type objects (or non-type objects), a
  julia> super(Union(Float64,Int64))
  ERROR: `super` has no method matching super(::Type{Union(Float64,Int64)})
 
- julia> super(None)
- ERROR: `super` has no method matching super(::Type{None})
-
- julia> super((Float64,Int64))
- ERROR: `super` has no method matching super(::Type{(Float64,Int64)})
-
 "Value types"
 -------------