= -- assignment

Description

In this section we'll discuss simple assignment to variables, multiple assignment, assignment to parts of objects, assignment covered by various other methods, and briefly touch on the possibility of custom installation of assignment methods. See also the operator :=, which handles assignment and declaration of local variables and assignment of methods to operators, as well as the operator <-, which is an assignment operator that evaluates its left hand side and can have assignment methods installed for it by the user.

simple assignment

Usage:
x = e
Inputs:
- x, a symbol, (unevaluated)
- e, a thing
Consequences:
- e is assigned to x, so future references to the value of x yield e
- if x is a global variable, then the global assignment hook for the class of e, if any, is run (see GlobalAssignHook), and the global assignment hook for the symbol itself (see globalAssignmentHooks), if any, is run.
Outputs:
- a thing, the value of the expression is e

i1 : x

o1 = x

o1 : Symbol

i2 : x = 4

o2 = 4

i3 : x

o3 = 4

Since the value of the entire expression is e, and since the operator = is right-associative (see precedence of operators), e can be easily assigned to more than one variable, as in the following example.

i4 : x = y = 44

o4 = 44

i5 : x

o5 = 44

i6 : y

o6 = 44

multiple assignment

Usage:
(x,y,z,...) = (c,d,e,...)
Inputs:
- (x,y,z,...) a sequence of symbols (unevaluated)
- (c,d,e,...) a sequence of things
Consequences:
- the expressions c,d,e,... are assigned to the variables x,y,z,..., respectively, as above. Global assignment hooks may be run, as above.
- If the left hand side has more elements than the right hand side, then the extra symbols on the left side are given the value null.
- If the left hand side has fewer elements than the right hand side, then the last symbol on the left hand side is given as value a sequence containing the trailing elements of the right hand side.
- If the right hand side is not a sequence, then it is assigned to the first symbol on the left, and the remaining symbols are assigned the value null.
Outputs:
- the value of the expression is (c,d,e,...)

Multiple assignment makes it easy to switch the values of two variables, or to permute the values of several.

i7 : x = 444

o7 = 444

i8 : y = foo

o8 = foo

o8 : Symbol

i9 : (y,x) = (x,y)

o9 = (444, foo)

o9 : Sequence

i10 : x

o10 = foo

o10 : Symbol

i11 : y

o11 = 444

Multiple assignment effectively means that functions can return multiple values usefully.

i12 : f = i -> (i,i^2)

o12 = f

o12 : FunctionClosure

i13 : (x,y) = f 9

o13 = (9, 81)

o13 : Sequence

i14 : x

o14 = 9

i15 : y

o15 = 81

assignment to an element of a mutable list

Usage:
x#i = e
Inputs:
- x, a mutable list
- i, an integer
- e, a thing
Consequences:
- the i-th element of the list x is replaced by e, so that future references to the value of x#i yield e
Outputs:
- the value of the expression is e

i16 : x = new MutableList from a .. e

o16 = MutableList{...5...}

o16 : MutableList

i17 : peek x

o17 = MutableList{a, b, c, d, e}

i18 : x#3

o18 = d

o18 : Symbol

i19 : x#3 = "foo"

o19 = foo

i20 : x#3

o20 = foo

i21 : peek x

o21 = MutableList{a, b, c, foo, e}

assignment to an element of a mutable hash table

Usage:
x#i = e
Inputs:
- x, a mutable list
- i, a thing
- e, a thing
Consequences:
- e is stored in the hash table x under the key i, so that future references to the value of x#i yield e
- future references to the value of x#?i will yield the value true, indicating that something has been stored in x under the key i. See #?.
Outputs:
- the value of the expression is e

i22 : x = new MutableHashTable from { "a" => 2, "b" => 3 }

o22 = MutableHashTable{...2...}

o22 : MutableHashTable

i23 : peek x

o23 = MutableHashTable{a => 2}
                       b => 3

i24 : x#?"foo"

o24 = false

i25 : x#"foo" = "bar"

o25 = bar

i26 : x#?"foo"

o26 = true

i27 : x#"foo"

o27 = bar

i28 : peek x

o28 = MutableHashTable{a => 2    }
                       b => 3
                       foo => bar

installing assignment methods for binary operators

Usage:
X OP Y = (x,y,e) -> ...
Inputs:
- X, a type
- OP, one of the binary operators for which users may install methods, namely: % & * ** + ++ - .. / // : << <==> == ===> ==> >> ? @ @@ \ \\ ^ ^** ^^ _ | |- || and or SPACE . The operator SPACE, indicating adjacency, may be omitted from the usage above.
- Y, a type
- (x,y,e) -> ..., a function
Consequences:
- the function on the right hand side is installed as the method for assignment to X OP Y. See the next subsection below for using it
Outputs:
- the value of the expression is the same as the function on the right hand side

The first line of the following example illustrates the syntax above.

