함수

문자열 함수 link

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 함수 link

1. count-selected(field): select_multiple 필드에서 선택된 항목의 수를 반환합니다.

   • 예시: count-selected(.) = 3은 정확히 세 가지 선택지가 선택되었는지 확인하는 제약 표현식으로 사용할 수 있습니다.

2. selected(field, value): 지정된 값이 select_one 또는 select_multiple 필드에서 선택되었는지 여부에 따라 true 또는 false를 반환합니다.

   • 예시: selected(${color}, 'Blue')는 응답자가 좋아하는 색상으로 “Blue"를 선택한 경우에만 그룹이나 필드를 표시하기 위한 연관성 표현식으로 사용할 수 있습니다.
   • 참고: 두 번째 매개변수는 항상 선택지 레이블이 아닌 선택지 값을 지정해야 합니다.

3. selected-at(field, number): select_multiple 필드에서 지정된 위치의 선택된 항목을 반환합니다. 전달된 숫자가 0이면 첫 번째 선택된 항목을 반환하고, 1이면 두 번째 선택된 항목을 반환합니다.

   • 예시: selected-at(${fruits}, 0) = 'Apple'은 첫 번째 선택된 선택지가 “Apple"인 경우에만 그룹이나 필드를 표시하기 위한 연관성 표현식으로 사용할 수 있습니다.

4. choice-label(field, value): 양식 정의의 choices 워크시트에 정의된 select_one 또는 select_multiple 필드 선택지의 레이블을 반환합니다.

   • 예시 1: choice-label(${country}, ${country})는 country라는 필드에서 현재 선택된 선택지의 레이블을 반환합니다.
   • 예시 2: choice-label(${languages}, selected-at(${languages}, 0))는 languages라는 필드에서 첫 번째 선택된 선택지의 레이블을 반환합니다.

반복 필드 함수 link

rtSurvey에서 같은 질문을 여러 번 하려면 필드를 반복 그룹에 넣을 수 있습니다. 이는 같은 필드의 여러 인스턴스를 생성합니다. 다음 함수들은 이러한 반복 필드와 그것이 생성하는 반복 데이터를 처리하는 데 도움이 됩니다.

1. join(string, repeatedfield): 반복 그룹 내의 필드에 대해 값의 문자열 구분 목록을 생성합니다. 첫 번째 매개변수는 값 사이를 구분하는 구분자를 지정합니다.

   • 예시: join(', ', ${member_name})은 입력된 모든 이름에서 단일 쉼표로 구분된 목록을 생성합니다.

2. join-if(string, repeatedfield, expression): join()과 정확히 동일하게 작동하지만 제공된 표현식을 사용하여 반복 그룹의 각 인스턴스를 확인합니다. 표현식이 false로 평가되면 해당 항목은 출력에서 제외됩니다.

   • 예시: join-if(', ', ${member_name}, ${age} >= 18)은 성인 구성원 (18세 이상)의 이름만의 쉼표로 구분된 목록을 생성합니다.

3. count(repeatgroup): 반복 그룹이 반복된 현재 횟수를 반환합니다.

   • 예시: count(${groupname})은 그룹의 인스턴스 수를 반환합니다.

4. count-if(repeatgroup, expression): count()와 정확히 동일하게 작동하지만 제공된 표현식을 사용하여 반복 그룹의 각 인스턴스를 확인합니다. 표현식이 false로 평가되면 해당 항목은 출력에서 제외됩니다.

   • 예시: count-if(${members}, ${age} >= 18)은 “members” 반복 그룹 내의 나이 필드를 기반으로 성인 구성원의 수를 반환합니다.

5. sum(repeatedfield): 반복 그룹 내의 필드에 대해 모든 값의 합을 계산합니다.

   • 예시: sum(${loan_amount})은 모든 대출의 총 값을 반환합니다.

6. sum-if(repeatedfield, expression): sum()과 정확히 동일하게 작동하지만 제공된 표현식을 사용하여 반복 그룹의 각 인스턴스를 확인합니다. 표현식이 false로 평가되면 해당 항목은 출력에서 제외됩니다.

   • 예시: sum-if(${loan_amount}, ${loan_amount} > 500)은 500 초과인 모든 대출의 총 값을 반환합니다.

7. min(repeatedfield): 반복 그룹 내의 필드에 대해 모든 값의 최솟값을 계산합니다.

   • 예시: min(${member_age})는 그룹에서 가장 어린 구성원의 나이를 반환합니다.

