map Function - DataFrame Library Documentation

Overview

The map function transforms each element in a Serie using a callback function, creating and returning a new Serie with the transformed values. This function is at the heart of functional transformations in DataFrame.

Function Signatures


          // Single serie version
          template <typename F, typename T>
          auto map(F&& callback, const Serie<T>& serie);
          
          // Multi-series version
          template <typename F, typename T, typename... Args>
          auto map(F&& callback, const Serie<T>& first, const Serie<T>& second, const Args&... args);
          
          // Member function version
          template <typename F>
          auto Serie<T>::map(F&& callback) const;
          
          // Bound version for pipeline operations
          template <typename F> auto bind_map(F&& callback);

Parameters

Parameter	Type	Description
callback	F&& (callable)	Function to transform each element. For single Serie version, should accept `(T value, size_t index)` and return the transformed value. For multi-Serie version, should accept `(T first_value, U second_value, ... args_values, size_t index)` and return the transformed value.
serie	const Serie<T>&	The Serie to transform.
first, second, args...	const Serie<T>&, const Serie<U>&, ...	Multiple Series to transform together.

Return Value

A new Serie containing the transformed values. The type of the returned Serie is automatically deduced from the return type of the callback function.

Example Usage

Basic Transformation


// Create a Serie
df::Serie<int> numbers{1, 2, 3, 4, 5};

// Using Serie member function to double each value
auto doubled = numbers.map([](int value, size_t) {
    return value * 2;
});  // {2, 4, 6, 8, 10}

// Using free function
auto squared = df::map([](int value, size_t) {
    return value * value;
}, numbers);  // {1, 4, 9, 16, 25}

// Using index in transformation
auto indexed = numbers.map([](int value, size_t index) {
    return value + static_cast(index);
});  // {1, 3, 5, 7, 9}

Type Conversion


// Create a Serie of integers
df::Serie<int> numbers{1, 2, 3, 4, 5};

// Convert to strings
auto strings = numbers.map([](int value, size_t) {
    return std::to_string(value);
});  // {"1", "2", "3", "4", "5"}

// Convert to booleans (even/odd)
auto even = numbers.map([](int value, size_t) {
    return value % 2 == 0;
});  // {false, true, false, true, false}

Multiple Series


// Create multiple Series
df::Serie<std::string> names{"Alice", "Bob", "Charlie"};
df::Serie<int> ages{25, 32, 28};

// Combine into a new Serie of strings
auto descriptions = df::map([](const std::string& name, int age, size_t) {
    return name + " is " + std::to_string(age) + " years old";
}, names, ages);
// {"Alice is 25 years old", "Bob is 32 years old", "Charlie is 28 years old"}

// Compute with multiple numerical Series
df::Serie<double> heights{1.65, 1.80, 1.75};  // in meters
df::Serie<double> weights{60.0, 75.0, 70.0};  // in kg

// Calculate BMI (weight / height²)
auto bmi = df::map([](double height, double weight, size_t) {
    return weight / (height * height);
}, heights, weights);

Pipeline Example


// Create a Serie
df::Serie<double> values{1.1, 2.2, 3.3, 4.4, 5.5};

// Use bind_map in a pipeline
auto rounded = values | df::bind_map([](double value, size_t) {
    return std::round(value);
});  // {1.0, 2.0, 3.0, 4.0, 6.0}

// Multiple transformations in a pipeline
auto processed = df::Serie<int>{1, 2, 3, 4, 5}
    | df::bind_map([](int x, size_t) { return x * 2; })            // Double
    | df::bind_map([](int x, size_t) { return x + 10; })           // Add 10
    | df::bind_map([](int x, size_t) { return std::to_string(x); });  // Convert to string
// {"12", "14", "16", "18", "20"}

Implementation Notes

Unlike forEach, map creates and returns a new Serie without modifying the original.
The return type of the callback function determines the element type of the returned Serie.
For multiple Series, all Series must have the same size.
The callback function is called once for each element, in order from first to last.
The index parameter is optional in the callback function.

map