본문으로 건너뛰기

Number 확장 사용법 ($number)

개요​

$number는 숫자 값을 다루는 확장 함수를 제공합니다. 밀리초 값을 사람이 읽기 쉬운 기간으로 변환하거나, 바이트 크기 문자열 변환, 난수 생성, 범위 검사/보정, 백분율·금액 계산, 다중 값 집계(SUM/AVG/MIN/MAX 등)와 같은 화면 로직에서 자주 쓰는 숫자 연산을 모아 둔 모듈입니다.

로드 방법​

syn.js가 로드되면 전역에 $number로 즉시 사용할 수 있습니다. (syn. 접두사 없이 전역 변수로 노출됨에 유의)

빠른 시작​

$number.random(1, 100);          // 1~100 사이의 임의 정수
$number.toByteString(1048576);   // '1 MB'

주요 시나리오​

밀리초 값을 기간 정보로 변환​

duration(ms)는 밀리초 값을 연/주/일/시/분/초/밀리초로 분해한 객체로 반환합니다. 경과 시간 표시 UI에 활용할 수 있습니다.

$number.duration(90061000); // { year:0, week:0, day:1, hour:1, minute:1, second:1, millisecond:0 }

값의 범위 검증과 보정​

isRange(num, low, high)로 범위 포함 여부를 확인하고, limit(num, low, high)로 범위를 벗어난 값을 경계값으로 강제 보정합니다.

$number.isRange(120, 0, 100); // false
$number.limit(120, 0, 100);   // 100

백분율과 금액 계산​

percent(num, total, precision)은 백분율을, amount(rate, total, precision)은 비율에 따른 실제 금액(수량)을 계산합니다.

$number.percent(30, 200);     // 15
$number.amount(15, 200);      // 30

여러 값 집계하기​

aggregate(type, columnValues)는 콤마 문자열 또는 배열로 전달된 숫자들을 SUM, MIN, MAX, COUNT, AVG, MEDIAN 중 원하는 방식으로 집계합니다. 그리드 컬럼 합계 등에 활용합니다.

$number.aggregate('SUM', [10, 20, 30]);   // 60
$number.aggregate('AVG', '10,20,30');     // 20

실전 예제 페이지​

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

  • $number.version 속성 조회
  • duration(), toByteString()
  • random(), isRange(), limit()
  • percent(), amount()
  • aggregate() (SUM/AVG/MIN/MAX/COUNT/MEDIAN)

주의 사항​

  • aggregate()는 숫자로 변환할 수 없는 값을 집계 대상에서 제외합니다. COUNT를 제외한 나머지 타입은 유효한 값이 하나도 없으면 0을 반환합니다.
  • percent(), amount()는 total이 0이거나 숫자가 아니면 0을 반환하도록 방어 처리되어 있습니다.
  • toByteString()은 1 미만 값은 단위 변환 없이 B 단위로 표시합니다.
  • random(start, end)는 start/end 순서에 상관없이 두 값 중 작은 값과 큰 값을 각각 최소/최대로 사용합니다.

관련 모듈​

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

API 참조​

모듈 정보​

항목내용
전역 별칭$number (syn.$ 접두사 없음, 전역 변수)
예제 페이지/sample/syn/extension_number.html
의존 모듈$string(toNumber, aggregate 내부에서 사용)

메서드​

$number.duration(ms)​

  • 설명: 밀리초 값을 연/주/일/시/분/초/밀리초로 분해한 객체로 변환합니다.
  • 매개변수
    이름타입필수설명
    msnumberY밀리초 값
  • 반환값: object — { year, week, day, hour, minute, second, millisecond }. 숫자가 아니면 {}
  • 예시 
    const result = $number.duration(100000000);

$number.toByteString(num, precision = 3, addSpace = true)​

  • 설명: 바이트 단위 숫자를 B, KB, MB, ... YB 단위의 사람이 읽기 쉬운 문자열로 변환합니다.
  • 매개변수
    이름타입필수설명
    numnumberY바이트 값
    precisionnumberN유효 자릿수(기본값 3)
    addSpacebooleanN숫자와 단위 사이 공백 삽입 여부(기본값 true)
  • 반환값: string
  • 예시 
    const result = $number.toByteString(100000000); // '95.4 MB'

$number.random(start = 0, end = 10)​

  • 설명: start~end 범위(양 끝 포함)의 임의 정수를 반환합니다. 두 값의 순서는 자동으로 정렬되어 처리됩니다.
  • 매개변수
    이름타입필수설명
    startnumberN범위 시작(기본값 0)
    endnumberN범위 끝(기본값 10)
  • 반환값: number
  • 예시 
    const result = $number.random(1, 10000);

$number.isRange(num, low, high)​

  • 설명: num이 low~high 범위(포함) 안에 있는지 확인합니다.
  • 매개변수
    이름타입필수설명
    numnumberY검사할 값
    lownumberY최소값
    highnumberY최대값
  • 반환값: boolean
  • 예시 
    const result = $number.isRange(50, 30, 80);

$number.limit(num, low, high)​

  • 설명: num이 low~high 범위를 벗어나면 가까운 경계값으로 보정합니다.
  • 매개변수
    이름타입필수설명
    numnumberY보정할 값
    lownumberY최소값
    highnumberY최대값
  • 반환값: number — num이 숫자가 아니면 low 반환
  • 예시 
    const result = $number.limit(120, 30, 80); // 80

$number.percent(num, total, precision = 0)​

  • 설명: total 대비 num의 백분율 값을 계산합니다.
  • 매개변수
    이름타입필수설명
    numnumberY부분 값
    totalnumberY전체 값
    precisionnumberN소수점 자릿수(기본값 0)
  • 반환값: number — total이 0이거나 숫자가 아니면 0
  • 예시 
    const result = $number.percent(30, 200); // 15

$number.amount(rate, total, precision = 0)​

  • 설명: total에 대한 rate(%) 비율만큼의 실제 값을 계산합니다. percent()의 역연산에 해당합니다.
  • 매개변수
    이름타입필수설명
    ratenumberY비율(%)
    totalnumberY전체 값
    precisionnumberN소수점 자릿수(기본값 0)
  • 반환값: number — total이 0이거나 숫자가 아니면 0
  • 예시 
    const result = $number.amount(15, 200); // 30

$number.aggregate(type, columnValues)​

  • 설명: 콤마로 구분된 문자열 또는 배열로 전달된 숫자 값들을 집계합니다. 숫자로 변환할 수 없는 값은 집계에서 제외됩니다.
  • 매개변수
    이름타입필수설명
    typestringY'SUM', 'MIN', 'MAX', 'COUNT', 'AVG', 'MEDIAN' 중 하나(대소문자 무관)
    columnValuesstring | ArrayY집계 대상 값 목록
  • 반환값: number — 유효 값이 없고 type이 'COUNT'가 아니면 0
  • 예시 
    const result = $number.aggregate('AVG', [10, 20, 30, 40]); // 25