- Main Page
- Modules
- Namespaces
- Classes
- Files

# Global Row Functions

Functions for manipulating Lists as musical rows. More...

## Functions
template<class Type>
Type Reference | Rotate (Type Reference f, Integer n)
| Rotate the elements of a List.
template<class Type1, class Type2>
Type1 | Transpose (Type1 L, Type2 t, Type2 lim)
| Transpose the elements of a List.
PitchList | Transpose (PitchList L, Integer t)
| Transpose the elements of a PitchList.
template<class Type1, class Type2>
Type1 | Invert (Type1 L, Type2 lim)
| Invert a List.
PitchList | Invert (PitchList L, Integer lim=12)
| Invert a PitchList.
template<class Type>
Type Reference | Retrograde (Type Reference L)
| Retrograde a List.
template<class MatrixType, class ListType>
MatrixType | SetComplex (ListType prime)
| Create a set class (matrix) from a List.
template<class ElementType, class ListType>
ElementType | cycle (ListType L, Integer Reference pos, Integer inc)
| Traverse cyclicly through a List.
template<class ElementType, class ListType>
ElementType | palindrome (ListType L, Integer Reference pos, Integer Reference inc)
| Traverse a List palindromically.
template<class ElementType, class ListType>
ElementType | permute (ListType L, Integer Reference pos, Integer Reference count, Integer inc)
| Permute a List.
Integer | InterpTendency (Real f, IntegerList L1, Integer Reference pos1, IntegerList L2, Integer Reference pos2, Integer inc)
| Interpolation tendency.
Pitch | LinearInterpolate (Pitch x, Pitch xMin, Pitch xMax, Pitch yMin, Pitch yMax)
| Linear interpolation in Pitch space.
template<class ElementType, class ListType>
ListType | stretch (ListType L, ElementType xMin, ElementType xMax, ElementType yMin, ElementType yMax)
| Use linear interpolation to map an entire function to a different range.
template<class ListType>
ListType | RandomRow (Integer N)
| RandomRow.
template<class ElementType, class ListType>
Void | swap (ListType Reference L, Integer from, Integer to)
| Swap two elements in a List.
template<class ElementType, class ListType>
ListType | shuffle (ListType L)
| Perform swap() operation on every element of List, thereby shuffling it.
template<class ElementType, class ListType>
ElementType | randTendency (ListType L1, Integer Reference pos1, ListType L2, Integer Reference pos2, Integer inc)
| Use a row to specify an upper boundary and another row to specify a lower boundary, and then pick a pitch in this range.

## Detailed Description

Functions for manipulating Lists as musical rows.

## Function Documentation

template<class ElementType, class ListType>

ElementType cycle | ( | ListType | L,
|  | Integer Reference | pos,
|  | Integer | inc |
| ) |  |  |

Traverse cyclicly through a List.

cycle() returns to the head of the list when it walks off the end, and returns to the end of the list if it walks off the head.

Parameters:

  | L | List to be traversed
  | pos | Current position in the list. Updated on return to new position in the list.
  | inc | Number of list elements to skip.

Returns:
  The element of the list based on pos and inc

Definition at line 119 of file Row.h.

References Length(), PosMod(), and Return.

    00119                                                                                                                 {
    00120         Integer i = PosMod( pos, Length( L ) );
    00121         pos = PosMod( pos + inc, Length( L ) );
    00122         Return( L[ i ] );
    00123 }

Integer InterpTendency | ( | Real | f,
|  | IntegerList | L1,
|  | Integer Reference | pos1,
|  | IntegerList | L2,
|  | Integer Reference | pos2,
|  | Integer | inc |
| ) |  |  |

Interpolation tendency.

Parameters:

  | f | Factor ranging from 0.0 to 1.0
  | L1 | List 1
  | pos1 | Position parameter for List 1
  | L2 | List 2
  | pos2 | Position parameter for List 2
  | inc | Amount by which to adjust position

Returns:
  Interpolated tendency value

Definition at line 21 of file Row.cpp.

