log.h File Reference

Go to the source code of this file.

Data Structures

struct  log_t
 The log data structure. More...

Functions

void log_init (log_t *l)
 Initializes the log.
void log_destroy (log_t *l)
 Frees all internal memory associated with the log.
void log_append (log_t *l, char *item)
 Appends an item to the end of the log.
char * log_pop (log_t *l)
 Removes and returns the last item in the log.
char * log_at (log_t *l, unsigned int idx)
 Returns a pointer to the idx-th element in the log, where the 0-th element is the first element appended to the log.
unsigned int log_size (log_t *l)
 Returns the number of elements in the log.
char * log_search (log_t *l, const char *prefix)
 Preforms a newest-to-oldest search of log entries for an entry matching a given prefix.

Detailed Description

Function Documentation

void log_append ( log_t *  l,
char *  item 
)

Appends an item to the end of the log.

The item MUST NOT be copied. Only a pointer is stored in the log.

You may assume that:

  • All pointers will be valid, non-NULL pointer.
Parameters:
l Pointer to the log data structure.
item Pointer to a string to be added to the log.
char* log_at ( log_t *  l,
unsigned int  idx 
)

Returns a pointer to the idx-th element in the log, where the 0-th element is the first element appended to the log.

You may assume that:

  • All pointers will be valid, non-NULL pointer.
Parameters:
l Pointer to the log data structure.
idx Zero-based index into the log, where the 0-th entry corresponds to the first (oldest) entry in the log and the (n-1)-th entry corresponds to the latest (newest) entry in the log.
Returns:
The idx-th entry in the log, or NULL if such an extry does not exist.
void log_destroy ( log_t *  l  ) 

Frees all internal memory associated with the log.

You may assume that:

  • This function will be called once per instance of log_t.
  • This funciton will be the last function called per instance of log_t.
  • All pointers will be valid, non-NULL pointer.
Parameters:
l Pointer to the log data structure to be destoryed.
void log_init ( log_t *  l  ) 

Initializes the log.

You may assuem that:

  • This function will only be called once per instance of log_t.
  • This function will be the first function called per instance of log_t.
  • All pointers will be valid, non-NULL pointer.
Parameters:
l Pointer to the log data structure to be initialized.
char* log_pop ( log_t *  l  ) 

Removes and returns the last item in the log.

If this function was called following a call to log_append(), the return value will be the value that was just to the log. If multiple calls are made to log_pop(), is should continue to remove entries from the log in a Last-In First-Out (LIFO) or "stack" order.

You may assume that:

  • All pointers will be valid, non-NULL pointer.
Parameters:
l Pointer to the log data structure.
Returns:
The last item in the log, or NULL if the log is empty.
char* log_search ( log_t *  l,
const char *  prefix 
)

Preforms a newest-to-oldest search of log entries for an entry matching a given prefix.

This search starts with the newest or (n-1)-th entry in the log and compares each entry to determine if query is a prefix of the log entry. Upon reaching a match, a pointer to that element is returned. If no match is found, a NULL pointer is returned.

For example, a log may be built with five entries: 

    log_append(&l, "ab  1");
    log_append(&l, "a   2");
    log_append(&l, "abc 3");
    log_append(&l, "ab  4");
    log_append(&l, "a   5");

Using the log that was build above:

  • A call to log_search(&l, "ab") will return the pointer to the string "ab 4" since the search must begin from the newest entry and move backwards.
  • A call to log_search(&l, "a") will return the pointer to the string "a 5".
  • A call to log_search(&l, "abc") will return the pointer to the string "abc 3".
  • A call to log_search(&l, "d") will return a NULL pointer.

You may assume that:

  • All pointers will be valid, non-NULL pointer.
Parameters:
l Pointer to the log data structure.
prefix The prefix to test each entry in the log for a match.
Returns:
The newest entry in the log whose string matches the specified prefix. If no strings has the specified prefix, NULL is returned.
unsigned int log_size ( log_t *  l  ) 

Returns the number of elements in the log.

You may assume that:

  • All pointers will be valid, non-NULL pointer.
Parameters:
l Pointer to the log data structure.
Returns:
Number of entires in the log.
Generated by  doxygen 1.6.3