Class: Stannum::Constraints::Types::ArrayType

Inherits:
Stannum::Constraints::Type show all
Defined in:
lib/stannum/constraints/types/array_type.rb

Overview

An Array type constraint asserts that the object is an Array.

Examples:

Using an Array type constraint

constraint = Stannum::Constraints::Types::ArrayType.new

constraint.matches?(nil)        # => false
constraint.matches?(Object.new) # => false
constraint.matches?([])         # => true
constraint.matches?([1, 2, 3])  # => true

Using an Array type constraint with an item constraint

constraint = Stannum::Constraints::Types::ArrayType.new(item_type: String)

constraint.matches?(nil)               # => false
constraint.matches?(Object.new)        # => false
constraint.matches?([])                # => true
constraint.matches?([1, 2, 3])         # => false
constraint.matches?(%w[one two three]) # => true

Using an Array type constraint with a presence constraint

constraint = Stannum::Constraints::Types::ArrayType.new(allow_empty: false)

constraint.matches?(nil)               # => false
constraint.matches?(Object.new)        # => false
constraint.matches?([])                # => false
constraint.matches?([1, 2, 3])         # => true
constraint.matches?(%w[one two three]) # => true

Constant Summary

Constants inherited from Stannum::Constraints::Type

Stannum::Constraints::Type::NEGATED_TYPE, Stannum::Constraints::Type::TYPE

Constants inherited from Base

Base::NEGATED_TYPE, Base::TYPE

Instance Attribute Summary

Attributes inherited from Base

#options

Instance Method Summary collapse

Methods inherited from Stannum::Constraints::Type

#expected_type, #negated_errors_for, #with_options

Methods included from Support::Optional

#optional?, #required?, resolve

Methods inherited from Base

#==, #clone, #dup, #match, #message, #negated_errors_for, #negated_match, #negated_message, #negated_type, #type, #with_options

Constructor Details

#initialize(allow_empty: true, item_type: nil, **options) ⇒ ArrayType

Returns a new instance of ArrayType.

Parameters:

  • allow_empty (true, false) (defaults to: true) —

    If false, then the constraint will not match against an Array with no items.

  • item_type (Stannum::Constraints::Base, Class, nil) (defaults to: nil) —

    If set, then the constraint will check the types of each item in the Array against the expected type and will fail if any items do not match.

  • options (Hash<Symbol, Object>) —

    Configuration options for the constraint. Defaults to an empty Hash.



42
43
44
45
46
47
48
49
 
# File 'lib/stannum/constraints/types/array_type.rb', line 42

def initialize(allow_empty: true, item_type: nil, **options)
  super(
    ::Array,
    allow_empty: !!allow_empty,
    item_type:   coerce_item_type(item_type),
    **options
  )
end

Instance Method Details

#allow_empty? ⇒ true, false

Returns if false, then the constraint will not match against an Array with no items.

Returns:

  • (true, false) —

    if false, then the constraint will not match against an Array with no items.



53
54
55
 
# File 'lib/stannum/constraints/types/array_type.rb', line 53

def allow_empty?
  options[:allow_empty]
end

#does_not_match?(actual) ⇒ true, false

Checks that the object is not an Array instance.

Returns:

  • (true, false) —

    true if the object is not an Array instance, otherwise false.

See Also:



63
64
65
 
# File 'lib/stannum/constraints/types/array_type.rb', line 63

def does_not_match?(actual)
  !matches_type?(actual)
end

#errors_for(actual, errors: nil) ⇒ Stannum::Errors

Note:

This method should only be called for an object that does not match the constraint. Generating errors for a matching object can result in undefined behavior.

Generates an errors object for the given object.

The errors object represents the difference between the given object and the expected properties or behavior. It may be the same for all objects, or different based on the details of the object or the constraint.

Examples:

Generating errors for a non-matching object.

constraint = CustomConstraint.new
object     = NonMatchingObject.new
errors     = constraint.errors_for(object)

errors.class #=> Stannum::Errors
errors.to_a  #=> [{ type: 'some_error', message: 'some error message' }]

Parameters:

  • actual (Object) —

    The object to generate errors for.

  • errors (Stannum::Errors) (defaults to: nil) —

    The errors object to append errors to. If an errors object is not given, a new errors object will be created.

Returns:

See Also:



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/stannum/constraints/types/array_type.rb', line 68

def errors_for(actual, errors: nil)
  return super unless actual.is_a?(expected_type)

  errors ||= Stannum::Errors.new

  return add_presence_error(errors) unless presence_matches?(actual)

  unless item_type_matches?(actual)
    non_matching_items(actual).each do |item, index|
      item_type.errors_for(item, errors: errors[index])
    end
  end

  errors
end

#item_type ⇒ Stannum::Constraints::Base?

Returns the expected type for the items in the array.

Returns:



86
87
88
 
# File 'lib/stannum/constraints/types/array_type.rb', line 86

def item_type
  options[:item_type]
end

#matches?(actual) ⇒ true, false Also known as: match?

Checks that the object is an Array instance and that the items match.

If the constraint was configured with an item_type, each item in the Array will be compared to the expected type. If any items do not match the expectation, then #matches? will return false.

Returns:

  • (true, false) —

    true if the object is an Array instance with matching items, otherwise false.

See Also:



100
101
102
103
104
105
106
107
108
 
# File 'lib/stannum/constraints/types/array_type.rb', line 100

def matches?(actual)
  return false unless super

  return false unless presence_matches?(actual)

  return false unless item_type_matches?(actual)

  true
end