<ppdoc>
<copyright>
    Copyright (c) 2001 by Addison Wesley Longman.  This
    material may be distributed only subject to the terms and
    conditions set forth in the Open Publication License, v1.0 or
    later (the latest version is presently available at
    http://www.opencontent.org/openpub/).
</copyright>
<class name="Struct" super="Object" type="class">  <subclasses>Struct::Tms</subclasses>
<p/>
A <classname>Struct</classname> is a convenient way to bundle a number of attributes
together, using accessor methods, without having to write an explicit
class.
<p/>
The <classname>Struct</classname> class is a generator of specific classes, each one of
which is defined to hold a set of variables and their accessors. In
these examples, we'll call the generated class ``<obj>Customer</obj>Class,'' and
we'll show an example instance of that class as ``<obj>Customer</obj>Inst.''
<p/>
In the descriptions that follow, the
  parameter <obj>aSymbol</obj> refers to a symbol, which is either a
  quoted string or a <classname>Symbol</classname> (such as <tt>:name</tt>).<mixins>
    <mixin name="Enumerable">
   collect, detect, each_with_index, entries, find, find_all, grep,
   include?, map, max, member?, min, reject, select, sort, to_a</mixin>
  </mixins>
<p/>
<methods type="class">
<p/>
      <method name="new" ref="new">
      <callseq>
        Struct.new( <opt><obj>aString</obj></opt> <optn>, <obj>aSym</obj></optn> )
      <returns><obj>Customer</obj>Class</returns>
      </callseq>
      <desc>
<p/>
    Creates a new class, named by <obj>aString</obj>, containing
    accessor methods for the given symbols.
    If the name <obj>aString</obj> is omitted, an anonymous structure
    class will be created. Otherwise, the name of this struct will
    appear as a constant in class <classname>Struct</classname>, so it must be unique
    for all <classname>Struct</classname>s in the system and should start with a
    capital letter.
<p/>
    <ccm><file>struct</file><front>Struct</front><back>new</back><mref>new</mref></ccm> returns a new <classname>Class</classname> object, which can then be used
    to create specific instances of the new structure.
    The remaining methods listed below (class and instance) are
    defined for this generated class. See the description that follows 
    for an example.
<p/>
      </desc>
    </method>
<p/>
      <method name="new" ref="new">
      <callseq>
        <obj>Customer</obj>Class.new( <optn><obj>anObject</obj></optn> )
      <returns><obj>Customer</obj>Inst</returns>
      </callseq>
      <desc>
<p/>
    Creates a new instance.  The number of actual parameters must be
    less than or equal to the number of attributes defined for this
    class; unset parameters default to <tt>nil</tt>.  Passing too many
    parameters will raise an <exception>ArgumentError</exception>.
<p/>
<codefragment>
<fullcode><![CDATA[      Customer = Struct.new( "Customer", :name, :address, :zip )
      joe = Customer.new( "Joe Smith", "123 Maple, Anytown NC", 12345 )
      joe.name
      joe.zip
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>Customer<nbsp/>=<nbsp/>Struct.new(<nbsp/>"Customer",<nbsp/>:name,<nbsp/>:address,<nbsp/>:zip<nbsp/>)</tt></td>
</tr>
<tr>
<td colspan="3"><tt>joe<nbsp/>=<nbsp/>Customer.new(<nbsp/>"Joe<nbsp/>Smith",<nbsp/>"123<nbsp/>Maple,<nbsp/>Anytown<nbsp/>NC",<nbsp/>12345<nbsp/>)</tt></td>
</tr>
<tr>
  <td><tt>joe.name</tt></td>
  <td>&#187;</td>
  <td><tt>"Joe<nbsp/>Smith"</tt></td>
</tr>
<tr>
  <td><tt>joe.zip</tt></td>
  <td>&#187;</td>
  <td><tt>12345</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
      <method name="members" ref="members">
      <callseq>
        <obj>Customer</obj>Class.members
      <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
    Returns an array of strings representing the names of the
    instance variables.
<p/>
<codefragment>
<fullcode><![CDATA[      Customer = Struct.new( "Customer", :name, :address, :zip )
      Customer.members
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>Customer<nbsp/>=<nbsp/>Struct.new(<nbsp/>"Customer",<nbsp/>:name,<nbsp/>:address,<nbsp/>:zip<nbsp/>)</tt></td>
</tr>
<tr>
  <td><tt>Customer.members</tt></td>
  <td>&#187;</td>
  <td><tt>["name",<nbsp/>"address",<nbsp/>"zip"]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
</methods>
<p/>
<methods type="instance">
<p/>
      <method name="==" ref="_eq_eq">
      <callseq>
        <obj>Customer</obj>Inst == <obj>anOtherStruct</obj>
      <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
    Equality---Returns <const>true</const> if <obj>anOtherStruct</obj> is equal to this
    one: they must be of the same class as generated by
    <ccm><file>struct</file><front>Struct</front><back>new</back><mref>new</mref></ccm>, and the values of
    all instance variables must be equal (according to
    <cim><file>object</file><front>Object</front><back>==</back><mref>_eq_eq</mref></cim>).
<p/>
<codefragment>
<fullcode><![CDATA[      Customer = Struct.new( "Customer", :name, :address, :zip )
      joe   = Customer.new( "Joe Smith", "123 Maple, Anytown NC", 12345 )
      joejr = Customer.new( "Joe Smith", "123 Maple, Anytown NC", 12345 )
      jane  = Customer.new( "Jane Doe", "456 Elm, Anytown NC", 12345 )
      joe == joejr
      joe == jane
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>Customer<nbsp/>=<nbsp/>Struct.new(<nbsp/>"Customer",<nbsp/>:name,<nbsp/>:address,<nbsp/>:zip<nbsp/>)</tt></td>
</tr>
<tr>
<td colspan="3"><tt>joe<nbsp/><nbsp/><nbsp/>=<nbsp/>Customer.new(<nbsp/>"Joe<nbsp/>Smith",<nbsp/>"123<nbsp/>Maple,<nbsp/>Anytown<nbsp/>NC",<nbsp/>12345<nbsp/>)</tt></td>
</tr>
<tr>
<td colspan="3"><tt>joejr<nbsp/>=<nbsp/>Customer.new(<nbsp/>"Joe<nbsp/>Smith",<nbsp/>"123<nbsp/>Maple,<nbsp/>Anytown<nbsp/>NC",<nbsp/>12345<nbsp/>)</tt></td>
</tr>
<tr>
<td colspan="3"><tt>jane<nbsp/><nbsp/>=<nbsp/>Customer.new(<nbsp/>"Jane<nbsp/>Doe",<nbsp/>"456<nbsp/>Elm,<nbsp/>Anytown<nbsp/>NC",<nbsp/>12345<nbsp/>)</tt></td>
</tr>
<tr>
  <td><tt>joe<nbsp/>==<nbsp/>joejr</tt></td>
  <td>&#187;</td>
  <td><tt>true</tt></td>
</tr>
<tr>
  <td><tt>joe<nbsp/>==<nbsp/>jane</tt></td>
  <td>&#187;</td>
  <td><tt>false</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
      <method name="[ ]" ref="_ob_cb">
      <callseq>
                <obj>Customer</obj>Inst[ <obj>aSymbol</obj> ] <returns><obj>anObject</obj></returns><br/><obj>Customer</obj>Inst[ <obj>anInteger</obj> ] <returns><obj>anObject</obj></returns>
<p/>
      </callseq>
      <desc>
<p/>
    Attribute Reference---Returns the value of the instance variable
    named by <obj>aSymbol</obj>, or indexed (0..length-1) by
    <obj>anInteger</obj>.  Will raise <exception>NameError</exception> if the named
    variable does not exist, or <exception>IndexError</exception> if the index is out of range.
<p/>
<codefragment>
<fullcode><![CDATA[      Customer = Struct.new( "Customer", :name, :address, :zip )
      joe = Customer.new( "Joe Smith", "123 Maple, Anytown NC", 12345 )
      
      joe["name"]
      joe[:name]
      joe[0]
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>Customer<nbsp/>=<nbsp/>Struct.new(<nbsp/>"Customer",<nbsp/>:name,<nbsp/>:address,<nbsp/>:zip<nbsp/>)</tt></td>
</tr>
<tr>
<td colspan="3"><tt>joe<nbsp/>=<nbsp/>Customer.new(<nbsp/>"Joe<nbsp/>Smith",<nbsp/>"123<nbsp/>Maple,<nbsp/>Anytown<nbsp/>NC",<nbsp/>12345<nbsp/>)</tt></td>
</tr>
<tr>
<td colspan="3"><tt></tt></td>
</tr>
<tr>
  <td><tt>joe["name"]</tt></td>
  <td>&#187;</td>
  <td><tt>"Joe<nbsp/>Smith"</tt></td>
</tr>
<tr>
  <td><tt>joe[:name]</tt></td>
  <td>&#187;</td>
  <td><tt>"Joe<nbsp/>Smith"</tt></td>
</tr>
<tr>
  <td><tt>joe[0]</tt></td>
  <td>&#187;</td>
  <td><tt>"Joe<nbsp/>Smith"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
      <method name="[ ]=" ref="_ob_cb_eq">
      <callseq>
                <obj>Customer</obj>Inst[ <obj>aSymbol</obj> ] = <obj>anObject</obj> <returns><obj>anObject</obj></returns><br/><obj>Customer</obj>Inst[ <obj>anInteger</obj> ] = <obj>anObject</obj> <returns><obj>anObject</obj></returns>
<p/>
      </callseq>
      <desc>
<p/>
    Attribute Assignment---Assigns to the instance variable named by
    <obj>aSymbol</obj> or <obj>anInteger</obj>
    the value <obj>anObject</obj> and returns it.  Will raise
    a <exception>NameError</exception> if the named variable does not exist, or an
    <exception>IndexError</exception> if the index is out of range.
<p/>
<codefragment>
<fullcode><![CDATA[      Customer = Struct.new( "Customer", :name, :address, :zip )
      joe = Customer.new( "Joe Smith", "123 Maple, Anytown NC", 12345 )

      joe["name"] = "Luke"
      joe[:zip]   = "90210"

      joe.name
      joe.zip
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>Customer<nbsp/>=<nbsp/>Struct.new(<nbsp/>"Customer",<nbsp/>:name,<nbsp/>:address,<nbsp/>:zip<nbsp/>)</tt></td>
</tr>
<tr>
<td colspan="3"><tt>joe<nbsp/>=<nbsp/>Customer.new(<nbsp/>"Joe<nbsp/>Smith",<nbsp/>"123<nbsp/>Maple,<nbsp/>Anytown<nbsp/>NC",<nbsp/>12345<nbsp/>)</tt></td>
</tr>
<tr>
<td colspan="3"><tt></tt></td>
</tr>
<tr>
<td colspan="3"><tt>joe["name"]<nbsp/>=<nbsp/>"Luke"</tt></td>
</tr>
<tr>
<td colspan="3"><tt>joe[:zip]<nbsp/><nbsp/><nbsp/>=<nbsp/>"90210"</tt></td>
</tr>
<tr>
<td colspan="3"><tt></tt></td>
</tr>
<tr>
  <td><tt>joe.name</tt></td>
  <td>&#187;</td>
  <td><tt>"Luke"</tt></td>
</tr>
<tr>
  <td><tt>joe.zip</tt></td>
  <td>&#187;</td>
  <td><tt>"90210"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
      <method name="each" ref="each">
      <callseq>
        <obj>Customer</obj>Inst.each <block>{| anObject | <blockbody>block</blockbody> }</block>
<p/>
      <returns><obj>Customer</obj>Inst</returns>
      </callseq>
      <desc>
<p/>
    Calls <obj>block</obj> once for each instance variable, passing the 
    value as a parameter.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[      Customer = Struct.new( "Customer", :name, :address, :zip )
      joe = Customer.new( "Joe Smith", "123 Maple, Anytown NC", 12345 )
      joe.each {|x| puts(x) }
]]></fullcode>
Customer<nbsp/>=<nbsp/>Struct.new(<nbsp/>"Customer",<nbsp/>:name,<nbsp/>:address,<nbsp/>:zip<nbsp/>)
joe<nbsp/>=<nbsp/>Customer.new(<nbsp/>"Joe<nbsp/>Smith",<nbsp/>"123<nbsp/>Maple,<nbsp/>Anytown<nbsp/>NC",<nbsp/>12345<nbsp/>)
joe.each<nbsp/>{|x|<nbsp/>puts(x)<nbsp/>}
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
Joe<nbsp/>Smith
123<nbsp/>Maple,<nbsp/>Anytown<nbsp/>NC
12345
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
      <method name="length" ref="length">
      <callseq>
        <obj>Customer</obj>Inst.length
      <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
    Returns the number of instance variables.
<p/>
<codefragment>
<fullcode><![CDATA[      Customer = Struct.new( "Customer", :name, :address, :zip )
      joe = Customer.new( "Joe Smith", "123 Maple, Anytown NC", 12345 )
      joe.length
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>Customer<nbsp/>=<nbsp/>Struct.new(<nbsp/>"Customer",<nbsp/>:name,<nbsp/>:address,<nbsp/>:zip<nbsp/>)</tt></td>
</tr>
<tr>
<td colspan="3"><tt>joe<nbsp/>=<nbsp/>Customer.new(<nbsp/>"Joe<nbsp/>Smith",<nbsp/>"123<nbsp/>Maple,<nbsp/>Anytown<nbsp/>NC",<nbsp/>12345<nbsp/>)</tt></td>
</tr>
<tr>
  <td><tt>joe.length</tt></td>
  <td>&#187;</td>
  <td><tt>3</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
      <method name="members" ref="members">
      <callseq>
        <obj>Customer</obj>Inst.members
      <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
    Returns an array of strings representing the names of the
    instance variables.
<p/>
<codefragment>
<fullcode><![CDATA[      Customer = Struct.new( "Customer", :name, :address, :zip )
      joe = Customer.new( "Joe Smith", "123 Maple, Anytown NC", 12345 )
      joe.members
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>Customer<nbsp/>=<nbsp/>Struct.new(<nbsp/>"Customer",<nbsp/>:name,<nbsp/>:address,<nbsp/>:zip<nbsp/>)</tt></td>
</tr>
<tr>
<td colspan="3"><tt>joe<nbsp/>=<nbsp/>Customer.new(<nbsp/>"Joe<nbsp/>Smith",<nbsp/>"123<nbsp/>Maple,<nbsp/>Anytown<nbsp/>NC",<nbsp/>12345<nbsp/>)</tt></td>
</tr>
<tr>
  <td><tt>joe.members</tt></td>
  <td>&#187;</td>
  <td><tt>["name",<nbsp/>"address",<nbsp/>"zip"]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
      <method name="size" ref="size">
      <callseq>
        <obj>Customer</obj>Inst.size
      <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
    Synonym for <cim><file>struct</file><front>Struct</front><back>length</back><mref>length</mref></cim>.
<p/>
      </desc>
    </method>
<p/>
      <method name="to_a" ref="to_a">
      <callseq>
        <obj>Customer</obj>Inst.to_a
      <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
    Returns the values for this instance as an array.
<p/>
<codefragment>
<fullcode><![CDATA[      Customer = Struct.new( "Customer", :name, :address, :zip )
      joe = Customer.new( "Joe Smith", "123 Maple, Anytown NC", 12345 )
      joe.to_a[1]
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>Customer<nbsp/>=<nbsp/>Struct.new(<nbsp/>"Customer",<nbsp/>:name,<nbsp/>:address,<nbsp/>:zip<nbsp/>)</tt></td>
</tr>
<tr>
<td colspan="3"><tt>joe<nbsp/>=<nbsp/>Customer.new(<nbsp/>"Joe<nbsp/>Smith",<nbsp/>"123<nbsp/>Maple,<nbsp/>Anytown<nbsp/>NC",<nbsp/>12345<nbsp/>)</tt></td>
</tr>
<tr>
  <td><tt>joe.to_a[1]</tt></td>
  <td>&#187;</td>
  <td><tt>"123<nbsp/>Maple,<nbsp/>Anytown<nbsp/>NC"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
      <method name="values" ref="values">
      <callseq>
        <obj>Customer</obj>Inst.values
      <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
    Synonym for <meth>to_a</meth>.
<p/>
      </desc>
    </method>
<p/>
</methods>
<p/>
</class>
</ppdoc>