> ## Documentation Index
> Fetch the complete documentation index at: https://hangulpy.uiharu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# v1.5.0 릴리즈 노트

> 검색 정확도와 확장성 개선, 발음 사전 지원, Python 3.11 전환

## 호환성 변경

Python 3.11 이상이 필요합니다. v1.4에서 폐기를 예고한 `chosungIncludes`,
`notallowempty`, `allowDoubleConsonant`를 제거했습니다. 대체 이름과 옵션의
타입 변경은 [마이그레이션 가이드](/migration-v1-5)를 확인하세요.

## 검색 구간과 치환 정확도

호환 자모를 조합하는 과정에서 원문 위치를 함께 추적합니다. 이전에 뒤 음절의
초성까지 포함하던 `ㄱㅗㅏㄴㅏ`의 `과` 검색은 이제 원문의 `[0, 3)`을 반환합니다.

```python theme={null}
from hangulpy import find_hangul_spans, hangul_replace

matches = find_hangul_spans("ㄱㅗㅏㄴㅏ", "과")
[match.span() for match in matches]  # [(0, 3)]
hangul_replace("ㄱㅗㅏㄴㅏ", "과", "X")  # Xㄴㅏ
```

`overlap=False`는 원문에서 겹치는 구간을 제외합니다. NFC·NFD·호환 자모가
섞여 있어도 같은 원칙을 적용하며, Unicode 결합 문자의 정렬이 바뀌는 묶음은
하나의 원문 구간으로 보존합니다. 제한된 개수의 치환·분할은 필요한 매치까지만
읽습니다.

## 검색과 자모 처리 성능

* 접두 문자열을 반복 정규화하던 검색 위치 계산을 조합 구간 추적으로 바꿨습니다.
* 참/거짓 검색은 원문 위치 배열을 만들지 않습니다. 전역 검색 캐시는 256자 이하
  문자열을 최대 256개 보관하며 긴 입력은 캐시에 저장하지 않습니다.
* `HangulIndex`는 정규화한 검색 데이터를 직접 보관합니다. 데이터가 전역 캐시의
  크기를 넘더라도 매 검색마다 전체 문자열을 다시 분해하지 않습니다.
* 인덱스의 정확한 부분 문자열 검색과 `min_score=1`은 불필요한 편집 거리 계산을
  생략합니다. `limit`이 있으면 전체 정렬 대신 필요한 상위 결과만 선택합니다.
* 자모 분해는 실제로 사용한 현대 한글 음절의 변환을 재사용합니다. 이 테이블은
  현대 한글 음절 11,172개와 겹자모 18개를 넘지 않습니다.

## 발음과 표기

`꽃잎`, `솜이불`, `색연필` 등 지원 어휘의 ㄴ 첨가 규칙을 발음 변환과
로마자 표기에서 공유합니다. `금요일`의 로마자 표기에 불필요하게 들어가던
`n`을 제거했습니다. 임의의 형태소 경계를 모두 분석하는 기능은 아닙니다.

`standardize_pronunciation`에 호출별 `lexicon` 옵션을 추가했습니다. 정규화한
연속 한글 구간과 정확히 일치하는 항목의 최종 발음을 지정할 수 있습니다.
`explain=False`에서는 단계별 설명 문자열을 생성하지 않습니다.

```python theme={null}
from hangulpy import standardize_pronunciation

standardize_pronunciation("꽃잎")  # 꼰닙
standardize_pronunciation("솜이불")  # 솜니불
standardize_pronunciation("꽃잎", lexicon={"꽃잎": "꼰닙"}, explain=True)
```

## 단어 결합과 큰 수

`jarip_noun`의 진열·분열·기념·사례·요령 결과를 수정했습니다. 이 함수의
범위는 지원하는 접미 한자음의 결합 규칙이며 의미를 추론하는 사전은 아닙니다.

`hangul_to_number("일구")`는 이제 `10**32`를 복원합니다. `십구`는 기본적으로
19이며 큰 단위 구를 의도하면 `large_unit_gu=True`를 지정하세요.
숫자 9와 큰 단위 구의 표기가 같아 모든 입력을 자동으로 구분할 수는 없습니다.
[큰 수의 중의성](/api/conversions/hangul-to-number)에 자세히 설명했습니다.

## 재현 가능한 비교 벤치마크

비교 브랜치의 Python·JavaScript 벤치마크를 통합했습니다. 측정 구간 밖에서
전체 출력의 SHA-256을 비교하고, 출력이나 처리 단위가 다른 항목은 순위에서
제외합니다. 원시 측정값과 실행 환경을 결과에 함께 기록합니다.

`python -m benchmarks.scaling`은 문자열 길이·Unicode 표현·반복 입력·검색 실패·
인덱스 크기와 점수 기준을 바꾸어 측정합니다. 속도는 입력과 실행 환경에 따라
달라지며, 다른 라이브러리와 출력이 같다는 사실만으로 언어학적 정확도를
보장하지는 않습니다. 실행 방법은 저장소의 `benchmarks/README.md`를
확인하세요.