例如，直接使用String是不明智的，因为这会导致bE != Be != BE != Belgium != Belgique != België。尽管这些实际上都指的是同一个国家。在这种情况下，至少创建一个包装类型，如struct Country(String)，以在创建值时强制执行清理/验证，并确保概念上相同的值的哈希值将相同。

❓ 我该如何使过滤器成为可选的？

过滤器（bool属性）和过滤器映射（具有#[venndb(filter)]属性的T != bool属性）可以通过使用Option来包裹类型，从而使其成为可选的，结果是Option<bool>和Option<T>。

对于具有此类可选列的Option::None值的行，无法对该属性进行筛选，但除此之外没有其他后果。

❓ 为什么键必须唯一且非可选的？

在venndb中，键是为了能够查找之前通过过滤器接收到的行。

因此，这样的键应该是

• 唯一的：因为这会导致返回多行或错误的行；
• 非可选的：因为这意味着在键未定义时无法查找该行；

❓ 我如何允许某些行与某个（过滤器）列的任何值匹配？

过滤器映射允许有一个值匹配所有其他值。您需要声明该过滤器为这样，并定义对于该类型，哪个是“统治一切”的值。

使用方法

use venndb::{Any, VennDB};
#[derive(Debug, PartialEq, Eq, Clone, Hash)]
pub enum Department {
  Any,
  Hr,
  Engineering,
}

impl Any for Department {
  fn is_any(&self) -> bool {
    self == Department::Any
  }
}

#[derive(Debug, VennDB)]
pub struct Employee {
  name: String,
  #[venndb(filter, any)]
  department: Department,
}

let db = EmployeeDB::from_iter([
  Employee { name: "Jack".to_owned(), department: Department::Any },
  Employee { name: "Derby".to_owned(), department: Department::Hr },
]);
let mut query = db.query();

// will match Jack and Derby, as Jack is marked as Any, meaning it can work for w/e value
let hr_employees: Vec<_> = query.department(Department::Hr).execute().unwrap().iter().collect();
assert_eq!(hr_employees.len(), 2);

❓ 我如何在将行附加之前提供自定义验证？

能否根据一行的一个或多个属性进行验证？基于多个属性之间的关系进行验证？能否提供自定义验证以防止不符合自定义验证规则的行被追加？

以上都是可以的。

示例

#[derive(Debug, VennDB)]
#[venndb(validator = my_validator_fn)]
pub struct Value {
   pub foo: String,
   pub bar: u32,
}

fn my_validator_fn(value: &Value) -> bool {
    !value.foo.is_empty() && value.bar > 0
}

let mut db = ValueDB::default();
assert!(db.append(Value {
    foo: "".to_owned(),
    bar: 42,
}).is_err()); // fails because foo == empty

❓ 为什么 any 过滤值只匹配具有该属性 any 值的行？

假设我有以下 struct

use venndb::{Any, VennDB};

#[derive(Debug, VennDB)]
pub struct Value {
   #[venndb(filter, any)]
   pub foo: MyString,
   pub bar: u32,
}

#[derive(Debug)]
pub struct MyString(String);

impl Any for MyString {
    fn is_any(&self) -> bool {
        self.0 == "*"
    }
}

let db = ValueDB::from_iter([
    Value {
        foo: MyString("foo".to_owned()),
        bar: 8,
    },
    Value {
        foo: MyString("*".to_owned()),
        bar: 16,
    }
].into_Iter()).unwrap();

let mut query = db.query();
query.foo(MyString("*".to_owned()));
let value = query.execute().unwrap().any();
// this will never match the row with bar == 8,
// tiven foo != an any value
assert_eq!(value.bar, 16);

这是为什么？因为它是对的。

允许它也匹配值 foo 会对 foo 相对于 任何 值的选择机会产生不公平的影响。这看起来可能不是一个很大的区别，但它是。因为如果我们为 Value 生成一个随机的字符串，并且有一个 _any 值，如果我们允许所有行都匹配，那么这种逻辑现在就是被操纵的，foo 的值比其他字符串更有可能。

因此，对于 任何 值的过滤，唯一正确的答案就是返回具有 任何 值的行。

❓ 我如何对“过滤器映射”属性的多个变体进行查询？

只需多次调用 query 方法。这将允许您匹配具有这些值之一的行。

示例

use venndb::{Any, VennDB};

#[derive(Debug, VennDB)]
pub struct Value {
   #[venndb(filter)]
   pub foo: String,
   pub bar: u32,
}

