Programming Ruby: The Pragmatic Programmer's Guide

# Programming Ruby ### The Pragmatic Programmer's Guide
Previous < | Contents ^ | Next >

class Struct |
Parent: | Object
Version: | 1.6

### Index:

new new members == [ ] [ ]= each length members size to_a values

Subclasses: Struct::Tms

A `Struct` is a convenient way to bundle a number of attributes together, using accessor methods, without having to write an explicit class.

The `Struct` 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 ``CustomerClass,'' and we'll show an example instance of that class as ``CustomerInst.''

In the descriptions that follow, the parameter aSymbol refers to a symbol, which is either a quoted string or a `Symbol` (such as `:name`).

mixins
Enumerable: | collect, detect, each_with_index, entries, find, find_all, grep, include?, map, max, member?, min, reject, select, sort, to_a

class methods
new | Struct.new( [ aString ] [, aSym ]+ ) -> CustomerClass
|  | Creates a new class, named by aString, containing accessor methods for the given symbols. If the name aString is omitted, an anonymous structure class will be created. Otherwise, the name of this struct will appear as a constant in class `Struct`, so it must be unique for all `Struct`s in the system and should start with a capital letter. `Struct.new` returns a new `Class` 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.
new | CustomerClass.new( [ anObject ]+ ) -> CustomerInst
|  | 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 `nil`. Passing too many parameters will raise an `ArgumentError`.
`Customer = Struct.new( "Customer", :name, :address, :zip )`
`joe = Customer.new( "Joe Smith", "123 Maple, Anytown NC", 12345 )`
`joe.name` | » | `"Joe Smith"`
`joe.zip` | » | `12345`
members | CustomerClass.members -> anArray
|  | Returns an array of strings representing the names of the instance variables.
`Customer = Struct.new( "Customer", :name, :address, :zip )`
`Customer.members` | » | `["name", "address", "zip"]`

instance methods
== | CustomerInst == anOtherStruct -> `true` or `false`
|  | Equality---Returns `true` if anOtherStruct is equal to this one: they must be of the same class as generated by `Struct.new` , and the values of all instance variables must be equal (according to `Object#==` ).
`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` | » | `true`
`joe == jane` | » | `false`
[ ] | CustomerInst[ aSymbol ] -> anObject CustomerInst[ anInteger ] -> anObject
|  | Attribute Reference---Returns the value of the instance variable named by aSymbol, or indexed (0..length-1) by anInteger. Will raise `NameError` if the named variable does not exist, or `IndexError` if the index is out of range.
`Customer = Struct.new( "Customer", :name, :address, :zip )`
`joe = Customer.new( "Joe Smith", "123 Maple, Anytown NC", 12345 )`
``
`joe["name"]` | » | `"Joe Smith"`
`joe[:name]` | » | `"Joe Smith"`
`joe[0]` | » | `"Joe Smith"`
[ ]= | CustomerInst[ aSymbol ] = anObject -> anObject CustomerInst[ anInteger ] = anObject -> anObject
|  | Attribute Assignment---Assigns to the instance variable named by aSymbol or anInteger the value anObject and returns it. Will raise a `NameError` if the named variable does not exist, or an `IndexError` if the index is out of range.
`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` | » | `"Luke"`
`joe.zip` | » | `"90210"`
each | CustomerInst.each {| anObject | block } -> CustomerInst
|  | Calls block once for each instance variable, passing the value as a parameter.
    Customer = Struct.new( "Customer", :name, :address, :zip )
    joe = Customer.new( "Joe Smith", "123 Maple, Anytown NC", 12345 )
    joe.each {|x| puts(x) }
produces:
    Joe Smith
    123 Maple, Anytown NC
    12345
length | CustomerInst.length -> anInteger
|  | Returns the number of instance variables.
`Customer = Struct.new( "Customer", :name, :address, :zip )`
`joe = Customer.new( "Joe Smith", "123 Maple, Anytown NC", 12345 )`
`joe.length` | » | `3`
members | CustomerInst.members -> anArray
|  | Returns an array of strings representing the names of the instance variables.
`Customer = Struct.new( "Customer", :name, :address, :zip )`
`joe = Customer.new( "Joe Smith", "123 Maple, Anytown NC", 12345 )`
`joe.members` | » | `["name", "address", "zip"]`
size | CustomerInst.size -> anInteger
|  | Synonym for `Struct#length` .
to_a | CustomerInst.to_a -> anArray
|  | Returns the values for this instance as an array.
`Customer = Struct.new( "Customer", :name, :address, :zip )`
`joe = Customer.new( "Joe Smith", "123 Maple, Anytown NC", 12345 )`
`joe.to_a[1]` | » | `"123 Maple, Anytown NC"`
values | CustomerInst.values -> anArray
|  | Synonym for `to_a`.

Previous < | Contents ^ | Next >

Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide"
Copyright © 2000 Addison Wesley Longman, Inc. Released under the terms of the Open Publication License V1.0.
This reference is available for download.