본문으로 건너뛰기

$string 사용법 ($string)

개요​

$string는 자바스크립트 String 객체를 대상으로 하는 확장 함수 모음입니다. null/undefined 안전 처리, HTML 이스케이프, 문자열 템플릿 치환(interpolate), 타입 변환(Boolean/Number/Date 추론), CSV류 문자열 파싱과 검증, 통화/패딩 포맷팅까지 문자열을 다루는 대부분의 상용구 작업을 대체합니다. syn.js가 로드되면 전역 객체로 즉시 사용할 수 있으며, syn.$string과 같은 별도의 syn. 접두 별칭은 없습니다.

로드 방법​

syn.js가 로드되면 전역에 $string로 즉시 사용할 수 있습니다. 별도의 초기화나 new 호출이 필요하지 않습니다.

빠른 시작​

$string.toValue(null, '기본값'); // "기본값"
$string.interpolate('<span>#{name}</span>', { name: 'HandStack' });

주요 시나리오​

null-safe 문자열 처리​

값이 null/undefined일 수 있는 상황에서 안전하게 문자열로 변환하거나 빈 값 여부를 확인합니다.

$string.toValue(undefined, '-');      // "-"
$string.isNullOrEmpty('');            // true
$string.isNullOrWhiteSpace('   ');    // true

템플릿 문자열 치환​

#{key} 형태의 플레이스홀더가 포함된 템플릿 문자열을 JSON 객체(또는 객체 배열)로 치환합니다.

const json = { symbol: 'HandStack', price: 12345 };
$string.interpolate('<span>#{symbol}</span> <span>#{price}</span>', json);

HTML 문자열 안전 처리​

사용자 입력을 화면에 출력하기 전 태그를 제거하거나 특수문자를 이스케이프합니다.

$string.sanitizeHTML('<b>hello</b>');      // "hello"
$string.toHtmlChar('<b>hello</b>');        // 특수문자가 HTML 엔티티로 치환된 문자열

값 타입 변환​

문자열 값을 의도한 타입(Boolean/Number/Date) 또는 자동 추론된 타입으로 변환합니다.

$string.toBoolean('Y');                    // true
$string.toNumber('-12,345.123');           // -12345.123
$string.toDynamic('2023-12-11T04:45:56.558Z'); // Date 객체로 추론
$string.toParseType('100', 'number');      // 100 (의도한 타입으로 강제 변환)

CSV류 문자열 파싱과 검증​

클립보드에서 붙여넣은 구분자 문자열을 JSON 배열/2차원 배열로 변환하고, 규칙(rules) 기반으로 검증합니다.

const rows = $string.toJsv('System;Progress\nERP;80%', { delimiter: ';' });
const validate = $string.validateJsv(rows, {
    0: { name: 'System', required: true, enum: ['ERP', 'MES'] },
    1: { name: 'Progress', required: true, pattern: '^\\d+%$' }
}, { validateAll: true });

통화/자릿수 포맷팅​

숫자를 통화 형식 문자열로, 문자열을 원하는 자릿수로 패딩합니다.

$string.toCurrency(1234567.891);      // "1,234,567.891"
$string.pad('7', 5);                  // "00007"

실전 예제 페이지​