let db = ValueDB::from_iter([
    Value {
        foo: "a".to_owned(),
        bar: 8,
    },
    Value {
        foo: "b".to_owned(),
        bar: 12,
    },
    Value {
        foo: "c".to_owned(),
        bar: 16,
    },
].into_Iter()).unwrap();

let mut query = db.query();
query.foo(MyString("a".to_owned()));
query.foo(MyString("c".to_owned()));
let values: Vec<_> = query.execute().unwrap().iter().collect();
assert_eq!(values.len(), 2);
assert_eq!(values[0].bar, 8);
assert_eq!(values[0].bar, 16);

示例

以下是一个示例，展示了 VennDB 的所有功能。

如果您希望查看生成的总结，或者不理解以下示例中的某些内容，您还可以阅读下面的 “生成代码总结”章节。

use itertools::Itertools;
use venndb::VennDB;

#[derive(Debug, VennDB)]
// These attributes are optional,
// e.g. by default the database would be called `EmployeeDB` (name + 'DB').
#[venndb(name = "EmployeeInMemDB", validator = employee_validator)]
pub struct Employee {
    // you can use the `key` arg to be able to get an `Employee` instance
    // directly by this key. It will effectively establishing a mapping from key to a reference
    // of that Employee in the database. As such keys have to have unique values,
    // or else you get an error while appending / creating the DB.
    //
    // NOTE: keys do not only have to be unique, they also have to implement `Clone`!!
    //
    // A property cannot be a filter and a key at the same time,
    // trying to do so will result in a compile-team failure.
    #[venndb(key)]
    id: u32,
    name: String,
    is_manager: bool,
    is_admin: bool,
    // filter (booleans) can be made optional,
    // meaning that the row will not be able to be filtered (found)
    // on this column when the row has a `None` value for it
    is_active: Option<bool>,
    // booleans are automatically turned into (query) filters,
    // use the `skip` arg to stop this. As such it is only really needed for
    // bool properties :)
    #[venndb(skip)]
    foo: bool,
    // non-bool values can also be turned into filters, turning them into 2D filters.
    // For each uniquely inserted Department variant that is inserted,
    // a new filter is kept track of. This allows you to apply a (query) filter
    // based on department, a pretty useful thing to be able to do.
    //
    // NOTE: this does mean that such filter-map types have to also be:
    // `PartialEq + Eq + Hash + Clone`!!
    //
    // A property cannot be a filter and a key at the same time,
    // trying to do so will result in a compile-team failure.
    #[venndb(filter)]
    department: Department,
    // similar to regular bool filters,
    // filter maps can also be optional.
    // When a filter map is optional and the row's property for that filter is None,
    // it will not be registered and thus not be able to filtered (found) on that property
    #[venndb(filter)]
    country: Option<String>,
}

fn employee_validator(employee: &Employee) -> bool {
    employee.id > 0
}

