Class: Array

Inherits:
Object show all
Defined in:
lib/musa-dsl/matrix/matrix.rb,
lib/musa-dsl/matrix/matrix.rb,
lib/musa-dsl/matrix/matrix.rb,
lib/musa-dsl/core-ext/arrayfy.rb,
lib/musa-dsl/core-ext/hashify.rb,
lib/musa-dsl/series/array-to-serie.rb,
lib/musa-dsl/neumas/array-to-neumas.rb,
lib/musa-dsl/neumas/array-to-neumas.rb,
lib/musa-dsl/neumas/array-to-neumas.rb,
lib/musa-dsl/core-ext/array-explode-ranges.rb

Instance Method Summary collapse

Instance Method Details

#arrayfy(size: nil, default: nil) ⇒ Array

Note:

This method is added to Array via refinement. Requires using Musa::Extension::Arrayfy.

Note:

The cycling formula: array * (size / array.size + (size % array.size).zero? ? 0 : 1) ensures enough repetitions to reach target size.

Clones or cycles the array to achieve the target size, with nil replacement.

The cycling behavior multiplies the array enough times to reach or exceed the target size, then takes exactly the requested number of elements. Singleton class modules (like P, V dataset extensions) are preserved.

Examples:

Cycling shorter array

using Musa::Extension::Arrayfy
[1, 2].arrayfy(size: 5)  # => [1, 2, 1, 2, 1]

Truncating longer array

using Musa::Extension::Arrayfy
[1, 2, 3, 4, 5].arrayfy(size: 3)  # => [1, 2, 3]

Preserving dataset modules

using Musa::Extension::Arrayfy
p_sequence = [60, 1, 62].extend(Musa::Datasets::P)
p_sequence.arrayfy(size: 6)  # Result also extended with P


128
 
# File 'lib/musa-dsl/core-ext/arrayfy.rb', line 128

class ::Array; end

#condensed_matrices ⇒ Array<::Matrix>

Note:

This method is added to Array via refinement. Requires using Musa::Extension::Matrix.

Condenses matrices that share common boundary rows.

This method merges matrices that have matching first or last rows, effectively connecting musical gestures that share endpoints. This is particularly useful for creating continuous trajectories from fragmented matrix segments.

The algorithm compares each matrix with all previously processed matrices, looking for matches at either the beginning or end of the row sequence. When a match is found, the matrices are merged.

Examples:

using Musa::Extension::Matrix
# Matrix A ends where Matrix B begins -> they merge
a = Matrix[[0, 60], [1, 62]]
b = Matrix[[1, 62], [2, 64]]
[a, b].condensed_matrices
# => [Matrix[[0, 60], [1, 62], [2, 64]]]


153
 
# File 'lib/musa-dsl/matrix/matrix.rb', line 153

class ::Array; end

#explode_ranges ⇒ Array

Note:

This method is added to Array via refinement. Requires using Musa::Extension::ExplodeRanges.

Expands all Range objects in the array into their individual elements.

Iterates through the array and converts any Range objects to their constituent elements via to_a, leaving non-Range elements unchanged. The result is a new flat array.

Examples:

Empty ranges

using Musa::Extension::ExplodeRanges
[1, (5..4), 8].explode_ranges  # (5..4) is empty
# => [1, 8]

Exclusive ranges

using Musa::Extension::ExplodeRanges
[1, (3...6), 9].explode_ranges
# => [1, 3, 4, 5, 9]

Nested arrays are NOT expanded recursively

using Musa::Extension::ExplodeRanges
[1, [2..4], 5].explode_ranges
# => [1, [2..4], 5]  # Inner range NOT expanded


70
 
# File 'lib/musa-dsl/core-ext/array-explode-ranges.rb', line 70

class ::Array; end

#hashify(keys: , default: nil) ⇒ Hash

Note:

This method is added to Array via refinement. Requires using Musa::Extension::Hashify.

Maps array elements to hash keys in order, consuming the array.

Elements are assigned to keys sequentially. If the array has fewer elements than keys, remaining keys get nil (or default). The array is cloned before consumption, so the original is unchanged.

Examples:

Basic array mapping

using Musa::Extension::Hashify
[60, 100, 0.25].hashify(keys: [:pitch, :velocity, :duration])
# => { pitch: 60, velocity: 100, duration: 0.25 }

Fewer elements than keys

using Musa::Extension::Hashify
[60, 100].hashify(keys: [:pitch, :velocity, :duration], default: nil)
# => { pitch: 60, velocity: 100, duration: nil }

More elements than keys (extras ignored)

