Строковые функции

rtSurvey поддерживает различные функции, в том числе:

  1. string(field): преобразует поле в строку.

    • Пример: string(34.8) будет преобразован в '34.8'.

  2. string-length(field): возвращает длину строкового поля.

    • Пример: string-length(.) > 3 and string-length(.) < 10 может использоваться для проверки, что текущее поле содержит от 3 до 10 символов.

  3. substr(fieldorstring, startindex, endindex): возвращает подстроку, начинающуюся с startindex и заканчивающуюся перед endindex. Индексы начинаются с 0 для первого символа строки.

    • Пример: substr(${phone}, 0, 3) вернёт первые три цифры номера телефона.

  4. concat(a, b, c, ...): объединяет поля (и/или строки) вместе.

    • Пример: concat(${firstname}, ' ', ${lastname}) вернёт полное имя, объединив значения полей firstname и lastname.

  5. linebreak(): возвращает символ переноса строки.

    • Пример: concat(${field1}, linebreak(), ${field2}, linebreak(), ${field3}) вернёт список трёх значений полей с переносами строк между ними.

  6. lower(): преобразует строку в нижний регистр.

    • Пример: lower('Street Name') вернёт “street name”.

  7. upper(): преобразует строку в верхний регистр.

    • Пример: upper('Street Name') вернёт “STREET NAME”.

Функции select_one и select_multiple

  1. count-selected(field): возвращает количество выбранных элементов в поле select_multiple.

    • Пример: count-selected(.) = 3 может использоваться как выражение ограничения для обеспечения выбора ровно трёх вариантов.

  2. selected(field, value): возвращает true или false в зависимости от того, был ли указанный вариант выбран в поле select_one или select_multiple.

    • Пример: selected(${color}, 'Blue') может использоваться как выражение релевантности для отображения группы или поля только если респондент выбрал “Blue” в качестве любимого цвета.
    • Примечание: второй параметр должен всегда указывать значение варианта, а не его метку. Используйте значение из столбца value в листе choices.

  3. selected-at(field, number): возвращает выбранный элемент на указанной позиции в поле select_multiple. При передаче числа 0 возвращается первый выбранный элемент; при числе 1 — второй, и так далее.

    • Пример: selected-at(${fruits}, 0) = 'Apple' может использоваться как выражение релевантности для отображения группы или поля только если первый выбранный вариант — “Apple”.
    • Примечание: возвращаемое значение будет значением варианта, а не его меткой.

  4. choice-label(field, value): возвращает метку для варианта поля select_one или select_multiple из листа choices.

    • Пример 1: choice-label(${country}, ${country}) вернёт метку варианта для текущего выбранного варианта в поле country.
    • Пример 2: choice-label(${languages}, selected-at(${languages}, 0)) вернёт метку первого выбранного варианта в поле languages.
    • Примечание: эта функция получает метку варианта, а не значение.

Функции для повторяющихся полей