References Return, Round(), and unitInterp().

    00021                                                                                                                               {
    00022         Integer x = cycle<Integer,IntegerList>(L1, pos1, inc);
    00023         Integer y = cycle<Integer,IntegerList>(L2, pos2, inc);
    00024         Return( Integer( Round( unitInterp( f, x, y ) ) ) );
    00025 }

PitchList Invert | ( | PitchList | L,
|  | Integer | lim = `12` |
| ) |  |  | `[inline]`

Invert a PitchList.

Parameters:

  | L | PitchList to invert
  | lim | Modulo limit to apply

Returns:
  Inverted PitchList

Definition at line 74 of file Row.h.

References For, List< Type >::length(), and Return.

    00074                                                          {
    00075         For ( Integer i = 0; i < L.length(); i = i + 1 ) {
    00076                 L[i].invert();
    00077         }
    00078         Return( L );
    00079 }

template<class Type1, class Type2>

Type1 Invert | ( | Type1 | L,
|  | Type2 | lim |
| ) |  |  |

Invert a List.

Parameters:

  | L | List to invert
  | lim | Modulo limit to apply

Returns:
  Inverted list

Definition at line 65 of file Row.h.

References Return.

Referenced by SetComplex().

    00065                                                                       {
    00066         L.invert(lim);
    00067         Return( L );
    00068 }

Pitch LinearInterpolate | ( | Pitch | x,
|  | Pitch | xMin,
|  | Pitch | xMax,
|  | Pitch | yMin,
|  | Pitch | yMax |
| ) |  |  |

Linear interpolation in Pitch space.

Parameters:

  | x | Value ranging from xMin to xMax
  | xMin | Minimum range of x
  | xMax | Maximum range of x
  | yMin | Target minimum range
  | yMax | Target maximum range

Returns:
  The interpolated value

Definition at line 27 of file Row.cpp.

References Pitch::degree(), and Return.

    00027                                                                                    {
    00028         Real xr = x.degree();
    00029         Real xm = xMin.degree();
    00030         Real xM = xMax.degree();
    00031         Real ym = yMin.degree();
    00032         Real yM = yMax.degree();
    00033         Real a = ( xr - xm) / (xM - xm );
    00034         Real b = yM - ym;
    00035         Return( Integer(a * b + ym) );
    00036 }

template<class ElementType, class ListType>

ElementType palindrome | ( | ListType | L,
|  | Integer Reference | pos,
|  | Integer Reference | inc |
| ) |  |  |

Traverse a List palindromically.

palindrome() returns to the head of the list when it walks off the end, and returns to the end of the list if it walks off the head. palindrome() alternates traversal of prime and retrograde form

Parameters:

  | L | List to be traversed
  | pos | Current position in the list. Updated on return to new position in the list.
  | inc | Number of list elements to skip.

Returns:
  The element of the list based on pos and inc

Definition at line 133 of file Row.h.

References If, and Return.

    00133                                                                                                                                {
    00134         Integer curPos = pos;
    00135         ElementType x = cycle<ElementType,ListType>( L, pos, inc );
    00136         If ( curPos + inc != pos ) {
    00137                 inc = inc * (-1); // change direction
    00138                 pos = curPos;
    00139         }
    00140         Return( x );
    00141 }

template<class ElementType, class ListType>

ElementType permute | ( | ListType | L,
|  | Integer Reference | pos,
|  | Integer Reference | count,
|  | Integer | inc |
| ) |  |  |

Permute a List.

Iterate the supplied sequence in prime order until exhausted, then permute the entire row by inc steps and repeat from the beginning

Parameters:

  | L | List to be traversed
  | pos | Current position in the list. Updated on return to new position in the list.
  | count | Reference parameter that tracks the number of steps so far
  | inc | Number of list elements to skip when we permute

Returns:
  The element of the list based on pos

Definition at line 150 of file Row.h.

