ProTrackR (version 0.4.4)

patternOrder: Get the pattern order table

Description

The pattern order table is a vector of numeric indices of PTPattern tables, which determines in which order the patterns need to be played. This method returns this vector.

Usage

# S4 method for PTModule
patternOrder(x, full = FALSE)
# S4 method for PTModule,ANY,numeric
patternOrder(x, full = FALSE) <- value

Value

For patternOrder, a vector of numeric

PTPattern indices is returned.

For patternOrder<-, an updated version of object x is returned, in which the pattern order table is modified based on value.

Arguments

x

A PTModule object for which the pattern order table needs to be returned or modified.

full

A logical value indicating whether the full (TRUE, default), or only the visible (FALSE) part of the pattern order table should be returned. This argument will also affect how new pattern order tables are assigned (see value).

value

A numeric vector (maximum length: 128) holding PTPattern indices minus 1 for the new pattern order table.

When full = TRUE, the vector will be padded with zeros to a length of 128, and the patternOrderLength will be set to the length of value. When full = FALSE, value will only replace the part of the order table up to the length of value. The remainder of the table is not changed. The patternOrderLength is also not modified in this case.

Author

Pepijn de Vries

Details

The actual length of the vector containing the pattern order is 128 as per ProTracker standards. Only part of this vector is `visible' and will be used to determine in which order pattern tables are to be played. This method can be used to return either the visible or full (all 128) part of the table. It can also be used to assign a new patter order table.

Note that PTPattern indices start at 0, as per ProTracker standards, whereas R start indices at 1. Hence, add 1 to the indices obtained with patternOrder, in order to extract the correct PTPattern from a PTModule.

The maximum index plus 1 in the full pattern order table should equal the number of pattern tables (see patternLength) in the PTModule. Is you assign a new pattern order, with a lower maximum, PTPattern objects will get lost (see also examples)!

See Also

Other pattern.operations: MODPlugToPTPattern(), PTPattern-class, PTPattern-method, PTPatternToMODPlug(), appendPattern(), deletePattern(), pasteBlock(), patternLength(), patternOrderLength()

Other module.operations: PTModule-class, appendPattern(), clearSamples(), clearSong(), deletePattern(), fix.PTModule(), modToWave(), moduleSize(), patternLength(), patternOrderLength(), playMod(), playingtable(), rawToPTModule(), read.module(), trackerFlag(), write.module()

Examples

data("mod.intro")

## get the visible part of the patternOrder table:
patternOrder(mod.intro)

## get the full patternOrder table:
patternOrder(mod.intro, full = TRUE)

## add 1 to get extract the right PTPattern from
## mod.intro:
first.pattern.played <-
  (PTPattern(mod.intro, patternOrder(mod.intro)[1] + 1))

## set a different playing order:
patternOrder(mod.intro) <- c(0:3, 0:3, 0:3)

## The assignment above uses a value that
## longer than the patternOrderLength.
## This means that a part ends up in the
## 'invisible' part of the order table:
patternOrder(mod.intro)
patternOrder(mod.intro, full = TRUE)

## Let's do the same assignment, but update
## the visible part of the table as well:
patternOrder(mod.intro, full = TRUE) <- c(0:3, 0:3, 0:3)

## note that the maximum of the order table plus 1
## equals the patternLength of mod.intro (always the case
## for a valid PTModule object):
max(patternOrder(mod.intro, full = TRUE) + 1) ==
  patternLength(mod.intro)

## Let's do something dangerous. If the replacement
## indices do not hold a maximum value that equals
## the patternLength minus 1, PTPatterns will get lost,
## in order to maintain the validity of mod.intro:
patternOrder(mod.intro) <- rep(0, 12)