using Musa::Extension::Hashify
[60, 100, 0.5, :ignored].hashify(keys: [:pitch, :velocity])
# => { pitch: 60, velocity: 100 }


137
 
# File 'lib/musa-dsl/core-ext/hashify.rb', line 137

class ::Array; end

#indexes_of_values ⇒ Hash{Object => Array<Integer>}

Note:

This method is added to Array via refinement. Requires using Musa::Extension::Matrix.

Creates a hash mapping values to their indices in the array.

This method scans the array and builds an inverted index where each unique value maps to an array of positions where it appears.

Examples:

using Musa::Extension::Matrix
[10, 20, 10, 30, 20].indexes_of_values
# => { 10 => [0, 2], 20 => [1, 4], 30 => [3] }


103
 
# File 'lib/musa-dsl/matrix/matrix.rb', line 103

class ::Array; end

#n ⇒ Object

Note:

This method is added to Array via refinement. Requires using Musa::Extension::Neumas.

Short alias for to_neumas.

See Also:



144
 
# File 'lib/musa-dsl/neumas/array-to-neumas.rb', line 144

class ::Array; end

#neumas ⇒ Object

Note:

This method is added to Array via refinement. Requires using Musa::Extension::Neumas.

Alias for to_neumas.

See Also:



134
 
# File 'lib/musa-dsl/neumas/array-to-neumas.rb', line 134

class ::Array; end

#to_neumas ⇒ Serie, Neuma

Note:

This method is added to Array via refinement. Requires using Musa::Extension::Neumas.

Converts array elements to merged neuma series.

  • Single element: Returns converted element directly
  • Multiple elements: Returns MERGE of all converted elements

Each element is converted based on its type:

  • String → parsed as neuma notation
  • Neuma::Serie → used directly
  • Neuma::Parallel → wrapped in series

Examples:

Convert string array

using Musa::Extension::Neumas

phrases = [
  "0 +2 +4",
  "+5 +7"
].to_neumas
# Returns MERGE of two parsed series

Mixed types

using Musa::Extension::Neumas

existing = "0 +2".to_neumas
combined = [existing, "+4 +5"].to_neumas

Single element

using Musa::Extension::Neumas

single = ["0 +2 +4"].to_neumas
# Returns parsed series directly (not merged)

Raises:

  • (ArgumentError) —

    if element type cannot be converted



124
 
# File 'lib/musa-dsl/neumas/array-to-neumas.rb', line 124

class ::Array; end

#to_p(time_dimension: , keep_time: nil) ⇒ Array<Musa::Datasets::P>

Note:

This method is added to Array via refinement. Requires using Musa::Extension::Matrix.

Converts an array of matrices to an array of P sequences.

This method processes each matrix in the array, first condensing matrices that share common endpoints, then converting each resulting matrix to P (point sequence) format.

Examples:

Converting array of matrices

using Musa::Extension::Matrix
matrices = [Matrix[[0, 60], [1, 62]], Matrix[[2, 64], [3, 65]]]
result = matrices.to_p(time_dimension: 0)
# Returns array of P sequences, one per matrix (or merged if they connect)

See Also:



128
 
# File 'lib/musa-dsl/matrix/matrix.rb', line 128

class ::Array; end

#to_serie(of_series: nil, recursive: nil) ⇒ Serie Also known as: s

Converts array to Serie.

Three conversion modes:

  • Basic: Direct conversion to serie
  • of_series: Each element of the array becomes a new serie (for array of arrays)
  • recursive: Recursive conversion of nested arrays

Examples:

Basic conversion

[60, 64, 67].to_serie.i.to_a  # => [60, 64, 67]

Serie of series

[[1, 2], [3, 4]].to_serie(of_series: true)
# Each [1,2], [3,4] becomes S(1,2), S(3,4)

Recursive conversion

[[1, [2, 3]], [4, 5]].to_serie(recursive: true)
# Nested arrays become nested series

Raises:

  • (ArgumentError) —

    if both of_series and recursive are true



34
35
36
37
38
39
40
41
42
43
44
45
46
47
 
# File 'lib/musa-dsl/series/array-to-serie.rb', line 34

def to_serie(of_series: nil, recursive: nil)
  of_series ||= false
  recursive ||= false

  raise ArgumentError, 'Cannot convert to serie of_series and recursive simultaneously' if recursive && of_series

  if recursive
    Musa::Series::Constructors.S(*(collect { |_| _.is_a?(Array) ? _.to_serie(recursive: true) : _ }))
  elsif of_series
    Musa::Series::Constructors.S(*(collect { |_| Musa::Series::Constructors.S(*_) }))
  else
    Musa::Series::Constructors.S(*self)
  end
end