Semantic v1.0.0 — Declarative Stream Processing for Modern C++17

Semantic

A header-only declarative stream processing library for modern C++17, inspired by Java Streams and functional programming paradigms.

Overview

Semantic provides a fluent, type-safe API for composing lazy data processing pipelines. It supports both single-parameter and dual-parameter (element + index) callbacks throughout, automatic type deduction, and seamless interoperability with the C++ Standard Library containers.

Features

• Lazy evaluation — operations are deferred until a terminal operation is invoked
• Dual-parameter support — all intermediate operations accept (E) or (E, Timestamp) callables
• Rich operation set — map, filter, flatMap, takeWhile, dropWhile, distinct, sort, peek, limit, skip, and more
• Comprehensive collectors — toVector, toSet, toMap, group, partition, join, reduce, count, statistical analysis
• Standard container specialisations — std::vector, std::list, std::deque, std::queue, std::stack, std::priority_queue, std::set, std::multiset, std::unordered_set, std::map, std::multimap, std::unordered_map, std::array, std::pair, std::tuple, std::variant, std::bitset
• Text and character processing — useBlob, useText, useSequence, useCharsequence with charset encoding support
• Random generation — useRandom with optional bounds and count
• Infinite streams — useInfinite, useIterate, useGenerate
• Window operations — tumble and slide for time-series and batch processing
• Statistical collectors — sum, average, variance, standard deviation, median, mode, percentiles, quartiles, skewness, kurtosis, DFT/FFT, gradient descent
• Concurrency support — configurable parallel processing via parallel(n)

Requirements

• C++17 or later
• A conforming C++ compiler (GCC 8+, Clang 7+, MSVC 2019+)

Quick Start

#include "semantics.h"

// Create a stream of integers
auto result = semantic::useRange(0, 10)
    .filter([](int x) { return x % 2 == 0; })
    .map([](int x) { return x * x; })
    .takeWhile([](int x) { return x < 50; })
    .sort()
    .toVector();

// Output: [0, 4, 16, 36]

Stream Sources

// Numeric ranges
semantic::useRange(0, 100);
semantic::useRange(0, 100, 2);
semantic::useRangeClosed(1, 10);

// From containers
semantic::useFrom(std::vector<int>{1, 2, 3});
semantic::useOf(1, 2, 3);

// Infinite streams
semantic::useInfinite(1, [](int x) { return x * 2; });
semantic::useGenerate([]() { return rand() % 100; });

// Random generation
semantic::useRandom<int>(1, 100, 50);

// Text processing
semantic::useText("hello world", ' ');
semantic::useSequence("Hello, 世界");

Intermediate Operations

Operation Description
map Transforms each element
filter Filters elements by predicate
flatMap One-to-many transformation
flat Flattens nested containers
takeWhile Takes elements while predicate holds
dropWhile Drops elements while predicate holds
limit Limits to first n elements
skip Skips first n elements
distinct Removes duplicates
sort Sorts elements (with optional comparator)
peek Performs side-effect on each element
reverse Reverses element indices
translate Offsets element indices
redirect Redirects elements via function
sub Extracts a sub-range
concatenate Concatenates two streams
parallel Enables parallel processing

Terminal Operations (Collectors)

// Collection
.toVector();
.toSet();
.toList();
.toDeque();
.toMap(keyExtractor);
.toUnorderedMap(keyExtractor, valueExtractor);

// Reduction
.reduce(accumulator);
.reduce(identity, accumulator);
.count();

// Matching
.anyMatch(predicate);
.allMatch(predicate);
.noneMatch(predicate);

// Finding
.findFirst();
.findLast();
.findAny();
.findAt(index);
.findMaximum();
.findMinimum();

// Grouping
.group(keyExtractor);
.partition(size);

// Output
.out();
.out(delimiter);
.out(prefix, delimiter, suffix);
.join();
.error();

// Statistics
.toStatistics<double>()
    .summate()
    .average()
    .median()
    .standardDeviation()
    .percentile(90.0);

Example: Word Frequency

auto wordFrequency = semantic::useText("the quick brown fox jumps over the lazy dog", ' ')
    .map([](auto cs) { return cs.toString(); })
    .group([](const std::string& s) { return s; })
    .map([](auto& pair) { return std::make_pair(pair.first, pair.second.size()); })
    .toVector();

Example: Parallel Processing

auto squares = semantic::useRange(0, 1000)
    .parallel(4)
    .map([](int x) { return x * x; })
    .toVector();

Example: Statistical Analysis

auto stats = semantic::useRange(0, 100)
    .toStatistics<double>()
    .map([](int x) { return static_cast<double>(x); });

auto mean = stats.average();
auto stddev = stats.standardDeviation();
auto med = stats.median();

Custom Collectors

auto result = stream.collect(
    identitySupplier,
    accumulator,
    combiner,
    finisher
);

Licence

This project is provided under the MIT Licence. See the LICENCE file for details.

Version History

v1.0.0

· Initial release
· Full stream processing API
· Comprehensive collector framework
· Standard container specialisations
· Statistical analysis collectors
· Text and character sequence processing
· Parallel processing support
· Window operations (tumble/slide)