167 lines
6.8 KiB
C
167 lines
6.8 KiB
C
/*----------------------------------------------------------
|
|
* 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 <stdbool.h>
|
|
|
|
/**
|
|
* 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
|