Google Apps Script (GAS) часто используется для автоматизации задач, связанных с обработкой данных из различных источников, таких как Google Sheets, Google Forms, внешние API и другие. Нередко данные поступают в виде строк, даже если они представляют числовые значения. Для выполнения математических операций, сравнений или анализа таких данных необходимо преобразовывать строки в числовые типы, в частности, в целые числа (integers).
Необходимость преобразования строки в число
Представьте сценарий анализа данных рекламной кампании из Google Sheets. Бюджеты, клики или показы могут быть импортированы как строки (‘100’, ‘50.5’, ‘1,000’). Попытка выполнить арифметические операции (например, сложение бюджетов) непосредственно со строками приведет либо к конкатенации строк (‘100′ + ’50’ = ‘10050’), либо к ошибкам во время выполнения. Поэтому корректное преобразование типов является критически важным шагом.
Обзор методов преобразования
В JavaScript, а следовательно и в Google Apps Script, существует несколько встроенных способов преобразования строк в числа. Основными и наиболее часто используемыми для получения целых чисел являются:
parseInt(): Анализирует строковый аргумент и возвращает целое число в соответствии с указанным основанием системы счисления.
Number(): Преобразует переданное значение в число. Может возвращать как целые, так и числа с плавающей точкой.
Выбор метода зависит от конкретной задачи и ожидаемого формата входных строк.
Использование parseInt() для преобразования строки в целое число
parseInt() — это функция, специально предназначенная для извлечения целочисленного значения из начала строки.
Синтаксис и параметры parseInt()
/**
* Преобразует строку в целое число.
*
* @param {string} string Строка для преобразования.
* @param {number} [radix] Основание системы счисления (от 2 до 36). По умолчанию 10.
* @return {number} Целое число или NaN, если преобразование невозможно.
*/
parseInt(string, radix);string: Входная строка, которую необходимо преобразовать.
radix (необязательный): Целое число от 2 до 36, представляющее основание системы счисления. Крайне рекомендуется всегда указывать radix, как правило, 10, чтобы избежать неожиданного поведения, особенно со строками, начинающимися с ‘0’ или ‘0x’.
Примеры использования parseInt()
Рассмотрим пример извлечения бюджета кампании из строки, полученной из ячейки Google Sheet.
/**
* Извлекает целочисленный бюджет из строки.
* @param {string} budgetString Строка, содержащая бюджет (например, "1500 USD" или "2,000").
* @returns {number} Целочисленное значение бюджета или NaN.
*/
function getBudgetAsInt(budgetString: string): number {
// Удаляем нечисловые символы, кроме потенциального разделителя тысяч
const cleanedString: string = budgetString.replace(/[^\d]/g, '');
// Преобразуем в целое число с основанием 10
const budgetInt: number = parseInt(cleanedString, 10);
Logger.log(`Исходная строка: ${budgetString}, Результат parseInt: ${budgetInt}`);
return budgetInt;
}
// Пример вызова
const budget1: number = getBudgetAsInt("1500 USD"); // Лог: Исходная строка: 1500 USD, Результат parseInt: 1500
const budget2: number = getBudgetAsInt("2,000"); // Лог: Исходная строка: 2,000, Результат parseInt: 2000
const budget3: number = getBudgetAsInt("Бюджет: 500"); // Лог: Исходная строка: Бюджет: 500, Результат parseInt: 500parseInt() останавливает парсинг строки, как только встречает нечисловой символ (после начальных числовых символов). Если строка начинается не с цифры (и не со знака +/-), результат будет NaN.
Обработка ошибок и некорректных значений с parseInt()
Если parseInt() не может преобразовать строку в число, она возвращает NaN (Not-a-Number). Важно проверять результат преобразования с помощью функции isNaN().
/**
* Безопасно преобразует строку в целое число, возвращая 0 в случае ошибки.
* @param {string} value Строковое значение.
* @returns {number} Целое число или 0.
*/
function safeParseInt(value: string): number {
const result: number = parseInt(value, 10);
if (isNaN(result)) {
Logger.log(`Не удалось преобразовать '${value}' в число. Возвращено 0.`);
return 0;
}
return result;
}
const clicksStr: string = "unknown";
const clicks: number = safeParseInt(clicksStr); // Лог: Не удалось преобразовать 'unknown' в число. Возвращено 0.
Logger.log(clicks); // 0
const validClicksStr: string = "123";
const validClicks: number = safeParseInt(validClicksStr);
Logger.log(validClicks); // 123Использование Number() для преобразования строки в число
Конструктор Number() также можно использовать для преобразования строк в числа, но он работает несколько иначе, чем parseInt().
Синтаксис и параметры Number()
/**
* Преобразует переданное значение в числовое представление.
*
* @param {*} value Значение для преобразования.
* @return {number} Числовое представление или NaN.
*/
Number(value);Number() пытается преобразовать всю строку в число. Он может обрабатывать десятичные точки и экспоненциальное представление, но более строг к нечисловым символам.
Примеры использования Number()
Предположим, мы получаем показатель CTR (Click-Through Rate) из API в виде строки.
/**
* Преобразует строковое представление CTR в число.
* @param {string} ctrString Строка с CTR (например, "1.5" или "0.05").
* @returns {number} Числовое значение CTR или NaN.
*/
function getCtrAsNumber(ctrString: string): number {
const ctrNumber: number = Number(ctrString);
Logger.log(`Исходная строка: ${ctrString}, Результат Number: ${ctrNumber}`);
return ctrNumber;
}
// Пример вызова
const ctr1: number = getCtrAsNumber("2.75"); // Лог: Исходная строка: 2.75, Результат Number: 2.75
const ctr2: number = getCtrAsNumber("0.05e2"); // Лог: Исходная строка: 0.05e2, Результат Number: 5
const ctr3: number = getCtrAsNumber("-10"); // Лог: Исходная строка: -10, Результат Number: -10Различия между Number() и parseInt()
Обработка нечисловых символов: parseInt() извлекает число из начала строки, игнорируя последующие нечисловые символы (parseInt("100px", 10) вернет 100). Number() вернет NaN, если вся строка не является валидным числом (Number("100px") вернет NaN).
Плавающая точка: parseInt() всегда возвращает целое число, отбрасывая дробную часть (parseInt("10.5", 10) вернет 10). Number() может возвращать числа с плавающей точкой (Number("10.5") вернет 10.5).
Основание системы счисления: parseInt() позволяет указать основание (radix), Number() всегда работает с десятичной системой (хотя распознает префиксы 0x для шестнадцатеричной).
Пустая строка/null: Number('') или Number(null) вернет 0. parseInt('') или parseInt(null) вернет NaN.
Обработка ошибок и некорректных значений с Number()
Аналогично parseInt(), Number() возвращает NaN при невозможности преобразования. Проверка isNaN() так же необходима.
/**
* Безопасно преобразует строку в число с помощью Number(), возвращая 0 в случае ошибки.
* @param {string} value Строковое значение.
* @returns {number} Число или 0.
*/
function safeConvertToNumber(value: string): number {
const result: number = Number(value);
// Дополнительная проверка, т.к. Number(null) === 0, что может быть нежелательно
if (value === null || isNaN(result)) {
Logger.log(`Не удалось преобразовать '${value}' в число с помощью Number(). Возвращено 0.`);
return 0;
}
return result;
}
const costStr: string = "Not Available";
const cost: number = safeConvertToNumber(costStr); // Лог: Не удалось преобразовать 'Not Available' в число с помощью Number(). Возвращено 0.
Logger.log(cost); // 0
const validCostStr: string = " 99.99 "; // Пробелы по краям обрабатываются
const validCost: number = safeConvertToNumber(validCostStr);
Logger.log(validCost); // 99.99Особые случаи и продвинутые техники
Преобразование строк с плавающей точкой в целые числа (округление)
Если входная строка представляет число с плавающей точкой, но требуется целое число, можно сначала использовать Number() или parseFloat(), а затем применить методы округления Math.floor(), Math.ceil() или Math.round().
/**
* Преобразует строку в округленное целое число.
* @param {string} floatString Строка с числом (возможно, с плавающей точкой).
* @param {'round' | 'floor' | 'ceil'} [method='round'] Метод округления.
* @returns {number} Округленное целое число или NaN.
*/
function parseAndRound(floatString: string, method: 'round' | 'floor' | 'ceil' = 'round'): number {
const num: number = Number(floatString);
if (isNaN(num)) {
return NaN;
}
switch (method) {
case 'floor':
return Math.floor(num);
case 'ceil':
return Math.ceil(num);
case 'round':
default:
return Math.round(num);
}
}
const conversionValueStr: string = "15.7";
const roundedValue: number = parseAndRound(conversionValueStr, 'round'); // 16
const floorValue: number = parseAndRound(conversionValueStr, 'floor'); // 15
const ceilValue: number = parseAndRound(conversionValueStr, 'ceil'); // 16
Logger.log(`Rounded: ${roundedValue}, Floor: ${floorValue}, Ceil: ${ceilValue}`);Работа с разными системами счисления (parseInt с основанием)
Параметр radix в parseInt() полезен при работе с числами в не-десятичных системах, например, при обработке шестнадцатеричных цветовых кодов или данных из специфических источников.
/**
* Преобразует шестнадцатеричную строку в десятичное целое число.
* @param {string} hexString Шестнадцатеричная строка (например, "FF").
* @returns {number} Десятичное представление или NaN.
*/
function hexToInt(hexString: string): number {
// Убираем возможный префикс '0x'
const cleanHex: string = hexString.startsWith('0x') ? hexString.substring(2) : hexString;
const decimalValue: number = parseInt(cleanHex, 16); // Основание 16
Logger.log(`Hex: ${hexString}, Decimal: ${decimalValue}`);
return decimalValue;
}
const colorComp: number = hexToInt("FF"); // Лог: Hex: FF, Decimal: 255
const dataId: number = hexToInt("1A3"); // Лог: Hex: 1A3, Decimal: 419Преобразование строк, содержащих нечисловые символы
Часто строки содержат валютные символы, разделители тысяч, единицы измерения и т.д. Перед преобразованием такие строки необходимо очистить с помощью регулярных выражений или методов замены строк.
/**
* Извлекает число из строки с денежным форматом.
* @param {string} currencyString Строка (напр., "$1,250.99", "€500").
* @returns {number} Целочисленное значение (дробная часть отбрасывается) или NaN.
*/
function parseCurrencyToInt(currencyString: string): number {
// Удаляем все, кроме цифр и точки/запятой как десятичного разделителя (если нужен)
// Для простоты примера - убираем всё не цифровое
const digitsOnly: string = currencyString.replace(/[^\d]/g, '');
if (digitsOnly === '') {
return NaN; // Если после очистки ничего не осталось
}
const result: number = parseInt(digitsOnly, 10);
Logger.log(`Currency String: ${currencyString}, Parsed Int: ${result}`);
return result;
}
const revenue1: number = parseCurrencyToInt("$1,250.99"); // Лог: Currency String: $1,250.99, Parsed Int: 125099 (Внимание: без обработки точки!)
// Для корректного извлечения целой части из $1,250.99 может потребоваться более сложная логика или parseFloat + Math.floor
const revenue2: number = parseCurrencyToInt("€500"); // Лог: Currency String: €500, Parsed Int: 500
const revenue3: number = parseCurrencyToInt("N/A"); // Лог: Currency String: N/A, Parsed Int: NaNВажно: Приведенный выше пример parseCurrencyToInt упрощен. Для надежной обработки денежных строк с разными форматами и десятичными разделителями может потребоваться более сложный парсинг.
Заключение и рекомендации
Правильное преобразование строк в целые числа является фундаментальным навыком при работе с данными в Google Apps Script.
Выбор подходящего метода преобразования (parseInt vs. Number)
Используйте parseInt(string, 10), когда вам нужно извлечь только целое число из начала строки и вы хотите игнорировать последующие нечисловые символы или дробную часть. Всегда указывайте основание 10. Идеально подходит для извлечения ID, счетчиков, целых значений бюджета из смешанных строк.
Используйте Number(string), когда вам нужно преобразовать всю строку в число, и строка должна представлять собой валидное число (целое или с плавающей точкой). Менее терпим к посторонним символам. Подходит для преобразования чистых числовых строк, возможно, с десятичной точкой.
Лучшие практики при работе с преобразованием типов данных
Всегда проверяйте результат: Используйте isNaN() для проверки результата parseInt() и Number(), чтобы избежать ошибок NaN в последующих вычислениях.
Указывайте основание: При использовании parseInt() всегда явно указывайте radix (обычно 10).
Очищайте строки: Перед преобразованием удаляйте или заменяйте нерелевантные символы (валюты, разделители тысяч, единицы измерения), если они мешают парсингу.
Учитывайте локаль: Разделители тысяч и десятичные разделители могут отличаться. Если вы работаете с данными из разных источников, учитывайте возможные форматы.
Используйте строгую типизацию: Если возможно (например, при работе с TypeScript в Apps Script с помощью CLASP), используйте типы для повышения надежности кода.
Дополнительные ресурсы и материалы
Для углубленного изучения рекомендуется обратиться к официальной документации Mozilla Developer Network (MDN) по функциям parseInt() и Number(), а также изучить методы объекта Math для округления и работы с числами. Практика на реальных задачах автоматизации в Google Workspace поможет закрепить полученные знания.