1use core::fmt;
9use core::hash::Hash;
10
11pub trait Enumeration: Clone + Copy + PartialEq + Eq + Hash + fmt::Debug {
13 const IS_NULL_VALUE: bool = false;
22
23 fn from_i32(value: i32) -> Option<Self>;
27
28 fn to_i32(&self) -> i32;
30
31 fn proto_name(&self) -> &'static str;
33
34 fn from_proto_name(_name: &str) -> Option<Self> {
40 None
41 }
42
43 fn values() -> &'static [Self] {
60 &[]
61 }
62}
63
64#[derive(Clone, Copy, PartialEq, Eq, Hash)]
105pub enum EnumValue<E: Enumeration> {
106 Known(E),
108 Unknown(i32),
110}
111
112impl<E: Enumeration> EnumValue<E> {
113 #[inline]
115 pub fn to_i32(&self) -> i32 {
116 match self {
117 Self::Known(e) => e.to_i32(),
118 Self::Unknown(v) => *v,
119 }
120 }
121
122 #[inline]
127 pub fn is_known(&self) -> bool {
128 matches!(self, Self::Known(_))
129 }
130
131 #[inline]
133 pub fn is_unknown(&self) -> bool {
134 matches!(self, Self::Unknown(_))
135 }
136
137 #[inline]
139 pub fn as_known(&self) -> Option<E> {
140 match self {
141 Self::Known(e) => Some(*e),
142 Self::Unknown(_) => None,
143 }
144 }
145}
146
147impl<E: Enumeration> From<i32> for EnumValue<E> {
148 fn from(value: i32) -> Self {
149 match E::from_i32(value) {
150 Some(e) => Self::Known(e),
151 None => Self::Unknown(value),
152 }
153 }
154}
155
156impl<E: Enumeration> From<E> for EnumValue<E> {
157 fn from(value: E) -> Self {
158 Self::Known(value)
159 }
160}
161
162impl<E: Enumeration> PartialEq<E> for EnumValue<E> {
173 fn eq(&self, other: &E) -> bool {
174 match self {
175 Self::Known(e) => e == other,
176 Self::Unknown(_) => false,
177 }
178 }
179}
180
181impl<E: Enumeration> fmt::Debug for EnumValue<E> {
182 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
183 match self {
184 Self::Known(e) => write!(f, "{:?}", e),
185 Self::Unknown(v) => write!(f, "Unknown({v})"),
186 }
187 }
188}
189
190impl<E: Enumeration> fmt::Display for EnumValue<E> {
191 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
192 match self {
193 Self::Known(e) => f.write_str(e.proto_name()),
194 Self::Unknown(v) => write!(f, "{v}"),
195 }
196 }
197}
198
199#[cfg(feature = "json")]
200impl<E: Enumeration> serde::Serialize for EnumValue<E> {
201 fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
202 match self {
203 Self::Known(e) => s.serialize_str(e.proto_name()),
204 Self::Unknown(v) => s.serialize_i32(*v),
205 }
206 }
207}
208
209#[cfg(feature = "json")]
210impl<'de, E: Enumeration> serde::Deserialize<'de> for EnumValue<E> {
211 fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
212 use crate::json_helpers::EnumJsonErrorReason;
213
214 struct EnumValueVisitor<E>(core::marker::PhantomData<E>);
215
216 impl<'de, E: Enumeration> serde::de::Visitor<'de> for EnumValueVisitor<E> {
217 type Value = EnumValue<E>;
218
219 fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
220 f.write_str("a protobuf enum name string or integer value")
221 }
222
223 fn visit_unit<Err: serde::de::Error>(self) -> Result<EnumValue<E>, Err> {
226 Ok(EnumValue::from(0))
227 }
228
229 #[cfg(feature = "zeroize")]
230 fn visit_byte_buf<Err: serde::de::Error>(
231 self,
232 value: alloc::vec::Vec<u8>,
233 ) -> Result<Self::Value, Err> {
234 let value = zeroize::Zeroizing::new(value);
237 self.visit_bytes(&value)
238 }
239 fn visit_str<Err: serde::de::Error>(self, v: &str) -> Result<EnumValue<E>, Err> {
240 match E::from_proto_name(v) {
241 Some(e) => Ok(EnumValue::Known(e)),
242 None => {
243 #[cfg(all(feature = "std", feature = "json"))]
248 if crate::json::ignore_unknown_enum_values() {
249 return Ok(EnumValue::from(0));
250 }
251 Err(Err::custom(EnumJsonErrorReason::UnknownName))
252 }
253 }
254 }
255
256 #[cfg(feature = "zeroize")]
257 fn visit_string<Err: serde::de::Error>(
258 self,
259 value: alloc::string::String,
260 ) -> Result<Self::Value, Err> {
261 let value = zeroize::Zeroizing::new(value);
264 self.visit_str(&value)
265 }
266
267 fn visit_i64<Err: serde::de::Error>(self, v: i64) -> Result<EnumValue<E>, Err> {
268 let n =
269 i32::try_from(v).map_err(|_| Err::custom(EnumJsonErrorReason::OutOfRange))?;
270 Ok(EnumValue::from(n))
271 }
272
273 fn visit_u64<Err: serde::de::Error>(self, v: u64) -> Result<EnumValue<E>, Err> {
274 let n =
275 i32::try_from(v).map_err(|_| Err::custom(EnumJsonErrorReason::OutOfRange))?;
276 Ok(EnumValue::from(n))
277 }
278
279 fn visit_i128<Err: serde::de::Error>(self, v: i128) -> Result<Self::Value, Err> {
282 let v =
283 i64::try_from(v).map_err(|_| Err::custom(EnumJsonErrorReason::OutOfRange))?;
284 self.visit_i64(v)
285 }
286
287 fn visit_u128<Err: serde::de::Error>(self, v: u128) -> Result<Self::Value, Err> {
288 let v =
289 u64::try_from(v).map_err(|_| Err::custom(EnumJsonErrorReason::OutOfRange))?;
290 self.visit_u64(v)
291 }
292
293 fn visit_f64<Err: serde::de::Error>(self, _: f64) -> Result<Self::Value, Err> {
294 Err(Err::custom(EnumJsonErrorReason::InvalidType))
295 }
296
297 fn visit_bool<Err: serde::de::Error>(self, _: bool) -> Result<Self::Value, Err> {
298 Err(Err::custom(EnumJsonErrorReason::InvalidType))
299 }
300 }
301
302 d.deserialize_any(EnumValueVisitor(core::marker::PhantomData))
303 }
304}
305
306impl<E: Enumeration> Default for EnumValue<E> {
307 fn default() -> Self {
315 Self::from(0)
316 }
317}
318
319#[cfg(feature = "arbitrary")]
320impl<'a, E: Enumeration + arbitrary::Arbitrary<'a>> arbitrary::Arbitrary<'a> for EnumValue<E> {
321 fn arbitrary(u: &mut arbitrary::Unstructured<'a>) -> arbitrary::Result<Self> {
322 if u.ratio(3, 4)? {
325 Ok(EnumValue::Known(E::arbitrary(u)?))
326 } else {
327 Ok(EnumValue::Unknown(i32::arbitrary(u)?))
328 }
329 }
330}
331
332#[cfg(test)]
333mod tests {
334 use super::*;
335
336 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
337 enum Color {
338 Red,
339 Green,
340 Blue,
341 }
342
343 impl Enumeration for Color {
344 fn from_i32(v: i32) -> Option<Self> {
345 match v {
346 0 => Some(Color::Red),
347 1 => Some(Color::Green),
348 2 => Some(Color::Blue),
349 _ => None,
350 }
351 }
352 fn to_i32(&self) -> i32 {
353 *self as i32
354 }
355 fn proto_name(&self) -> &'static str {
356 match self {
357 Color::Red => "RED",
358 Color::Green => "GREEN",
359 Color::Blue => "BLUE",
360 }
361 }
362 fn from_proto_name(name: &str) -> Option<Self> {
363 match name {
364 "RED" => Some(Color::Red),
365 "GREEN" => Some(Color::Green),
366 "BLUE" => Some(Color::Blue),
367 _ => None,
368 }
369 }
370 }
371
372 #[test]
375 fn from_i32_known_value_produces_known_variant() {
376 let v: EnumValue<Color> = EnumValue::from(1);
377 assert_eq!(v, EnumValue::Known(Color::Green));
378 }
379
380 #[test]
381 fn from_i32_unknown_values_produce_unknown_variant() {
382 for v in [99, -1, i32::MIN, i32::MAX] {
384 let ev: EnumValue<Color> = EnumValue::from(v);
385 assert_eq!(ev, EnumValue::Unknown(v), "from({v})");
386 assert_eq!(ev.to_i32(), v, "to_i32 roundtrip for {v}");
387 }
388 }
389
390 #[test]
393 fn from_enum_variant_produces_known() {
394 let v = EnumValue::from(Color::Blue);
395 assert_eq!(v, EnumValue::Known(Color::Blue));
396 }
397
398 #[test]
401 fn to_i32_known_returns_variant_value() {
402 let v = EnumValue::Known(Color::Green);
403 assert_eq!(v.to_i32(), 1);
404 }
405
406 #[test]
407 fn to_i32_unknown_returns_raw_value() {
408 let v: EnumValue<Color> = EnumValue::Unknown(42);
409 assert_eq!(v.to_i32(), 42);
410 }
411
412 #[test]
413 fn to_i32_unknown_negative_returns_raw_value() {
414 let v: EnumValue<Color> = EnumValue::Unknown(-1);
415 assert_eq!(v.to_i32(), -1);
416 }
417
418 #[test]
421 fn as_known_returns_some_for_known_variant() {
422 let v = EnumValue::Known(Color::Red);
423 assert_eq!(v.as_known(), Some(Color::Red));
424 }
425
426 #[test]
427 fn as_known_returns_none_for_unknown() {
428 let v: EnumValue<Color> = EnumValue::Unknown(7);
429 assert_eq!(v.as_known(), None);
430 }
431
432 #[test]
435 fn debug_known_variant_uses_enum_debug() {
436 let v = EnumValue::Known(Color::Blue);
437 assert_eq!(format!("{v:?}"), "Blue");
438 }
439
440 #[test]
441 fn debug_unknown_shows_raw_value() {
442 let v: EnumValue<Color> = EnumValue::Unknown(99);
443 assert_eq!(format!("{v:?}"), "Unknown(99)");
444 }
445
446 #[test]
449 fn display_known_variant_uses_proto_name() {
450 let v = EnumValue::Known(Color::Green);
451 assert_eq!(format!("{v}"), "GREEN");
452 }
453
454 #[test]
455 fn display_unknown_shows_raw_integer() {
456 let v: EnumValue<Color> = EnumValue::Unknown(99);
457 assert_eq!(format!("{v}"), "99");
458 }
459
460 #[test]
461 fn display_unknown_negative_shows_signed_integer() {
462 let v: EnumValue<Color> = EnumValue::Unknown(-1);
463 assert_eq!(format!("{v}"), "-1");
464 }
465
466 #[test]
469 fn default_produces_known_when_zero_is_valid() {
470 let v: EnumValue<Color> = EnumValue::default();
472 assert_eq!(v, EnumValue::Known(Color::Red));
473 }
474
475 #[test]
476 fn default_produces_unknown_when_zero_is_not_a_valid_variant() {
477 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
479 enum Status {
480 Active,
481 Inactive,
482 }
483 impl Enumeration for Status {
484 fn from_i32(v: i32) -> Option<Self> {
485 match v {
486 1 => Some(Status::Active),
487 2 => Some(Status::Inactive),
488 _ => None,
489 }
490 }
491 fn to_i32(&self) -> i32 {
492 match self {
493 Status::Active => 1,
494 Status::Inactive => 2,
495 }
496 }
497 fn proto_name(&self) -> &'static str {
498 match self {
499 Status::Active => "ACTIVE",
500 Status::Inactive => "INACTIVE",
501 }
502 }
503 }
504
505 let v: EnumValue<Status> = EnumValue::default();
507 assert_eq!(v, EnumValue::Unknown(0));
508 }
509
510 #[test]
513 fn is_known_returns_true_for_known_variant() {
514 let v = EnumValue::Known(Color::Red);
515 assert!(v.is_known());
516 assert!(!v.is_unknown());
517 }
518
519 #[test]
520 fn is_unknown_returns_true_for_unknown_value() {
521 let v: EnumValue<Color> = EnumValue::Unknown(99);
522 assert!(v.is_unknown());
523 assert!(!v.is_known());
524 }
525
526 #[test]
529 fn known_variant_equals_same_variant() {
530 let v = EnumValue::Known(Color::Green);
531 assert!(v == Color::Green);
532 }
533
534 #[test]
535 fn known_variant_not_equal_to_different_variant() {
536 let v = EnumValue::Known(Color::Red);
537 assert!(!(v == Color::Green));
538 }
539
540 #[test]
541 fn unknown_value_never_equals_known_variant() {
542 let v: EnumValue<Color> = EnumValue::Unknown(1); assert!(!(v == Color::Green));
545 }
546
547 #[test]
548 fn unknown_value_with_out_of_range_int_not_equal() {
549 let v: EnumValue<Color> = EnumValue::Unknown(99);
550 assert!(!(v == Color::Red));
551 }
552
553 #[cfg(feature = "json")]
556 mod serde_tests {
557 use super::*;
558
559 #[test]
560 fn known_variant_serializes_as_proto_name() {
561 let v = EnumValue::Known(Color::Green);
562 assert_eq!(serde_json::to_string(&v).unwrap(), r#""GREEN""#);
563 }
564
565 #[test]
566 fn unknown_variant_serializes_as_integer() {
567 let v: EnumValue<Color> = EnumValue::Unknown(99);
568 assert_eq!(serde_json::to_string(&v).unwrap(), "99");
569 }
570
571 #[test]
572 fn deserialize_table() {
573 use EnumValue::{Known, Unknown};
574 #[rustfmt::skip]
576 let cases: &[(&str, Option<EnumValue<Color>>)] = &[
577 (r#""RED""#, Some(Known(Color::Red))), ("1", Some(Known(Color::Green))), ("99", Some(Unknown(99))), ("null", Some(Known(Color::Red))), (r#""PURPLE""#, None), ("9223372036854775807", None), ];
584 for &(json, expected) in cases {
585 let result = serde_json::from_str::<EnumValue<Color>>(json);
586 assert_eq!(result.ok(), expected, "input: {json}");
587 }
588 }
589
590 #[test]
591 fn deserialize_unknown_string_error_omits_the_value() {
592 let err = serde_json::from_str::<EnumValue<Color>>(r#""PURPLE""#).unwrap_err();
593 assert_eq!(err.to_string(), "unknown enum name at line 1 column 8");
594 }
595
596 #[test]
597 fn deserialize_unknown_string_returns_default_when_lenient() {
598 use crate::json::{with_json_parse_options, JsonParseOptions};
599 let opts = JsonParseOptions {
600 ignore_unknown_enum_values: true,
601 ..Default::default()
602 };
603 let v: EnumValue<Color> =
604 with_json_parse_options(&opts, || serde_json::from_str(r#""PURPLE""#).unwrap());
605 assert_eq!(v, EnumValue::Known(Color::Red));
607 }
608
609 #[test]
610 fn deserialize_known_string_unaffected_by_lenient_mode() {
611 use crate::json::{with_json_parse_options, JsonParseOptions};
612 let opts = JsonParseOptions {
613 ignore_unknown_enum_values: true,
614 ..Default::default()
615 };
616 let v: EnumValue<Color> =
617 with_json_parse_options(&opts, || serde_json::from_str(r#""BLUE""#).unwrap());
618 assert_eq!(v, EnumValue::Known(Color::Blue));
619 }
620
621 #[test]
622 fn round_trip_known_variant() {
623 let original = EnumValue::Known(Color::Blue);
624 let json = serde_json::to_string(&original).unwrap();
625 let recovered: EnumValue<Color> = serde_json::from_str(&json).unwrap();
626 assert_eq!(original, recovered);
627 }
628 }
629}