use mysql_async::consts::{ColumnFlags, ColumnType};
use mysql_async::Column;
pub const BINARY_CHARSET: u16 = 63;
pub const SAFE_INTEGER: u64 = 9_007_199_254_740_991;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Shape {
Number,
Text,
Absent,
Structure,
Description,
}
impl Shape {
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Number => "number",
Self::Text => "text",
Self::Absent => "absent",
Self::Structure => "structure",
Self::Description => "description",
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Family {
Integer,
WideInteger,
ExactDecimal,
FloatingPoint,
Text,
Absent,
Bits,
Date,
DateTime,
Timestamp,
Time,
Year,
SingleChoice,
ChoiceSet,
Document,
Uuid,
Inet4,
Inet6,
Binary,
Geometry,
Unknown,
}
impl Family {
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Integer => "integer",
Self::WideInteger => "wide_integer",
Self::ExactDecimal => "exact_decimal",
Self::FloatingPoint => "floating_point",
Self::Text => "text",
Self::Absent => "absent",
Self::Bits => "bits",
Self::Date => "date",
Self::DateTime => "date_time",
Self::Timestamp => "timestamp",
Self::Time => "time",
Self::Year => "year",
Self::SingleChoice => "single_choice",
Self::ChoiceSet => "choice_set",
Self::Document => "document",
Self::Uuid => "uuid",
Self::Inet4 => "inet4",
Self::Inet6 => "inet6",
Self::Binary => "binary",
Self::Geometry => "geometry",
Self::Unknown => "unknown",
}
}
#[must_use]
pub const fn shape(self) -> Shape {
match self {
Self::Integer | Self::FloatingPoint | Self::Bits | Self::Year => Shape::Number,
Self::WideInteger
| Self::ExactDecimal
| Self::Text
| Self::Date
| Self::DateTime
| Self::Timestamp
| Self::Time
| Self::SingleChoice
| Self::ChoiceSet
| Self::Geometry
| Self::Uuid
| Self::Inet4
| Self::Inet6
| Self::Unknown => Shape::Text,
Self::Absent => Shape::Absent,
Self::Document => Shape::Structure,
Self::Binary => Shape::Description,
}
}
}
#[derive(Debug, Clone, Copy)]
pub struct Entry {
pub family: Family,
pub shape: Shape,
pub note: &'static str,
}
#[must_use]
pub const fn published() -> &'static [Entry] {
PUBLISHED
}
const fn row(family: Family, note: &'static str) -> Entry {
Entry {
family,
shape: family.shape(),
note,
}
}
static PUBLISHED: &[Entry] = &[
row(
Family::Integer,
"fits the range every reader parses exactly",
),
row(
Family::WideInteger,
"text, so no digit is lost in the reader",
),
row(
Family::ExactDecimal,
"always text, because a number would round it",
),
row(
Family::FloatingPoint,
"already approximate, so a number loses nothing",
),
row(Family::Text, "the bytes as text"),
row(Family::Absent, "its own marker, never empty text"),
row(Family::Bits, "the bits read as one integer"),
row(Family::Date, "year, month and day"),
row(
Family::DateTime,
"date and time, with the fraction the column declares",
),
row(
Family::Timestamp,
"same form as date and time, in the declared zone",
),
row(
Family::Time,
"an interval, which may be negative or exceed a day",
),
row(Family::Year, "a plain calendar year"),
row(Family::SingleChoice, "the chosen label"),
row(Family::ChoiceSet, "the chosen labels, separated by commas"),
row(Family::Document, "a real structure, never the text of one"),
row(
Family::Uuid,
"the canonical text of the identifier, with its hyphens",
),
row(Family::Inet4, "four numbers separated by dots, as text"),
row(
Family::Inet6,
"the shortened canonical text the server itself returns",
),
row(
Family::Binary,
"size, apparent kind and signature, never the content",
),
row(
Family::Geometry,
"the readable form the server itself returned",
),
row(Family::Unknown, "text carrying the declared type name"),
];
#[must_use]
pub fn family_of(column: &Column) -> Family {
let kind = column.column_type();
match kind {
ColumnType::MYSQL_TYPE_TINY
| ColumnType::MYSQL_TYPE_SHORT
| ColumnType::MYSQL_TYPE_LONG
| ColumnType::MYSQL_TYPE_INT24
| ColumnType::MYSQL_TYPE_LONGLONG => Family::Integer,
ColumnType::MYSQL_TYPE_DECIMAL | ColumnType::MYSQL_TYPE_NEWDECIMAL => Family::ExactDecimal,
ColumnType::MYSQL_TYPE_FLOAT | ColumnType::MYSQL_TYPE_DOUBLE => Family::FloatingPoint,
ColumnType::MYSQL_TYPE_NULL => Family::Absent,
ColumnType::MYSQL_TYPE_BIT => Family::Bits,
ColumnType::MYSQL_TYPE_DATE | ColumnType::MYSQL_TYPE_NEWDATE => Family::Date,
ColumnType::MYSQL_TYPE_DATETIME | ColumnType::MYSQL_TYPE_DATETIME2 => Family::DateTime,
ColumnType::MYSQL_TYPE_TIMESTAMP | ColumnType::MYSQL_TYPE_TIMESTAMP2 => Family::Timestamp,
ColumnType::MYSQL_TYPE_TIME | ColumnType::MYSQL_TYPE_TIME2 => Family::Time,
ColumnType::MYSQL_TYPE_YEAR => Family::Year,
ColumnType::MYSQL_TYPE_ENUM => Family::SingleChoice,
ColumnType::MYSQL_TYPE_SET => Family::ChoiceSet,
ColumnType::MYSQL_TYPE_JSON => Family::Document,
ColumnType::MYSQL_TYPE_VECTOR => Family::Binary,
ColumnType::MYSQL_TYPE_GEOMETRY => Family::Geometry,
ColumnType::MYSQL_TYPE_VARCHAR
| ColumnType::MYSQL_TYPE_VAR_STRING
| ColumnType::MYSQL_TYPE_STRING
| ColumnType::MYSQL_TYPE_BLOB
| ColumnType::MYSQL_TYPE_TINY_BLOB
| ColumnType::MYSQL_TYPE_MEDIUM_BLOB
| ColumnType::MYSQL_TYPE_LONG_BLOB => textual_or_binary(column),
ColumnType::MYSQL_TYPE_TYPED_ARRAY | ColumnType::MYSQL_TYPE_UNKNOWN => Family::Unknown,
}
}
fn textual_or_binary(column: &Column) -> Family {
if column.character_set() == BINARY_CHARSET {
return Family::Binary;
}
if column.character_set() == 0 && column.flags().contains(ColumnFlags::BINARY_FLAG) {
return Family::Binary;
}
Family::Text
}
static SERVER_ONLY: &[(&str, Family)] = &[
("uuid", Family::Uuid),
("inet4", Family::Inet4),
("inet6", Family::Inet6),
];
#[must_use]
pub fn declared_family(declared: &str) -> Option<Family> {
let named = declared.trim().to_ascii_lowercase();
SERVER_ONLY
.iter()
.find(|(name, _)| *name == named)
.map(|(_, family)| *family)
}
#[must_use]
pub fn family_for(column: &Column, declared: Option<&str>) -> Family {
declared
.and_then(declared_family)
.unwrap_or_else(|| family_of(column))
}
#[must_use]
pub fn declared_name(kind: ColumnType) -> String {
format!("{kind:?}")
}
#[cfg(test)]
mod tests {
use super::*;
fn column(kind: ColumnType) -> Column {
Column::new(kind)
}
fn binary_column(kind: ColumnType) -> Column {
Column::new(kind).with_character_set(BINARY_CHARSET)
}
#[test]
fn every_published_family_declares_its_shape_once() {
let table = published();
assert_eq!(table.len(), 21, "the published table has a fixed length");
for entry in table {
assert_eq!(
entry.shape,
entry.family.shape(),
"{}",
entry.family.as_str()
);
assert!(!entry.note.is_empty());
}
}
#[test]
fn family_names_are_unique_so_a_caller_can_branch_on_them() {
let mut names: Vec<&str> = published()
.iter()
.map(|entry| entry.family.as_str())
.collect();
names.sort_unstable();
let before = names.len();
names.dedup();
assert_eq!(names.len(), before, "family names must not repeat");
}
#[test]
fn exact_decimal_is_text_and_floating_point_is_a_number() {
assert_eq!(
family_of(&column(ColumnType::MYSQL_TYPE_NEWDECIMAL)),
Family::ExactDecimal
);
assert_eq!(Family::ExactDecimal.shape(), Shape::Text);
assert_eq!(
family_of(&column(ColumnType::MYSQL_TYPE_DOUBLE)),
Family::FloatingPoint
);
assert_eq!(Family::FloatingPoint.shape(), Shape::Number);
}
#[test]
fn a_document_is_a_structure_and_never_text() {
assert_eq!(
family_of(&column(ColumnType::MYSQL_TYPE_JSON)),
Family::Document
);
assert_eq!(Family::Document.shape(), Shape::Structure);
}
#[test]
fn absence_has_a_shape_of_its_own_apart_from_text() {
assert_ne!(Family::Absent.shape(), Family::Text.shape());
assert_eq!(Family::Absent.shape(), Shape::Absent);
}
#[test]
fn the_character_set_tells_a_byte_column_from_a_text_one() {
assert_eq!(
family_of(&binary_column(ColumnType::MYSQL_TYPE_BLOB)),
Family::Binary
);
assert_eq!(
family_of(&column(ColumnType::MYSQL_TYPE_BLOB)),
Family::Text
);
assert_eq!(
family_of(&column(ColumnType::MYSQL_TYPE_VAR_STRING)),
Family::Text
);
}
#[test]
fn each_temporal_type_lands_on_its_own_family() {
assert_eq!(
family_of(&column(ColumnType::MYSQL_TYPE_DATE)),
Family::Date
);
assert_eq!(
family_of(&column(ColumnType::MYSQL_TYPE_DATETIME)),
Family::DateTime
);
assert_eq!(
family_of(&column(ColumnType::MYSQL_TYPE_TIMESTAMP)),
Family::Timestamp
);
assert_eq!(
family_of(&column(ColumnType::MYSQL_TYPE_TIME)),
Family::Time
);
assert_eq!(
family_of(&column(ColumnType::MYSQL_TYPE_YEAR)),
Family::Year
);
}
#[test]
fn a_server_only_family_comes_from_the_catalogue_and_never_from_the_packet() {
let carrier = column(ColumnType::MYSQL_TYPE_VAR_STRING);
assert_eq!(
family_of(&carrier),
Family::Text,
"the packet of this server cannot name these families"
);
for (declared, family) in [
("uuid", Family::Uuid),
("inet4", Family::Inet4),
("inet6", Family::Inet6),
] {
assert_eq!(declared_family(declared), Some(family));
assert_eq!(family_for(&carrier, Some(declared)), family);
assert_eq!(family.shape(), Shape::Text, "{declared}");
}
assert_eq!(declared_family(" INET6 "), Some(Family::Inet6));
}
#[test]
fn a_column_with_no_declared_origin_keeps_the_family_of_the_packet() {
let carrier = column(ColumnType::MYSQL_TYPE_VAR_STRING);
assert_eq!(family_for(&carrier, None), Family::Text);
assert_eq!(family_for(&carrier, Some("something_else")), Family::Text);
assert_eq!(declared_family("something_else"), None);
}
#[test]
fn an_unknown_type_keeps_its_declared_name() {
assert_eq!(
family_of(&column(ColumnType::MYSQL_TYPE_TYPED_ARRAY)),
Family::Unknown
);
let name = declared_name(ColumnType::MYSQL_TYPE_TYPED_ARRAY);
assert!(name.contains("TYPED_ARRAY"), "{name}");
}
}