В rtSurvey, если нужно задать одни и те же вопросы несколько раз, можно поместить поле внутрь группы повторений. В результате получается несколько экземпляров одного и того же поля. Следующие функции помогают работать с такими повторяющимися полями.

  1. join(string, repeatedfield): для поля внутри группы повторений генерирует список значений, разделённых строкой. Первый параметр задаёт разделитель.

    • Пример: join(', ', ${member_name}) создаст единый список имён через запятую.

  2. join-if(string, repeatedfield, expression): работает как join(), но проверяет каждый экземпляр в группе повторений с помощью указанного выражения. Если выражение ложно, элемент исключается из результата.

    • Пример: join-if(', ', ${member_name}, ${age} >= 18) создаст список имён только взрослых членов.

  3. count(repeatgroup): возвращает текущее количество повторений группы.

    • Пример: count(${groupname}) вернёт количество экземпляров группы.

  4. count-if(repeatgroup, expression): работает как count(), но проверяет каждый экземпляр с помощью указанного выражения.

    • Пример: count-if(${members}, ${age} >= 18) вернёт количество взрослых членов на основе поля age.

  5. sum(repeatedfield): для поля внутри группы повторений вычисляет сумму всех значений.

    • Пример: sum(${loan_amount}) вернёт общую сумму всех займов.

  6. sum-if(repeatedfield, expression): работает как sum(), но проверяет каждый экземпляр с помощью указанного выражения.

    • Пример: sum-if(${loan_amount}, ${loan_amount} > 500) вернёт сумму всех займов свыше 500.

  7. min(repeatedfield): для поля внутри группы повторений вычисляет минимальное из всех значений.

    • Пример: min(${member_age}) вернёт возраст самого молодого члена группы.

  8. min-if(repeatedfield, expression): работает как min(), но проверяет каждый экземпляр с помощью указанного выражения.

    • Пример: min-if(${member_age}, ${member_age} >= 18) вернёт возраст самого молодого взрослого в группе.

  9. max(repeatedfield): для поля внутри группы повторений вычисляет максимальное из всех значений.

    • Пример: max(${member_age}) вернёт возраст старейшего члена группы.

  10. max-if(repeatedfield, expression): работает как max(), но проверяет каждый экземпляр с помощью указанного выражения.

    • Пример: max-if(${member_age}, ${member_age} >= 18) вернёт возраст старейшего взрослого в группе.

  11. index(): вызванная внутри группы повторений, возвращает порядковый номер текущей группы или экземпляра.

    • Пример: index() внутри группы повторений вернёт 1 для первого экземпляра, 2 для второго и так далее.

  12. indexed-repeat(repeatedfield, repeatgroup, index): ссылается на поле или группу внутри группы повторений извне этой группы. Первый параметр задаёт повторяющееся поле или группу, второй — группу повторений, третий — номер экземпляра.

    • Пример 1: indexed-repeat(${name}, ${names}, 1) вернёт первое имя из предыдущей группы повторений “names”.
    • Пример 2: indexed-repeat(${name}, ${names}, index()) извлечёт имя, соответствующее номеру текущего экземпляра.

  13. rank-index(index, repeatedfield): вычисляет порядковый ранг указанного экземпляра повторяющегося поля для использования за пределами группы повторений. Ранг 1 присваивается экземпляру с наибольшим значением, ранг 2 — следующему по убыванию и так далее.

    • Пример: rank-index(1, ${random_draw}) вычисляет ранг первого экземпляра на основе значения его поля random_draw.

  14. rank-index-if(index, repeatedfield, expression): работает аналогично rank-index(), но проверяет каждый экземпляр с помощью указанного выражения.

    • Пример: rank-index-if(1, ${age}, ${age} >= 18) вычисляет ранг возраста в наборе взрослых, учитывая только экземпляры, где возраст больше или равен 18.

Числовые функции

ОператорОперацияПримерПример ответа
+Сложение1 + 12
-Вычитание3 - 21
*Умножение3 * 26
divДеление10 div 25
modОстаток9 mod 21

rtSurvey поддерживает числовые функции, в том числе:

  • number(field): преобразует значение поля в число.

    • Пример: number('34.8') = 34.8

  • int(field): преобразует значение поля в целое число.

    • Пример: int('39.2') = 39

  • min(field1, ..., fieldx): возвращает минимальное значение среди переданных полей.

    • Пример: min(${father_age}, ${mother_age}) вернёт возраст матери или отца, смотря кто моложе.

  • max(field1, ..., fieldx): возвращает максимальное значение среди переданных полей.

    • Пример: max(${father_age}, ${mother_age}) вернёт возраст матери или отца, смотря кто старше.

  • format-number(field): форматирует значение целочисленного или дробного поля в соответствии с региональными настройками пользователя.

    • Пример: format-number(${income}) может отформатировать “120000” как “120,000”.

  • round(field, digits): округляет числовое значение поля до указанного количества знаков после запятой.

    • Пример: round(${interest_rate}, 2)

  • abs(number): возвращает абсолютное значение числа.

  • pow(base, exponent): возвращает значение первого параметра, возведённого в степень второго параметра.

  • log10(fieldorvalue): возвращает десятичный логарифм переданного поля или значения.

  • sin(fieldorvalue): возвращает синус переданного поля или значения в радианах.

  • cos(fieldorvalue): возвращает косинус переданного поля или значения в радианах.

  • tan(fieldorvalue): возвращает тангенс переданного поля или значения в радианах.

  • asin(fieldorvalue): возвращает арксинус переданного поля или значения в радианах.

  • acos(fieldorvalue): возвращает арккосинус переданного поля или значения в радианах.

  • atan(fieldorvalue): возвращает арктангенс переданного поля или значения в радианах.

  • atan2(x, y): возвращает угол в радианах, образованный началом координат и точкой с координатами (x, y) и положительной осью x.

  • sqrt(fieldorvalue): возвращает неотрицательный квадратный корень переданного поля или значения.

  • exp(x): возвращает значение e^x.

  • pi(): возвращает значение числа пи.

