U:RDoc::TopLevel[	iI"syntax/assignment.rdoc:EFcRDoc::Parser::Simpleo:RDoc::Markup::Document:@parts[
ÀS:RDoc::Markup::Heading:
leveli:	textI"Assignment;To:RDoc::Markup::BlankLineo:RDoc::Markup::Paragraph;[I"OIn Ruby assignment uses the <code>=</code> (equals sign) character.  This ;TI"?example assigns the number five to the local variable +v+:;T@
o:RDoc::Markup::Verbatim;[I"v = 5
;T:@format0o;
;[I"LAssignment creates a local variable if the variable was not previously ;TI"referenced.;T@
S;	;
i;I"Local Variable Names;T@
o;
;[I"LA local variable name must start with a lowercase US-ASCII letter or a ;TI"Ocharacter with the eight bit set.  Typically local variables are US-ASCII ;TI"Ccompatible since the keys to type them exist on all keyboards.;T@
o;
;[I"P(Ruby programs must be written in a US-ASCII-compatible character set.  In ;TI"Jsuch character sets if the eight bit is set it indicates an extended ;TI"Icharacter.  Ruby allows local variables to contain such characters.);T@
o;
;[I"KA local variable name may contain letters, numbers, an <code>_</code> ;TI"E(underscore or low line) or a character with the eighth bit set.;T@
S;	;
i;I"Local Variable Scope;T@
o;
;[I"ROnce a local variable name has been assigned-to all uses of the name for the ;TI"6rest of the scope are considered local variables.;T@
o;
;[I"Here is an example:;T@
o;;[I"1.times do
;TI"
  a = 1
;TI"I  puts "local variables in the block: #{local_variables.join ", "}"
;TI"	end
;TI"
;TI"Kputs "no local variables outside the block" if local_variables.empty?
;T;0o;
;[I"This prints:;T@
o;;[I"%local variables in the block: a
;TI"*no local variables outside the block
;T;0o;
;[I"SSince the block creates a new scope, any local variables created inside it do ;TI"'not leak to the surrounding scope.;T@
o;
;[I"<Variables defined in an outer scope appear inner scope:;T@
o;;[
I"a = 0
;TI"
;TI"1.times do
;TI"<  puts "local variables: #{local_variables.join ", "}"
;TI"	end
;T;0o;
;[I"This prints:;T@
o;;[I"local variables: a
;T;0o;
;[	I"OYou may isolate variables in a block from the outer scope by listing them ;TI"Qfollowing a <code>;</code> in the block's arguments.  See the documentation ;TI"/for block local variables in the {calling ;TI"Qmethods}[rdoc-ref:syntax/calling_methods.rdoc] documentation for an example.;T@
o;
;[I"SSee also Kernel#local_variables, but note that a +for+ loop does not create a ;TI"!new scope like a block does.;T@
S;	;
i;I" Local Variables and Methods;T@
o;
;[	I"QIn Ruby local variable names and method names are nearly identical.  If you ;TI"Thave not assigned to one of these ambiguous names ruby will assume you wish to ;TI"Rcall a method.  Once you have assigned to the name ruby will assume you wish ;TI"#to reference a local variable.;T@
o;
;[I"RThe local variable is created when the parser encounters the assignment, not ;TI" when the assignment occurs:;T@
o;;[
I"+a = 0 if false # does not assign to a
;TI"
;TI"%p local_variables # prints [:a]
;TI"
;TI"p a # prints nil
;T;0o;
;[I"RThe similarity between method and local variable names can lead to confusing ;TI"code, for example:;T@
o;;[
I"def big_calculation
;TI"+  42 # pretend this takes a long time
;TI"	end
;TI"
;TI")big_calculation = big_calculation()
;T;0o;
;[I"TNow any reference to +big_calculation+ is considered a local variable and will ;TI"Kbe cached.  To call the method, use <code>self.big_calculation</code>.;T@
o;
;[I"TYou can force a method call by using empty argument parentheses as shown above ;TI"Ror by using an explicit receiver like <code>self.</code>.  Using an explicit ;TI"Mreceiver may raise a NameError if the method's visibility is not public.;T@
o;
;[I"CAnother commonly confusing case is when using a modifier +if+:;T@
o;;[I"p a if a = 0.zero?
;T;0o;
;[
I"TRather than printing "true" you receive a NameError, "undefined local variable ;TI"Tor method `a'".  Since ruby parses the bare +a+ left of the +if+ first and has ;TI"Snot yet seen an assignment to +a+ it assumes you wish to call a method.  Ruby ;TI"Qthen sees the assignment to +a+ and will assume you are referencing a local ;TI"method.;T@
o;
;[I"SThe confusion comes from the out-of-order execution of the expression.  First ;TI"Nthe local variable is assigned-to then you attempt to call a nonexistent ;TI"method.;T@
S;	;
i;I"Instance Variables;T@
o;
;[I"JInstance variables are shared across all methods for the same object.;T@
o;
;[	I"IAn instance variable must start with a <code>@</code> ("at" sign or ;TI"Rcommercial at).  Otherwise instance variable names follow the rules as local ;TI"Tvariable names.  Since the instance variable starts with an <code>@</code> the ;TI"2second character may be an upper-case letter.;T@
o;
;[I"3Here is an example of instance variable usage:;T@
o;;[I"
class C
;TI"  def initialize(value)
;TI"$    @instance_variable = value
;TI"  end
;TI"
;TI"  def value
;TI"    @instance_variable
;TI"  end
;TI"	end
;TI"
;TI""object1 = C.new "some value"
;TI"#object2 = C.new "other value"
;TI"
;TI"+p object1.value # prints "some value"
;TI",p object2.value # prints "other value"
;T;0o;
;[I"TAn uninitialized instance variable has a value of +nil+.  If you run Ruby with ;TI"Mwarnings enabled you will get a warning when accessing an uninitialized ;TI"instance variable.;T@
o;
;[I"TThe +value+ method has access to the value set by the +initialize+ method, but ;TI"only for the same object.;T@
S;	;
i;I"Class Variables;T@
o;
;[I"RClass variables are shared between a class, its subclasses and its instances.;T@
o;
;[I"TA class variable must start with a <code>@@</code> (two "at" signs).  The rest ;TI">of the name follows the same rules as instance variables.;T@
o;
;[I"Here is an example:;T@
o;;[I"
class A
;TI"  @@class_variable = 0
;TI"
;TI"  def value
;TI"    @@class_variable
;TI"  end
;TI"
;TI"  def update
;TI"1    @@class_variable = @@class_variable + 1
;TI"  end
;TI"	end
;TI"
;TI"class B < A
;TI"  def update
;TI"1    @@class_variable = @@class_variable + 2
;TI"  end
;TI"	end
;TI"
;TI"a = A.new
;TI"b = B.new
;TI"
;TI" puts "A value: #{a.value}"
;TI" puts "B value: #{b.value}"
;T;0o;
;[I"This prints:;T@
o;;[I"A value: 0
;TI"B value: 0
;T;0o;
;[I"OContinuing with the same example, we can update using objects from either ;TI"#class and the value is shared:;T@
o;;[I"puts "update A"
;TI"a.update
;TI"
;TI" puts "A value: #{a.value}"
;TI" puts "B value: #{b.value}"
;TI"
;TI"puts "update B"
;TI"b.update
;TI"
;TI" puts "A value: #{a.value}"
;TI" puts "B value: #{b.value}"
;TI"
;TI"puts "update A"
;TI"a.update
;TI"
;TI" puts "A value: #{a.value}"
;TI" puts "B value: #{b.value}"
;T;0o;
;[I"This prints:;T@
o;;[I"update A
;TI"A value: 1
;TI"B value: 1
;TI"update B
;TI"A value: 3
;TI"B value: 3
;TI"update A
;TI"A value: 4
;TI"B value: 4
;T;0o;
;[I"PAccessing an uninitialized class variable will raise a NameError exception.;T@
o;
;[I"ONote that classes have instance variables because classes are objects, so ;TI"5try not to confuse class and instance variables.;T@
S;	;
i;I"Global Variables;T@
o;
;[I"0Global variables are accessible everywhere.;T@
o;
;[I"RGlobal variables start with a <code>$</code> (dollar sign).  The rest of the ;TI"7name follows the same rules as instance variables.;T@
o;
;[I"Here is an example:;T@
o;;[I"$global = 0
;TI"
;TI"
class C
;TI"%  puts "in a class: #{$global}"
;TI"
;TI"  def my_method
;TI"(    puts "in a method: #{$global}"
;TI"
;TI"    $global = $global + 1
;TI"    $other_global = 3
;TI"  end
;TI"	end
;TI"
;TI"C.new.my_method
;TI"
;TI"Oputs "at top-level, $global: #{$global}, $other_global: #{$other_global}"
;T;0o;
;[I"This prints:;T@
o;;[I"in a class: 0
;TI"in a method: 0
;TI"0at top-level, $global: 1, $other_global: 3
;T;0o;
;[I";An uninitialized global variable has a value of +nil+.;T@
o;
;[	I"PRuby has some special globals that behave differently depending on context ;TI"Tsuch as the regular expression match variables or that have a side-effect when ;TI"Sassigned to.  See the {global variables documentation}[rdoc-ref:globals.rdoc] ;TI"for details.;T@
S;	;
i;I"Assignment Methods;T@
o;
;[I"JYou can define methods that will behave like assignment, for example:;T@
o;;[
I"
class C
;TI"  def value=(value)
;TI"    @value = value
;TI"  end
;TI"	end
;TI"
;TI"c = C.new
;TI"c.value = 42
;T;0o;
;[I"RUsing assignment methods allows your programs to look nicer.  When assigning ;TI"Bto an instance variable most people use Module#attr_accessor:;T@
o;;[I"
class C
;TI"  attr_accessor :value
;TI"	end
;T;0o;
;[I"RWhen using method assignment you must always have a receiver.  If you do not ;TI"Hhave a receiver Ruby assumes you are assigning to a local variable:;T@
o;;[I"
class C
;TI"  attr_accessor :value
;TI"
;TI"  def my_method
;TI"    value = 42
;TI"
;TI">    puts "local_variables: #{local_variables.join ", "}"
;TI"*    puts "@value: #{@value.inspect}"
;TI"  end
;TI"	end
;TI"
;TI"C.new.my_method
;T;0o;
;[I"This prints:;T@
o;;[I"local_variables: value
;TI"@value: nil
;T;0o;
;[I"<To use the assignment method you must set the receiver:;T@
o;;[I"
class C
;TI"  attr_accessor :value
;TI"
;TI"  def my_method
;TI"    self.value = 42
;TI"
;TI">    puts "local_variables: #{local_variables.join ", "}"
;TI"*    puts "@value: #{@value.inspect}"
;TI"  end
;TI"	end
;TI"
;TI"C.new.my_method
;T;0o;
;[I"This prints:;T@
o;;[I"local_variables:
;TI"@value: 42
;T;0S;	;
i;I"Abbreviated Assignment;T@
o;
;[I"QYou can mix several of the operators and assignment.  To add 1 to an object ;TI"you can write:;T@
o;;[
I"a = 1
;TI"
;TI"a += 2
;TI"
;TI"p a # prints 3
;T;0o;
;[I"This is equivalent to:;T@
o;;[
I"a = 1
;TI"
;TI"a = a + 2
;TI"
;TI"p a # prints 3
;T;0o;
;[	I"TYou can use the following operators this way:  <code>+</code>, <code>-</code>, ;TI"F<code>*</code>, <code>/</code>, <code>%</code>, <code>**</code>, ;TI"F<code>&</code>, <code>|</code>, <code>^</code>, <code><<</code>, ;TI"<code>>></code>;T@
o;
;[I"PThere are also <code>||=</code> and <code>&&=</code>.  The former makes an ;TI"Lassignment if the value was +nil+ or +false+ while the latter makes an ;TI"6assignment if the value was not +nil+ or +false+.;T@
o;
;[I"Here is an example:;T@
o;;[	I"
a ||= 0
;TI"
a &&= 1
;TI"
;TI"p a # prints 1
;T;0o;
;[I"QNote that these two operators behave more like <code>a || a = 0</code> than ;TI"<code>a = a || 0</code>.;T@
S;	;
i;I"Implicit Array Assignment;T@
o;
;[I"RYou can implicitly create an array by listing multiple values when assigning:;T@
o;;[I"a = 1, 2, 3
;TI"
;TI"p a # prints [1, 2, 3]
;T;0o;
;[I"&This implicitly creates an Array.;T@
o;
;[I"PYou can use <code>*</code> or the "splat" operator or unpack an Array when ;TI"8assigning.  This is similar to multiple assignment:;T@
o;;[I"a = *[1, 2, 3]
;TI"
;TI"p a # prints [1, 2, 3]
;T;0o;
;[I"EYou can splat anywhere in the right-hand side of the assignment:;T@
o;;[I"a = 1, *[2, 3]
;TI"
;TI"p a # prints [1, 2, 3]
;T;0S;	;
i;I"Multiple Assignment;T@
o;
;[I"QYou can assign multiple values on the right-hand side to multiple variables:;T@
o;;[I"a, b = 1, 2
;TI"
;TI"*p a: a, b: b # prints {:a=>1, :b=>2}
;T;0o;
;[I"RIn the following sections any place "variable" is used an assignment method, ;TI".instance, class or global will also work:;T@
o;;[I"def value=(value)
;TI"  p assigned: value
;TI"	end
;TI"
;TI"8self.value, $global = 1, 2 # prints {:assigned=>1}
;TI"
;TI"p $global # prints 2
;T;0o;
;[I"AYou can use multiple assignment to swap two values in-place:;T@
o;;[I"old_value = 1
;TI"
;TI")new_value, old_value = old_value, 2
;TI"
;TI"2p new_value: new_value, old_value: old_value
;TI"-# prints {:new_value=>1, :old_value=>2}
;T;0o;
;[I"UIf you have more values on the right hand side of the assignment than variables ;TI"8on the left hand side the extra values are ignored:;T@
o;;[I"a, b = 1, 2, 3
;TI"
;TI"*p a: a, b: b # prints {:a=>1, :b=>2}
;T;0o;
;[I"QYou can use <code>*</code> to gather extra values on the right-hand side of ;TI"the assignment.;T@
o;;[I"a, *b = 1, 2, 3
;TI"
;TI"/p a: a, b: b # prints {:a=>1, :b=>[2, 3]}
;T;0o;
;[I"BThe <code>*</code> can appear anywhere on the left-hand side:;T@
o;;[I"*a, b = 1, 2, 3
;TI"
;TI"/p a: a, b: b # prints {:a=>[1, 2], :b=>3}
;T;0o;
;[I">But you may only use one <code>*</code> in an assignment.;T@
S;	;
i;I"Array Decomposition;T@
o;
;[I"RLike Array decomposition in {method arguments}[rdoc-ref:syntax/methods.rdoc] ;TI"Dyou can decompose an Array during assignment using parenthesis:;T@
o;;[I"(a, b) = [1, 2]
;TI"
;TI"*p a: a, b: b # prints {:a=>1, :b=>2}
;T;0o;
;[I"HYou can decompose an Array as part of a larger multiple assignment:;T@
o;;[I"a, (b, c) = 1, [2, 3]
;TI"
;TI"7p a: a, b: b, c: c # prints {:a=>1, :b=>2, :c=>3}
;T;0o;
;[I"TSince each decomposition is considered its own multiple assignment you can use ;TI"=<code>*</code> to gather arguments in the decomposition:;T@
o;;[	I")a, (b, *c), *d = 1, [2, 3, 4], 5, 6
;TI"
;TI"p a: a, b: b, c: c, d: d
;TI"4# prints {:a=>1, :b=>2, :c=>[3, 4], :d=>[5, 6]};T;0:
@file@:0@omit_headings_from_table_of_contents_below0