Skip to main content

salary_parser_jp/
lib.rs

1//! # salary-parser-jp — 日本語求人の給与テキスト解析
2//!
3//! 求人票の自由記述の給与欄(「月給21万円〜26万円」「時給1,200円以上」など)を
4//! 正規化し、給与種別と円建て金額へ解析するライブラリ。求人媒体の実データで
5//! 鍛えられた置換・判定パターンを、panic 経路のない実装で提供する。
6//!
7//! ## 設計方針
8//!
9//! - **精度優先(fail-closed)**: 確信の持てない入力は推測せずエラーで返す。
10//!   種別語と金額の隣接を要求し、金額のみの場合は桁が明確な帯だけ種別を推定する
11//! - **監査可能**: [`normalize`] を公開しており、どの正準形から金額が読まれたかを
12//!   突き合わせられる。エラーにも正規化後テキストや金額を含める
13//! - **業界非依存**: 介護・看護など、どのバーティカルの取り込みからも使い回せる
14//!
15//! ## 使い方
16//!
17//! ```
18//! use salary_parser_jp::{MonthlyAssumption, SalaryParser, SalaryType};
19//!
20//! let salary = SalaryParser::new().parse("月給21万円〜26万円")?;
21//! assert_eq!(salary.salary_type, SalaryType::Monthly);
22//! assert_eq!(salary.min_yen, 210_000);
23//! assert_eq!(salary.max_yen, Some(260_000));
24//!
25//! // タグ付けやスコアリングへ供給する、下限の月給換算
26//! assert_eq!(salary.monthly_min_yen(&MonthlyAssumption::default()), 210_000);
27//! # Ok::<(), salary_parser_jp::ParseError>(())
28//! ```
29//!
30//! ## 主な項目
31//!
32//! | 項目 | 役割 |
33//! |---|---|
34//! | [`SalaryParser`] | 解析器。唯一の入口([`new`](SalaryParser::new) / [`with_bounds`](SalaryParser::with_bounds)) |
35//! | [`Salary`] | 種別 + 円建ての下限・上限([`FromStr`](std::str::FromStr) 実装) |
36//! | [`Salary::monthly_min_yen`] | 下限の月給換算(種別をまたいだ比較用) |
37//! | [`Salary::monthly_max_yen`] | 上限の月給換算(上限なしなら `None`) |
38//! | [`MonthlyAssumption`] | 時給・日給を月給換算する前提値 |
39//! | [`SalaryType`] | 時給 / 日給 / 月給 / 年収 |
40//! | [`SalaryType::valid_yen_range`] | 種別ごとの妥当範囲(健全性チェックの基準) |
41//! | [`SalaryBounds`] | 種別ごとの妥当範囲(解析器へ渡す設定) |
42//! | [`normalize`] | 正規化のみを行う(監査・突き合わせ用) |
43//! | [`ParseError`] | 解析失敗の理由 |
44//!
45//! ## 対応する表記ゆれ(抜粋)
46//!
47//! ```
48//! use salary_parser_jp::{SalaryParser, SalaryType};
49//!
50//! let parser = SalaryParser::new();
51//! // 全角数字・装飾記号・カンマ区切り
52//! assert_eq!(parser.parse("【月給】210000円")?.min_yen, 210_000);
53//! // 「万」「千」表記と小数
54//! assert_eq!(parser.parse("月給21万5千円")?.min_yen, 215_000);
55//! assert_eq!(parser.parse("月給21.5万円")?.min_yen, 215_000);
56//! // 範囲の右側にだけ付いた単位は左へ分配する
57//! assert_eq!(parser.parse("年収300〜400万円")?.max_yen, Some(4_000_000));
58//! // 「以上」は上限なしの範囲
59//! assert_eq!(parser.parse("時給1,200円以上")?.max_yen, None);
60//! // 賞与などの給与外数値は無視する
61//! assert_eq!(parser.parse("月給20万円(賞与年2回)")?.min_yen, 200_000);
62//! // 種別語がなくても桁が明確なら推定する
63//! assert_eq!(parser.parse("¥250000")?.salary_type, SalaryType::Monthly);
64//! # Ok::<(), salary_parser_jp::ParseError>(())
65//! ```
66//!
67//! ## エラー処理
68//!
69//! 失敗は [`ParseError`] の各変種として返る。いずれも
70//! 「このレコードは解析できなかった」を意味するだけで、取り込み全体を止める
71//! 性質のものではない。呼び出し側でレコード単位に隔離・集計し、種別語辞書や
72//! アダプタの改善材料にすることを想定している。
73//!
74//! ```
75//! use salary_parser_jp::{ParseError, SalaryParser};
76//!
77//! match SalaryParser::new().parse("時給90000円") {
78//!     Ok(salary) => println!("{}: {}円", salary.salary_type, salary.min_yen),
79//!     // 妥当範囲外・種別不明などは診断情報を持つ
80//!     Err(error @ ParseError::OutOfRange { .. }) => println!("要確認: {error}"),
81//!     Err(error) => println!("解析不能: {error}"),
82//! }
83//! ```
84//!
85//! 最低賃金など法令面の検証は本クレートの責務外(`minimum_wage_jp` などを併用)。
86
87mod error;
88mod extract;
89mod normalize;
90
91use std::ops::RangeInclusive;
92
93pub use error::ParseError;
94pub use normalize::normalize;
95
96// 以下の妥当範囲は「日本の求人票に実在しうる金額」を広めに包含する健全性チェック用の
97// 境界。最低賃金のような改定される値には意図的に連動させていない(連動させると毎年の
98// 追随が必要になり、過去アーカイブの解析も弾いてしまうため)。
99
100/// 妥当範囲: 時給の下限(円)。求人がデジタル化された 2000 年代以降、
101/// 日本の最低賃金が 600 円台を下回ったことはないため、その下に余裕を取った値。
102/// 「時給50円」のような誤読を弾きつつ、過去の求人アーカイブは通す。
103const HOURLY_MIN_YEN: u64 = 500;
104/// 妥当範囲: 時給の上限(円)。医師のスポット勤務や専門コンサルなど、
105/// 時給 1 万円超の求人が実在するため高めに取る。
106const HOURLY_MAX_YEN: u64 = 20_000;
107/// 妥当範囲: 日給の下限(円)。半日勤務などの低額日給を通す下限。
108const DAILY_MIN_YEN: u64 = 2_000;
109/// 妥当範囲: 日給の上限(円)。医師の日当が 10 万円規模まで実在する。
110const DAILY_MAX_YEN: u64 = 100_000;
111/// 妥当範囲: 月給の下限(円)。短時間パートの月給表記を通す下限。
112/// 桁からの種別推定が月給とみなす境界(60,000 円)と揃えてある。
113const MONTHLY_MIN_YEN: u64 = 60_000;
114/// 妥当範囲: 月給の上限(円)。役員・エグゼクティブ求人の月給表記に対応する。
115const MONTHLY_MAX_YEN: u64 = 2_000_000;
116/// 妥当範囲: 年収の下限(円)。パート等の低い年収表記を通す下限。
117const YEARLY_MIN_YEN: u64 = 1_000_000;
118/// 妥当範囲: 年収の上限(円)。年収 1,000 万円超のハイクラス求人は
119/// 独立した市場を形成しており、ここを狭めると当該層を丸ごと取りこぼす。
120const YEARLY_MAX_YEN: u64 = 50_000_000;
121
122/// 月給換算の既定値: 月間労働時間(週 40 時間 × 4 週)。
123///
124/// [`DEFAULT_DAYS_PER_MONTH`] と週数を揃えてあり、両者の比は 1 日 8 時間に
125/// なる。時給表記と日給表記の求人が同じ賃金水準なら同じ月給換算値になる。
126pub const DEFAULT_HOURS_PER_MONTH: u64 = 160;
127/// 月給換算の既定値: 月間労働日数(週 5 日 × 4 週)。
128///
129/// [`DEFAULT_HOURS_PER_MONTH`] と同じ 4 週を前提にしている。ここを崩すと
130/// 種別違いの求人が同一賃金でも異なる換算値になり、閾値タグが歪む。
131pub const DEFAULT_DAYS_PER_MONTH: u64 = 20;
132/// 年収 → 月給換算の除数。
133const MONTHS_PER_YEAR: u64 = 12;
134
135/// 給与種別。
136///
137/// [`Display`](std::fmt::Display) は日本語表記(「月給」など)を返すため、
138/// ログや管理画面へそのまま出せる。`serde` feature を有効にすると `snake_case`
139/// (`"hourly"` / `"daily"` / `"monthly"` / `"yearly"`)で直列化される。
140///
141/// ```
142/// use salary_parser_jp::SalaryType;
143///
144/// assert_eq!(SalaryType::Monthly.to_string(), "月給");
145/// ```
146#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
147#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
148#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
149pub enum SalaryType {
150    /// 時給。
151    Hourly,
152    /// 日給。
153    Daily,
154    /// 月給。
155    Monthly,
156    /// 年収。
157    Yearly,
158}
159
160impl std::fmt::Display for SalaryType {
161    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
162        let label = match self {
163            Self::Hourly => "時給",
164            Self::Daily => "日給",
165            Self::Monthly => "月給",
166            Self::Yearly => "年収",
167        };
168        write!(f, "{label}")
169    }
170}
171
172/// 解析済みの給与。金額はすべて円建て。
173///
174/// 上限が明示されなかった場合([`max_yen`](Self::max_yen) が `None`)と、
175/// 下限と上限が同額の場合は区別される。JSON/JSONL 連携が必要なら `serde`
176/// feature を有効にすること(既定では無効)。
177///
178/// ```
179/// use salary_parser_jp::{SalaryParser, SalaryType};
180///
181/// let parser = SalaryParser::new();
182/// // 上限あり
183/// let range = parser.parse("月給21万円〜26万円")?;
184/// assert_eq!((range.min_yen, range.max_yen), (210_000, Some(260_000)));
185///
186/// // 「以上」は上限なし
187/// let open = parser.parse("月給21万円以上")?;
188/// assert_eq!((open.min_yen, open.max_yen), (210_000, None));
189/// # Ok::<(), salary_parser_jp::ParseError>(())
190/// ```
191#[derive(Debug, Clone, PartialEq, Eq)]
192#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
193pub struct Salary {
194    /// 給与種別。
195    pub salary_type: SalaryType,
196    /// 下限金額(円)。単一金額の場合もここに入る。
197    pub min_yen: u64,
198    /// 上限金額(円)。「〜」等で上限が明示された場合のみ。
199    pub max_yen: Option<u64>,
200}
201
202impl Salary {
203    /// 下限金額を月給換算した円額を返す。
204    ///
205    /// 給与レンジでの絞り込みや、閾値による判定(高給与タグなど)へ供給する値の
206    /// 算出を想定している。時給・日給の換算は
207    /// `assumption` の前提値に依存するため、推測を避けたい場合は呼び出し側で
208    /// 実際の労働時間から前提を組み立てること。
209    ///
210    /// ```
211    /// use salary_parser_jp::{MonthlyAssumption, SalaryParser};
212    ///
213    /// let hourly = SalaryParser::new().parse("時給1,200円以上")?;
214    /// assert_eq!(hourly.monthly_min_yen(&MonthlyAssumption::default()), 192_000);
215    /// # Ok::<(), salary_parser_jp::ParseError>(())
216    /// ```
217    #[must_use]
218    pub fn monthly_min_yen(&self, assumption: &MonthlyAssumption) -> u64 {
219        self.to_monthly(self.min_yen, assumption)
220    }
221
222    /// 上限金額を月給換算した円額を返す。上限がなければ `None`。
223    ///
224    /// [`monthly_min_yen`](Self::monthly_min_yen) と対になる。給与レンジの上限で
225    /// 絞り込む検索や、レンジ全体を月給軸へ揃えたい場合に使う。
226    ///
227    /// ```
228    /// use salary_parser_jp::{MonthlyAssumption, SalaryParser};
229    ///
230    /// let parser = SalaryParser::new();
231    /// let assumption = MonthlyAssumption::default();
232    /// let range = parser.parse("時給1200円~1500円")?;
233    /// assert_eq!(range.monthly_max_yen(&assumption), Some(240_000));
234    ///
235    /// // 「以上」など上限のない求人では None
236    /// let open = parser.parse("時給1,200円以上")?;
237    /// assert_eq!(open.monthly_max_yen(&assumption), None);
238    /// # Ok::<(), salary_parser_jp::ParseError>(())
239    /// ```
240    #[must_use]
241    pub fn monthly_max_yen(&self, assumption: &MonthlyAssumption) -> Option<u64> {
242        self.max_yen.map(|yen| self.to_monthly(yen, assumption))
243    }
244
245    /// 金額 1 つを、この給与種別に応じて月給換算する。
246    fn to_monthly(&self, yen: u64, assumption: &MonthlyAssumption) -> u64 {
247        match self.salary_type {
248            SalaryType::Monthly => yen,
249            SalaryType::Yearly => yen / MONTHS_PER_YEAR,
250            SalaryType::Hourly => yen.saturating_mul(assumption.hours_per_month),
251            SalaryType::Daily => yen.saturating_mul(assumption.days_per_month),
252        }
253    }
254}
255
256impl std::str::FromStr for Salary {
257    type Err = ParseError;
258
259    /// 既定設定の [`SalaryParser`] と同じ解析を行う。`str::parse()` 用の実装。
260    ///
261    /// これがあることで、serde の `deserialize_with` や clap の `value_parser`、
262    /// `Iterator::map(str::parse)` など、`FromStr` を前提に書かれた既存のコードへ
263    /// そのまま差し込める。
264    ///
265    /// # Errors
266    ///
267    /// [`SalaryParser::parse`] と同じ条件で [`ParseError`] を返す。
268    ///
269    /// ```
270    /// use salary_parser_jp::{Salary, SalaryType};
271    ///
272    /// let salary: Salary = "月給21万円〜26万円".parse()?;
273    /// assert_eq!(salary.salary_type, SalaryType::Monthly);
274    ///
275    /// // 失敗もそのまま Result として扱える
276    /// let amounts: Result<Vec<Salary>, _> =
277    ///     ["時給1200円", "日給12000円"].iter().map(|s| s.parse()).collect();
278    /// assert_eq!(amounts?.len(), 2);
279    /// # Ok::<(), salary_parser_jp::ParseError>(())
280    /// ```
281    fn from_str(text: &str) -> Result<Self, Self::Err> {
282        SalaryParser::new().parse(text)
283    }
284}
285
286/// 時給・日給を月給換算するときの前提値。
287///
288/// 換算は近似であるため、前提を明示的に受け取る設計にしている。既定値は
289/// 160 時間([`DEFAULT_HOURS_PER_MONTH`])と 20 日([`DEFAULT_DAYS_PER_MONTH`])で、
290/// どちらも週 4 週前提(= 1 日 8 時間)で整合している。差し替える場合も
291/// 両者の比を崩さないこと。崩すと時給表記と日給表記の求人が同一賃金でも
292/// 異なる換算値になる。実際の所定労働時間が分かっているならその値を渡す。
293///
294/// ```
295/// use salary_parser_jp::{MonthlyAssumption, SalaryParser};
296///
297/// let hourly = SalaryParser::new().parse("時給1200円")?;
298/// // 既定前提(月 160 時間)
299/// assert_eq!(hourly.monthly_min_yen(&MonthlyAssumption::default()), 192_000);
300///
301/// // 週 30 時間契約など、求人ごとの実態に合わせて差し替える
302/// let part_time = MonthlyAssumption {
303///     hours_per_month: 120,
304///     ..MonthlyAssumption::default()
305/// };
306/// assert_eq!(hourly.monthly_min_yen(&part_time), 144_000);
307/// # Ok::<(), salary_parser_jp::ParseError>(())
308/// ```
309#[derive(Debug, Clone, PartialEq, Eq)]
310#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
311pub struct MonthlyAssumption {
312    /// 月間労働時間(時給 × この値 = 月給換算)。
313    pub hours_per_month: u64,
314    /// 月間労働日数(日給 × この値 = 月給換算)。
315    pub days_per_month: u64,
316}
317
318impl Default for MonthlyAssumption {
319    fn default() -> Self {
320        Self {
321            hours_per_month: DEFAULT_HOURS_PER_MONTH,
322            days_per_month: DEFAULT_DAYS_PER_MONTH,
323        }
324    }
325}
326
327/// 妥当範囲の検証に使う、種別ごとの許容金額(円)。
328///
329/// 既定値は [`SalaryType::valid_yen_range`] と同じで、[`SalaryParser::new`] はこれを使う。
330/// 取り扱う求人の分布が既定の想定と違う場合(エグゼクティブサーチ、役員報酬、
331/// 逆に自社求人だけを厳しく締めたい場合など)は、この構造体を組み立てて
332/// [`SalaryParser::with_bounds`] へ渡す。
333///
334/// [`MonthlyAssumption`] と同じく「前提は利用側が明示的に渡す」設計。
335///
336/// ```
337/// use salary_parser_jp::{SalaryBounds, SalaryParser, SalaryType};
338///
339/// // 既定では年収 5,000 万円が上限なので弾かれる
340/// assert!(SalaryParser::new().parse("年収8000万円").is_err());
341///
342/// // 上限を広げれば通る
343/// let parser = SalaryParser::with_bounds(SalaryBounds {
344///     yearly: 1_000_000..=200_000_000,
345///     ..SalaryBounds::default()
346/// })?;
347/// let salary = parser.parse("年収8000万円")?;
348/// assert_eq!(salary.salary_type, SalaryType::Yearly);
349/// assert_eq!(salary.min_yen, 80_000_000);
350/// # Ok::<(), salary_parser_jp::ParseError>(())
351/// ```
352#[derive(Debug, Clone, PartialEq, Eq)]
353#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
354pub struct SalaryBounds {
355    /// 時給として許容する金額(円)。
356    pub hourly: RangeInclusive<u64>,
357    /// 日給として許容する金額(円)。
358    pub daily: RangeInclusive<u64>,
359    /// 月給として許容する金額(円)。
360    pub monthly: RangeInclusive<u64>,
361    /// 年収として許容する金額(円)。
362    pub yearly: RangeInclusive<u64>,
363}
364
365impl SalaryBounds {
366    /// 指定した給与種別に対応する範囲を返す。
367    #[must_use]
368    pub fn range(&self, salary_type: SalaryType) -> &RangeInclusive<u64> {
369        match salary_type {
370            SalaryType::Hourly => &self.hourly,
371            SalaryType::Daily => &self.daily,
372            SalaryType::Monthly => &self.monthly,
373            SalaryType::Yearly => &self.yearly,
374        }
375    }
376
377    /// 4 種別すべての範囲が逆転していないことを検証する。
378    ///
379    /// フィールドが公開されているため逆転した範囲を組み立てられてしまう。
380    /// 逆転した範囲は何も含まず全レコードが [`ParseError::OutOfRange`] になるので、
381    /// 設定ミスとして明示的に弾く。
382    ///
383    /// # Errors
384    ///
385    /// いずれかの種別で下限 > 上限なら [`ParseError::InvalidBounds`]。
386    ///
387    /// ```
388    /// use salary_parser_jp::{ParseError, SalaryBounds, SalaryType};
389    ///
390    /// let inverted = SalaryBounds {
391    ///     monthly: 500_000..=150_000,
392    ///     ..SalaryBounds::default()
393    /// };
394    /// assert_eq!(
395    ///     inverted.validate(),
396    ///     Err(ParseError::InvalidBounds {
397    ///         salary_type: SalaryType::Monthly,
398    ///         min: 500_000,
399    ///         max: 150_000,
400    ///     })
401    /// );
402    /// assert!(SalaryBounds::default().validate().is_ok());
403    /// ```
404    pub fn validate(&self) -> Result<(), ParseError> {
405        for salary_type in [
406            SalaryType::Hourly,
407            SalaryType::Daily,
408            SalaryType::Monthly,
409            SalaryType::Yearly,
410        ] {
411            let range = self.range(salary_type);
412            if range.start() > range.end() {
413                return Err(ParseError::InvalidBounds {
414                    salary_type,
415                    min: *range.start(),
416                    max: *range.end(),
417                });
418            }
419        }
420        Ok(())
421    }
422}
423
424impl Default for SalaryBounds {
425    fn default() -> Self {
426        Self {
427            hourly: SalaryType::Hourly.valid_yen_range(),
428            daily: SalaryType::Daily.valid_yen_range(),
429            monthly: SalaryType::Monthly.valid_yen_range(),
430            yearly: SalaryType::Yearly.valid_yen_range(),
431        }
432    }
433}
434
435impl SalaryType {
436    /// この給与種別の妥当範囲(円)を返す。
437    ///
438    /// 解析結果の健全性チェックに使う範囲。桁ずれや種別の取り違えといった明らかな
439    /// 誤読を弾くことだけが目的で、[`SalaryParser::new`] はこの範囲を外れた金額を
440    /// [`ParseError::OutOfRange`] で拒否する。
441    ///
442    /// これは既定値であって唯一の基準ではない。[`SalaryParser::with_bounds`] に
443    /// 別の [`SalaryBounds`] を渡した場合、判定にはそちらが使われる。
444    ///
445    /// | 種別 | 下限(円) | 上限(円) |
446    /// |---|---:|---:|
447    /// | [`Hourly`](SalaryType::Hourly) | 500 | 20,000 |
448    /// | [`Daily`](SalaryType::Daily) | 2,000 | 100,000 |
449    /// | [`Monthly`](SalaryType::Monthly) | 60,000 | 2,000,000 |
450    /// | [`Yearly`](SalaryType::Yearly) | 1,000,000 | 50,000,000 |
451    ///
452    /// # 法令上の下限ではない
453    ///
454    /// **最低賃金の遵守判定には使えない。** 目的が違ううえ、最低賃金は毎年改定され
455    /// 都道府県ごとに異なる(2025 年度は全国加重平均 1,121 円、最低額 1,023 円)。
456    /// 法令面の検証は `minimum_wage_jp` などを併用すること。
457    ///
458    /// 上の範囲は改定される値に連動させていない。連動させると毎年の追随が必要になり、
459    /// 過去の求人アーカイブも解析できなくなるため、「日本の求人票に実在しうる金額」を
460    /// 広めに包含する固定値にしてある。医師のスポット勤務(時給 1 万円超)や
461    /// 年収 1,000 万円超のハイクラス求人も通る。
462    ///
463    /// ```
464    /// use salary_parser_jp::SalaryType;
465    ///
466    /// let hourly = SalaryType::Hourly.valid_yen_range();
467    /// assert_eq!((*hourly.start(), *hourly.end()), (500, 20_000));
468    /// assert!(hourly.contains(&1_200));
469    /// // 桁ずれ(時給に月給の額)は弾く
470    /// assert!(!hourly.contains(&210_000));
471    /// ```
472    #[must_use]
473    pub fn valid_yen_range(self) -> RangeInclusive<u64> {
474        match self {
475            Self::Hourly => HOURLY_MIN_YEN..=HOURLY_MAX_YEN,
476            Self::Daily => DAILY_MIN_YEN..=DAILY_MAX_YEN,
477            Self::Monthly => MONTHLY_MIN_YEN..=MONTHLY_MAX_YEN,
478            Self::Yearly => YEARLY_MIN_YEN..=YEARLY_MAX_YEN,
479        }
480    }
481}
482
483/// 給与テキストの解析器。このクレートの唯一の入口。
484///
485/// 既定の妥当範囲でよければ [`new`](Self::new)、取り扱う求人の分布が既定の想定と
486/// 違う場合([`SalaryBounds`] に用途と例)は [`with_bounds`](Self::with_bounds) で作る。
487///
488/// # 設定の検証は構築時に 1 度だけ
489///
490/// 逆転した範囲などの設定ミスは [`with_bounds`](Self::with_bounds) が返す。
491/// 解析のたびに検証しないので、一括取り込みの最内ループで無駄が出ず、
492/// 設定ミスも「全レコードのエラー」ではなく「構築の失敗」として即座に現れる。
493///
494/// ```
495/// use salary_parser_jp::{SalaryBounds, SalaryParser};
496///
497/// // エグゼクティブ向けに年収の上限を広げる
498/// let parser = SalaryParser::with_bounds(SalaryBounds {
499///     yearly: 1_000_000..=500_000_000,
500///     ..SalaryBounds::default()
501/// })?;
502///
503/// // 設定は使い回す。ここでは検証が走らない
504/// assert_eq!(parser.parse("年収1億2000万円")?.min_yen, 120_000_000);
505/// assert_eq!(parser.parse("年収8000万円")?.min_yen, 80_000_000);
506/// # Ok::<(), salary_parser_jp::ParseError>(())
507/// ```
508#[derive(Debug, Clone, PartialEq, Eq, Default)]
509pub struct SalaryParser {
510    bounds: SalaryBounds,
511}
512
513impl SalaryParser {
514    /// 既定の妥当範囲([`SalaryBounds::default`])で解析器を作る。
515    ///
516    /// 既定値は常に妥当なので失敗しない。
517    ///
518    /// ```
519    /// use salary_parser_jp::{SalaryParser, SalaryType};
520    ///
521    /// let parser = SalaryParser::new();
522    /// let salary = parser.parse("月給21万円")?;
523    /// assert_eq!(salary.salary_type, SalaryType::Monthly);
524    /// assert_eq!(salary.min_yen, 210_000);
525    /// # Ok::<(), salary_parser_jp::ParseError>(())
526    /// ```
527    #[must_use]
528    pub fn new() -> Self {
529        Self::default()
530    }
531
532    /// 妥当範囲を指定して解析器を作る。
533    ///
534    /// # Errors
535    ///
536    /// `bounds` の指定が逆転していれば [`ParseError::InvalidBounds`]
537    /// ([`SalaryBounds::validate`] と同じ判定)。
538    pub fn with_bounds(bounds: SalaryBounds) -> Result<Self, ParseError> {
539        bounds.validate()?;
540        Ok(Self { bounds })
541    }
542
543    /// この解析器が使う妥当範囲を返す。
544    #[must_use]
545    pub fn bounds(&self) -> &SalaryBounds {
546        &self.bounds
547    }
548
549    /// 給与テキストを解析し、給与種別と円建て金額を返す。
550    ///
551    /// [`normalize`] による正規化の後、種別語(月給・時給など)と金額の隣接
552    /// ペアを優先度順に探す。同じ種別語が複数回現れる場合や、種別語グループを
553    /// またいで候補が複数ある場合は、グループの優先順(月給 → 年収 → 曖昧語 →
554    /// 日給 → 時給)で最初に妥当範囲を満たしたものを採用する。
555    ///
556    /// # あいまいな金額は拾わない
557    ///
558    /// 種別語がまったく無いテキストでは、文頭の金額を桁から推定する。ただしこれは
559    /// 「その数値がそもそも給与か」を確かめない推測なので、支度金・祝い金・交通費・
560    /// 退職金・賞与・手当など**給与以外の金額を指す語が同居していれば推測を放棄**し、
561    /// [`ParseError::UnknownType`] を返す。曖昧な金額帯(5,001〜59,999 円など)も
562    /// 推定しない(精度優先)。
563    ///
564    /// ```
565    /// use salary_parser_jp::{SalaryParser, SalaryType};
566    ///
567    /// let parser = SalaryParser::new();
568    /// // 種別語がなく、金額が給与とは限らない → 拾わない
569    /// assert!(parser.parse("100,000円 支度金").is_err());
570    /// // 種別語があれば申告を信頼する
571    /// assert_eq!(parser.parse("月給21万円 交通費全額支給")?.min_yen, 210_000);
572    /// assert_eq!(parser.parse("230000円")?.salary_type, SalaryType::Monthly);
573    /// # Ok::<(), salary_parser_jp::ParseError>(())
574    /// ```
575    ///
576    /// # 範囲が影響するもの
577    ///
578    /// 範囲はエラーになるか否かだけでなく、**テキスト中のどの金額が採用されるかも
579    /// 変える**。候補は妥当範囲を満たした時点で確定するため、範囲を狭めると先頭付近の
580    /// 候補が退けられ、後ろの候補が採用されうる。たとえば `"月給12万円 月給25万円"` は
581    /// 既定では 120,000 を返すが、月給の下限を 200,000 に上げると 250,000 を返す。
582    ///
583    /// 一方で、種別語がない場合の**桁からの種別推定は変わらない**。推定は
584    /// 「種別語なしでも確信できる帯」という別の基準で動いており、範囲を広げても
585    /// 推定されない金額は [`ParseError::UnknownType`] のままになる。
586    ///
587    // 下のリンクの `[]` は必須。`[X]: 説明` は Markdown のリンク参照定義と解釈される
588    /// # Errors
589    ///
590    /// - [`ParseError::NoAmount`][]: 金額表現がない(例: 「応相談」)
591    /// - [`ParseError::UnknownType`][]: 金額はあるが種別を特定できない
592    /// - [`ParseError::AmountTooLarge`][]: 数値が大きすぎる破損データ
593    /// - [`ParseError::OutOfRange`][]: この解析器の妥当範囲外(例: 時給 90,000 円)
594    /// - [`ParseError::InvertedRange`][]: 下限より上限が小さい
595    ///
596    /// 設定の妥当性は構築時に検証済みなので [`ParseError::InvalidBounds`][] は返らない。
597    ///
598    /// ```
599    /// use salary_parser_jp::{ParseError, SalaryBounds, SalaryParser};
600    ///
601    /// let parser = SalaryParser::new();
602    /// assert_eq!(parser.parse("日給12,000円")?.min_yen, 12_000);
603    /// assert_eq!(parser.parse("応相談"), Err(ParseError::NoAmount));
604    ///
605    /// // 自社求人は月給 15〜50 万円に収まると分かっているなら、より厳しく締められる
606    /// let strict = SalaryParser::with_bounds(SalaryBounds {
607    ///     monthly: 150_000..=500_000,
608    ///     ..SalaryBounds::default()
609    /// })?;
610    /// assert!(strict.parse("月給12万円").is_err());
611    /// // 既定の範囲(6 万円〜)なら通る
612    /// assert!(parser.parse("月給12万円").is_ok());
613    /// # Ok::<(), salary_parser_jp::ParseError>(())
614    /// ```
615    pub fn parse(&self, text: &str) -> Result<Salary, ParseError> {
616        extract::extract(&normalize(text), &self.bounds)
617    }
618}