formatify/
placeholder_formatter.rs

1use std::collections::HashMap;
2
3/// Trait used to abstract Formatify from a system.
4pub trait PlaceholderFormatter {
5    /// Replaces placeholders in the input string with corresponding values from a HashMap.
6    ///
7    /// This method scans the input string `inp` for placeholders, identified by a specific
8    /// syntax, and replaces them with corresponding values from the `key_value` HashMap. The function
9    /// supports various types of placeholders, including simple variable substitution, alignment,
10    /// and optional truncation.
11    ///
12    /// For detailed information on supported placeholders, see [Supported Placeholder Types](#supported-placeholder-types).
13    ///
14    /// # Arguments
15    /// * `key_value` - A reference to a HashMap where keys correspond to placeholder identifiers in the input string and values are their replacements.
16    /// * `inp` - The input string containing placeholders.
17    ///
18    /// # Returns
19    /// A new `String` with placeholders replaced by their respective values from the `key_value` HashMap.
20    /// If a placeholder has no corresponding value in the map, it remains unchanged in the output string.
21    ///
22    /// # Examples
23    /// ```
24    /// # use formatify::{Formatify, PlaceholderFormatter};
25    /// # use std::collections::HashMap;
26    /// let mut key_value : HashMap<&str, String> = HashMap::new();
27    /// key_value.insert("name", "Alice".into());
28    /// key_value.insert("date", "Monday".into());
29    /// let formatter = Formatify::new();
30    /// let formatted_string = formatter.replace_placeholders(&key_value, "Hello, %(name)! Today is %<(10)%(date).");
31    /// assert_eq!(formatted_string, "Hello, Alice! Today is Monday    .");
32    /// ```
33    ///
34    /// This function is essential for dynamic string formatting in the Formatify library. It allows users
35    /// to create template strings with various types of placeholders, which can be filled with different values at runtime.
36    /// This is particularly useful for generating customized messages, dynamic user interfaces, or any other text-based content
37    /// that needs to be generated or modified based on changing data.
38    fn replace_placeholders(&self, key_value: &HashMap<&str, String>, inp: &str) -> String;
39
40    /// Measures the length of the entire string and the lengths of valid placeholders within it.
41    ///
42    /// This method processes the input string `inp`, which is analyzed as if it were to be formatted.
43    /// Instead of replacing the placeholders, it calculates the overall length of the string with
44    /// placeholders hypothetically replaced, followed by the lengths of each valid placeholder. This
45    /// is particularly useful for layout planning and understanding the impact of placeholders on the
46    /// total length of the string.
47    ///
48    /// For detailed information on supported placeholders, see [Supported Placeholder Types](#supported-placeholder-types).
49    ///
50    /// # Arguments
51    /// * `key_value` - A reference to a HashMap containing key-value pairs. The keys represent placeholders in the input string, and the values are their potential replacements.
52    /// * `inp` - The input string with placeholders to be measured.
53    ///
54    /// # Returns
55    /// A `Vec<usize>` where the first element represents the length of the entire string with placeholders
56    /// replaced, and subsequent elements represent the lengths of each valid placeholder. Placeholders
57    /// are replaced with their corresponding values from the `key_value` HashMap for these calculations.
58    ///
59    /// # Examples
60    /// ```
61    /// # use formatify::{Formatify, PlaceholderFormatter};
62    /// # use std::collections::HashMap;
63    /// let mut key_value : HashMap<&str, String> = HashMap::new();
64    /// key_value.insert("name", "Alice".into());
65    /// let formatter = Formatify::new();
66    /// let lengths = formatter.measure_lengths(&key_value, "Hello, %(name)! This is a test.");
67    /// assert_eq!(lengths, vec![29, 5]); // Total length with "Alice" as the placeholder, length of "Alice"
68    /// ```
69    fn measure_lengths(&self, key_value: &HashMap<&str, String>, inp: &str) -> Vec<usize>;
70
71    /// Extracts and lists all placeholder keys from a given string.
72    ///
73    /// This method analyzes the input string `inp` to identify and collect the keys of all
74    /// placeholders defined within it. Placeholders are identified by a specific syntax, typically
75    /// denoted by `%(key)`. This function is particularly useful for determining which placeholders
76    /// are used in a string without modifying the string itself. It helps in preparing or validating
77    /// the necessary keys in a key-value map for subsequent processing, like formatting or replacing
78    /// placeholders. Single char and formatting placeholders are ignored by this function.
79    ///  
80    /// For detailed information on supported placeholders, see [Supported Placeholder Types](#supported-placeholder-types).
81    ///
82    /// # Arguments
83    /// * `inp` - The input string to be analyzed for placeholder keys.
84    ///
85    /// # Returns
86    /// A `Vec<String>` containing all placeholder keys found in the input string. If no
87    /// valid placeholders are found, an empty vector is returned.
88    ///
89    /// # Examples
90    /// ```
91    /// # use formatify::{Formatify, PlaceholderFormatter};
92    /// let formatter = Formatify::new();
93    /// let placeholder_keys = formatter.extract_placeholder_keys("Hello, %(name)! Today is %(day).");
94    /// assert_eq!(placeholder_keys, vec!["name", "day"]);
95    /// ```
96    fn extract_placeholder_keys(&self, inp: &str) -> Vec<String>;
97}
formatify/placeholder_formatter.rs

formatify/
placeholder_formatter.rs