/sample/syn/extension_string.html 예제에서 다음 항목을 실습할 수 있습니다.

  • $string.toValue() - null/undefined 안전 문자열 변환
  • $string.br() - 줄바꿈을 <br />로 변환
  • $string.interpolate() - 템플릿 치환(단일 객체/배열 지원)
  • $string.isNullOrEmpty() / $string.isNullOrWhiteSpace() - 공백/빈 값 확인
  • $string.sanitizeHTML() / $string.cleanHTML() - HTML 태그 제거
  • $string.toHtmlChar() / $string.toCharHtml() - HTML 문자 엔티티 상호 변환
  • $string.length() - 바이트 기준 길이 계산
  • $string.split() - 구분자 기준 배열 변환
  • $string.isNumber() / $string.toNumber() - 숫자 판별/변환
  • $string.capitalize() - 단어 첫 글자 대문자화
  • $string.toJson() / $string.toJsv() / $string.validateJsv() - CSV류 문자열 파싱과 검증
  • $string.toParameterObject() - key:value 문자열을 객체로 변환
  • $string.toBoolean() / $string.toDynamic() / $string.toParseType() - 타입 변환
  • $string.toNumberString() - 숫자 관련 문자만 추출
  • $string.toStringCounts() - 글자수/단어수/문장수 계산
  • $string.toCurrency() - 통화 형식 변환
  • $string.pad() - 자릿수 패딩

주의 사항​

  • toJson()/toJsv()의 옵션 속성명은 delimiter(구분자), newline(줄바꿈), meta(컬럼별 타입 지정)입니다. delimeter처럼 오탈자로 전달하면 옵션이 무시되고 기본 구분자(,)가 사용되므로 주의하세요.
  • toStringCounts()는 Intl.Segmenter를 사용할 수 있는 최신 브라우저에서 정확한 글자/단어/문장 수를 계산하며, 지원하지 않는 환경에서는 정규식 기반의 근사치를 반환합니다.
  • length()는 문자열의 .length가 아니라 숫자/영어 1바이트, 그 외 문자 다바이트로 계산한 바이트 길이를 반환하므로 화면 폭 계산 등에 사용할 수 있습니다.
  • 예제 페이지의 "속성" 카드에 있는 $string.version 값은 다른 syn.js 샘플 페이지와 동일하게 syn.$m.version(라이브러리 공용 버전 표시 관례)을 그대로 사용합니다.
  • 문자열 조합/포맷팅에는 $string.interpolate()나 템플릿 리터럴을 사용하세요.

관련 모듈​

  • API 상세는 아래 API 참조 섹션을 확인하세요.

API 참조​

모듈 정보​

항목내용
전역 별칭$string (전역, syn.$string 별칭 없음)
예제 페이지/sample/syn/extension_string.html
의존 모듈$object(isNullOrUndefined), $date(toString, isDate)

메서드​

$string.toValue(value, defaultValue = '')​

  • 설명: 값이 undefined/null이 아니면 문자열로 변환하고, 그렇지 않으면 defaultValue를 문자열로 변환해 반환합니다.
  • 매개변수
    이름타입필수설명
    valueanyY변환할 값
    defaultValueanyNvalue가 없을 때 사용할 기본값(기본값 '')
  • 반환값: string
  • 예시 
    const result = $string.toValue(null, '기본값');

$string.br(val)​

  • 설명: 문자열의 줄바꿈 문자(\r\n, \r, \n)를 <br /> 태그로 치환합니다.
  • 매개변수
    이름타입필수설명
    valanyY변환할 값(내부에서 문자열로 변환)
  • 반환값: string
  • 예시 
    const result = $string.br('hello\nworld');

$string.interpolate(text, json, options = {})​

  • 설명: #{key} 형태의 플레이스홀더가 포함된 템플릿 문자열을 JSON 객체(또는 객체 배열)의 값으로 치환합니다. 배열이면 각 항목별로 치환한 결과를 separator로 연결합니다.
  • 매개변수
    이름타입필수설명
    textstringY#{key} 플레이스홀더가 포함된 템플릿 문자열
    jsonObject | Array<Object>Y치환에 사용할 값
    options.defaultValueanyN값이 없을 때 사용할 기본값(기본값 null이면 플레이스홀더 유지)
    options.separatorstringN배열 치환 시 결과 연결 구분자(기본값 \n)
  • 반환값: string
  • 예시 
    const result = $string.interpolate('<span>#{name}</span>', { name: 'HandStack' });

