/*---------------------------------------------------------- * HTBLA-Leonding, 2. JG * Marc Tismonar * --------------------------------------------------------- * Defines an abstract data type for managing a list of customers. * ---------------------------------------------------------- */ #ifndef __CUSTOMER_LIST_H #define __CUSTOMER_LIST_H #include /** * A customer list is organized as an array. MAX_LIST_ENTRIES defines the maximum * number of list entries. */ #define MAX_LIST_ENTRIES 13 /** * A CustomerListEntry consists of a unique customer ID, a name, * and the revenue (in €1000) associated with this customer. */ typedef struct CustomerListEntryData* CustomerListEntry; /** * The CustomerList stores the number of currently saved customer list * entries and an array to store the actual customer list entries. * @remark Memory for the customer list entries must be provided by the caller. * The `customers` array only manages references to customer list entries. */ typedef struct CustomerListData* CustomerList; /** * Provides the initialized empty instance of the customer list. * @return The customer list instance. */ CustomerList init_customer_list(); /** * @param cl The customer list data. * @return The number of entries in `cl` or a value less than zero if the list is invalid. */ int get_length(const CustomerList cl); /** * Creates an entry for a single customer. * @param id The ID of the customer. * @param customer_name The name of the customer. * @param revenue The revenue generated by that customer, in units of € 1000,-- (k€). * @return The entry if it could be created, else a null-entry (0). */ CustomerListEntry create_customer(int id, const char* customer_name, int revenue); /** * Adds an entry to the customer list. If the list is already full OR a customer * with the given ID already exists within the list, the entry is not added * and `false` is returned. * @param cl The customer list data. * @param id The ID of the customer. * @param customer_name The name of the customer. * @param revenue The revenue generated by that customer, in units of € 1000,-- (k€). * @return `true` if the addition was successful, `false` otherwise. * @see add_customers */ bool add_customer(CustomerList cl, int id, const char* customer_name, int revenue); /** * Adds `n` entries to the customer list. If the customer list cannot accommodate * all `n` entries without exceeding `MAX_LIST_ENTRIES`, none of the entries * are added, and `add_entries` returns `false`. * @param cl The customer list data. * @param e Array of pointers to entries to be added to `cl`. * @param n The number of entries in `e`. * @warning If `e` contains fewer than `n` entries, the function may crash due to * memory issues. * @return `true` if the addition was successful, `false` otherwise. Adding a customer is * considered being successful even if the customer was not added because it was already * included in the list. * @see add_customer */ bool add_customers(CustomerList cl, CustomerListEntry e[], int n); /** * Provides the customer with a specific index within the list. * @param cl The customer list data. * @param index The index of the requested customer. * @return The entry of the customer with the given index or null. */ CustomerListEntry get_customer_with_index(const CustomerList cl, int index); /** * Searches for a customer with a specific ID. * @param cl The customer list data. * @param id The unique customer ID to search for. * @return The entry of the customer with the given ID or null. */ CustomerListEntry get_customer_with_id(const CustomerList cl, int id); /** * Searches for customers within specific revenue bounds and returns them in the * order they are stored in the customer list. * @param cl The customer list data. * @param lower_bound The lower revenue limit. * @param upper_bound The upper revenue limit. * @param result_list The array holding the search results. * @param result_len The maximum number of entries that can be stored in the result list. * @return The number of entries found. */ int get_customers_with_revenue(const CustomerList cl, int lower_bound, int upper_bound, CustomerListEntry result_list[], int result_len); /** * Finds the customer with the highest revenue. If multiple customers have the * maximum revenue, the first customer in `cl` with this revenue is returned. * @param cl The customer list data. * @return The customer with the highest revenue. */ CustomerListEntry get_customer_with_highest_revenue(const CustomerList cl); /** * Finds the customer with the lowest revenue. If multiple customers have the * minimum revenue, the first customer in `cl` with this revenue is returned. * @param cl The customer list data. * @return The customer with the lowest revenue. */ CustomerListEntry get_customer_with_lowest_revenue(const CustomerList cl); /** * Finds the `n` customers with the highest revenue. If multiple customers satisfy * the search criteria, they are returned in the order they appear in the customer list. * @param cl The customer list data. * @param n The number of customers to find. * @param result_list Pointer to the list holding the search results. Must be of length 'n'. * @return The number of customers found. * @remark If `n` is greater than the number of customers in `cl`, only * `MAX_LIST_ENTRIES` entries are stored in `result_list`, and the return value is * `MAX_LIST_ENTRIES`. * @warning It is not verified whether `result_list` has sufficient size. If the size * of `result_list` is smaller than `n`, the function may crash due to memory issues. */ int get_top_n_customers_revenue(const CustomerList cl, int n, CustomerListEntry result_list[]); /** * Finds the `n` customers with the lowest revenue. If multiple customers satisfy * the search criteria, they are returned in the order they appear in the customer list. * @param cl The customer list data. * @param n The number of customers to find. * @param result_list Pointer to the list holding the search results. Must be of length 'n'. * @return The number of customers found. * @remark If `n` is greater than the number of customers in `cl`, only * `MAX_LIST_ENTRIES` entries are stored in `result_list`, and the return value is * `MAX_LIST_ENTRIES`. * @warning It is not verified whether `result_list` has sufficient size. If the size * of `result_list` is smaller than `n`, the function may crash due to memory issues. */ int get_bottom_n_customers_revenue(const CustomerList cl, int n, CustomerListEntry result_list[]); /** * @brief Provides the ID of the given customer. * @param customer The customer to query. * @return The ID of this customer or a value less than 0, * if the given customer is invalid. */ int get_customer_id(const CustomerListEntry customer); #endif