Palm

Palm is a small standard library provided and used by CoCoNut.

str.h

Defines

F_PTR

Functions

char *STRcpy(const char *source)

Copy string and allocate memory for new string.

Parameters:

source – String to copy

Returns:

New copied string

char *STRncpy(const char *source, int maxlen)

Copy string and allocate memory for new string.

Copy only maxlen characters.

Parameters:

  • source – String to copy

  • maxlen – Number of characters to copy

Returns:

New copied string

bool STReq(const char *first, const char *second)

Compare two strings.

Parameters:

  • first – First string to compare

  • second – Second string to compare

Returns:

True if string contents are equal, false if they are not equal.

bool STReqci(const char *first, const char *second)

Compare two strings in a case insensitive way.

Parameters:

  • first – First string to compare

  • second – Second string to compare

Returns:

True if string contents are equal, false if they are not equal.

bool STReqn(const char *first, const char *second, int n)

Compare two strings up to a certain limit of characters.

Parameters:

  • first – First string to compare

  • second – Second string to compare

  • n – number of relevant characters

Returns:

True if the relevant prefixes of strings are equal, false if they are not equal.

size_t STRlen(const char *str)

Yield the length of a string

Mostly to provide a complete interface and to avoid using standard string facilities throughout the compiler.

Returns:

Length of the string

char *STRcat(const char *first, const char *second)

Concatenate two strings and allocate memory for new string.

Copy only maxlen characters.

Parameters:

  • first – First string

  • second – Second string

Returns:

New concatenated string

char *STRcatn(int n, ...)

Concatenate n strings and allocate memory for new string.

Parameters:

  • n – Number of strings

  • ... – n amount of “const char *”-type strings

Returns:

New concatenated string

char *STRfmt(const char *fmt, ...)

Create a format string of an arbitrary length.

Can be used like printf, but returns a string instead of printing to the terminal.

Similar to s(n)printf, but STRfmt will allocate a new string of the required length, saving you the hassle of determining the length of a format string.

Parameters:

  • fmt – format string that supports the same conversion specifiers as printf. See man 3 printf

  • ... – format string arguments Arbitrary amount of arguments for format string

Returns:

The newly allocated formatted string

char *STRonNull(char *alt, char *str)

Yields either the argument string if it is not NULL or an empty constant string otherwise.

This is helpful for instance when printing strings with the s conversion specifier and the string to print may be NULL.

Parameters:

  • alt – Alternative string to return if str is NULL

  • str – String that may be NULL

Returns:

str if str != NULL, else alt

char *STRitoa(int number)

Convert integer to string in decimal representation. This is equivalent to STRfmt("%d", number).

Parameters:

number – to convert

Returns:

The newly allocated string representation of number

char *STRlower(const char *str)

Convert a string to its lower form, but does not consume original string.

Parameters:

str – The string to transform.

Returns:

Allocated string, which is the lower form of str.

char *STRupper(const char *str)

Convert a string to its upper form, but does not consume original string.

Parameters:

str – The string to transform.

Returns:

Allocated string, which is the upper form of str.

char *STRtok(const char *str, const char *tok)

Tokenize string.

On first call the str will be copied to internal static variable, next calls str should be NULL. With last call the allocated memory of the copy will be freed.

In contrast to strtok, STRtok leaves the argument string untouched and always allocates the tokens in fresh memory.

Parameters:

  • str – String to tokenize

  • tok – Tokenizer

Returns:

Either a pointer to the next token or NULL when no more tokens.

bool STRprefix(const char *prefix, const char *str)

Checks if prefix is at the start of str

Parameters:

  • prefix – First string to compare

  • str – Second string to compare

Returns:

True if prefix is at the start of str, false otherwise.

bool STRsuffix(const char *suffix, const char *str)

Checks if suffix is at the end of str

Parameters:

  • prefix – First string to compare

  • str – Second string to compare

Returns:

True if suffix is at the end of str, false otherwise.

bool STRsub(const char *sub, const char *str)

Checks if sub is contained inside of str

Parameters:

  • sub – Substring to find

  • str – String to search

Returns:

True when sub is a substring of str, false otherwise

char *STRsubStr(const char *string, int start, int len)

copy part of a string from start to start + len.

If len is <0 then len is relative to the length of the string.

Parameters:

  • string – String to copy from

  • start – Position to start copy

  • len – Length to copy, can be negative

Returns:

Copied part of the string

char *STRsubstToken(const char *str, const char *token, const char *subst)

Substitute all occurrences of token in str with subst

Parameters:

  • str – The string in which to make substitutions

  • token – a string to substitute occurrences of in str

  • subst – a string to substitute tokens with

Returns:

A new String or NULL if str is NULL

