Google Apps Script: Как работать с массивами в Google Sheets?

/**
 * Создает и инициализирует массив строк.
 * @return {string[]} - Созданный массив.
 */
function createStringArray(): string[] {
  let stringArray: string[] = ["apple", "banana", "cherry"];
  return stringArray;
}

/**
 * Создает пустой числовой массив.
 * @return {number[]} - Пустой числовой массив.
 */
function createEmptyNumberArray(): number[] {
  let numberArray: number[] = [];
  return numberArray;
}

let myArray: string[] = ["a", "b", "c"];
let firstElement: string = myArray[0]; // firstElement = "a"
myArray[1] = "new value"; // Изменяем значение второго элемента

console.log(firstElement);
console.log(myArray[1]);

/**
 * Считывает данные из Google Sheets в массив.
 * @param {string} sheetName - Имя листа Google Sheets.
 * @param {string} range - Диапазон ячеек для чтения (например, "A1:B10").
 * @return {any[][]} - Двумерный массив, содержащий данные из таблицы.
 */
function readDataFromSheet(sheetName: string, range: string): any[][] {
  const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = spreadsheet.getSheetByName(sheetName);

  if (!sheet) {
    Logger.log("Лист с именем " + sheetName + " не найден.");
    return [];
  }

  const dataRange = sheet.getRange(range);
  const data: any[][] = dataRange.getValues();
  return data;
}

// Пример использования:
let sheetData: any[][] = readDataFromSheet("Sheet1", "A1:C5");
console.log(sheetData);

let myArray: string[] = ["x", "y", "z"];

// Цикл for
for (let i: number = 0; i < myArray.length; i++) {
  console.log("Элемент " + i + ": " + myArray[i]);
}

// forEach
myArray.forEach(function(element: string, index: number) {
  console.log("Элемент " + index + ": " + element);
});

let myArray: string[] = ["a", "b", "c"];

myArray.push("d"); // ["a", "b", "c", "d"]
myArray.pop();    // ["a", "b", "c"] (возвращает "d")
myArray.shift();  // ["b", "c"] (возвращает "a")
myArray.unshift("x"); // ["x", "b", "c"]
myArray.splice(1, 1, "y", "z"); // ["x", "y", "z", "c"]

/**
 * Пример использования map для умножения чисел в массиве на 2.
 * @param {number[]} numbers - Исходный массив чисел.
 * @return {number[]} - Новый массив, где каждое число умножено на 2.
 */
function multiplyByTwo(numbers: number[]): number[] {
  return numbers.map(function(number: number): number {
    return number * 2;
  });
}

/**
 * Пример использования filter для фильтрации четных чисел из массива.
 * @param {number[]} numbers - Исходный массив чисел.
 * @return {number[]} - Новый массив, содержащий только четные числа.
 */
function filterEvenNumbers(numbers: number[]): number[] {
  return numbers.filter(function(number: number): boolean {
    return number % 2 === 0;
  });
}

/**
 * Пример использования reduce для суммирования чисел в массиве.
 * @param {number[]} numbers - Исходный массив чисел.
 * @return {number} - Сумма всех чисел в массиве.
 */
function sumNumbers(numbers: number[]): number {
  return numbers.reduce(function(accumulator: number, currentValue: number): number {
    return accumulator + currentValue;
  }, 0); // 0 - начальное значение аккумулятора
}

//Примеры использования с данными из Google Sheets:
function processSheetData() {
  let sheetData: any[][] = readDataFromSheet("Sheet1", "A1:A5"); // Предполагаем, что в столбце A числа
  let numbers: number[] = sheetData.map(row => Number(row[0])); // Преобразуем в массив чисел

  let multiplied: number[] = multiplyByTwo(numbers);
  let even: number[] = filterEvenNumbers(numbers);
  let sum: number = sumNumbers(numbers);

  console.log("Умноженные на 2: " + multiplied);
  console.log("Четные: " + even);
  console.log("Сумма: " + sum);
}

let myArray: string[] = ["a", "b", "c", "b"];

let index: number = myArray.indexOf("b"); // index = 1
let includesB: boolean = myArray.includes("b"); // includesB = true

let found: string | undefined = myArray.find(function(element: string): boolean {
  return element === "c";
}); // found = "c"

let foundIndex: number = myArray.findIndex(function(element: string): boolean {
  return element === "c";
}); // foundIndex = 2

/**
 * Записывает одномерный массив в столбец Google Sheets.
 * @param {string} sheetName - Имя листа Google Sheets.
 * @param {string} startCell - Начальная ячейка для записи (например, "A1").
 * @param {any[]} dataArray - Одномерный массив данных.
 */
