core/utility.h Documentation

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
struct	string
bool	init (string & dst, const char * src, unsigned int length)
bool	init (string & dst, const string & src)
bool	init (string & dst, unsigned int length)
bool	read (string & s, Stream & in)
bool	write (const string & s, Stream & out)
bool	print (const string & s, Stream && stream)
bool	operator == (const string & first, const char * second)
bool	operator == (const char * first, const string & second)
bool	operator == (const string & first, const string & second)
bool	operator != (const string & first, const char * second)
bool	operator != (const char * first, const string & second)
bool	operator != (const string & first, const string & second)
struct	string_map_scribe
bool	print (unsigned int item, Stream && out, const string_map_scribe & printer, Printer &&... string_printer)
bool	get_token (const string & identifier, unsigned int & id, hash_map< string, unsigned int > & map)
FILE *	open_file (const char * filename, const char * mode)
char *	read_file (const char * filename, size_t & bytes_read)
bool	get_files_in_directory (array< string > & out, const char * directory)

struct string
[view source]

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

Public members
unsigned int	length
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
void	operator = (const string & s)
void	operator += (const char * src)
void	operator += (const string & src)
bool	operator < (const string & other) const
unsigned int	index_of (char c) const
static bool	is_empty (const string & key)
static void	set_empty (string & key)
static void	set_empty (string * keys, unsigned int length)
static unsigned int	hash (const string & key)
static void	move (const string & src, string & dst)
static bool	copy (const string & src, string & dst)
static void	swap (string & first, string & second)
static void	free (string & str)

[view source]

unsigned int string::length

The length of the string in characters.

[view source]

char * string::data

The native char array containing the string data.

[view source]

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.

[view source]

string::string(

const char * src )

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

[view source]

string::string(

const char *	src,
unsigned int	length	)

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

[view source]

string::string(

unsigned int length )

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

[view source]

char & string::operator [] (

unsigned int index )

Accesses the character at the given index.

[view source]

const char & string::operator [] (

unsigned int index ) const

Accesses the character at the given index.

[view source]

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.

[view source]

void string::operator += (

const char * src )

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

[view source]

void string::operator += (

const string & src )

Appends the given string to this string.

[view source]

bool string::operator < (

const string & other ) const

Returns whether the current string precedes other in lexicographical order.

[view source]

unsigned int string::index_of(

char c ) const

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

[view source]

static bool string::is_empty(

const string & key )

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

[view source]

static void string::set_empty(

string & key )

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

[view source]

static void string::set_empty(

string *	keys,
unsigned int	length	)

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

[view source]

static unsigned int string::hash(

const string & key )

Returns the hash of the given key.

[view source]

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.

[view source]

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.

[view source]

static void string::swap(

string &	first,
string &	second	)

Swaps the contents and lengths of first and second.

[view source]

static void string::free(

string & str )

Frees the underlying char array in str.

[view source]

bool init(

string &	dst,
const char *	src,
unsigned int	length	)

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

[view source]

bool init(

string &	dst,
const string &	src	)

Initializes the string dst with the given string src.

[view source]

bool init(

string &	dst,
unsigned int	length	)

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

[view source]

template<typename Stream>

bool read(

string &	s,
Stream &	in	)

Reads a string s from in.

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.

[view source]

template<typename Stream>

bool write(

const string &	s,
Stream &	out	)

Writes the string s to out.

[view source]

template<typename Stream>

bool print(

const string &	s,
Stream &&	stream	)

Prints the string s to stream.

[view source]

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.

[view source]

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.

[view source]

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.

[view source]

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.

[view source]

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.

[view source]

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
[view source]

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 int	length

[view source]

const string ** string_map_scribe::map

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

[view source]

unsigned int string_map_scribe::length

The length of the native array string_map_scribe::map.

[view source]

template<typename Stream, typename... Printer>

bool print(

unsigned int	item,
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:

If the function bool print_special_string(unsigned int, Stream&) is defined, this function calls it with arguments item and out.
If such a function is not defined, an error message is printed to stderr and the function returns true.

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.

[view source]

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.

[view source]

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.

[view source]

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.

AppendNull

if true, a null terminating character is appended.

[view source]

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.

See

http://stackoverflow.com/questions/306533/how-do-i-get-a-list-of-files-in-a-directory-in-c

struct string[view source]

struct string_map_scribe[view source]

struct string
[view source]

struct string_map_scribe
[view source]