Функции даты и времени

  1. today(): возвращает сегодняшнюю дату в виде строки в формате YYYY-MM-DD. Вычисляется один раз при открытии формы.

    • Пример: today() → '2024-03-15'
    • Частое применение: столбец default для предзаполнения сегодняшней датой, или в relevant/constraint для сравнения с полем даты.

  2. now(): возвращает текущую дату и время в виде строки ISO 8601. Вычисляется каждый раз при вычислении выражения.

    • Пример: now() → '2024-03-15T14:32:00.000+03:00'
    • Частое применение: запись точной временной метки конкретного события во время опроса.

  3. date(value): преобразует значение (строку или число) в строку даты.

    • Пример: date('2024-03-15') → '2024-03-15'

  4. date-time(value): преобразует значение в строку даты и времени.

    • Пример: date-time(${event_timestamp})

  5. decimal-date-time(value): преобразует строку даты или даты-времени в дробное число, представляющее количество миллисекунд с начала эпохи Unix, делённое на 86400000 (то есть дробное количество дней с 1970-01-01). Используйте это для арифметики с датами.

    • Пример: длительность в днях между двумя датами: decimal-date-time(${end_date}) - decimal-date-time(${start_date})
    • Пример: длительность в минутах между двумя датами-временами: (decimal-date-time(${end_time}) - decimal-date-time(${start_time})) * 1440

  6. format-date(date, format): форматирует значение даты с использованием строки шаблона.

    • Токены формата: %Y (4-значный год), %y (2-значный год), %m (месяц 01–12), %d (день 01–31), %a (аббревиатура дня недели), %b (аббревиатура месяца)
    • Пример: format-date(today(), '%d/%m/%Y') → '15/03/2024'

  7. format-date-time(datetime, format): форматирует значение даты-времени с использованием строки шаблона. Принимает все токены format-date плюс:

    • %H (часы 00–23), %h (часы 01–12), %M (минуты 00–59), %S (секунды 00–59), %3 (миллисекунды), %P (AM/PM)
    • Пример: format-date-time(now(), '%d/%m/%Y %H:%M') → '15/03/2024 14:32'

Булевы функции

  1. boolean(value): преобразует любое значение в булево. Возвращает true для непустых строк, ненулевых чисел и true; возвращает false для пустых строк, 0 и false.

    • Пример: boolean(${name}) возвращает true, если name не пустое.

  2. boolean-from-string(string): возвращает true, если строка равна '1' или 'true' (без учёта регистра); в противном случае возвращает false.

    • Пример: boolean-from-string(${enabled_flag}) — полезно, когда поле хранит 'true'/'false' как текст.

  3. true(): возвращает булево значение true.

    • Пример: в столбце required true() эквивалентно yes.

  4. false(): возвращает булево значение false.

    • Пример: if(${skip_section} = 'yes', false(), true()) — динамическое установление обязательности.

  5. not(expression): возвращает логическое отрицание выражения. Возвращает true, если выражение ложно, и наоборот.

    • Пример: not(${consent} = 'yes') — показывает предупреждение, когда согласие НЕ дано.
    • Пример: not(selected(${issues}, 'none')) — требует детализации только если “none” не выбрано.

Дополнительные строковые функции

  1. starts-with(string, prefix): возвращает true, если string начинается с prefix.

    • Пример: starts-with(${phone}, '+254') проверяет, начинается ли номер телефона с кода Кении.

  2. contains(string, substring): возвращает true, если string содержит substring.

    • Пример: contains(${email}, '@') проверяет наличие знака @ в адресе электронной почты.

  3. substring-before(string, needle): возвращает часть string, расположенную до первого вхождения needle.

    • Пример: substring-before(${full_name}, ' ') извлекает первое слово (имя).

  4. substring-after(string, needle): возвращает часть string, расположенную после первого вхождения needle.

    • Пример: substring-after(${email}, '@') извлекает доменную часть адреса электронной почты.

  5. normalize-space(string): удаляет ведущие и завершающие пробелы и сворачивает внутренние последовательности пробелов в один.

    • Пример: normalize-space(${name}) — очищает имя, введённое с лишними пробелами.

  6. translate(string, search_chars, replace_chars): заменяет каждый символ в string, присутствующий в search_chars, соответствующим символом из replace_chars. Символы из search_chars, не имеющие соответствия в replace_chars, удаляются.

    • Пример: translate(${phone}, ' -()', '') удаляет пробелы, дефисы и скобки из номера телефона.

