utility.h

This file contains a number of useful miscellaneous definitions and implementations, such as a core::string structure, a binary logarithm function, and a function to access the directory structure in the filesystem.

Classes, functions, and variables in this file
structstring
boolinit (string & dst, const char * src, unsigned int length)
boolinit (string & dst, const string & src)
boolinit (string & dst, unsigned int length)
boolread (string & s, FILE * in)
boolwrite (const string & s, FILE * out)
boolprint (const string & s, Stream & stream)
booloperator == (const string & first, const char * second)
booloperator == (const char * first, const string & second)
booloperator == (const string & first, const string & second)
booloperator != (const string & first, const char * second)
booloperator != (const char * first, const string & second)
booloperator != (const string & first, const string & second)
structstring_map_scribe
boolprint (unsigned int item, Stream & out, const string_map_scribe & printer, Printer &&... string_printer)
boolget_token (const string & identifier, unsigned int & id, hash_map< string, unsigned int > & map)
unsigned intlog2 (unsigned int x)
constexpr unsigned intstatic_log2 (unsigned int x)
FILE *open_file (const char * filename, const char * mode)
char *read_file (const char * filename, size_t & bytes_read)
boolget_files_in_directory (array< string > & out, const char * directory)

struct string

A basic string structure, containing a native array of char elements and an unsigned int length.

Public members
unsigned intlength
char *data
string ()
string (const char * src)
string (const char * src, unsigned int length)
string (unsigned int length)
char &operator [] (unsigned int index)
const char &operator [] (unsigned int index) const
voidoperator = (const string & s)
voidoperator += (const char * src)
booloperator < (const string & other) const
unsigned intindex_of (char c) const
static boolis_empty (const string & key)
static voidset_empty (string & key)
static voidset_empty (string * keys, unsigned int length)
static unsigned inthash (const string & key)
static voidmove (const string & src, string & dst)
static boolcopy (const string & src, string & dst)
static voidswap (string & first, string & second)
static voidfree (string & str)
unsigned int string::length

The length of the string in characters.

char * string::data

The native char array containing the string data.

string::string()

A constructor that does not initialize any fields. WARNING: The destructor will free string::data, which this constructor does not initialize. The user must initialize string::data using init or manually before the string is destroyed.

string::string(
const char *src)

Constructs the string by copying from the given null-terminated C string src.

string::string(
const char *src,
unsigned intlength)

Constructs the string by copying from the given native char array src with given length.

string::string(
unsigned intlength)

Constructs the string by initializing string::data with size length but without settings its contents.

char & string::operator [] (
unsigned intindex)

Accesses the character at the given index.

const char & string::operator [] (
unsigned intindex) const

Accesses the character at the given index.

void string::operator = (
const string &s)

Initializes this string by copying from s. Note that if this string was previously initialized, it is not freed.

void string::operator += (
const char *src)

Appends the given null-terminated C string to this string.

bool string::operator < (
const string &other) const

Returns whether the current string precedes other in lexicographical order.

unsigned int string::index_of(
charc) const

Returns the smallest index i such that string::data[i] == c.

static bool string::is_empty(
const string &key)

Returns whether string::data is NULL. This enables strings to be used as keys in hashtables.

static void string::set_empty(
string &key)

Sets string::data to NULL. This enables strings to be used as keys in hashtables.

static void string::set_empty(
string *keys,
unsigned intlength)

Sets string::data to NULL for every element in keys. This enables strings to be used as keys in hashtables.

static unsigned int string::hash(
const string &key)

Returns the hash of the given key.

static void string::move(
const string &src,
string &dst)

Copies the string::length and string::data pointer from src to dst. Note this function does not create a new pointer and copy the character contents, it simply copies the char* pointer.

static bool string::copy(
const string &src,
string &dst)

Copies the string in src to dst. This function initializes a new string::data array in dst and copies the contents from src.data.

static void string::swap(
string &first,
string &second)

Swaps the contents and lengths of first and second.

static void string::free(
string &str)

Frees the underlying char array in str.

bool init(
string &dst,
const char *src,
unsigned intlength)

Initializes the string dst with the given native char array src and the given length.

bool init(
string &dst,
const string &src)

Initializes the string dst with the given string src.

bool init(
string &dst,
unsigned intlength)

Initializes the string dst by allocating string::data with size length, but this function does not set its contents.

bool read(
string &s,
FILE *in)

Reads a string s from in.

Parameters
s

an uninitialized string structure. This function initializes s, and the caller is responsible for its memory and must call free to release its memory resources.

bool write(
const string &s,
FILE *out)