References If, Length(), and Return.

    00150                                                                                                                                            {
    00151         Integer curPos = pos;                   // save the current position
    00152         ElementType x = cycle<ElementType,ListType>( L, pos, 1 );       // update pos and get list value
    00153         count = count + 1;                              // increment counter
    00154         If ( count == Length( L ) ) {   // have we output L items from list?
    00155                 count = 0;                                      // reset count
    00156                 pos = curPos + inc;                     // permute position for next time
    00157         }
    00158         Return( x );
    00159 }

template<class ListType>

ListType RandomRow | ( | Integer | N | ) |

RandomRow.

Parameters:

  | N | Length of row

Returns:
  Randomly generated row of length N

Definition at line 198 of file Row.h.

References For, If, IRandom(), and Return.

    00198                                                          {
    00199         IntegerList L;                          // Keep track of the pitches chosen so far
    00200         ListType M;                             // Used to build up our random 12-tone row
    00201         Integer i;
    00202         // First, set all list elements to zero, which means "unused"
    00203         For ( i = 0; i < N; i = i + 1 ) {
    00204                  L[ i ] = 0;
    00205         }
    00206         // Now build up M, marking off elements in L when they are chosen
    00207         For ( i = 0; i < N; i = i ) {
    00208                 Integer x = IRandom( 0, N - 1 );
    00209                 If ( L[ x ] == 0 ) {    // Hasn’t been chosen yet?
    00210                          L[ x ] = 1;    // Mark it "used"
    00211                          M[ i ] = x;    // Save the result
    00212                         i = i + 1;      // Now increment the control variable
    00213                 }
    00214         }
    00215         Return( M );
    00216 }

template<class ElementType, class ListType>

ElementType randTendency | ( | ListType | L1,
|  | Integer Reference | pos1,
|  | ListType | L2,
|  | Integer Reference | pos2,
|  | Integer | inc |
| ) |  |  |

Use a row to specify an upper boundary and another row to specify a lower boundary, and then pick a pitch in this range.

Parameters:

  | L1 | List specifying upper boundary
  | pos1 | Current position in L1
  | L2 | List specifying upper boundary
  | pos2 | Current position in L2
  | inc | Amount to increment

Returns:
  Random value chosen to lie in the range between indexed elements of L1 and L2

Definition at line 250 of file Row.h.

References Else, If, IRandom(), and Return.

    00250                                                                                                                                                               {
    00251         Integer x = cycle<ElementType,ListType>( L1, pos1, inc );
    00252         Integer y = cycle<ElementType,ListType>( L2, pos2, inc );
    00253         If ( x < y )
    00254                 Return( IRandom( x, y ) );
    00255         Else
    00256                 Return( IRandom( y, x ) );
    00257 }

template<class Type>

Type Reference Retrograde | ( | Type Reference | L | ) |

Retrograde a List.

Parameters:

  | L | List to retrograde

Returns:
  Retrograde list

Definition at line 84 of file Row.h.

References Return.

    00084                                                                    {
    00085         L.retrograde();
    00086         Return( L );
    00087 }

template<class Type>

Type Reference Rotate | ( | Type Reference | f,
|  | Integer | n |
| ) |  |  |

Rotate the elements of a List.

Parameters:

  | f | Row to rotate
  | n | Number of positions to rotate by

Definition at line 31 of file Row.h.

References Return.

    00032 {
    00033         f.rotate(n);
    00034         Return( f );
    00035 }

template<class MatrixType, class ListType>

MatrixType SetComplex | ( | ListType | prime | ) |

Create a set class (matrix) from a List.

Parameters:

  | prime | Prime form of the list

Returns:
  The set class (matrix)

Definition at line 92 of file Row.h.