i29 : String * String = peek;

i30 : "left" * "right" = "value"

o30 = ("left", "right", "value")

Warning: the installation of new methods may supplant old ones, changing the behavior of Macaulay 2.

using assignment methods for binary operators

Usage:
x OP y = e
Inputs:
- x, an object of type X
- OP, one of the binary operators for which users may install methods, listed above. The operator SPACE, indicating adjacency, may be omitted from the usage above.
- y, an object of type Y
- e, a thing
Outputs:
- the previously installed method for assignment to X OP Y is called with arguments (x,y,e), and its return value is returned. If no such method has been installed, then Macaulay 2 searches for a method for assignment to X' OP Y', where X' is an ancestor of X and Y' is an ancestor of Y (see inheritance for details).

The return value and the consequences depend on the code of the installed assignment method. References to currently installed assignment methods are given below.

The second line of the following example illustrates the syntax above.

i31 : String * String = peek;

i32 : "left" * "right" = "value"

o32 = ("left", "right", "value")

assignment to indexed variables

Usage:
x_i = e
Inputs:
- x, a symbol, (evaluated)
- i, a thing
- e, a thing
Consequences:
- The indexed variable x_i is created (if necessary) and is assigned the value e so that future references to x_i yield the value e. Moreover, the value of the symbol x is set to x.
Outputs:
- e

The method for assignment to indexed variables is pre-installed.

i33 : s

o33 = s

o33 : Symbol

i34 : s_2

o34 = s
       2

o34 : IndexedVariable

i35 : s_2 = 44

o35 = 44

i36 : s_2

o36 = 44

i37 : s_(i,j)

o37 = s
       i,j

o37 : IndexedVariable

installing assignment methods for unary prefix operators

Usage:
OP X = (x,e) -> ...
Inputs:
- OP, one of the unary prefix operators for which users may install methods, namely: * + - < << <= > >= ? |- not
- X, a type
- (x,e) -> ..., a function
Consequences:
- the function on the right hand side is installed as the method for assignment to OP X. See the next subsection below for using it.
Outputs:
- the value of the expression is the same as the function on the right hand side

The first line of the following example illustrates the syntax above.

i38 : - String = peek;

i39 : - "foo" = "value"

o39 = ("foo", "value")

Warning: the installation of new methods may supplant old ones, changing the behavior of Macaulay 2.

using assignment methods for unary prefix operators

Usage:
OP x = e
Inputs:
- OP, one of the unary prefix operators for which users may install methods, listed above.
- x, an object of type X
- e, a thing
Outputs:
- the previously installed method for assignment to OP X is called with arguments (x,e), and its return value is returned.

The return value and the consequences depend on the code of the installed assignment method. References to currently installed assignment methods are given below.

The second line of the following example illustrates the syntax above.

i40 : - String = peek;

i41 : - "foo" = "value"

o41 = ("foo", "value")

installing assignment methods for unary postfix operators

Usage:
X OP = (x,e) -> ...
Inputs:
- OP, one of the unary postfix operators for which users may install methods, namely: (*) ~
- X, a type
- (x,e) -> ..., a function
Consequences:
- the function on the right hand side is installed as the method for assignment to OP X. See the next subsection below for using it.
Outputs:
- the value of the expression is the same as the function on the right hand side

The first line of the following example illustrates the syntax above.

i42 : String ~ = peek;

i43 : "foo" ~ = "value"

o43 = ("foo", "value")

Warning: the installation of new methods may supplant old ones, changing the behavior of Macaulay 2.

using assignment methods for unary postfix operators

Usage:
x OP = e
Inputs:
- x, an object of type X
- OP, one of the unary postfix operators for which users may install methods, listed above.
- e, a thing
Outputs:
- the previously installed method for assignment to X OP is called with arguments (x,e), and its return value is returned.

The return value and the consequences depend on the code of the installed assignment method. References to currently installed assignment methods are given below.

The second line of the following example illustrates the syntax above.

i44 : String ~ = peek;

i45 : "foo" ~ = "value"

o45 = ("foo", "value")

Ways to use `=` :

ChainComplex _ ZZ = Thing -- missing documentation
ChainComplexMap _ ZZ = Thing -- missing documentation
MutableMatrix _ Sequence = Thing -- assignment to an element of a mutable matrix
Symbol _ Thing = Thing -- assignment to an indexed variable

For the programmer

The object = is a keyword.

= -- assignment

Description

simple assignment

multiple assignment

assignment to an element of a mutable list

assignment to an element of a mutable hash table

installing assignment methods for binary operators

using assignment methods for binary operators

assignment to indexed variables

installing assignment methods for unary prefix operators

using assignment methods for unary prefix operators

installing assignment methods for unary postfix operators

using assignment methods for unary postfix operators

See also

Ways to use = :

For the programmer

Ways to use `=` :