Writes the string s to out.

template<typename Stream>
bool print(
const string &s,
Stream &stream)

Prints the string s to stream.

bool operator == (
const string &first,
const char *second)

Compares the string first to the null-terminated C string second and returns true if they are equivalent, and false otherwise.

bool operator == (
const char *first,
const string &second)

Compares the null-terminated C string first to the string second and returns true if they are equivalent, and false otherwise.

bool operator == (
const string &first,
const string &second)

Compares the string first to the string second and returns true if they are equivalent, and false otherwise.

bool operator != (
const string &first,
const char *second)

Compares the string first to the null-terminated C string second and returns false if they are equivalent, and true otherwise.

bool operator != (
const char *first,
const string &second)

Compares the null-terminated C string first to the string second and returns false if they are equivalent, and true otherwise.

bool operator != (
const string &first,
const string &second)

Compares the string first to the string second and returns false if they are equivalent, and true otherwise.

struct string_map_scribe

A scribe that maps unsigned integer indices to core::string pointers.

#include <core/utility.h>
using namespace core;

int main() {
    string first = "first";
    string second = "second";

    string_map_scribe scribe;
    scribe.map = (const string**) malloc(sizeof(const string*) * 2);
    scribe.map[0] = &first; scribe.map[1] = &second;
    scribe.length = 2;

    print(0, stdout, scribe); print(' ', stdout);
    print(1, stdout, scribe);

    free(scribe.map);
}
The expected output of this program is first second.

Another way to construct this structure is to convert a hash_map<string, unsigned int> into a core::string** array using the core::invert() function.

#include <core/utility.h>
using namespace core;

int main() {
    hash_map<string, unsigned int> token_map(16);
    token_map.put("first", 0);
    token_map.put("second", 1);

    string_map_scribe scribe;
    scribe.map = invert(token_map);
    scribe.length = 2;

    print(0, stdout, scribe); print(' ', stdout);
    print(1, stdout, scribe);

    free(scribe.map);
    for (auto entry : token_map)
        free(entry.key);
}
The expected output of this program is first second. Notice that since hash_map does not automatically free its elements, we do it manually using a range-based for loop.

Public members
const string **map
unsigned intlength
const string ** string_map_scribe::map

The native array of const string* elements that represents the effective map from unsigned integers to strings.

unsigned int string_map_scribe::length

The length of the native array string_map_scribe::map.

template<typename Stream, typename... Printer>
bool print(
unsigned intitem,
Stream &out,
const string_map_scribe &printer,
Printer &&...string_printer)

Prints item to out using the string_map_scribe printer. If item < printer.length, the string at index item is accessed from string_map_scribe::map and printed to out. Otherwise, there are two cases:

  1. If the function bool print_special_string(unsigned int, Stream&) is defined, this function calls it with arguments item and out.

  2. If such a function is not defined, an error message is printed to stderr and the function returns true.

Parameters
string_printer

a scribe for which the function bool print(const string&, Stream&, Printer&&...) is defined, which is used to print the string itself. Note that since this is a variadic argument, it may be empty.

bool get_token(
const string &identifier,
unsigned int &id,
hash_map< string, unsigned int > &map)

Looks for the token identifier in the given hash_map map. If such a key exists in the map, id is set to its corresponding value and true is returned. If not, a new entry is added to the map with identifier as the key and map.table.size + 1 as its value, and id is set to this new value.

Returns

true upon success, or false if the hash_map map could not be resized to accommodate the new entry.

unsigned int log2(
unsigned intx)

Returns the base-2 logarithm of the given unsigned int argument. This function assumes the argument is not 0.

constexpr unsigned int static_log2(
unsigned intx)

Returns the base-2 logarithm of the given unsigned int argument. This function assumes the argument is not 0.

FILE * open_file(
const char *filename,
const char *mode)

Opens the file with the given filename with the given mode and returns either a FILE pointer on success, or NULL on failure. fclose should be used to close the stream once reading is complete.

On Windows, this function uses fopen_s to open the stream.

template<bool AppendNull>
char * read_file(
const char *filename,
size_t &bytes_read)

Reads the contents of the file whose path is given by filename. If the file cannot be opened for reading, or if there is insufficient memory to allocate a buffer, NULL is returned. bytes_read is set to the number of bytes read, and the file contents are returned. The caller is responsible for the memory of the returned buffer and must call free to release its memory resources.

Template parameters
AppendNull

if true, a null terminating character is appended.

bool get_files_in_directory(
array< string > &out,
const char *directory)

This function inspects the directory given by the path directory and adds the list of filenames in that directory to the string array out.