Comparing Chars In C effectively is crucial for various programming tasks. At compare.edu.vn, we delve into the most efficient methods for comparing characters in C, focusing on both performance and readability. This includes exploring strcmp()
and other techniques to optimize your code. Discover how to streamline your comparisons and enhance your programming projects.
1. What Are the Basics of Character Comparison in C?
Character comparison in C involves evaluating if two characters are the same, different, or ordered in a specific way. It uses the ASCII values of characters to determine relationships, which is vital for string manipulation, input validation, and decision-making processes in programs.
In C, characters are represented as integers based on their ASCII values. Comparing characters involves comparing these integer values. The standard comparison operators (==
, !=
, <
, >
, <=
, >=
) can be used directly to compare character variables or literals. Here’s a breakdown:
==
(Equal to): Checks if two characters have the same ASCII value.!=
(Not equal to): Checks if two characters have different ASCII values.<
(Less than): Checks if the ASCII value of the first character is less than that of the second.>
(Greater than): Checks if the ASCII value of the first character is greater than that of the second.<=
(Less than or equal to): Checks if the ASCII value of the first character is less than or equal to that of the second.>=
(Greater than or equal to): Checks if the ASCII value of the first character is greater than or equal to that of the second.
1.1 How to compare single characters
Comparing single characters in C is straightforward and involves using the basic comparison operators. This method is commonly used for validating input, controlling program flow, and other simple decision-making processes.
Example:
#include <stdio.h>
int main() {
char char1 = 'A';
char char2 = 'B';
if (char1 == char2) {
printf("The characters are equal.n");
} else {
printf("The characters are not equal.n");
}
if (char1 < char2) {
printf("'A' is less than 'B'.n");
} else {
printf("'A' is not less than 'B'.n");
}
return 0;
}
In this example, char1
is assigned the character 'A'
and char2
is assigned the character 'B'
. The if
statements compare these characters using the ==
and <
operators. The output shows that the characters are not equal and that 'A'
is less than 'B'
, based on their ASCII values.
1.2 What are the common pitfalls in character comparison?
Several common pitfalls can occur when comparing characters in C, especially for beginners. Being aware of these can help you write more robust and error-free code.
1. Confusing Character Literals with Strings:
- Pitfall: Using double quotes
"
for character literals instead of single quotes'
. - Explanation: Single quotes denote a character literal (e.g.,
'A'
), while double quotes denote a string literal (e.g.,"A"
). A string literal is an array of characters terminated by a null character.
- Example:
char character = "A"; // Incorrect: "A" is a string char character = 'A'; // Correct: 'A' is a character
2. Ignoring Case Sensitivity:
-
Pitfall: Comparing characters without considering whether they are uppercase or lowercase.
-
Explanation: In ASCII, uppercase and lowercase letters have different values (e.g.,
'A'
is 65, and'a'
is 97). -
Solution: Use functions like
tolower()
ortoupper()
from<ctype.h>
to convert characters to the same case before comparing. -
Example:
#include <stdio.h> #include <ctype.h> int main() { char char1 = 'A'; char char2 = 'a'; if (tolower(char1) == tolower(char2)) { printf("The characters are equal (case-insensitive).n"); } else { printf("The characters are not equal (case-insensitive).n"); } return 0; }
3. Comparing Characters with Integers Directly:
- Pitfall: While characters are represented as integers, directly comparing them without understanding ASCII values can lead to confusion.
- Explanation: Characters are often compared based on their ASCII values, but it’s important to know which character corresponds to which value.
- Example:
char character = 65; // This is equivalent to 'A' if (character == 'A') { printf("The character is 'A'.n"); }
4. Assuming Specific Character Encodings:
- Pitfall: Assuming that all systems use the same character encoding (e.g., ASCII).
- Explanation: While ASCII is common, other encodings like UTF-8 or EBCDIC exist. Code that assumes ASCII may not work correctly on systems using different encodings.
- Note: For most modern systems, ASCII or UTF-8 are prevalent, but being aware of potential differences is important for portability.
5. Incorrectly Using Comparison Operators:
- Pitfall: Using the wrong comparison operator (e.g.,
=
instead of==
). - Explanation: The assignment operator
=
assigns a value, while the equality operator==
compares two values. - Example:
char char1 = 'A'; if (char1 = 'B') { // Incorrect: Assignment, always true printf("This will always print.n"); } if (char1 == 'B') { // Correct: Comparison printf("This will print only if char1 is 'B'.n"); }
6. Not Handling Special Characters Correctly:
- Pitfall: Failing to account for special characters like null terminators (
), newline characters (
n
), or escape sequences. - Explanation: Special characters have specific meanings in C and can affect comparisons.
- Example: When reading strings, ensure that you handle the null terminator correctly to avoid reading beyond the allocated memory.
7. Ignoring Locale-Specific Behavior:
- Pitfall: Assuming character comparisons are consistent across different locales.
- Explanation: The behavior of functions like
tolower()
andtoupper()
can change based on the current locale, affecting comparisons. - Note: This is more relevant in internationalized applications where character handling must adapt to different language settings.
By understanding and avoiding these common pitfalls, you can write more reliable and accurate character comparison code in C. Always double-check your assumptions about character encoding, case sensitivity, and the correct use of comparison operators.
2. How Does strcmp()
Function Work for Character Arrays?
The strcmp()
function in C is used to compare two strings (character arrays). It is defined in the <string.h>
header file. The function compares the strings character by character until it finds a difference or reaches the end of the strings.
2.1 What is the syntax of strcmp()
?
The syntax for strcmp()
is:
int strcmp(const char *str1, const char *str2);
str1
: A pointer to the first string to be compared.str2
: A pointer to the second string to be compared.
The function returns:
- 0: If the strings are identical.
- A negative value: If
str1
is lexicographically less thanstr2
. - A positive value: If
str1
is lexicographically greater thanstr2
.
2.2 How to use strcmp()
effectively?
To use strcmp()
effectively, consider the following points:
- Include the Header: Always include
<string.h>
at the beginning of your program. - Null-Terminated Strings: Ensure that the character arrays you are comparing are null-terminated.
strcmp()
relies on the null terminator () to determine the end of the string.
- Case Sensitivity:
strcmp()
is case-sensitive. If you need a case-insensitive comparison, usestrcasecmp()
(a non-standard function available on many systems) or convert the strings to the same case before comparing. - Error Handling:
strcmp()
does not perform bounds checking. Ensure that the strings you are comparing are properly allocated and do not cause buffer overflows.
Example:
#include <stdio.h>
#include <string.h>
int main() {
char str1[] = "Hello";
char str2[] = "Hello";
char str3[] = "World";
int result1 = strcmp(str1, str2); // Returns 0
int result2 = strcmp(str1, str3); // Returns a negative value
if (result1 == 0) {
printf("str1 and str2 are equal.n");
} else {
printf("str1 and str2 are not equal.n");
}
if (result2 < 0) {
printf("str1 is less than str3.n");
} else {
printf("str1 is not less than str3.n");
}
return 0;
}
2.3 What are the alternatives to strcmp()
?
While strcmp()
is the standard function for comparing strings in C, there are alternatives that can be used depending on specific requirements. Here are some notable alternatives:
1. strncmp()
:
-
Purpose: Compares the first
n
characters of two strings. -
Syntax:
int strncmp(const char *str1, const char *str2, size_t n);
-
Use Case: Useful when you need to compare only a portion of the strings.
-
Example:
#include <stdio.h> #include <string.h> int main() { char str1[] = "HelloWorld"; char str2[] = "HelloC++"; int result = strncmp(str1, str2, 5); // Compare first 5 characters if (result == 0) { printf("The first 5 characters are equal.n"); } else { printf("The first 5 characters are not equal.n"); } return 0; }
2. strcasecmp()
/ stricmp()
:
-
Purpose: Performs a case-insensitive comparison of two strings.
-
Syntax:
int strcasecmp(const char *str1, const char *str2);
(orstricmp()
on some systems) -
Availability:
strcasecmp()
is a POSIX function, whilestricmp()
is typically found in Windows environments. -
Use Case: Useful when you want to compare strings without regard to case.
-
Example:
#include <stdio.h> #include <string.h> int main() { char str1[] = "Hello"; char str2[] = "hello"; int result = strcasecmp(str1, str2); if (result == 0) { printf("The strings are equal (case-insensitive).n"); } else { printf("The strings are not equal (case-insensitive).n"); } return 0; }
3. Manual Comparison:
-
Purpose: Implementing your own comparison logic using loops and conditional statements.
-
Use Case: Useful when you need more control over the comparison process or when dealing with specific encoding requirements.
-
Example:
#include <stdio.h> #include <stdbool.h> bool compareStrings(const char *str1, const char *str2) { int i = 0; while (str1[i] != '' && str2[i] != '') { if (str1[i] != str2[i]) { return false; } i++; } return (str1[i] == '' && str2[i] == ''); } int main() { char str1[] = "Hello"; char str2[] = "Hello"; char str3[] = "World"; if (compareStrings(str1, str2)) { printf("str1 and str2 are equal.n"); } else { printf("str1 and str2 are not equal.n"); } if (compareStrings(str1, str3)) { printf("str1 and str3 are equal.n"); } else { printf("str1 and str3 are not equal.n"); } return 0; }
4. memcmp()
:
-
Purpose: Compares two blocks of memory.
-
Syntax:
int memcmp(const void *ptr1, const void *ptr2, size_t num);
-
Use Case: Can be used to compare strings, but it treats them as blocks of memory. It’s more generic and doesn’t assume null-terminated strings.
-
Example:
#include <stdio.h> #include <string.h> int main() { char str1[] = "Hello"; char str2[] = "Hello"; int result = memcmp(str1, str2, strlen(str1)); if (result == 0) { printf("str1 and str2 are equal.n"); } else { printf("str1 and str2 are not equal.n"); } return 0; }
5. Custom Hash Functions:
-
Purpose: Generate a unique hash value for each string and compare the hash values.
-
Use Case: Can be faster for very long strings or when comparing strings frequently in a lookup table.
-
Note: Requires careful implementation to avoid hash collisions.
#include <stdio.h> #include <string.h> #include <stdint.h> // For uint32_t // Simple hash function (not collision-resistant) uint32_t hashString(const char *str) { uint32_t hash = 5381; int c; while ((c = *str++)) { hash = ((hash << 5) + hash) + c; /* hash * 33 + c */ } return hash; } int main() { char str1[] = "Hello"; char str2[] = "Hello"; char str3[] = "World"; uint32_t hash1 = hashString(str1); uint32_t hash2 = hashString(str2); uint32_t hash3 = hashString(str3); if (hash1 == hash2) { printf("str1 and str2 are equal (based on hash).n"); } else { printf("str1 and str2 are not equal (based on hash).n"); } if (hash1 == hash3) { printf("str1 and str3 are equal (based on hash).n"); } else { printf("str1 and str3 are not equal (based on hash).n"); } return 0; }
2.4 When to use strcmp()
?
strcmp()
is most suitable when you need to compare entire strings and differentiate between them lexicographically. It’s also useful when you need a simple and standard way to check for equality or inequality between two strings in a case-sensitive manner.
Here are some scenarios where strcmp()
is particularly useful:
- Sorting: When sorting an array of strings alphabetically.
- Searching: When searching for a specific string in a list of strings.
- Validating Input: When checking if user input matches a specific string.
- Comparing Configuration Values: When comparing configuration values read from a file.
3. What is the Efficiency of Different Comparison Methods?
The efficiency of different character comparison methods in C can vary significantly based on factors such as the length of the strings, the specific requirements of the comparison (e.g., case-sensitivity), and the underlying hardware and compiler optimizations. Here’s an overview of the efficiency of different methods:
3.1 strcmp()
and strncmp()
:
- Efficiency:
strcmp()
andstrncmp()
are generally efficient for comparing strings because they are implemented in highly optimized assembly code in most standard C libraries. - Complexity: The time complexity of
strcmp()
is O(n), where n is the length of the shorter string being compared. In the worst case, it needs to compare every character until it reaches the end of one of the strings or finds a difference.strncmp()
has a similar complexity but is bounded by the specified number of characters to compare. - Use Case: Suitable for general-purpose string comparison, especially when you need to compare entire strings or a specific prefix.
3.2 strcasecmp()
/ stricmp()
:
- Efficiency:
strcasecmp()
andstricmp()
perform case-insensitive comparisons, which typically involves converting characters to the same case before comparing them. This additional step can make them slightly less efficient thanstrcmp()
. - Complexity: The time complexity is still O(n), but the actual time taken can be higher due to the case conversion.
- Use Case: Ideal when case-insensitive comparison is required.
3.3 Manual Comparison:
- Efficiency: Manual comparison involves writing your own loop to compare characters one by one. The efficiency can vary depending on how well the loop is optimized.
- Complexity: The time complexity is O(n), similar to
strcmp()
. However, the overhead of the loop and conditional checks can make it less efficient than the optimizedstrcmp()
function provided by the standard library. - Use Case: Useful when you need fine-grained control over the comparison process or when dealing with specific encoding requirements.
3.4 memcmp()
:
- Efficiency:
memcmp()
compares blocks of memory and can be used for string comparison. It is generally very efficient because it operates at the memory level. - Complexity: The time complexity is O(n), where n is the number of bytes to compare.
- Use Case: Suitable for comparing strings or other data structures where you want to compare a specific number of bytes.
3.5 Hash Functions:
- Efficiency: Using hash functions to compare strings involves calculating a hash value for each string and then comparing the hash values. This can be very efficient, especially for long strings, because the comparison is reduced to comparing two integer values.
- Complexity: The time complexity of calculating the hash is O(n), where n is the length of the string. However, the comparison of hash values is O(1).
- Use Case: Useful when comparing strings frequently in a lookup table or when you need very fast comparisons. However, you need to handle hash collisions, which can add complexity.
3.6 Table: Efficiency Comparison of String Comparison Methods
Method | Efficiency | Complexity | Use Case |
---|---|---|---|
strcmp() |
High | O(n) | General-purpose string comparison, case-sensitive. |
strncmp() |
High | O(n) | Comparing a specific prefix of strings, case-sensitive. |
strcasecmp() |
Medium | O(n) | Case-insensitive string comparison. |
Manual | Variable | O(n) | Fine-grained control over comparison, specific encoding requirements. |
memcmp() |
High | O(n) | Comparing blocks of memory, including strings. |
Hash Functions | Very High | O(n) + O(1) | Frequent string comparisons in lookup tables, very long strings. Requires collision handling. |
3.7 Factors Affecting Efficiency:
- String Length: For very short strings, the overhead of function calls might outweigh the benefits of optimized functions like
strcmp()
. - Case Sensitivity: Case-insensitive comparisons are generally slower due to the additional case conversion step.
- Hardware and Compiler: Modern compilers can optimize string comparison functions significantly. The underlying hardware also plays a role in the speed of memory access and processing.
3.8 Best Practices for Efficiency:
- Use Standard Library Functions: Whenever possible, use the standard library functions like
strcmp()
,strncmp()
, andmemcmp()
because they are highly optimized. - Minimize Case Conversions: If case sensitivity is not required, avoid case conversions to improve performance.
- Consider Hash Functions: For frequent comparisons of long strings, consider using hash functions to reduce the comparison to integer comparisons.
- Profile Your Code: Use profiling tools to measure the actual performance of different comparison methods in your specific application.
4. How to Optimize String Comparison in C?
Optimizing string comparison in C can significantly improve the performance of your programs, especially when dealing with large datasets or performance-critical applications. Here are several strategies to optimize string comparison:
4.1 Use Efficient Comparison Functions:
strcmp()
andstrncmp()
: These are highly optimized functions in the C standard library. Use them whenever possible for general-purpose string comparison.memcmp()
: For comparing a specific number of bytes,memcmp()
can be very efficient.
4.2 Minimize Case Conversions:
- Case-Sensitive Comparisons: If case sensitivity is not required, avoid using case conversion functions like
tolower()
ortoupper()
before comparing strings. - Pre-Process Strings: If you need to perform multiple case-insensitive comparisons, convert the strings to the same case once and store the converted strings for future comparisons.
4.3 Use Hash Functions:
- Hash Table Lookup: For frequent string comparisons, especially in lookup tables, use hash functions to generate a unique hash value for each string and compare the hash values instead of the strings themselves.
- Collision Handling: Choose a good hash function and implement collision handling to ensure that the hash table works correctly.
4.4 Short-Circuit Evaluation:
- Early Exit: In manual comparison loops, check for inequality as early as possible and exit the loop immediately if a difference is found.
4.5 Optimize Memory Access:
- Cache-Friendly Access: Ensure that the strings you are comparing are stored in contiguous memory locations to improve cache performance.
- Avoid Unnecessary Copies: Minimize the number of string copies to reduce memory overhead.
4.6 Use SIMD Instructions:
- SIMD (Single Instruction, Multiple Data): Modern CPUs support SIMD instructions that can perform the same operation on multiple data elements simultaneously. Use SIMD instructions to compare multiple characters in parallel.
- Compiler Optimization: Compilers can automatically generate SIMD instructions for string comparison if you enable optimization flags (e.g.,
-O3
in GCC).
4.7 Profile Your Code:
- Profiling Tools: Use profiling tools like
gprof
orperf
to identify the hotspots in your code and measure the actual performance of different string comparison methods. - Experiment: Try different optimization techniques and measure their impact on performance to find the best approach for your specific application.
4.8 Example: Optimizing Case-Insensitive Comparison
#include <stdio.h>
#include <string.h>
#include <ctype.h>
// Optimized case-insensitive comparison
int compareCaseInsensitive(const char *str1, const char *str2) {
while (*str1 && *str2) {
int diff = tolower((unsigned char)*str1) - tolower((unsigned char)*str2);
if (diff != 0) {
return diff;
}
str1++;
str2++;
}
return tolower((unsigned char)*str1) - tolower((unsigned char)*str2);
}
int main() {
char str1[] = "Hello";
char str2[] = "hello";
int result = compareCaseInsensitive(str1, str2);
if (result == 0) {
printf("The strings are equal (case-insensitive).n");
} else {
printf("The strings are not equal (case-insensitive).n");
}
return 0;
}
4.9 Table: Optimization Techniques for String Comparison
Technique | Description |
---|---|
Efficient Functions | Use strcmp() , strncmp() , memcmp() for optimized comparisons. |
Minimize Case Conversions | Avoid unnecessary case conversions, pre-process if needed. |
Hash Functions | Use hash functions for frequent comparisons, handle collisions. |
Short-Circuit Evaluation | Exit comparison loops early when a difference is found. |
Memory Access | Ensure contiguous memory access, avoid unnecessary copies. |
SIMD Instructions | Use SIMD instructions for parallel comparison, enable compiler optimizations. |
Profiling | Use profiling tools to identify hotspots, experiment with different techniques. |
By applying these optimization techniques, you can significantly improve the performance of string comparison in your C programs, making them faster and more efficient.
5. What Are Some Real-World Examples of Comparing Chars in C?
Comparing characters in C is a fundamental operation with numerous applications in real-world software development. Here are several examples illustrating how character comparison is used in various scenarios:
5.1 Input Validation:
- Scenario: Validating user input to ensure it meets specific criteria.
- Example:
#include <stdio.h>
#include <ctype.h>
#include <stdbool.h>
bool isValidInput(const char *input) {
for (int i = 0; input[i] != ''; i++) {
if (!isalnum(input[i])) {
return false; // Input contains non-alphanumeric characters
}
}
return true; // Input is valid
}
int main() {
char input[] = "ValidInput123";
if (isValidInput(input)) {
printf("Input is valid.n");
} else {
printf("Input is invalid.n");
}
return 0;
}
- Explanation: This example checks if the input string contains only alphanumeric characters using the
isalnum()
function.
5.2 Parsing Data:
- Scenario: Parsing data from a file or network stream.
- Example:
#include <stdio.h>
#include <string.h>
int main() {
char data[] = "name=John,age=30";
char *token;
char *delimiter = ",=";
token = strtok(data, delimiter);
while (token != NULL) {
if (strcmp(token, "name") == 0) {
token = strtok(NULL, delimiter);
printf("Name: %sn", token);
} else if (strcmp(token, "age") == 0) {
token = strtok(NULL, delimiter);
printf("Age: %sn", token);
}
token = strtok(NULL, delimiter);
}
return 0;
}
- Explanation: This example parses a string of comma-separated key-value pairs using
strtok()
and compares the keys to extract the values.
5.3 String Searching:
- Scenario: Searching for a specific substring within a larger string.
- Example:
#include <stdio.h>
#include <string.h>
int main() {
char text[] = "This is a sample text.";
char search[] = "sample";
char *result = strstr(text, search);
if (result != NULL) {
printf("Substring found at position: %ldn", result - text);
} else {
printf("Substring not found.n");
}
return 0;
}
- Explanation: This example uses
strstr()
to find the first occurrence of a substring within a larger string.
5.4 Sorting Algorithms:
- Scenario: Implementing sorting algorithms for strings.
- Example:
#include <stdio.h>
#include <string.h>
void bubbleSort(char arr[][50], int n) {
for (int i = 0; i < n - 1; i++) {
for (int j = 0; j < n - i - 1; j++) {
if (strcmp(arr[j], arr[j + 1]) > 0) {
char temp[50];
strcpy(temp, arr[j]);
strcpy(arr[j], arr[j + 1]);
strcpy(arr[j + 1], temp);
}
}
}
}
int main() {
char strings[][50] = {"banana", "apple", "orange", "grape"};
int n = sizeof(strings) / sizeof(strings[0]);
bubbleSort(strings, n);
printf("Sorted strings:n");
for (int i = 0; i < n; i++) {
printf("%sn", strings[i]);
}
return 0;
}
- Explanation: This example sorts an array of strings using the bubble sort algorithm and
strcmp()
for comparison.
5.5 File Handling:
- Scenario: Reading and processing text files.
- Example:
#include <stdio.h>
#include <string.h>
int main() {
FILE *file = fopen("example.txt", "r");
if (file == NULL) {
perror("Error opening file");
return 1;
}
char line[100];
while (fgets(line, sizeof(line), file) != NULL) {
if (strstr(line, "keyword") != NULL) {
printf("Found keyword in line: %s", line);
}
}
fclose(file);
return 0;
}
- Explanation: This example reads a text file line by line and searches for a specific keyword using
strstr()
.
5.6 Network Programming:
- Scenario: Handling network protocols and data.
- Example:
#include <stdio.h>
#include <string.h>
int main() {
char protocol[] = "HTTP/1.1 200 OK";
if (strncmp(protocol, "HTTP/1.1", 8) == 0) {
printf("Valid HTTP protocol.n");
} else {
printf("Invalid HTTP protocol.n");
}
return 0;
}
- Explanation: This example checks if a network protocol string starts with “HTTP/1.1” using
strncmp()
.
5.7 Command-Line Arguments:
- Scenario: Parsing command-line arguments.
- Example:
#include <stdio.h>
#include <string.h>
int main(int argc, char *argv[]) {
for (int i = 1; i < argc; i++) {
if (strcmp(argv[i], "-help") == 0) {
printf("Displaying help information.n");
} else if (strcmp(argv[i], "-version") == 0) {
printf("Displaying version information.n");
}
}
return 0;
}
- Explanation: This example parses command-line arguments and checks for specific options like “-help” and “-version”.
5.8 Configuration Files:
- Scenario: Reading and parsing configuration files.
- Example:
#include <stdio.h>
#include <string.h>
int main() {
FILE *file = fopen("config.txt", "r");
if (file == NULL) {
perror("Error opening file");
return 1;
}
char line[100];
while (fgets(line, sizeof(line), file) != NULL) {
char *key = strtok(line, "=");
char *value = strtok(NULL, "n");
if (key != NULL && value != NULL) {
if (strcmp(key, "username") == 0) {
printf("Username: %sn", value);
} else if (strcmp(key, "password") == 0) {
printf("Password: %sn", value);
}
}
}
fclose(file);
return 0;
}
- Explanation: This example reads a configuration file, parses key-value pairs, and extracts configuration settings.
5.9 Data Structures:
- Scenario: Managing and comparing strings within data structures.
- Example:
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
typedef struct {
char name[50];
int age;
} Person;
int comparePersons(const void *a, const void *b) {
const Person *personA = (const Person *)a;
const Person *personB = (const Person *)b;
return strcmp(personA->name, personB->name);
}
int main() {
Person people[] = {
{"John", 30},
{"Alice", 25},
{"Bob", 35}
};
int n = sizeof(people) / sizeof(people[0]);
qsort(people, n, sizeof(Person), comparePersons);
printf("Sorted persons:n");
for (int i = 0; i < n; i++) {
printf("Name: %s, Age: %dn", people[i].name, people[i].age);
}
return 0;
}
- Explanation: This example defines a
Person
struct and usesstrcmp()
to compare names when sorting an array ofPerson
structs usingqsort()
.
5.10 Table: Real-World Examples of Character Comparison in C
| Scenario | Description | Example Function(s) |
| —————-