format Function - DataFrame Library Documentation

Overview

The format function converts a Serie of objects to a formatted string representation. It allows customizing separators, prefixes, and suffixes to control the output format, making it useful for display, logging, or generating formatted text output.

Function Signatures


// Format a Serie with prefix, separator, and suffix
template <typename T>
std::string format(const Serie<T>& serie, 
                  const std::string& prefix = "[",
                  const std::string& separator = ", ",
                  const std::string& suffix = "]");

// Create a pipeline-compatible formatter
template <typename... Args>
auto bind_format(const Args&... args);

Parameters

Parameter	Type	Default	Description
serie	const Serie<T>&	-	The Serie to format as a string.
prefix	const std::string&	"["	String to prepend to the formatted output.
separator	const std::string&	", "	String to insert between elements in the formatted output.
suffix	const std::string&	"]"	String to append to the formatted output.
args	const Args&...	-	For bind_format: objects to include in the formatted output.

Return Value

The format function returns a std::string containing the formatted representation of the Serie.

The bind_format function returns a callable object that can be used in a pipeline to format values.

Example Usage

Basic Formatting


// Create numeric Series
df::Serie<int> integers{1, 2, 3, 4, 5};
df::Serie<double> decimals{1.1, 2.2, 3.3, 4.4, 5.5};

// Format with default options (square brackets and comma separator)
std::string int_str = df::format(integers);
std::cout << int_str << std::endl;
// Output: [1, 2, 3, 4, 5]

// Format with custom separator
std::string dec_str = df::format(decimals, "[", " | ", "]");
std::cout << dec_str << std::endl;
// Output: [1.1 | 2.2 | 3.3 | 4.4 | 5.5]

// Without brackets
std::string plain = df::format(integers, "", ", ", "");
std::cout << plain << std::endl;
// Output: 1, 2, 3, 4, 5

// With parentheses instead of brackets
std::string parens = df::format(integers, "(", ", ", ")");
std::cout << parens << std::endl;
// Output: (1, 2, 3, 4, 5)

Formatting Complex Types


// String Series
df::Serie<std::string> names{"Alice", "Bob", "Charlie", "David"};
std::string name_list = df::format(names, "Names: [", ", ", "]");
std::cout << name_list << std::endl;
// Output: Names: [Alice, Bob, Charlie, David]

// Vector Series (using std::array in the Serie)
df::Serie<Vector2> points{
    {1.0, 2.0},
    {3.0, 4.0},
    {5.0, 6.0}
};
std::string coords = df::format(points);
std::cout << coords << std::endl;
// Output: [[1,2], [3,4], [5,6]]

// Custom types (requires operator<< to be defined)
struct Person {
    std::string name;
    int age;
    
    friend std::ostream& operator<<(std::ostream& os, const Person& p) {
        return os << p.name << " (" << p.age << ")";
    }
};

df::Serie<Person> people{
    {"Alice", 30},
    {"Bob", 25},
    {"Charlie", 35}
};

std::string people_str = df::format(people, "People: ", "\n- ", "");
std::cout << people_str << std::endl;
// Output:
// People: 
// - Alice (30)
// - Bob (25)
// - Charlie (35)

Using bind_format in Pipelines


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

// Simple pipeline formatting
std::string result = numbers 
    | df::bind_map([](int x, size_t) { return x * 2; })  // Double each number
    | df::bind_format("{", ", ", "}");                  // Format with custom delimiters
std::cout << result << std::endl;
// Output: {2, 4, 6, 8, 10}

// More complex pipeline with multiple operations
std::string complex_result = numbers
    | df::bind_filter([](int x, size_t) { return x % 2 == 1; })  // Keep odd numbers
    | df::bind_map([](int x, size_t) { return x * x; })          // Square each number
    | df::bind_format("Odd squares: ", " ~ ", "");              // Format with custom delimiters
std::cout << complex_result << std::endl;
// Output: Odd squares: 1 ~ 9 ~ 25

// Concatenating strings in a pipeline
std::string greeting = "Hello"
    | df::bind_format(", ", "world", "!")
    | df::bind_format("(", "Greeting: ", ")");
std::cout << greeting << std::endl;
// Output: (Greeting: Hello, world!)

Practical Applications


// Creating CSV rows from a Serie
df::Serie<std::string> csv_fields{"name", "age", "city"};
std::string csv_header = df::format(csv_fields, "", ",", "");
std::cout << csv_header << std::endl;
// Output: name,age,city

// Building SQL queries
df::Serie<std::string> columns{"id", "name", "age"};
std::string select_clause = "SELECT " + df::format(columns, "", ", ", "");
std::cout << select_clause << " FROM users" << std::endl;
// Output: SELECT id, name, age FROM users

// Constructing HTML lists
df::Serie<std::string> items{"apple", "banana", "cherry"};
std::string html_list = df::format(items, "<ul>\n  <li>", "</li>\n  <li>", "</li>\n</ul>");
std::cout << html_list << std::endl;
// Output:
// 
//   apple
//   banana
//   cherry
// 

// Creating JSON array
df::Serie<std::string> json_values{"\"Alice\"", "\"Bob\"", "\"Charlie\""};
std::string json_array = df::format(json_values, "[", ", ", "]");
std::cout << json_array << std::endl;
// Output: ["Alice", "Bob", "Charlie"]

Implementation Notes

The format function relies on operator<< being defined for the type T of the Serie elements.
For empty Series, the result will be the concatenation of the prefix and suffix (e.g., [] with default parameters).
The function handles all types that can be converted to strings via the stream insertion operator.
For custom types, ensure that operator<< is properly defined to control how the type is converted to a string.
The bind_format function is particularly useful in pipeline expressions where it can be combined with other operations like map, filter, etc.

Performance Considerations

For large Series, string concatenation can be expensive. The function uses std::ostringstream internally to minimize allocations.
Consider the size of the Serie when choosing separator, prefix, and suffix strings, as these will affect the final string size.
When using the function in performance-critical code, prefer direct iteration over the Serie for very large datasets.

format