function writeArrayToColumn(sheetName: string, startCell: string, dataArray: any[]) {
  const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = spreadsheet.getSheetByName(sheetName);

  if (!sheet) {
    Logger.log("Лист с именем " + sheetName + " не найден.");
    return;
  }

  // Преобразуем одномерный массив в двумерный (столбец)
  let data: any[][] = dataArray.map(function(item: any): any[] {
    return [item];
  });

  const range = sheet.getRange(startCell).offset(0, 0, data.length, 1);
  range.setValues(data);
}


/**
 * Записывает одномерный массив в строку Google Sheets.
 * @param {string} sheetName - Имя листа Google Sheets.
 * @param {string} startCell - Начальная ячейка для записи (например, "A1").
 * @param {any[]} dataArray - Одномерный массив данных.
 */
function writeArrayToRow(sheetName: string, startCell: string, dataArray: any[]) {
  const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = spreadsheet.getSheetByName(sheetName);

  if (!sheet) {
    Logger.log("Лист с именем " + sheetName + " не найден.");
    return;
  }

  // Преобразуем одномерный массив в двумерный (строка)
  let data: any[][] = [dataArray];

  const range = sheet.getRange(startCell).offset(0, 0, 1, dataArray.length);
  range.setValues(data);
}

// Пример использования:
//writeArrayToColumn("Sheet1", "A1", [1, 2, 3, 4, 5]);
//writeArrayToRow("Sheet1", "A1", ["a", "b", "c", "d", "e"]);

/**
 * Записывает двумерный массив в диапазон ячеек Google Sheets.
 * @param {string} sheetName - Имя листа Google Sheets.
 * @param {string} startCell - Начальная ячейка для записи (например, "A1").
 * @param {any[][]} dataArray - Двумерный массив данных.
 */
function writeArrayToRange(sheetName: string, startCell: string, dataArray: any[][]) {
  const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = spreadsheet.getSheetByName(sheetName);

  if (!sheet) {
    Logger.log("Лист с именем " + sheetName + " не найден.");
    return;
  }

  const numRows: number = dataArray.length;
  const numCols: number = dataArray[0].length; // Предполагаем, что все строки имеют одинаковую длину

  const range = sheet.getRange(startCell).offset(0, 0, numRows, numCols);
  range.setValues(dataArray);
}

// Пример использования:
// let data: any[][] = [["A", "B", "C"], [1, 2, 3], ["X", "Y", "Z"]];
// writeArrayToRange("Sheet1", "A1", data);

try {
  writeArrayToRange("Sheet1", "A1", data);
} catch (e) {
  Logger.log("Ошибка записи данных: " + e);
}

/**
 * Фильтрует данные о продажах из Google Sheets по региону.
 * @param {string} sheetName - Имя листа Google Sheets.
 * @param {string} dataRange - Диапазон ячеек с данными о продажах (например, "A2:C100", где A - регион, B - продукт, C - объем продаж).
 * @param {number} regionColumnIndex - Индекс столбца с регионом (начиная с 0).
 * @param {string} targetRegion - Регион для фильтрации.
 * @return {any[][]} - Двумерный массив с отфильтрованными данными.
 */
function filterSalesByRegion(sheetName: string, dataRange: string, regionColumnIndex: number, targetRegion: string): any[][] {
  let data: any[][] = readDataFromSheet(sheetName, dataRange);

  let filteredData: any[][] = data.filter(function(row: any[]): boolean {
    return row[regionColumnIndex] === targetRegion;
  });

  return filteredData;
}

// Пример использования:
// let filteredSales: any[][] = filterSalesByRegion("SalesData", "A2:C100", 0, "North");
// writeArrayToRange("FilteredSales", "A1", filteredSales); // Запись отфильтрованных данных на другой лист

/**
 * Сортирует данные из Google Sheets по указанному столбцу.
 * @param {string} sheetName - Имя листа Google Sheets.
 * @param {string} dataRange - Диапазон ячеек с данными (например, "A2:C100").
 * @param {number} sortColumnIndex - Индекс столбца для сортировки (начиная с 0).
 * @param {boolean} ascending - `true` для сортировки по возрастанию, `false` - по убыванию.
 * @return {any[][]} - Двумерный массив с отсортированными данными.
 */
function sortDataByColumn(sheetName: string, dataRange: string, sortColumnIndex: number, ascending: boolean): any[][] {
  let data: any[][] = readDataFromSheet(sheetName, dataRange);

  data.sort(function(a: any[], b: any[]): number {
    if (a[sortColumnIndex]  b[sortColumnIndex]) {
      return ascending ? 1 : -1;
    }
    return 0;
  });

  return data;
}

// Пример использования:
// let sortedData: any[][] = sortDataByColumn("SalesData", "A2:C100", 2, false); // Сортировка по объему продаж по убыванию
// writeArrayToRange("SortedSales", "A1", sortedData);