References For, Invert(), Length(), Mod(), and Return.

    00092                                                                                    {
    00093         Integer len = Length( prime );
    00094         MatrixType M( len, len );
    00095         ListType inverted = Invert( prime, 12 );
    00096         Integer i;
    00097
    00098         For ( i = 0; i < len; i = i + 1 ) {
    00099                  M[0][i] = prime[i];
    00100                  M[i][0] = inverted[i];
    00101         }
    00102
    00103         For ( i = 1; i < len; i = i + 1 ) {
    00104                 For ( Integer j = 1; j < len; j = j + 1 ) {
    00105                           M[ i ][ j ] = Mod( M[ i ][ 0 ] + M[ 0 ][ j ], len);
    00106                 }
    00107         }
    00108
    00109         Return( M );
    00110 }

template<class ElementType, class ListType>

ListType shuffle | ( | ListType | L | ) |

Perform swap() operation on every element of List, thereby shuffling it.

Parameters:

  | L | List to shuffle

Returns:
  Shuffled list

Definition at line 232 of file Row.h.

References For, Length(), Print(), and Return.

    00232                                                                            {
    00233         // SeedRandom( 788429 );        // Uncomment to test alternative shuffle
    00234         ListType M = RandomRow<ListType>( Length( L ) ); // Determine what elements to swap
    00235         Print( "M=", M );
    00236         For ( Integer i = 0; i < Length( L ); i = i + 1 ) {
    00237                 Integer j = M[ i ];
    00238                 swap<ElementType,ListType>( L, i, j );
    00239         }
    00240         Return( L );
    00241 }

template<class ElementType, class ListType>

ListType stretch | ( | ListType | L,
|  | ElementType | xMin,
|  | ElementType | xMax,
|  | ElementType | yMin,
|  | ElementType | yMax |
| ) |  |  |

Use linear interpolation to map an entire function to a different range.

Parameters:

  | L | List to stretch
  | xMin | Minimum value range of L
  | xMax | Maximum value range L
  | yMin | Minimum range of resulting stretched list
  | yMax | Maximum range of resulting stretched list

Returns:
  Stretched list

Definition at line 187 of file Row.h.

References For, Length(), linearInterpolate(), and Return.

    00187                                                                                                                                                    {
    00188         For ( Integer i = 0; i < Length( L ); i = i + 1 ) {
    00189                  L[ i ] = ElementType( linearInterpolate( L[ i ], xMin, xMax, yMin, yMax ) );
    00190         }
    00191         Return( L );
    00192 }

template<class ElementType, class ListType>

Void swap | ( | ListType Reference | L,
|  | Integer | from,
|  | Integer | to |
| ) |  |  |

Swap two elements in a List.

Parameters:

  | L | List with elements to swap
  | from | Index of source
  | to | Index of destination

Returns:
  Modified list

Definition at line 223 of file Row.h.

    00223                                                                                                         {
    00224         ElementType x = L[ to ];                // save the target value
    00225          L[ to ] = L[ from ];           // swap from -> to
    00226          L[ from ] = x;                 // swap to -> from
    00227 }

PitchList Transpose | ( | PitchList | L,
|  | Integer | t |
| ) |  |  | `[inline]`

Transpose the elements of a PitchList.

Transpose performs modulus arithmetic on pitches within the scale. That is, pitches transposed outside the span of the scale are wrapped back into the scale.

Parameters:

  | L | PitchList to transpose
  | t | Number of degrees to transpose by

Returns:
  Transposed list

Definition at line 54 of file Row.h.

References For, List< Type >::length(), and Return.

    00054                                                      {
    00055         For ( Integer i = 0; i < L.length(); i = i + 1 ) {
    00056                 L[i].transModuloOctave(t);
    00057         }
    00058         Return( L );
    00059 }

template<class Type1, class Type2>

Type1 Transpose | ( | Type1 | L,
|  | Type2 | t,
|  | Type2 | lim |
| ) |  |  |

Transpose the elements of a List.

Parameters:

  | L | List to transpose
  | t | Number of degrees to transpose by
  | lim | Number of scale degrees. E.g., for the equal tempered scale, lim=12 semitones.

Returns:
  Transposed list

Definition at line 42 of file Row.h.

References Return.

    00042                                                                                   {
    00043         L.transpose(t, lim);
    00044         Return( L );
    00045 }