void STRtoLower(char *str)

Convert string to lower string by consuming the string.

Parameters:

str – the string to convert to lower form.

void STRtoUpper(char *str)

Convert string to upper string by consuming the string.

Parameters:

str – the string to convert to upper form.

char *STRnull()

Yield an empty string.

Returns:

An allocated empty string

hash_table.h

Typedefs

typedef struct htable htable_st
typedef struct htable_iter htable_iter_st
typedef size_t (*hash_key_ft)(void*)
typedef bool (*is_equal_ft)(void*, void*)
typedef void *(*cpy_ft)(void*)
typedef void *(*map_ft)(void*)
typedef void *(*mapk_ft)(void *key, void *item)
typedef void *(*mapdk_ft)(void *data, void *key, void *item)
typedef void *(*fold_ft)(void *acc, void *item)

Functions

htable_st *HTnew(size_t size, hash_key_ft hash_func, is_equal_ft is_equal_func)

Create a new hash table.

Parameters:

  • size – the number of buckets in a hash table. More buckets is more space, but les collisions. See pre-defined hash tables in the bottom of this file.

  • hash_func – the function used for hashing keys.

  • is_equal_func – the function to determine if two values are equal.

htable_st *HTnew_String(size_t size)

Htable that maps char * -> void *

Parameters:

size – the number of buckets in a hash table.

htable_st *HTnew_Ptr(size_t size)

Htable that maps void * -> void *

Parameters:

size – the number of buckets in a hash table.

htable_st *HTnew_Int(size_t size)

Htable that maps int * -> void *

Parameters:

size – the number of buckets in a hash table.

htable_st *HTcpy(htable_st *table)

Create a copy of the hash table. Note that keys and values are not deep- copied, use HTdeep_copy if you need this.

Parameters:

table – hash table to copy.

Returns:

the new hash table.

htable_st *HTdeep_copy(htable_st *table, cpy_ft key_copy_func, cpy_ft val_copy_func)

Create a deep copy of the hash table.

Parameters:

  • table – hash table to copy.

  • key_copy_func – function called on every key to copy the key element.

  • val_copy_func – function called on every value to copy the value element.

Returns:

the new hash table.

bool HTinsert(htable_st *table, void *key, void *value)

Insert the key, value pair from the table.

Returns:

true if insertion was successful.

void *HTlookup(htable_st *table, void *key)

Lookup a value in the hash table.

Returns:

the corresponding value or NULL if key is not found.

void *HTremove(htable_st *table, void *key)

Remove the key, value pair from the table.

Returns:

the deleted value or NULL if key is not found.

void HTclear(struct htable *table)

Clears all entries in the hash table. Does not delete the table, so can be reused.

void HTdelete(htable_st *table)

Delete all entries in the table and the table itself. Table is not usable after this operation.

void HTmap(htable_st *table, map_ft fun)

Map functions that apply a user function to all entries in the hash tables. The entry values are replaced by the return values of the user map function.

  • HTmap only passes the entry values to the map function.

  • HTmapWithKey passes the entry keys & values to the map functions.

  • HTmapWithKey passes the entry keys & values and user-provided data to the map functions.

void HTmapWithKey(htable_st *table, mapk_ft fun)
void HTmapWithDataAndKey(htable_st *table, void *data, mapdk_ft fun)
void HTfold(htable_st *table, fold_ft fun, void *init_acc)
size_t HTelementCount(htable_st *table)
Returns:

the amount of entries in the hash table.

htable_iter_st *HTiterate(htable_st *table)

Iteration functions that can be used to iterate over all keys and values in a hashtable. These functions are an alternative to the HTmap* functions.

Example usage: 

for (htable_iter_st *iter = HTiterate(htable); iter;
     iter = HTiterateNext(iter)) {
    // Getter functions to extract htable elements
    void *key = HTiterKey(iter);
    void *value = HTiterValue(iter);

    // Use HTiterateCancel in early loop exits
    if (condition) {
        HTiterateCancel(iter);
        break;
    }
}

Create new iterator

Returns:

The new iterator, use HTiterValue, and HTiterKey to retrieve values

htable_iter_st *HTiterateNext(htable_iter_st *iter)

Iterate to the next element.

Will clean up iterator if there are no more elements.

Parameters:

iter – The iterator, should not be used after call

Returns:

The iterator with the next element, NULL if there are no more elements

void HTiterateCancel(htable_iter_st *iter)

Cancel iteration.

Will clean up the iterator. Useful when breaking a loop.

Parameters:

iter – The iterator, should not be used after call

void *HTiterValue(htable_iter_st *iter)

Get value of current element from iterator.

void HTiterSetValue(htable_iter_st *iter, void *value)

Set value of current element from iterator.

