Module: Musa::Datasets::PackedV

Includes:
AbsI
Defined in:
lib/musa-dsl/datasets/packed-v.rb

Overview

Hash-based dataset with array conversion.

PackedV (Packed Value) represents datasets stored as hashes (named key-value pairs). Extends AbsI for absolute indexed events.

Purpose

PackedV provides named key-value storage for musical data and conversion to indexed arrays (V). This is useful for:

  • Semantic naming of values (pitch, duration, velocity)
  • Sparse data (only store non-default values)
  • Converting between hash and array representations
  • Serialization to readable formats

Conversion to V

The #to_V method converts hashes to arrays using a mapper that defines the correspondence between hash keys and array positions.

Array Mapper

Array mapper defines the order of keys in resulting array. Position i contains value for key mapper[i].

pv = { pitch: 60, duration: 1.0 }.extend(Musa::Datasets::PackedV)
v = pv.to_V([:pitch, :duration, :velocity])
# => [60, 1.0, nil]
# velocity missing, becomes nil
  • Missing keys become nil in array

Hash Mapper

Hash mapper defines both key order (keys) and default values (values). Position i contains value for key mapper.keys[i], using mapper.values[i] as default if key is missing or value is nil.

pv = { pitch: 60 }.extend(Musa::Datasets::PackedV)
v = pv.to_V({ pitch: 60, duration: 1.0, velocity: 64 })
# => [60, 1.0, 64]
# duration and velocity use defaults

Defaults fill in missing or nil values.

Examples:

Basic hash to array conversion

pv = { pitch: 60, duration: 1.0, velocity: 64 }.extend(Musa::Datasets::PackedV)
v = pv.to_V([:pitch, :duration, :velocity])
# => [60, 1.0, 64]

Missing keys become nil (array mapper)

pv = { a: 1, c: 3 }.extend(Musa::Datasets::PackedV)
v = pv.to_V([:c, :b, :a])
# => [3, nil, 1]
# b missing, becomes nil

Hash mapper with defaults

pv = { a: 1, b: nil, c: 3 }.extend(Musa::Datasets::PackedV)
v = pv.to_V({ c: 100, b: 200, a: 300, d: 400 })
# => [3, 200, 1, 400]
# b nil → uses default 200
# d missing → uses default 400

Partial mapper (fewer keys in mapper)

pv = { a: 1, b: 2, c: 3 }.extend(Musa::Datasets::PackedV)
v = pv.to_V([:c, :b])
# => [3, 2]
# Only c and b extracted

Key order matters

pv = { a: 1, b: 2, c: 3 }.extend(Musa::Datasets::PackedV)
v = pv.to_V([:c, :b, :a])
# => [3, 2, 1]

See Also:

Instance Method Summary collapse

Instance Method Details

#to_V(mapper) ⇒ V

Converts packed hash to array (V).

Examples:

Array mapper

pv.to_V([:pitch, :duration, :velocity])

Hash mapper with defaults

pv.to_V({ pitch: 60, duration: 1.0, velocity: 64 })

Parameters:

  • mapper (Array<Symbol>, Hash{Symbol => Object}) —

    key mapping

    • Array: maps keys to indices (order matters)
    • Hash: maps keys (keys) to indices with defaults (values)

Returns:

  • (V) —

    array dataset

Raises:

  • (ArgumentError) —

    if mapper is not Array or Hash



99
100
101
102
103
104
105
106
107
108
 
# File 'lib/musa-dsl/datasets/packed-v.rb', line 99

def to_V(mapper)
  case mapper
  when Hash
    mapper.collect { |key, default| self[key] || default }.extend(V)
  when Array
    mapper.collect { |key| self[key] }.extend(V)
  else
    raise ArgumentError, "Expected Hash or Array as mapper but got a #{mapper.class.name}"
  end
end

#valid? ⇒ Boolean Originally defined in module E

Checks if event is valid.

Base implementation always returns true. Subclasses should override to implement specific validation logic.

Examples:

event.valid?  # => true

Returns:

  • (Boolean) —

    true if valid

#validate! ⇒ void Originally defined in module E

This method returns an undefined value.

Validates event, raising if invalid.

Examples:

event.validate!  # Raises if invalid

Raises:

  • (RuntimeError) —

    if event is not valid