$string.isNullOrEmpty(val)​

  • 설명: 값이 undefined, null이거나 빈 문자열('')인지 확인합니다.
  • 매개변수
    이름타입필수설명
    valanyY확인할 값
  • 반환값: boolean
  • 예시 
    const result = $string.isNullOrEmpty('');

$string.isNullOrWhiteSpace(val)​

  • 설명: 값이 undefined, null이거나 공백 문자만으로 이루어져 있는지(trim() 결과가 빈 문자열인지) 확인합니다.
  • 매개변수
    이름타입필수설명
    valanyY확인할 값
  • 반환값: boolean
  • 예시 
    const result = $string.isNullOrWhiteSpace('   ');

$string.sanitizeHTML(val, removeSpecialChars = false)​

  • 설명: 문자열에서 HTML 태그와 &nbsp;를 제거하고 앞뒤 공백을 트리밍합니다. removeSpecialChars가 true면 일부 특수문자도 함께 제거합니다.
  • 매개변수
    이름타입필수설명
    valstringY대상 문자열(문자열이 아니면 빈 문자열 반환)
    removeSpecialCharsbooleanN특수문자 제거 여부(기본값 false)
  • 반환값: string
  • 예시 
    const result = $string.sanitizeHTML('<b>hello</b>');

$string.cleanHTML(val)​

  • 설명: 브라우저 환경에서 문자열의 HTML을 DOM으로 파싱해 텍스트만 추출하고, 연속 공백을 하나로 축약합니다(Node 환경에서는 원본을 그대로 반환).
  • 매개변수
    이름타입필수설명
    valstringY대상 문자열
  • 반환값: string
  • 예시 
    const result = $string.cleanHTML('<b>hello</b>   world');