8. min-if(repeatedfield, expression): min()과 정확히 동일하게 작동하지만 제공된 표현식을 사용하여 반복 그룹의 각 인스턴스를 확인합니다. 표현식이 false로 평가되면 해당 항목은 출력에서 제외됩니다.

   • 예시: 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): 반복 그룹 외부에서 사용하기 위해 반복 필드의 지정된 인스턴스의 서수 순위를 계산합니다.

    • 예시: rank-index(1, ${random_draw})는 다른 인스턴스 값과 비교하여 첫 번째 인스턴스의 random_draw 필드 값을 기반으로 순위를 계산합니다.

14. rank-index-if(index, repeatedfield, expression): rank-index()와 유사하게 작동하지만 제공된 표현식을 사용하여 반복 필드의 반복 그룹의 각 인스턴스를 확인합니다. 표현식이 false로 평가되면 해당 항목은 계산에서 제외됩니다.

    • 예시: rank-index-if(1, ${age}, ${age} >= 18)는 성인 집합 내의 나이 순위를 계산하며 18세 이상인 인스턴스만 고려합니다.

숫자 함수 link

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축에 의해 원점에서 이루어지는 각도를 라디안 단위로 반환합니다. 결과는 -pi()에서 pi() 범위입니다.

• sqrt(fieldorvalue): 전달된 필드 또는 값의 비음 제곱근을 반환합니다.

• exp(x): e^x의 값을 반환합니다.

• pi(): 파이의 값을 반환합니다.

날짜 및 시간 함수 link

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 epoch 이후 밀리초를 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'
   • 예시: format-date(${dob}, '%B %d, %Y') → 'March 15, 1990'

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'
   • 예시: format-date-time(${event_time}, '%I:%M %p') → '02:32 PM'

Boolean 함수 link

1. boolean(value): 모든 값을 boolean으로 변환합니다. 비어있지 않은 문자열, 0이 아닌 숫자, true에 대해 true를 반환하고, 빈 문자열, 0, false에 대해 false를 반환합니다.

   • 예시: boolean(${name})은 name이 비어있지 않으면 true를 반환합니다.

2. boolean-from-string(string): 문자열이 '1' 또는 'true'이면 (대소문자 무시) true를 반환하고, 그렇지 않으면 false를 반환합니다.

   • 예시: boolean-from-string(${enabled_flag}) — 필드가 텍스트로 'true'/'false'를 저장할 때 유용합니다.

3. true(): boolean 값 true를 반환합니다.

   • 예시: required 열에서 true()는 yes와 동일합니다.

4. false(): boolean 값 false를 반환합니다.

   • 예시: if(${skip_section} = 'yes', false(), true()) — 동적으로 필수 설정.

5. not(expression): 표현식의 논리 부정을 반환합니다. 표현식이 false이면 true를 반환하고 그 반대도 마찬가지입니다.

   • 예시: not(${consent} = 'yes') — 동의하지 않은 경우 경고 표시.
   • 예시: not(selected(${issues}, 'none')) — “없음"이 선택되지 않은 경우에만 세부 사항 요구.

추가 문자열 함수 link

1. starts-with(string, prefix): string이 prefix로 시작하면 true를 반환합니다.

   • 예시: starts-with(${phone}, '+254')는 전화번호가 케냐 국가 코드로 시작하는지 확인합니다.

