Pot.zip

与えられた配列 object の各アイテム n 番目の要素からなる配列を作成して返します。

引数 object は、対象の配列を指定します。
引数 callback は、任意にイテレートする関数を指定します。
引数 context が指定されると、callback 関数の this が context にとって代わります。
この関数は、Python の zip() のように振る舞います。

引数が以下のような配列とすると、
  [ [1, 2, 3],
    [4, 5, 6] ]

結果は以下のようになります。

  [ [1, 4],
    [2, 5],
    [3, 6] ]

言いかえると、各要素を縦に見立てて新しい配列を作ります。
要素数の扱いは「最小」であり、溢れたものは除外されます。

コールバック関数 callback の引数は以下のようになります。

function (item, object) { this === context }

    item   : {Array}      n 番目のアイテムを持つ配列。
    object : {Object|*}   object 自身。

処理は同期処理、非同期処理、それぞれ異なります。

Pot.zip は同期処理になります。
Pot.globalize() 適応済みの場合は zip() で実行できます。
Pot.Deferred.zip は非同期処理になり、Pot.Deferred のインスタンスを返します。
Pot.globalize() 適応済みの場合は Deferred.zip() で実行できます。
Pot.Deferred.prototype.zip は、Pot.Deferred.prototype.async() によって同期/非同期が変化します。
Pot.Deferred チェイン上で実行でき、Pot.Deferred のインスタンスを返します。

callback 関数の中で StopIteration (Pot.StopIteration) を throw することでループを止められます。

Pot.Deferred.zip.slow() のようにして速度の指定ができます。
非同期では、ほとんどの環境で速度指定が可能ですが、同期での速度指定は一部の環境 (XUL 上など) のみになります。
指定できる名前は以下の表を参照ください。
デフォルトの速度は normal です。

値 / メソッド名

速度

limp

最も遅い

doze

遅い

slow

遅め

normal

通常

fast

速め

rapid

速い

ninja

最も速い

引数 object のアイテムからなる配列が返ります。

Pot.zip で同期処理の例:

var result = Pot.zip([
    [1, 2, 3],
    [4, 5, 6]
]);
debug(result);
// [
//   [1, 4],
//   [2, 5],
//   [3, 6]
// ]

var result = Pot.zip([
    [1, 2, 3],
    [1, 2, 3, 4, 5]
]);
debug(result);
// [
//   [1, 1],
//   [2, 2],
//   [3, 3]
// ]

var result = Pot.zip([
    [ 1,  2, 3],
    [ 4,  5, 6],
    [ 7,  8, 9],
    [10, 11]
]);
debug(result);
// [
//   [1, 4, 7, 10],
//   [2, 5, 8, 11]
// ]

var result = Pot.zip(['hoge']);
debug(result); // [['hoge']]

var result = Pot.zip([[1], [2], [3]]);
debug(result); // [[1, 2, 3]]

var result = Pot.zip([
    [    1,     2,     3],
    ['foo', 'bar', 'baz'],
    [    4,     5]
]);
debug(result);
// [
//   [1, 'foo', 4],
//   [2, 'bar', 5]
// ]

// コールバック関数を使った例
var result = Pot.zip([
    [1, 2, 3],
    [4, 5, 6]
], function(item, array) {
    return item[0] + item[1];
});
debug(result); // [5, 7, 9]

Pot.Deferred.zip で非同期処理の例:

Pot.Deferred.zip([
    [1, 2, 3],
    [4, 5, 6]
]).then(function(result) {
    debug(result);
    // [
    //   [1, 4],
    //   [2, 5],
    //   [3, 6]
    // ]
});

// コールバック関数を使った例

Pot.Deferred.zip([
    [1, 2, 3],
    [4, 5, 6]
], function(item, array) {
    return item[0] + item[1];
}).then(function(result) {
    debug(result); // [5, 7, 9]
});

Pot.Deferred.prototype.zip で非同期処理の例:

var d = new Pot.Deferred();

d.then(function() {
    return [
        [1, 2, 3],
        [4, 5, 6]
    ];
}).zip().then(function(result) {
    debug(result);
    // [
    //   [1, 4],
    //   [2, 5],
    //   [3, 6]
    // ]
}).begin();

Pot.Deferred.begin(function() {
    return [
        [1, 2, 3],
        [4, 5, 6]
    ];
}).zip().then(function(result) {
    debug(result);
    // [
    //   [1, 4],
    //   [2, 5],
    //   [3, 6]
    // ]
});

// コールバック関数を使った例

var d = new Pot.Deferred();

d.zip(function(item, array) {
    return item[0] + item[1];
}).then(function(result) {
    debug(result); // [5, 7, 9]
}).begin([
    [1, 2, 3],
    [4, 5, 6]
]);