$string.toHtmlChar(val, charStrings)​

  • 설명: 문자열에 포함된 지정 특수문자를 HTML 문자 엔티티(&#nn; 등)로 치환합니다.
  • 매개변수
    이름타입필수설명
    valstringY대상 문자열(문자열이 아니면 빈 문자열 반환)
    charStringsstringN치환 대상 문자 목록(기본값은 소스 참고)
  • 반환값: string
  • 예시 
    const result = $string.toHtmlChar('<b>hello</b>');

$string.toCharHtml(val, escapedChars = '&(amp|#39|lt|gt|...);')​

  • 설명: toHtmlChar()로 치환된 HTML 엔티티 문자열을 원래 특수문자로 되돌립니다.
  • 매개변수
    이름타입필수설명
    valstringY대상 문자열(문자열이 아니면 빈 문자열 반환)
    escapedCharsstringN엔티티 매칭 정규식 패턴(기본값은 소스 참고)
  • 반환값: string
  • 예시 
    const result = $string.toCharHtml('&lt;b&gt;hello&lt;/b&gt;');

$string.length(val)​

  • 설명: 문자열 길이를 UTF-8 바이트 기준으로 계산합니다(ASCII 1바이트, 한글 등은 다바이트).
  • 매개변수
    이름타입필수설명
    valstringY대상 문자열(문자열이 아니면 0 반환)
  • 반환값: number
  • 예시 
    const result = $string.length('안녕 hello');

$string.split(val, char = ',')​

  • 설명: 문자열을 구분자로 분리하고, 트리밍 후 빈 문자열 항목을 제거한 배열을 반환합니다.
  • 매개변수
    이름타입필수설명
    valstringY대상 문자열(문자열이 아니면 빈 배열 반환)
    charstringN구분자(기본값 ,)
  • 반환값: Array<string>
  • 예시 
    const result = $string.split('1,2,3');

$string.isNumber(num)​

  • 설명: 값이 숫자(천단위 구분 기호, 소수점, 음수 부호 포함)로 변환 가능한 형식인지 확인합니다.
  • 매개변수
    이름타입필수설명
    numanyY확인할 값
  • 반환값: boolean
  • 예시 
    const result = $string.isNumber('-12,345.123');

$string.toNumber(val)​

  • 설명: 문자열(천단위 구분 기호 포함 가능)을 숫자로 변환합니다. 변환에 실패하면 경고 로그를 남기고 0을 반환합니다.
  • 매개변수
    이름타입필수설명
    valanyY변환할 값
  • 반환값: number
  • 예시 
    const result = $string.toNumber('-12,345.123');

$string.capitalize(val)​

  • 설명: 문자열 내 각 단어의 첫 글자(영문 소문자)를 대문자로 변환합니다.
  • 매개변수
    이름타입필수설명
    valstringY대상 문자열(문자열이 아니면 빈 문자열 반환)
  • 반환값: string
  • 예시 
    const result = $string.capitalize('aaa bbb ccc');

$string.toJson(val, options = {})​

  • 설명: 구분자와 줄바꿈으로 구성된 문자열(CSV류)을 첫 줄을 헤더로 사용하는 JSON 객체 배열로 변환합니다.
  • 매개변수
    이름타입필수설명
    valstringY대상 문자열(문자열이 아니면 빈 배열 반환)
    options.delimiterstringN열 구분자(기본값 ,)
    options.newlinestringN줄 구분자(기본값 \n)
    options.metaObjectN컬럼명별 타입 지정(toParseType에 사용)
  • 반환값: Array<Object>
  • 예시 
    const result = $string.toJson('col1;col2\na;b', { delimiter: ';' });

$string.toJsv(val, options = {})​

  • 설명: 구분자와 줄바꿈으로 구성된 문자열을 헤더 없이 행 단위 값 배열(2차원 배열)로 변환합니다. toJson()과 달리 첫 줄도 데이터 행으로 포함됩니다.
  • 매개변수
    이름타입필수설명
    valstringY대상 문자열(문자열이 아니면 빈 배열 반환)
    options.delimiterstringN열 구분자(기본값 ,)
    options.newlinestringN줄 구분자(기본값 \n)
    options.metaObjectN컬럼 인덱스별 타입 지정(toParseType에 사용)
  • 반환값: Array<Array<any>>
  • 예시 
    const result = $string.toJsv('ERP;80%\nMES;120%', { delimiter: ';' });

$string.validateJsv(data, rules, options = {})​

  • 설명: toJsv() 등으로 만들어진 2차원 배열 데이터를 컬럼 인덱스 기준 규칙(rules)으로 검증합니다. 필수값, 최소/최대 길이, 최소/최대값, 정규식 패턴, enum, 커스텀 validator 함수를 지원합니다.
  • 매개변수
    이름타입필수설명
    dataArray<Array<any>>Y검증할 2차원 배열 데이터
    rulesObject | ArrayY컬럼 인덱스를 키로 하는 규칙 객체(또는 배열)
    options.throwErrorbooleanN검증 실패 시 예외를 던질지 여부(기본값 false)
    options.returnDetailsbooleanN상세 결과 객체 반환 여부(기본값 true)
    options.validateAllbooleanN모든 행을 검증할지, 첫 행만 검증할지(기본값 false → 첫 행만)
  • 반환값: Object — { result, errorCount, errors, validatedRows, validatedColumns } (또는 returnDetails: false이면 { result })
  • 예시 
    const rows = $string.toJsv('ERP;80%', { delimiter: ';' });
    const result = $string.validateJsv(rows, {
        0: { name: 'System', required: true, enum: ['ERP', 'MES'] },
        1: { name: 'Progress', required: true, pattern: '^\\d+%$' }
    }, { validateAll: true });

$string.toParameterObject(parameters)​

  • 설명: @Name1:Value1;@Name2:Value2 형태의 문자열을 { Name1: 'Value1', Name2: 'Value2' } 형태의 객체로 변환합니다.
  • 매개변수
    이름타입필수설명
    parametersstringY@이름:값; 형식의 문자열
  • 반환값: Object
  • 예시 
    const result = $string.toParameterObject('@Name1:Value1;@Name2:Value2');

$string.toBoolean(val)​

  • 설명: 문자열(또는 값)이 true, y, 1, ok, yes, on(대소문자 무관) 중 하나인지 확인해 boolean으로 변환합니다.
  • 매개변수
    이름타입필수설명
    valanyY변환할 값
  • 반환값: boolean
  • 예시 
    const result = $string.toBoolean('Y');

$string.toDynamic(val, emptyIsNull = false)​

  • 설명: 문자열 값을 boolean/number/Date/string 중 알맞은 타입으로 자동 추론하여 변환합니다.
  • 매개변수
    이름타입필수설명
    valanyY변환할 값
    emptyIsNullbooleanN빈 문자열을 null로 취급할지 여부(기본값 false → 빈 문자열 반환)
  • 반환값: boolean \| number \| Date \| string \| null
  • 예시 
    const result = $string.toDynamic('2023-12-11T04:45:56.558Z');

$string.toParseType(val, metaType = 'string', emptyIsNull = false)​

  • 설명: 문자열 값을 지정한 타입(string/bool/boolean/number/numeric/int/date/datetime)에 맞게 강제 변환합니다.
  • 매개변수
    이름타입필수설명
    valanyY변환할 값
    metaTypestringN변환할 타입(기본값 string)
    emptyIsNullbooleanN빈 문자열을 null로 취급할지 여부(기본값 false)
  • 반환값: string \| boolean \| number \| Date \| null
  • 예시 
    const result = $string.toParseType('100', 'number');

$string.toNumberString(val)​

  • 설명: 문자열에서 숫자, 소수점(.), 마이너스 부호(-) 이외의 문자를 제거합니다.
  • 매개변수
    이름타입필수설명
    valstringY대상 문자열(문자열이 아니면 빈 문자열 반환)
  • 반환값: string
  • 예시 
    const result = $string.toNumberString('f-1,234.12');

$string.toStringCounts(text, locale)​

  • 설명: 문자열의 글자수, 단어수, 문장수를 계산합니다. Intl.Segmenter를 지원하는 환경에서는 grapheme/word/sentence 단위로 정확히 계산하고, 지원하지 않으면 정규식 기반 근사치를 계산합니다.
  • 매개변수
    이름타입필수설명
    textstringY대상 문자열
    localestringNIntl.Segmenter에 사용할 로케일(기본값 syn.$b?.language 또는 ko-KR)
  • 반환값: { characters: number, words: number, sentences: number }
  • 예시 
    const result = $string.toStringCounts('안녕하세요. hello world!');

$string.toCurrency(val, localeID, options = {})​

  • 설명: 값을 숫자로 변환한 뒤 천단위 구분 기호가 포함된 통화 형식의 문자열로 변환합니다. localeID가 지정되고 Intl.NumberFormat을 사용할 수 있으면 해당 로케일 형식을 우선 사용합니다.
  • 매개변수
    이름타입필수설명
    valanyY변환할 값
    localeIDstringNIntl.NumberFormat에 사용할 로케일(생략 시 수동 포맷 사용)
    optionsObjectNIntl.NumberFormat 옵션(기본값 { style: 'decimal', currency: 'KRW' }과 병합)
  • 반환값: string \| null — 변환에 실패하면 null
  • 예시 
    const result = $string.toCurrency(1234567.891, 'ko-KR');

$string.pad(val, length, fix = '0', isLeft = true)​

  • 설명: 문자열을 지정한 길이가 될 때까지 지정한 문자로 좌측 또는 우측을 채웁니다.
  • 매개변수
    이름타입필수설명
    valanyY대상 값(내부에서 문자열로 변환)
    lengthnumberY목표 길이
    fixstringN채울 문자(기본값 0)
    isLeftbooleanNtrue면 좌측 패딩, false면 우측 패딩(기본값 true)
  • 반환값: string
  • 예시 
    const result = $string.pad('7', 5); // "00007"