void *HTiterKey(htable_iter_st *iter)

Get key of current element from iterator.

dbug.h

This file provides a small debug library.

Defines

MODULE

When defined, will be used as a header before messages printed with DBUG calls. Need to be defined before including this header. DO NOT define MODULE inside a header file.

DBUG_ASSERT(expr, ...)

Assert expression and print message when expressions fails. In most cases, a simple assert is good enough and you dont need this!

Example usage:

  • DBUG_ASSERT(true, “Hello DBUG”);

  • DBUG_ASSERT(2 > 3, “%d is not bigger than %d”, 2, 3);

Parameters:

  • expr – the expr to test, must be testable in an if.

  • ... – Variable args like printf, however, this contains the format string for portability.

DBUG_ASSERTF(expr, format, ...)

Assert with format string. DEPRECATED (just use DBUG_ASSERT).

DBUG(...)

print a dbug message with the module, when defined, prepended.

Example usage:

  • DBUG(“Starting with phase”);

  • DBUG(“5+5=%d”, 5+5);

Parameters:

  • ... – Variable arguments. First message must be a format string.

DBUGF(header, format, ...)

Formatted debug message identified by header. DEPRECATED (just use DBUG)

Functions

void DBUGprintAssert(int line, char *file, const char *func, char *msg, ...)
void DBUGprint(char *header, char *msg, ...)
void DBUGoff()

memory.h

Functions

void *MEMmalloc(size_t size)

Allocate memory. If memory can not be allocated this function calls the CTIabortOufOfMemory function and exists.

Parameters:

size – Amount to allocate.

Returns:

A pointer to an allocated structure.

void *MEMrealloc(void *address, size_t size)

Reallocate memory. If memory can not be allocated this function calls the CTIabortOufOfMemory function and exists.

Parameters:

  • address – address to resize, can be NULL. Address can not be used again after call.

  • size – Amount to allocate.

Returns:

A pointer to an allocated structure.

void *MEMfree(void *address)

Free memory. Returns NULL, but allows to do assignment to freed structure.

Parameters:

address – address to free.

void *MEMcopy(size_t size, void *mem)

Copy memory to a new memory location.

Parameters:

  • size – amount of bytes to copy to new region.

  • mem – Memory location to copy from.

Returns:

New memory location of size bytes.

ctinfo.h

This file provides the interface for producing any kind of output during compilation.

We have 4 levels of verbosity controlled by the command line option -v and the global variable verbose_level.

Verbose level 0:

Only error messages are printed.

Verbose level 1:

Error messages and warnings are printed.

Verbose level 2:

Error messages, warnings and basic compile time information, e.g. compiler phases, are printed.

Verbose level 3:

Error messages, warnings and full compile time information are printed.

Default values are 1 for the product version and 3 for the developer version.

Enums

enum cti_type

Type of message for the CTI and CTIobj functions. Determines the header of the message. The error and warning messages have a counter counting the errors and warnings, which will be displayed on CTIabort functions.

Values:

enumerator CTI_STATE
enumerator CTI_NOTE
enumerator CTI_WARN
enumerator CTI_ERROR

Functions

void CTIinstallInterruptHandlers(void)

Installs interrupt handlers

int CTIgetErrorMessageLineLength()

Yields useful line length for error messages

Returns:

Line length

int CTIgetWarnMessageLineLength(void)

Yields useful line length for warning messages

Returns:

Line length

int CTIgetWarnings()
Returns:

The number of warnings currently produced

int CTIgetErrors()
Returns:

The number of errors currently produced.

void CTIabortCompilation()

Terminates the compilation process with a suitable error message.

void CTIabortOnError()

Terminates the compilation process if errors have occurred.

void CTIabortOutOfMemory(unsigned int request)

produces a specific “out of memory” error message without file name and line number and terminates the compilation process.

This very special function is needed because the normal procedure of formatting a message may require further llocation of memory, which in this very case generates a vicious circle of error messages instead of terminating compilation properly.

Parameters:

request – size of requested memory

void CTI(enum cti_type type, bool newline, const char *format, ...)

Prints a message to stderr with header according to the type.

Parameters:

  • type – the type of message, see enum cti_type

  • newline – Whether to append a newline to the output or not.

  • format – printf style format string

  • ... – variable args.

void CTIobj(enum cti_type type, bool newline, struct ctinfo obj, const char *format, ...)

See @CTI

Parameters:

obj – an object of type struct ctinfo with extra information.

struct ctinfo
#include <ctinfo.h>

Object to describe location information of a compile time object. Pass this to CTIobj function.

Values that are 0/NULL are not displayed, but are handled.

Public Members

int first_line
int first_column
int last_line
int last_column
char *filename
char *line