添加项目

将资源添加到现有存储中

let resource_handle = store.add( stam::TextResource::from_file("my-text.txt", store.config()) )?;

类似模式适用于 AnnotationDataSet

let annotationset_handle = store.add( stam::AnnotationDataSet::from_file("myset.json", store.config()) )?;

方法 add 直接添加项目，这意味着它们必须已经被构建。然而，许多 STAM 数据结构都有关联的构建器类型，并且不是直接实例化的。我们使用 annotate() 而不是 add() 来将注释添加到现有存储中

let annotation_handle = store.annotate( stam::AnnotationBuilder::new()
           .with_target( stam::SelectorBuilder::TextSelector("testres", stam::Offset::simple(6,11))) 
           .with_data("testdataset", "pos", "noun") 
)?;

这里我们看到一个使用构建器模式来构建其关联类型实例的Builder类型。实际的实例将由底层存储构建。

类似于AnnotationDataSets和TextResource的结构也有构建器，您可以通过在构建器上调用build()方法来使用它们与add()方法一起产生最终类型。

let annotationset_handle = store.add(
                   stam::AnnotationDataSetBuilder::new().with_id("testdataset"))
                                                 .with_data_with_id("pos", "noun", "D1").build()?)?;

现在让我们从头开始创建一个存储和注解，并使用显式填充的AnnotationDataSet。

let store = stam::AnnotationStore::new(stam::Config::default())
    .with_id("test")
    .add( stam::TextResource::from_string("testres", "Hello world"))?
    .add( stam::AnnotationDataSet::new().with_id("testdataset")
           .add( stam::DataKey::new("pos"))?
           .with_data_with_id("pos", "noun", "D1")?
    )?
    .with_annotation( stam::Annotation::builder() 
            .with_id("A1")
            .with_target( stam::SelectorBuilder::textselector("testres", stam::Offset::simple(6,11))) 
            .with_existing_data("testdataset", "D1") )?;

这里同样是同样的东西，但这里的AnnotationDataSet是隐式填充的。

let store = stam::AnnotationStore::default().with_id("test")
    .add( stam::TextResource::from_string("testres".to_string(),"Hello world"))?
    .add( stam::AnnotationDataSet::new().with_id("testdataset"))?
    .with_annotation( stam::AnnotationBuilder::new()
            .with_id("A1")
            .with_target( stam::SelectorBuilder::textselector("testres", stam::Offset::simple(6,11))) 
            .with_data_with_id("testdataset","pos","noun","D1")
    )?;

实现将确保尽可能重用任何已存在的AnnotationData，因为不重复数据是STAM模型的核心特性之一。

还有一个AnnotationStoreBuilder，您可以使用它来实现整个注解存储的构建器模式。

文件序列化

您可以将整个注解存储（包括所有集合和注解）序列化到一个STAM JSON文件。

store.to_file("example.stam.json")?;

或者到一个STAM CSV文件（这实际上将为集合和注解创建单独的衍生CSV文件）。

store.to_file("example.stam.csv")?;

迭代器 & 搜索

遍历存储中的所有注解，并以按注解和按注解的文本的简单制表符分隔格式输出数据。

for annotation in store.annotations() {
    let id = annotation.id().unwrap_or("");
    for data in annotation.data() {
        // get the text to which this annotation refers (if any)
        let text: Vec<&str> = annotation.text().collect();
        print!("{}\t{}\t{}\t{}", id, data.key().id().unwrap(), data.value(), text.join(" "));
    }
}

以下是返回迭代器的重要方法概述，迭代器反过来又返回ResultItem<T>实例（或ResultTextSelection）。表格分为两部分，上半部分是遵循STAM所有权的简单方法，下半部分利用了计算出的各种反向索引。

备注

• (1) 与已知的文本选择，我们指的是注解引用的文本部分。
• 左列中大部分方法仅在第二部分表格的ResultItem<T>中实现，而不是&T。
• 这个库始终使用迭代器，因此采用惰性求值。这种方法更高效且内存占用更少，因为您无需等待所有结果收集（和堆分配）后再进行计算。

STAM中的主要命名迭代器属性包括

这些迭代器公开了一个API，允许进行各种转换和过滤操作：您通常可以使用第三列中的方法将一种类型的迭代器转换为另一种类型。同样，您可以通过同名方法从ResultItem实例获得迭代器。

所有这些迭代器都有一个拥有集合对应物（Handles<T>），它将整个集合保存在内存中，项目通过引用存储来保存，因此减少了空间开销。您可以通过.to_handles()从前者转换为后者，并通过.items()从后者转换到格式。

迭代器可以通过过滤器进行扩展，它们在构建模式中应用，并返回一个仍然实现相同属性但应用了过滤器的迭代器

所有这些迭代器都是惰性迭代器，也就是说，除非被消费，否则不会做任何事情。一旦开始迭代，内部缓冲区可能会分配。

当您不关心实际的项目，只是想测试是否存在结果时，请使用这些迭代器上可用的test()方法。

为了提高性能，您可以将.parallel()添加到迭代器中，任何后续的迭代器方法（如通用的map()和filter()），将在多个核心上并行运行。

let dataset = store.dataset("linguistic-features").or_fail()?;
let key = dataset.key("part-of-speech").or_fail()?;
let annotationsiter = key.data().filter_value("noun".into()).annotations();

let annotationsiter = key.annotations().filter_value("noun".into());

let dataset = store.dataset("linguistic-features").or_fail()?;
let key = dataset.key("part-of-speech").or_fail()?;
if word.annotations().filter_key(&key).filter_value("noun".into()).test() {
   ...    
}

let data = store.find_data("linguistic-features", "part-of-speech", "noun".into()).next()

let dataset = store.dataset("structure-type").or_fail()?;
let key_word = dataset.key("word").or_fail()?;
for word in sentence.related_text(stam::TextSelectionOperator::embeds()).annotations().filter_key(key_word) {
    ...
}

let query: Query = "SELECT ANNOTATION ?a WHERE DATA myset type = phrase;".try_into()?;
let iter = store.query(query);
let names = iter.names();
for results in iter {
    if let Ok(result) = results.get_by_name(&names, "a") {
       if let QueryResultItem::Annotation(annotation) = result {
          ...
        }
    }
}