Module: Concurrent::ImmutableStruct

Defined in:
lib/concurrent/immutable_struct.rb

Overview

A thread-safe, immutable variation of Ruby’s standard ‘Struct`.

See Also:

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object 



12
13
14
 
# File 'lib/concurrent/immutable_struct.rb', line 12

def self.included(base)
  base.safe_initialization!
end

.new(*args, &block) ⇒ Object

Factory for creating new struct classes.

“‘ new( [, member_name]+>) -> StructClass click to toggle source new( [, member_name]+>) {|StructClass| block } -> StructClass new(value, …) -> obj StructClass[value, …] -> obj “`

The first two forms are used to create a new struct subclass ‘class_name` that can contain a value for each member_name . This subclass can be used to create instances of the structure like any other Class .

If the ‘class_name` is omitted an anonymous struct class will be created. Otherwise, the name of this struct will appear as a constant in the struct class, so it must be unique for all structs under this base class and must start with a capital letter. Assigning a struct class to a constant also gives the class the name of the constant.

If a block is given it will be evaluated in the context of ‘StructClass`, passing the created class as a parameter. This is the recommended way to customize a struct. Subclassing an anonymous struct creates an extra anonymous class that will never be used.

The last two forms create a new instance of a struct subclass. The number of value parameters must be less than or equal to the number of attributes defined for the struct. Unset parameters default to nil. Passing more parameters than number of attributes will raise an ‘ArgumentError`.

See Also:



74
75
76
77
78
79
80
81
82
 
# File 'lib/concurrent/immutable_struct.rb', line 74

def self.new(*args, &block)
  clazz_name = nil
  if args.length == 0
    raise ArgumentError.new('wrong number of arguments (0 for 1+)')
  elsif args.length > 0 && args.first.is_a?(String)
    clazz_name = args.shift
  end
  FACTORY.define_struct(clazz_name, args, &block)
end

Instance Method Details

#==(other) ⇒ Boolean

Equality

Returns:

  • (Boolean) —

    true if other has the same struct subclass and has equal member values (according to ‘Object#==`)



51
52
53
 
# File 'lib/concurrent/immutable_struct.rb', line 51

def ==(other)
  ns_equality(other)
end

#[](member) ⇒ Object

Attribute Reference

Parameters:

  • member (Symbol, String, Integer) —

    the string or symbol name of the memeber for which to obtain the value or the member’s index

Returns:

  • (Object) —

    the value of the given struct member or the member at the given index.

Raises:

  • (NameError) —

    if the member does not exist

  • (IndexError) —

    if the index is out of range.



46
47
48
 
# File 'lib/concurrent/immutable_struct.rb', line 46

def [](member)
  ns_get(member)
end

#each {|value| ... } ⇒ Object

Yields the value of each struct member in order. If no block is given an enumerator is returned.

Yields:

  • the operation to be performed on each struct member

Yield Parameters:

  • value (Object) —

    each struct value (in order)



56
57
58
59
 
# File 'lib/concurrent/immutable_struct.rb', line 56

def each(&block)
  return enum_for(:each) unless block_given?
  ns_each(&block)
end

#each_pair {|member, value| ... } ⇒ Object

Yields the name and value of each struct member in order. If no block is given an enumerator is returned.

Yields:

  • the operation to be performed on each struct member/value pair

Yield Parameters:

  • member (Object) —

    each struct member (in order)

  • value (Object) —

    each struct value (in order)



62
63
64
65
 
# File 'lib/concurrent/immutable_struct.rb', line 62

def each_pair(&block)
  return enum_for(:each_pair) unless block_given?
  ns_each_pair(&block)
end

#inspect ⇒ String Also known as: to_s

Describe the contents of this struct in a string.

Returns:

  • (String) —

    the contents of this struct in a string



29
30
31
 
# File 'lib/concurrent/immutable_struct.rb', line 29

def inspect
  ns_inspect
end

#merge(other) {|member, selfvalue, othervalue| ... } ⇒ Synchronization::AbstractStruct

Returns a new struct containing the contents of ‘other` and the contents of `self`. If no block is specified, the value for entries with duplicate keys will be that of `other`. Otherwise the value for each duplicate key is determined by calling the block with the key, its value in `self` and its value in `other`.

Parameters:

  • other (Hash) —

    the hash from which to set the new values

Yields:

  • an options block for resolving duplicate keys

Yield Parameters:

  • member (String, Symbol) —

    the name of the member which is duplicated

  • selfvalue (Object) —

    the value of the member in ‘self`

  • othervalue (Object) —

    the value of the member in ‘other`

Returns:

  • (Synchronization::AbstractStruct) —

    a new struct with the new values

Raises:

  • (ArgumentError) —

    of given a member that is not defined in the struct



36
37
38
 
# File 'lib/concurrent/immutable_struct.rb', line 36

def merge(other, &block)
  ns_merge(other, &block)
end

#select {|value| ... } ⇒ Array

Yields each member value from the struct to the block and returns an Array containing the member values from the struct for which the given block returns a true value (equivalent to ‘Enumerable#select`).

Yields:

  • the operation to be performed on each struct member

Yield Parameters:

  • value (Object) —

    each struct value (in order)

Returns:

  • (Array) —

    an array containing each value for which the block returns true



68
69
70
71
 
# File 'lib/concurrent/immutable_struct.rb', line 68

def select(&block)
  return enum_for(:select) unless block_given?
  ns_select(&block)
end

#to_h ⇒ Hash

Returns a hash containing the names and values for the struct’s members.

Returns:

  • (Hash) —

    the names and values for the struct’s members



41
42
43
 
# File 'lib/concurrent/immutable_struct.rb', line 41

def to_h
  ns_to_h
end

#values ⇒ Array Also known as: to_a

Returns the values for this struct as an Array.

Returns:

  • (Array) —

    the values for this struct



17
18
19
 
# File 'lib/concurrent/immutable_struct.rb', line 17

def values
  ns_values
end

#values_at(*indexes) ⇒ Object

Returns the struct member values for each selector as an Array.

A selector may be either an Integer offset or a Range of offsets (as in ‘Array#values_at`).

Parameters:

  • indexes (Fixnum, Range) —

    the index(es) from which to obatin the values (in order)



24
25
26
 
# File 'lib/concurrent/immutable_struct.rb', line 24

def values_at(*indexes)
  ns_values_at(indexes)
end