fn main() {
    let db = EmployeeInMemDB::from_iter([
        RawCsvRow("1,John Doe,true,false,true,false,Engineering,USA"),
        RawCsvRow("2,Jane Doe,false,true,true,true,Sales,"),
        RawCsvRow("3,John Smith,false,false,,false,Marketing,"),
        RawCsvRow("4,Jane Smith,true,true,false,true,HR,"),
        RawCsvRow("5,John Johnson,true,true,true,true,Engineering,"),
        RawCsvRow("6,Jane Johnson,false,false,,false,Sales,BE"),
        RawCsvRow("7,John Brown,true,false,true,false,Marketing,BE"),
        RawCsvRow("8,Jane Brown,false,true,true,true,HR,BR"),
    ])
    .expect("MemDB created without errors (e.g. no duplicate keys)");

    println!(">>> Printing all employees...");
    let all_employees: Vec<_> = db.iter().collect();
    assert_eq!(all_employees.len(), 8);
    println!("All employees: {:#?}", all_employees);

    println!(">>> You can lookup an employee by any registered key...");
    let employee = db
        .get_by_id(&2)
        .expect("to have found an employee with ID 2");
    assert_eq!(employee.name, "Jane Doe");

    println!(">>> Querying for all managers...");
    let mut query = db.query();
    query.is_manager(true);
    let managers: Vec<_> = query
        .execute()
        .expect("to have found at least one")
        .iter()
        .collect();
    assert_eq!(managers.len(), 4);
    assert_eq!(
        managers.iter().map(|e| e.id).sorted().collect::<Vec<_>>(),
        [1, 4, 5, 7]
    );

    println!(">>> Querying for all managers with a last name of 'Johnson'...");
    let managers_result = query
        .execute()
        .expect("to have found at least one")
        .filter(|e| e.name.ends_with("Johnson"))
        .expect("to have found a manager with a last name of Johnson");
    let managers = managers_result.iter().collect::<Vec<_>>();
    assert_eq!(managers.len(), 1);
    assert_eq!(managers.iter().map(|e| e.id).collect::<Vec<_>>(), [5]);

    println!(">>> You can also just get the first result if that is all you care about...");
    let manager = managers_result.first();
    assert_eq!(manager.id, 5);

    println!(">>> Querying for a random active manager in the Engineering department...");
    let manager = query
        .reset()
        .is_active(true)
        .is_manager(true)
        .department(Department::Engineering)
        .execute()
        .expect("to have found at least one")
        .any();
    assert!(manager.id == 1 || manager.id == 5);

    println!(">>> Optional bool filters have three possible values, where None != false. An important distinction to make...");
    let mut query = db.query();
    query.is_active(false);
    let inactive_employees: Vec<_> = query
        .execute()
        .expect("to have found at least one")
        .iter()
        .collect();
    assert_eq!(inactive_employees.len(), 1);
    assert_eq!(inactive_employees[0].id, 4);

    println!(">>> If you want you can also get the Employees back as a Vec, dropping the DB data all together...");
    let employees = db.into_rows();
    assert_eq!(employees.len(), 8);
    assert!(employees[1].foo);
    println!("All employees: {:?}", employees);

    println!(">>> You can also get the DB back from the Vec, if you want start to query again...");
    // of course better to just keep it as a DB to begin with, but let's pretend this is ok in this example
    let mut db = EmployeeInMemDB::from_rows(employees).expect("DB created without errors");
    assert_eq!(db.iter().count(), 8);

    println!(">>> Querying for all active employees in the Sales department...");
    let mut query = db.query();
    query.is_active(true);
    query.department(Department::Sales);
    let sales_employees: Vec<_> = query
        .execute()
        .expect("to have found at least one")
        .iter()
        .collect();
    assert_eq!(sales_employees.len(), 1);
    assert_eq!(sales_employees[0].name, "Jane Doe");

    println!(">>> Filter maps that are optional work as well, e.g. you can query for all employees from USA...");
    query.reset().country("USA".to_owned());
    let usa_employees: Vec<_> = query
        .execute()
        .expect("to have found at least one")
        .iter()
        .collect();
    assert_eq!(usa_employees.len(), 1);
    assert_eq!(usa_employees[0].id, 1);

    println!(">>> At any time you can also append new employees to the DB...");
    assert_eq!(EmployeeInMemDBErrorKind::DuplicateKey, db
        .append(RawCsvRow("8,John Doe,true,false,true,false,Engineering,"))
        .unwrap_err().kind());
    println!(">>> This will fail however if a property is not correct (e.g. ID (key) is not unique in this case), let's try this again...");
    assert!(db
        .append(RawCsvRow("9,John Doe,false,true,true,false,Engineering,"))
        .is_ok());
    assert_eq!(db.len(), 9);

    println!(">>> Rows are also validated prior to appending in case a validator is defined...");
    println!("    The next insertion will fail due to the id being zero, a condition defined in the custom validator...");
    assert_eq!(EmployeeInMemDBErrorKind::InvalidRow, db
        .append(RawCsvRow("0,John Doe,true,false,true,false,Engineering,"))
        .unwrap_err().kind());

    println!(">>> This new employee can now also be queried for...");
    let mut query = db.query();
    query.department(Department::Engineering).is_manager(false);
    let new_employee: Vec<_> = query
        .execute()
        .expect("to have found at least one")
        .iter()
        .collect();
    assert_eq!(new_employee.len(), 1);
    assert_eq!(new_employee[0].id, 9);

    println!(">>> You can also extend it using an IntoIterator...");
    db.extend([
        RawCsvRow("10,Glenn Doe,false,true,true,true,Engineering,"),
        RawCsvRow("11,Peter Miss,true,true,true,true,HR,USA"),
    ])
    .unwrap();
    let mut query = db.query();
    query
        .department(Department::HR)
        .is_manager(true)
        .is_active(true)
        .is_admin(true);
    let employees: Vec<_> = query
        .execute()
        .expect("to have found at least one")
        .iter()
        .collect();
    assert_eq!(employees.len(), 1);
    assert_eq!(employees[0].id, 11);

    println!(">>> There are now 2 employees from USA...");
    query.reset().country("USA".to_owned());
    let employees: Vec<_> = query
        .execute()
        .expect("to have found at least one")
        .iter()
        .collect();
    assert_eq!(employees.len(), 2);
    assert_eq!(
        employees.iter().map(|e| e.id).sorted().collect::<Vec<_>>(),
        [1, 11]
    );

    println!(">>> All previously data is still there as well of course...");
    query
        .reset()
        .is_active(true)
        .is_manager(true)
        .department(Department::Engineering);
    let managers: Vec<_> = query
        .execute()
        .expect("to have found at least one")
        .iter()
        .collect();
    assert_eq!(managers.len(), 2);
    assert_eq!(
        managers.iter().map(|e| e.id).sorted().collect::<Vec<_>>(),
        [1, 5]
    );
}

