dict.h

#include <sys/types.h>

struct dict_t;

// This library creates a binary dictionary file by mmapping memory.
// We're going to create a struct to hold individual words and they're going to
// be mapped across a given file.
//
// Then, we're going to write a handful of functions to search across that data.
//
// Internally, the data is just an array of structs. The dict_t type is what the
// user interacts with (it also holds state, like the file descriptor of the
// mmaped file).
//
// Example usage:
//
//  // Create a new binary dictionary in the file 'data', make space for 100
//  // entries.
//  struct dict_t *dict = dictionary_new("data", 100);
//
//  // Generate data from 'input_dictionary', which is a file that contains one
//  // word per line. Assume each word is < 100 characterss!
//  if (dictionary_generate(dict, "input_dictionary") < 0) {
//    // Uh oh! The return value was < 0, that means there was an error.
//    perror("dictionary generate");
//  }
//
//  // We can use our dictionary now.
//  char *cat = dictionary_exists(dict, "cat");
//  if (cat != NULL) {
//    // Found a cat!
//    printf("Found %s\n", cat);
//  }
//
//  // How many words are 3 letters long?
//  int threes = dictionary_equal_to(dict, 3);
//  printf("There are %d words that are 3 letters long\n", threes);
//
//  // All done, close it up.
//  dictionary_close(dict);
//
//  --
//  Alternatively, use dictionary_load to load a dictionary you already made:
//
//  struct dict_t *dict = dictionary_new("data", 100);
//  dictionary_load(dict);
//
//  // Now we can find use the other methods.
//  char *dog = dictionary_exists(dict, "dog");
//  if (dog != NULL) {
//    printf("Found %s\n", dog);
//  }
//  dictionary_close(dict);

// Allocates a new dictionary. Underlying dictionary is not initialized,
// use dictionary_generate to generate a new dictionary.
struct dict_t *dictionary_new(char *data_file, size_t num_items);

// Read the file at input. For each line in input, create a new dictionary
// entry.
int dictionary_generate(struct dict_t *dict, char *input);

// load a dictionary that was generated by calling generate.
int dictionary_load(struct dict_t *dict);

// Unmaps the given dictionary.
// Free/destroy the underlying dict. Does NOT delete the database file.
void dictionary_close(struct dict_t *dict);

// returns pointer to word if it exists, null otherwise
char *dictionary_exists(struct dict_t *dict, char *word);

//// Count of words with len > n
int dictionary_larger_than(struct dict_t *dict, size_t n);

// Count of words with len < n
int dictionary_smaller_than(struct dict_t *dict, size_t n);

// Count of words with len == n
int dictionary_equal_to(struct dict_t *dict, size_t n);