rlibphonenumber/phonenumberutil/enums.rs
1// Copyright (C) 2009 The Libphonenumber Authors
2// Copyright (C) 2025 Kashin Vladislav (Rust adaptation author)
3//
4// Licensed under the Apache License, Version 2.0 (the "License");
5// you may not use this file except in compliance with the License.
6// You may obtain a copy of the License at
7//
8// http://www.apache.org/licenses/LICENSE-2.0
9//
10// Unless required by applicable law or agreed to in writing, software
11// distributed under the License is distributed on an "AS IS" BASIS,
12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13// See the License for the specific language governing permissions and
14// limitations under the License.
15
16use rlibphonenumbers_macro::countries_enum;
17use strum::EnumIter;
18
19/// Defines the various standardized formats for representing phone numbers.
20///
21/// `INTERNATIONAL` and `NATIONAL` formats align with the ITU-T E.123 recommendation,
22/// but use local conventions like hyphens (-) instead of spaces for separators.
23///
24/// For example, the Google Switzerland office number would be:
25/// - **INTERNATIONAL**: `+41 44 668 1800`
26/// - **NATIONAL**: `044 668 1800`
27/// - **E164**: `+41446681800` (international format without formatting)
28/// - **RFC3966**: `tel:+41-44-668-1800` (hyphen-separated with a "tel:" prefix)
29#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
30pub enum PhoneNumberFormat {
31 /// **E.164 format.**
32 /// This is a standardized international format with no spaces or symbols,
33 /// always starting with a `+` followed by the country code.
34 /// Example: `+41446681800`.
35 E164,
36 /// **International format.**
37 /// This format includes the country code and is formatted with spaces
38 /// for readability, as recommended for international display.
39 /// Example: `+41 44 668 1800`.
40 International,
41 /// **National format.**
42 /// This format is used for dialing within the number's own country.
43 /// It may include a national prefix (like '0') and uses local formatting conventions.
44 /// Example: `044 668 1800`.
45 National,
46 /// **RFC3966 format.**
47 /// A technical format used in contexts like web links. It starts with "tel:",
48 /// uses hyphens as separators, and can include extensions.
49 /// Example: `tel:+41-44-668-1800`.
50 RFC3966,
51}
52
53/// Categorizes phone numbers based on their primary use.
54#[derive(Debug, EnumIter, Clone, Copy, PartialEq, Eq, Hash)]
55pub enum PhoneNumberType {
56 /// **Fixed-line numbers.**
57 /// These are traditional landline telephone numbers tied to a specific geographic location.
58 FixedLine,
59 /// **Mobile numbers.**
60 /// These numbers are assigned to wireless devices like mobile phones.
61 Mobile,
62 /// **Fixed-line or mobile.**
63 /// Used in regions (e.g., the USA) where it's impossible to distinguish between
64 /// fixed-line and mobile numbers by looking at the phone number itself.
65 FixedLineOrMobile,
66 /// **Toll-free numbers.**
67 /// Calls to these numbers are free for the caller, with the cost being paid by the recipient.
68 /// Examples include "800" or "888" numbers in the US.
69 TollFree,
70 /// **Premium-rate numbers.**
71 /// These numbers charge a higher rate than normal calls, often used for services
72 /// like horoscopes, adult chat lines, or tech support.
73 PremiumRate,
74 /// **Shared-cost numbers.**
75 /// The cost of the call is split between the caller and the recipient. These calls
76 /// are typically cheaper than premium-rate numbers.
77 SharedCost,
78 /// **Voice over IP (VoIP) numbers.**
79 /// These numbers are used for services that transmit voice calls over the internet.
80 VoIP,
81 /// **Personal numbers.**
82 /// A number associated with a person, not a location or device. It can be routed
83 /// to different destinations (mobile or fixed-line) as configured by the user.
84 PersonalNumber,
85 /// **Pagers.**
86 /// Numbers used for sending messages to paging devices.
87 Pager,
88 /// **Universal Access Numbers (UAN).**
89 /// A single number that a company can use to route calls to different offices or departments.
90 UAN,
91 /// **Voicemail access numbers.**
92 /// Numbers used to directly access a voicemail service.
93 VoiceMail,
94 /// **Unknown type.**
95 /// The number does not match any of the known patterns for its region and its type
96 /// cannot be determined.
97 Unknown,
98}
99
100/// Describes the degree of similarity between two phone numbers.
101#[derive(Debug, Clone, Copy, PartialEq, Hash)]
102pub enum MatchType {
103 /// **No match.**
104 /// The two numbers are entirely different.
105 NoMatch,
106 /// **Short National Significant Number match.**
107 /// One number is a shorter version of the other's National Significant Number (NSN).
108 /// For example, `6502530000` is a short match for `16502530000`.
109 ShortNsnMatch,
110 /// **National Significant Number (NSN) match.**
111 /// The numbers share the same NSN but may have different country codes or formatting.
112 /// For example, `0446681800` (national) and `+41446681800` (international) are an NSN match.
113 NsnMatch,
114 /// **Exact match.**
115 /// The two numbers are identical in every aspect, including country code, NSN, and
116 /// any specified extensions.
117 ExactMatch,
118}
119
120// Separated enum ValidationResult into ValidationResult err and
121// ValidationResultOk for using Result<Ok, Err>
122
123/// Represents the possible outcomes when checking if a phone number's length is valid.
124#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
125pub enum NumberLengthType {
126 /// **The length is valid for a dialable number.**
127 /// The number's length matches the expected length for a complete, dialable
128 /// number in its region.
129 IsPossible,
130 /// **The length is valid for a local-only number.**
131 /// The number's length is too short for a full national number but matches a pattern
132 /// for a number that can be dialed within a specific local area (e.g., without the area code).
133 IsPossibleLocalOnly,
134}
135
136countries_enum!(Region);