Zio.Utils

저장소를 보지 않는 묶음입니다. 받은 글에서 숫자를 찾아 그 옆에 사람이 적은 말과 함께 돌려줍니다. Zio.text 가 “이 글자가 저 글자와 같은 말인가” 를 답한다면, 이쪽은 “이 글에 무슨 숫자가 적혀 있나” 를 답합니다.

무엇으로 쓸지는 정해 주지 않습니다
섹션 제목: “무엇으로 쓸지는 정해 주지 않습니다”

같은 10% 가 어떤 산업에서는 찾던 값이고 어떤 산업에서는 버릴 값입니다. 공사 관리에서 영업 이익 약 10% 는 진척이 아니지만, 회계에서는 바로 그 값입니다.

그래서 이 함수는 고르지 않습니다. 값과 함께 label 을 돌려주고, 무엇인지는 부르는 쪽이 정합니다. 엔진이 골라 주면 산업 하나에는 맞고 나머지에는 반드시 틀립니다.

Method	Description
`Zio.utils.numbers(text, near=None, kinds=None)`	글 속의 숫자를 모두 찾아 목록으로 돌려줍니다. 여러 줄이면 줄 단위로 봅니다 — 라벨이 줄을 넘지 않기 때문입니다.
`Zio.utils.number(text, near=None, kinds=None)`	같은 것의 첫 하나. 없으면 `None` 입니다.

Zio.utils.numbers("진척률 : 약 90%")
# [{"kind": "percent", "value": 90, "label": "진척률", "about": True,
#   "raw": "90%", "line": "진척률 : 약 90%", "bracket": False}]

# 무엇을 진척으로 볼지는 **부르는 쪽이 말을 준다**
Zio.utils.numbers(worklog, near=["진척률", "진행률", "설치율"], kinds="percent")
# 90% ← "진척률"        16.4% ← "현장 설치율"
# (영업 이익 9% · 수신률 83.7% 는 걸러진다)

# 분량만
Zio.utils.numbers(worklog, kinds=["ratio", "count"])
# ratio  0 / 18     done=0  total=18
# count  18개점      value=18  unit="개점"

찾는 갈래는 여덟입니다

kind	예	함께 오는 칸
`percent`	`90%` · `5 % 미만` · `1.5%(±0.5%)`	`value`, `tolerance`, `bracket` — 대괄호 안에 있으면 사람이 일부러 표기한 것이라 근거의 세기가 다릅니다.
`ratio`	`0 / 18` · `522대중 244대` · `3분의 1`	`done`, `total`, `unit`
`count`	`18개점` · `2,823점포` · `522대`	`value`, `unit` — 단위 목록을 두지 않습니다. 붙어 있는 말을 그대로 돌려줍니다.
`money`	`579,000,000원` · `약 1억 2천만원`	`value`, `unit`, `maybe`
`range`	`5~10%` · `15~20%`	`low`, `high`, `unit` — `15~20%` 는 20% 하나가 아닙니다.
`nth`	`2차` · `3회차` · `제1장`	`index`, `unit`
`date`	`2026-08-21` · `8월 7일` · `2026년`	`value` 또는 `year` / `month` / `day`

애매한 것은 고르지 않습니다
섹션 제목: “애매한 것은 고르지 않습니다”

8/7 은 셋으로 읽힙니다 — 8월 7일, 7개 중 8번째, 7분의 8. 어느 하나를 골라 주면 나머지 두 경우에 조용히 틀리고, 그때부터 이 함수는 못 믿는 함수가 됩니다.
Zio.utils.numbers("장비 발주(8/7)")
# [{"kind": "ratio", "done": 8, "total": 7, "label": "장비 발주",
#   "ambiguous": ["ratio", "nth", "date"],
#   "date": {"month": 8, "day": 7},
#   "nth":  {"index": 8, "of": 7}}]

# 헷갈릴 수 없는 것에는 ambiguous 가 없다
Zio.utils.numbers("부착( 0 / 18, 0%)")
# [{"kind": "ratio", "done": 0, "total": 18, ...}]   ← 0월은 없다
읽기를 전부 담아 돌려주니 앞뒤 문맥을 보고 부르는 쪽이 정하십시오. 금액도 같습니다 — 2억 3천 은 200,003,000 이지만 만 이 생략된 말버릇이면 230,000,000 입니다. 앞을 value, 뒤를 maybe 로 함께 줍니다.

label 이 이 묶음의 전부입니다

숫자만 돌려주면 그 값은 어디에나 쓰입니다. 옆에 적힌 말이 있어야 부르는 쪽이 가려낼 수 있습니다. 그래서 라벨을 뽑는 규칙이 이 묶음에서 제일 공들인 곳입니다.

원문	label	규칙
`진척률 : 약 90%`	`진척률`	`:` 는 앞이 라벨입니다. 다른 구분자와 반대입니다.
`( 매출 194,132,600원 / 영업 이익 약 10% )`	`매출` · `영업 이익`	괄호·빗금은 칸을 나눕니다. 자릿점(`194,132,600`)은 나누지 않습니다.
`장비 발주(8/7)`	`장비 발주`	괄호 안이 숫자뿐이면 한 도막 더 앞을 봅니다.
`영업 이익 약 9%`	`영업 이익` + `about`	`약`·`총`·`최대` 는 라벨에서 떼고 뜻만 남깁니다.

넉넉히 찾고, 좁히는 것은 near 로
섹션 제목: “넉넉히 찾고, 좁히는 것은 near 로”

numbers() 는 일단 다 찾습니다. 못 찾은 것은 부르는 쪽에서 손쓸 방법이 없지만, 많이 찾은 것은 near 와 kinds 로 줄이면 됩니다. near 에 넣는 말은 언제나 부르는 쪽이 줍니다 — SDK 안에 진척률 같은 낱말을 넣는 순간 그것은 더 이상 공통 도구가 아닙니다.