#[derive(Debug)]
struct RawCsvRow<S>(S);

impl<S> From<RawCsvRow<S>> for Employee
where
    S: AsRef<str>,
{
    fn from(RawCsvRow(s): RawCsvRow<S>) -> Employee {
        let mut parts = s.as_ref().split(',');
        let id = parts.next().unwrap().parse().unwrap();
        let name = parts.next().unwrap().to_string();
        let is_manager = parts.next().unwrap().parse().unwrap();
        let is_admin = parts.next().unwrap().parse().unwrap();
        let is_active = match parts.next().unwrap() {
            "" => None,
            s => Some(s.parse().unwrap()),
        };
        let foo = parts.next().unwrap().parse().unwrap();
        let department = parts.next().unwrap().parse().unwrap();
        let country = match parts.next().unwrap() {
            "" => None,
            s => Some(s.to_string()),
        };
        Employee {
            id,
            name,
            is_manager,
            is_admin,
            is_active,
            foo,
            department,
            country,
        }
    }
}

#[derive(Debug, PartialEq, Eq, Hash, Clone)]
pub enum Department {
    Engineering,
    Sales,
    Marketing,
    HR,
}

impl std::str::FromStr for Department {
    type Err = ();

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "Engineering" => Ok(Department::Engineering),
            "Sales" => Ok(Department::Sales),
            "Marketing" => Ok(Department::Marketing),
            "HR" => Ok(Department::HR),
            _ => Err(()),
        }
    }
}

生成代码总结

在本章中，我们将列出 VennDB 生成以下示例代码的 API。

#[derive(Debug, VennDB)]
#[venndb(name = "EmployeeInMemDB", validator = employee_validator)]
pub struct Employee {
    #[venndb(key)]
    id: u32,
    name: String,
    is_manager: bool,
    is_admin: bool,
    is_active: Option<bool>,
    #[venndb(skip)]
    foo: bool,
    #[venndb(filter)]
    department: Department,
    country: Option<String>,
}

将生成以下公共 API 数据结构

• struct EmployeeInMemDB：数据库，可用于查询（通过过滤器）或查找数据（通过键）；
• enum EmployeeInMemDBError：在修改数据库和要插入行的属性时返回的错误类型；
• enum EmployeeInMemDBErrorKind：如 EmployeeInMemDBError 中所述可能发生的错误类型；
• struct EmployeeInMemDBQuery：用于构建可以 execute 以使用过滤器从数据库中查询数据的查询构建器；
• struct EmployeeInMemDBQueryResult：使用 EmployeeInMemDBQuery 查询并至少找到一行匹配定义的过滤器时的结果；
• struct EmployeeInMemDBQueryResultIter：当调用 EmployeeInMemDBQueryResult::iter 时使用的迭代器类型。它没有其他方法/api，除了它是一个 Iterator 并可以像这样使用。

这些数据结构的视觉指定符将与应用于 struct 的 VennDB 宏相同。例如，在这个例子中，Employee 有一个指定符 pub，因此上面的数据结构和它们的公共方法也将是 pub。

还生成了其他一些辅助数据结构——所有都以数据库名称作为前缀，例如本例中的 EmployeeInMemDB——但我们在这里不提及它们，因为不应依赖于它们，并且由于前缀，它们应该不会引起冲突。如果您不想将这些结构公开给外部，您可以将您的 struct 包裹在其自己的 mod（模块）中。

生成的代码摘要：方法API

数据库：（例如 EmployeeInMemDB）

查询（例如 EmployeeInMemDBQuery）

查询结果（例如 EmployeeInMemDBQueryResult）

⛨ | 安全性

此crate使用 #![forbid(unsafe_code)] 来确保一切都在100%安全的Rust中实现。