Crate semigroup 

Semigroup trait is useful for combining multiple elements. For example:

• Coalesce: reading configs from multiple sources
• Histogram: statistical aggregation

This crate enables you to derive Semigroup and provides many practical implementations.

Usage

cargo add semigroup --features derive,monoid

Examples

A CLI example of clap and serde integration, see https://github.com/hayas1/semigroup/blob/master/semigroup/examples/clap_serde.rs

Simple coalesce

use semigroup::Semigroup;
#[derive(Debug, Clone, PartialEq, Semigroup)]
#[semigroup(with = "semigroup::op::Coalesce")]
pub struct Config<'a> {
    pub num: Option<u32>,
    pub str: Option<&'a str>,
    #[semigroup(with = "semigroup::op::Overwrite")]
    pub boolean: bool,
}

let cli = Config { num: Some(1), str: None, boolean: true };
let file = Config { num: None, str: Some("ten"), boolean: false };
let env = Config { num: Some(100), str: None, boolean: false };

let config = cli.semigroup(file).semigroup(env);

assert_eq!(config, Config { num: Some(1), str: Some("ten"), boolean: false });

Coalesce with rich enum annotation and lazy evaluation

More detail is in Annotate and Lazy.

use semigroup::{Annotate, Lazy, Semigroup};
#[derive(Debug, Clone, PartialEq, Semigroup)]
#[semigroup(annotated, with = "semigroup::op::Coalesce")]
pub struct Config<'a> {
    pub num: Option<u32>,
    pub str: Option<&'a str>,
    #[semigroup(with = "semigroup::op::Overwrite")]
    pub boolean: bool,
}
#[derive(Debug, Clone, PartialEq)]
pub enum Source {
    File,
    Env,
    Cli,
}

let cli = Config { num: Some(1), str: None, boolean: true }.annotated(Source::Cli);
let file = Config { num: None, str: Some("ten"), boolean: false }.annotated(Source::File);
let env = Config { num: Some(100), str: None, boolean: false }.annotated(Source::Env);

let lazy = Lazy::from(cli).semigroup(file.into()).semigroup(env.into());
assert_eq!(lazy.first().value(), &Config { num: Some(1), str: None, boolean: true });
assert_eq!(lazy.last().value(), &Config { num: Some(100), str: None, boolean: false });

let config = lazy.combine();
assert_eq!(config.value(), &Config { num: Some(1), str: Some("ten"), boolean: false });
assert_eq!(config.annotation().num, Source::Cli);
assert_eq!(config.annotation().str, Source::File);
assert_eq!(config.annotation().boolean, Source::Env);

Highlights

• #[derive(Semigroup)] and #[derive(Construction)]
  • derive Semigroup implements semigroup for a struct by field level semantics.
  • derive Construction defines a new semigroup operation (Some operations are already defined in crate::op).
• Practical annotation support
  • Some semigroup operations such as op::Coalesce can have an annotation that is represented by Annotate trait.
• Combine multiple elements
  • CombineIterator provides fold and combine operations for iterators.
  • Lazy provides lazy evaluation.
  • segment_tree::SegmentTree is useful for fast range queries on Monoid.

	Semigroup	Annotate	Monoid	Commutative
property	associativity	annotation	identity element	commutativity
#[derive(Semigroup)] #[semigroup(...)]		annotated	monoid	commutative
#[derive(Construction)] #[construction(...)]		annotated	monoid	commutative
testing	assert_semigroup!		assert_monoid!	assert_commutative!
typical combiner	CombineIterator	Lazy	SegmentTree	CombineStream

Links

• GitHub: https://github.com/hayas1/semigroup
• GitHub Pages: https://hayas1.github.io/semigroup/semigroup
• Release Notes: https://github.com/hayas1/semigroup/releases
• Crates.io: https://crates.io/crates/semigroup
• Docs.rs: https://docs.rs/semigroup

Testing

Benchmarks

// TODO

Coverage

https://hayas1.github.io/semigroup/semigroup/tarpaulin-report.html

Modules

op

segment_treemonoid

test_combinetest

test_commutativetest

test_lazytest

test_monoidmonoid and test

test_semigrouptest

Macros

assert_commutative

Assert that the given type satisfies the commutative property.

assert_monoid

Assert that the given type satisfies the monoid property.

assert_semigroup

Assert that the given type satisfies the semigroup property.

Structs

Annotated

Annotated represents a Semigroup value with an annotation. The value will be annotated by Annotate trait.

Lazy

A lazy evaluated Semigroup with nonempty buffer that is implemented by Vec.

OptionMonoidmonoid

Construct Monoid from optional Semigroup. Some Semigroup lack a suitable identity element for extension to a Monoid.

Reverse

A Semigroup construction that flips the order of operands: op(Reverse(a), Reverse(b)) = Reverse(op(b, a)).

Traits

Annotate

Some Semigroup such as crate::op::Coalesce can have an annotation. The annotated operation is represented by AnnotatedSemigroup, and the annotated value is represented by a type Annotated.

AnnotatedSemigroup

AnnotatedSemigroup is a Semigroup that has an annotation, such as crate::Annotate.

AsyncCommutativeasync

Async version of Commutative.

AsyncSemigroupasync

Async version of Semigroup.

CombineIterator

Extensions for Iterators that items implement Semigroup.

CombineStreamasync

Extensions for Streams that items implement AsyncCommutative. Like crate::CombineIterator.

Commutative

Commutative represents a binary operation that satisfies the following property

Construction

Construction represents crate::Semigroup as a new type struct.

ConstructionAnnotated

ConstructionAnnotated represents crate::AnnotatedSemigroup as a new type struct like Construction.

ConstructionMonoidmonoid

ConstructionMonoid represents crate::Monoid as a new type struct. like Construction.

Monoidmonoid

Monoid represents a binary operation that satisfies the following properties

Semigroup

Semigroup represents a binary operation that satisfies the following properties

Attribute Macros

propertiesderive

Derive Macros

Constructionderive

Semigroupderive