Дополнительные математические функции

  1. floor(number): возвращает наибольшее целое, не превышающее number (округление к меньшему).

    • Пример: floor(4.9) = 4, floor(-2.1) = -3

  2. ceiling(number): возвращает наименьшее целое, не меньшее number (округление к большему).

    • Пример: ceiling(4.1) = 5, ceiling(-2.9) = -2

  3. random(): возвращает случайное дробное число от 0.0 (включительно) до 1.0 (не включая). Обычно используется в полях calculate для присвоения случайных значений или рандомизации порядка вопросов.

    • Пример: int(random() * 6) + 1 → случайное число от 1 до 6 (бросок кубика)

  4. coalesce(a, b): возвращает a, если a не пустое; иначе возвращает b. Полезно как запасное значение, когда поле может быть пустым.

    • Пример: coalesce(${preferred_name}, ${full_name}) — использует предпочтительное имя, если оно задано, иначе полное.

  5. once(value): вычисляет value и сохраняет его, но только если текущее поле пустое. Если поле уже имеет значение, once() возвращает существующее значение без изменений. Это предотвращает перезапись пользовательского ввода при пересчёте.

    • Пример: once(today()) в столбце default устанавливает сегодняшнюю дату один раз и не обновляется при повторном открытии формы.
    • Пример: once(uuid()) генерирует UUID один раз и сохраняет его при повторном редактировании.

Геофункции

  1. area(geoshape_value): вычисляет площадь в квадратных метрах, заключённую в геоформу (полигон).

    • Пример: area(${field_boundary}) — вычисляет площадь обследованного поля в м².
    • Пример: round(area(${field_boundary}) div 10000, 2) — перевод в гектары.

  2. distance(coordinates): вычисляет общую длину пути в метрах для геотрека (линии) или расстояние между двумя геоточками.

    • Для геотрека: distance(${route}) возвращает общую длину пути в метрах.
    • Пример: round(distance(${road_trace}) div 1000, 3) — длина дороги в километрах.

Функции валидации

  1. regex(value, pattern): возвращает true, если value соответствует регулярному выражению pattern. Используйте в столбце constraint для валидации по шаблону.

    • Пример: regex(., '^[0-9]{10}$') — проверка 10-значного числа.
    • Пример: regex(., '^[A-Z]{2}[0-9]{6}$') — проверка формата номера паспорта.
    • Пример: regex(., '^[^@]+@[^@]+\.[^@]{2,}$') — базовая проверка формата электронной почты.

  2. checklist(min, max, v1, v2, ...): оценивает список булевых выражений и возвращает true, если количество значений true находится между min и max включительно. Передайте -1 для min или max, чтобы пропустить это ограничение.

    • Пример: checklist(2, 3, ${q1} = 'yes', ${q2} = 'yes', ${q3} = 'yes') — проходит, если ровно 2 или 3 из трёх условий истинны.

  3. weighted-checklist(min, max, v1, w1, v2, w2, ...): аналогично checklist(), но каждое значение имеет вес. Сумма весов для значений true должна быть между min и max.

    • Пример: weighted-checklist(10, -1, ${has_toilet}, 4, ${has_sink}, 3, ${has_shower}, 5) — сумма весов имеющихся удобств должна быть не менее 10.

Служебные функции

  1. uuid(): генерирует случайный UUID (формат RFC 4122 v4) в виде строки.

    • Обычно используется с once() для генерации стабильного уникального ID: once(uuid())

  2. version(): возвращает значение атрибута version формы, установленного в листе settings.

    • Пример: version() → '3.1'

  3. position(): при вызове внутри группы повторений возвращает 1-базированный индекс текущего экземпляра повторения.

    • Пример: position() в первом экземпляре возвращает 1, во втором — 2 и так далее.

  4. thousandsep(length, separator, value): форматирует число с разделителем тысяч. length — минимальная общая длина строки, separator — используемый символ, value — число для форматирования.

    • Пример: thousandsep(0, ',', 1234567) → '1,234,567'

  5. substr-jsonpath(value, jsonpath): извлекает подстроку из строки JSON с использованием выражения JSONPath.

    • Пример: substr-jsonpath(${api_response}, '$.data.name') — извлечение поля name из JSON-строки, хранящейся в api_response.
    • Обычно используется вместе с callapi() для извлечения конкретных значений из ответов API.
Была ли эта страница полезной?