2. contains(string, substring): string이 substring을 포함하면 true를 반환합니다.

   • 예시: contains(${email}, '@')는 이메일 주소에 @ 기호가 있는지 확인합니다.
   • 예시: contains(${notes}, 'urgent')는 메모에 “urgent"가 언급된 경우 후속 질문을 트리거합니다.

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(${code}, 'abcdefghijklmnopqrstuvwxyz', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ')는 대문자로 변환합니다 (upper()와 동일).
   • 예시: translate(${phone}, ' -()', '')는 전화번호에서 공백, 대시, 괄호를 제거합니다.

추가 수학 함수 link

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 필드에서 사용됩니다.

   • 예시: random() → 예: 0.7341
   • 예시: int(random() * 6) + 1 → 1–6의 무작위 숫자 (주사위 굴리기)

4. coalesce(a, b): a가 비어있지 않으면 a를 반환하고, 그렇지 않으면 b를 반환합니다. 필드가 비어있을 수 있는 경우 폴백으로 유용합니다.

   • 예시: coalesce(${preferred_name}, ${full_name}) — 선호 이름이 설정된 경우 사용하고, 그렇지 않으면 전체 이름으로 대체합니다.

5. once(value): value를 평가하고 저장하지만 현재 필드가 비어있는 경우에만 합니다. 필드에 이미 값이 있는 경우 (예: 이전에 설정된 경우) once()는 기존 값을 변경하지 않고 반환합니다. 이는 재계산이 사용자 입력을 덮어쓰는 것을 방지합니다.

   • 예시: default 열의 once(today())는 오늘 날짜를 한 번 설정하고 조사원이 양식을 다시 열어도 업데이트하지 않습니다.
   • 예시: once(uuid())는 UUID를 한 번 생성하고 재편집에 걸쳐 안정적으로 유지합니다.

지리 함수 link

1. area(geoshape_value): geoshape (다각형) 값으로 둘러싸인 면적을 제곱미터로 계산합니다.

   • 매개변수는 lat1 lon1 0 0; lat2 lon2 0 0; ... 형식의 geoshape 필드 값입니다.
   • 예시: area(${field_boundary}) — 측량된 필지의 면적을 m²로 계산합니다.
   • 예시: round(area(${field_boundary}) div 10000, 2) — 헥타르로 변환합니다.

2. distance(coordinates): geotrace (선)의 총 경로 길이를 미터로 계산하거나, 두 geopoint 사이의 거리를 계산합니다.

   • geotrace의 경우: distance(${route})는 총 경로 길이를 미터로 반환합니다.
   • 두 geopoint의 경우: distance(concat(${point_a}, ' ', ${point_b}))는 두 지점 사이의 거리를 반환합니다.
   • 예시: round(distance(${road_trace}) div 1000, 3) — 도로 길이를 킬로미터로.

유효성 검사 함수 link

1. regex(value, pattern): value가 정규 표현식 pattern과 일치하면 true를 반환합니다. 패턴 기반 유효성 검사를 위해 constraint 열에서 사용합니다.

   • 예시: regex(., '^[0-9]{10}$') — 10자리 숫자를 유효성 검사합니다.
   • 예시: regex(., '^[A-Z]{2}[0-9]{6}$') — 여권 번호 형식을 유효성 검사합니다 (대문자 2자 뒤에 숫자 6자).
   • 예시: regex(., '^[^@]+@[^@]+\.[^@]{2,}$') — 기본 이메일 형식 확인.

2. checklist(min, max, v1, v2, ...): boolean 표현식 목록을 평가하고 true 값의 수가 min과 max 사이 (포함)이면 true를 반환합니다. 해당 경계를 건너뛰려면 min 또는 max에 -1을 전달합니다.

   • 예시: checklist(2, 3, ${q1} = 'yes', ${q2} = 'yes', ${q3} = 'yes') — 세 조건 중 정확히 2개 또는 3개가 참이면 통과합니다.
   • 예시: checklist(1, -1, ${smoke_alarm}, ${fire_ext}, ${emergency_plan}) — 적어도 하나의 안전 조치가 참이어야 합니다.

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이어야 합니다.

유틸리티 함수 link

1. uuid(): 임의의 UUID (RFC 4122 v4 형식)를 문자열로 생성합니다.

   • 예시: uuid() → 'a3f8b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c'
   • 일반적으로 안정적인 고유 ID를 생성하기 위해 once()와 함께 사용됩니다: once(uuid())

2. version(): settings 워크시트에 설정된 양식의 version 속성 값을 반환합니다.

   • 예시: version() → '3.1'
   • 내보낸 데이터에 양식 버전을 포함하기 위해 calculate 필드에서 유용합니다.

3. position(): 반복 그룹 내에서 호출될 때 현재 반복 인스턴스의 1기반 인덱스를 반환합니다.

   • 예시: position()은 첫 번째 인스턴스에서 1, 두 번째에서 2 등을 반환합니다.
   • 참고: index() (별칭), 그룹 외부에서 반복 값을 참조하기 위한 indexed-repeat().

4. thousandsep(length, separator, value): 천 단위 구분자로 숫자를 형식화합니다. length는 최소 총 문자열 길이 (더 짧으면 공백으로 채워짐), separator는 사용할 문자 (예: ','), value는 형식화할 숫자입니다.

   • 예시: thousandsep(0, ',', 1234567) → '1,234,567'
   • 예시: thousandsep(0, '.', ${income}) → 마침표를 천 단위 구분자로 사용하여 소득을 형식화합니다.

5. substr-jsonpath(value, jsonpath): JSONPath 표현식을 사용하여 JSON 문자열에서 부분 문자열을 추출합니다.

   • 예시: substr-jsonpath(${api_response}, '$.data.name') — api_response에 저장된 JSON 문자열에서 name 필드를 추출합니다.
   • 일반적으로 API 응답에서 특정 값을 추출하기 위해 callapi()와 함께 사용됩니다.