Sitemap

 

List

Detailed Descriptions

Global_ERWIN_EXPORT Vector_t * Vector_new ()

Create a new vector with default values. I.e., with the default zero element Vector_ZERO and the default initial hash table size of Vector_INITIAL_SIZE.

Global_ERWIN_EXPORT Vector_t * Vector_new_with_zero (oTypeTouched zero)

Create a vector specifying the zero element.

Global_ERWIN_EXPORT Vector_t * Vector_new_with_zero_and_initial_size (oTypeTouched zero, Vector_cnt_t initial_size)

Create a new, empty vector. The first form uses Global_oType_zero as the zero element.

If initial_size < 0

the default size Vector_INITIAL_SIZE will be used.

If initial_size == 0 but Vector_MINIMAL_SIZE > 0

a size of 1 will be used.

Note

The vector always has size==0 even if initial_size > 0. This initial size is the size of the data structure used. The vector does not resize it until the vector becomes larger than that.

Global_ERWIN_EXPORT Vector_t * Vector_new_with_initial_size (Vector_cnt_t initial_size)

Initialise with a given table size. See Vector_new_with_zero_and_initial_size.

Global_ERWIN_EXPORT Vector_t * Vector_new_from_raw (oTypeVar * contents, Vector_cnt_t nentries, Vector_cnt_t allocsize)

This makes a vector from contents. It 'steals' the pointer and makes it its internal vector table. It is assumed that we can (re/de)allocate the contents using the normal Global_ERWIN_TMALLOC/REALLOC/CMALLOC/FREE mechanism.

Initial_size is the amount of memory that is allocated. You can safely pass less than nentries, meaning we should assume that there are only nentries allocated cells (this is safe behaviour). If you know the amount that is allocated, you should pass it to this function to improve performance by preventing unnecessary reallocations.

If you want to copy contents into a vector, use _new_with_initial_size and _append_raw instead.

If contents is NULL or allocsize is 0, then we invoke new_with_initial_size instead, so whether you get a vector that has no allocated table at all depends on the setting of Vector_ZERO_SIZE. By default, table with Vector_INITIAL_SIZE will be allocated.

If allocsize is non-zero, Vector_MINIMAL_SIZE is ignored (as with the constructors that contain _with_initial_size), so you may allocate smaller vectors. (A size of 0, however, is special, see previous paragraph.)

Global_ERWIN_EXPORT Vector_t * Vector_new_from_raw_with_zero (oTypeVar * contents, Vector_cnt_t nentries, Vector_cnt_t allocsize, oTypeTouched zero)

Same as before but with a given zero element.

Global_ERWIN_EXPORT int Vector_init (Vector_t * self)

This is for initialising non-heap Vector_t objects that are allocated manually (thus, not via Vector_new).

Invoking this function manually is usually discouraged. It is thought to be for nesting data structures. However, if you need to optimise heap usage, it is ok to use this function.

Error Codes (errno)

• In case of operation, OK is signalled.
• If memory is exhausted, ERR_NOMEM is signalled. If the option NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Global_ERWIN_EXPORT int Vector_init_with_zero_and_initial_size (Vector_t * self, oTypeTouched zero, Vector_cnt_t initial_size)

This is for initialising non-heap Vector_t objects that are allocated manually (thus, not via Vector_new).

Invoking this function manually is usually discouraged. It is thought to be for nesting data structures. However, if you need to optimise heap usage, it is ok to use this function.

Error Codes (errno)

• In case of operation, OK is signalled.
• If memory is exhausted, ERR_NOMEM is signalled. If the option NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Global_ERWIN_EXPORT int Vector_init_with_initial_size (Vector_t * self, Vector_cnt_t initial_size)

This is for initialising non-heap Vector_t objects.

Invoking this function manually is usually discouraged. It is thought to be for nesting data structures. However, if you need to optimise heap usage, it is ok to use this function.

Error Codes (errno)

• In case of operation, OK is signalled.
• If memory is exhausted, ERR_NOMEM is signalled. If the option NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Global_ERWIN_EXPORT void Vector_destroy (Vector_t * self)

This is for deleting non-heap Vector_t objects.

Invoking this function manually is usually discouraged. It is thought to be for nesting data structures. However, if you need to optimise heap usage, it is ok to use this function.

Error Codes (errno)

• In case of operation, OK is signalled.

Global_ERWIN_EXPORT int Vector_errno (Vector_t const *)

If you compiled Erwin with Global_ERWIN_THREAD_SAFE, this is the way to get the status code of a given vector.

If you do not have a thread-safe Erwin library, there is a macro with the same name as this function.

Error Codes

The operation is always successful (not thinking of assertion failures).

Global_ERWIN_EXPORT Vector_t * Vector_copy (Vector_t const * self)

Copies a vector with all its elements and returns that copy.

Global_ERWIN_EXPORT Vector_t * Vector_copy_err (Vector_t const * self, int * err)

Like Vector_copy but sets *err to 1 on failure.

Global_ERWIN_EXPORT Vector_t * Vector_subvector (Vector_t const * self, Vector_index_t start_index, Vector_cnt_t size, Global_ERWIN_BOOL docopy)

Copies only a portion of the vector. The semantics of the parameters is like in Vector_insert_subvector.

Global_ERWIN_EXPORT void Vector_delete (Vector_t * self)

Deletes everything in the vector and the vector structure itself. Vector_delete is NULL safe (self may be NULL without crash or failed assertion).

Global_ERWIN_EXPORT oTypeResult Vector_first (Vector_t const * self)

Returns the first element of the vector. This is the same as

Vector_nth (self, 0)

Global_ERWIN_EXPORT oTypeResult Vector_last (Vector_t const * self)

Returns the last element of the vector

This is the same as

Vector_nth (self, Vector_nentries (self) - 1)

ERWIN_STATIC_INLINE oType const * Vector_nth_ptr_const (Vector_t const * self, Vector_index_t idx)

Like Vector_nth_ptr, but constant in input and output type.

Does not output anything to stderr even if you define Global_ERWIN_VERBOSE.

Dev.Note: not pure with ALLOW_OUTOFRANGE option.

ERWIN_STATIC_INLINE oType const * Vector_nth_ptr_check_const (Vector_t const * self, Vector_index_t idx)

Like Vector_nth_ptr_check, but constant in input and output type.

Does not output anything to stderr even if you define Global_ERWIN_VERBOSE.

Dev.Note: not pure with ALLOW_OUTOFRANGE option.

ERWIN_STATIC_INLINE oType const * Vector_nth_ptr_char_const (Vector_t const * self, Vector_index_t idx)

Like Vector_nth_ptr_char, but constant in input and output type.

Note that despite the 'const', this zero-terminates the vector just like Vector_nth_ptr_char() and Vector_as_array().

Does not output anything to stderr even if you define Global_ERWIN_VERBOSE.

Global_ERWIN_EXPORT int Vector_erase_flags (Vector_t * self, Vector_index_t index, Vector_cnt_t number_of_elements_to_delete, Global_ERWIN_BOOL resize, Global_ERWIN_BOOL delete_elems)

Like Vector_erase but you can specify whether

• the vector should be re-allocated by resize

• elements should be freed by delete_elems.

Returns its success.

Global_ERWIN_EXPORT int Vector_swap_erase_flags (Vector_t * self, Vector_index_t index, Vector_cnt_t number_of_elements_to_delete, Global_ERWIN_BOOL resize, Global_ERWIN_BOOL delete_elems)

Like Vector_swap_erase but you can specify whether

1. the vector should be re-allocated by resize

2. elements should be freed by delete_elems.

Returns its success.

Global_ERWIN_EXPORT Vector_cnt_t Vector_erase_if (Vector_t * self, Vector_feature_t feature, Global_ERWIN_BOOL value)

Erases those elements that satisfy feature. You can specify which value feature must return for the element in order to trigger that deletion. So if value is Global_ERWIN_FALSE, the feature described by feature is negated.

The values erased from the vector are freed using oType_OFREE.

Returns the number of elements cut out of the vector.

Note

In CommonLisp, this is called remove-if.

Global_ERWIN_EXPORT Vector_cnt_t Vector_erase_if_flags (Vector_t * self, Vector_feature_t feature, Global_ERWIN_BOOL value, Global_ERWIN_BOOL resize, Global_ERWIN_BOOL dealloc)

Additional to Vector_erase_if, you can specify whether to resize the vector or whether to deallocate the elements that are cut out.

Returns the number of elements cut out of the vector.

Global_ERWIN_EXPORT int Vector_chop_flags (Vector_t * self, Vector_cnt_t count, Global_ERWIN_BOOL resize, Global_ERWIN_BOOL delete_elems)

Like Vector_chop you can specify the deallocation behaviour.

Returns its success.

Global_ERWIN_EXPORT int Vector_set_size_no_resize (Vector_t * self, Vector_cnt_t size)

Set the vector size (by shrinking or enlarging and filling with null elements). When shrinking, no resizing of the table will be done.

Returns its success.

Global_ERWIN_EXPORT int Vector_set_size_raw (Vector_t * self, Vector_cnt_t size)

Set the vector size by shrinking or enlarging without, resizing, deallocation and without filling with null elements.

This function similar to Vector_set_size_no_resize: when shrinking, no resizing will be done. Further, this function does not free any elements during shrinking, so that the elements up to the allocation size will remain in memory unmodified. When enlarging the vector up to the allocation size, this function will not initialise the data.

This function is useful if you want to temporarily hide elements at the end of the vector. E.g. when handling heaps where the vector size is different from the heap size. See Vector_make_heap.

BE CAREFUL: if you use this function to shrink the vector, and then use it to enlarge the vector to a size greater than the original size, then there will be uninitialised elements. Basic initialisation (constructor invocation) is performed when the vector needs to be reallocated to enlarged it, however. But no null element is ever written by this function.

Returns its success.

Global_ERWIN_EXPORT Global_ERWIN_BOOL Vector_empty (Vector_t const * self)

Returns whether the vector contains no elements.

Global_ERWIN_EXPORT Vector_element_ptr_t Vector_find_ptr (Vector_t const * self, Vector_index_t start, oTypeParam needle)

Like Vector_find but returns a pointer to the found item or NULL on failure.

Global_ERWIN_EXPORT Vector_element_ptr_t Vector_rfind_ptr (Vector_t const * self, Vector_index_t start, oTypeParam needle)

Like Vector_rfind but returns a pointer to the found item or NULL on failure.

ERWIN_WRAPPER Global_hashval_t Vector_hash (Vector_t const *)

Same as Vector_hash_raw() now that hash_raw() is good enough.

Global_ERWIN_EXPORT void Vector_set_quotation_method (Vector_t const * self, int which, Vector_quotation_method_t const *)

Set new quotation methods for the `s' and `v' formats. `which' may only be Global_FO_QUOTE_USER1 or Global_FO_QUOTE_USER2.

self is needed to set the status code.

This function is not thread safe, even if you define Global_ERWIN_THREAD_SAFE. There is only one array of user quotation methods. If you change it, do it at the beginning of your program in the main thread!

Global_ERWIN_EXPORT Vector_quotation_method_t const * Vector_get_quotation_method (Vector_t const * self, int which)

Get quotation methods. Which must be from the Global_FO_QUOTE_* family.

Global_ERWIN_EXPORT void Vector_format (Vector_t * self, Tchar const * format, ...)

See Vector_oformat.

Global_ERWIN_EXPORT void Vector_vformat (Vector_t * self, Tchar const * format, va_list)

See Vector_oformat.

Global_ERWIN_EXPORT void Vector_oformat (Vector_t * self, unsigned long int options, Tchar const * format, ...)

The format is as in the printf family according to C99 standard. These functions will never cause a buffer overflow. The \type(long long) type (64 bits integer) is supported if the compiler supports one. Its format character is 'll', but `L' is also understood.

This function reimplements the whole printf functionality, so if you do not like this overhead, you can define Vector_NO_FORMAT, but because of the guaranteed prevention of buffer overflows, it is usually good to use this.

To keep ANSI/ISO conformance (ISO/IEC 9899:1999 = C99), all extra functionality has been put into the additional `options' argument. The following format options are supported:

Note

Use ll with integers only and L with floats only to be compliant with POSIX. (Erwin treats both exactly the same just like glibc.)

Currently unsupported

• L + float is only supported if the compiler has is a long double type

• ll + int is only supported if the compiler has a 64 bit int type.

Compatibility

For compatibility, the following are implemented (don't use if you want to be POSIX compliant).

Note

FO_RADIX(64) uses base-64 digits, but is not mmencode compatible, as the base64 encoding works on chunks of 3 bytes which are interpreted as 4 6-bit digits each. The problem is that the digit order is reversed to the normal order, so you cannot easily convert from the format output to real base64 output. Maybe we'll introduce a quotation method for base64 some day.

Further note that you can print negative number with base != 10 by using %d with the option FO_RADIX(...).

Options

You can use the Global_FO_CHECK option to simulate operation. By this, you can check things via the first argument to Vector_rovformat or Vector_roformat. The use of Vector_format_pos() and Vector_format_quoted() is deprecated.

The following options are supported to allow extended functionality. They can be ORed together.

Global_FO_VECTOR

All %p refer to a \type(Vector_t ) instead of to a \type(char ).

Global_FO_UPCASE

Use upper case digits first in numbers (this is needed because there is no %D). e.g.

format (Global_FO_UPCASE + Global_FO_RADIX(23), "%d", 2387)

appends 4BI

Global_FO_CENTER

Selects centering. I.e. in addition to default right adjustment or right adjustment by the - option.

This does not work for floating point arguments (see below) since the clib does not support it.

This can be combined with - to specify that if it cannot be centred exactly, it should be more left adjusted instead of right. E.g.

Vector_oformat (v, Global_FO_CENTER, "%04X", 10)

will append "00A " whereas

Vector_oformat (v, Global_FO_CENTER, "%-04X", 10)

will append "0A  ".

Global_FO_RADIX(radix)

radix: a number between 0 and 64: Switches the radix of the %d, %i, %x and %o command from their default to this number.

The digit set is as follows:

radix <= 36

for %x (lower case): 0..9, a..z and for %X (upper case): 0..9, A..Z

radix = 64

always base64 digits (but different digit order!)

radix > 36 && radix < 64

base64 with only the first radix characters.

Also see the documentation of the Global_FO_RADIX macro to learn about the special radix values of 'd', 'i', 'o', 'x', 'X', 'b', 'e', 'E', 'f', 'F', 'g', 'G', 'a', 'A'.

Global_FO_QUOTE_SHELL

Quotation for Shell: either Unix or Windows, depending on compilation environment: equivalent to Global_FO_QUOTE_BOURNE_SHELL under Unix and te Global_FO_QUOTE_WIN_SHELL under Dos or Windows.

Global_FO_QUOTE_BOURNE_SHELL

Quote for a Bourne shell.

Vector_oformat (FO_QUOTE_BOURNE_SHELL, "%s", "a b!c")

-> a\ b\!c

Global_FO_QUOTE_WIN_SHELL

Quote for a Windows shell.

Vector_oformat (FO_QUOTE_WIN_SHELL, "%s", "a b!c")

-> "a b!c"

Global_FO_QUOTE_C_STRING

Quote in double quoted C syntax. Single quotes are still quoted as \'. This also tries to get maximum compatibility for reading such a string by sometimes quoting although unnecessary since it is known that some buggy compilers may misinterpret something. E.g. someone might read \0001 as only one character. Therefore, the previous is quoted as \000\001.

Vector_oformat (FO_QUOTE_C_STRING, "%s", "a'b\\c\"d\0\7e")

-> "a\'b\\c\"d\000\007e"

This handles NULL and prints it as NULL.

Global_FO_QUOTE_IN_C_STRING

Similar to previous, but does not output enclosing double quotes, so it is suitable for either appending several quoted strings or for quoting in character syntax (single quotes), by manually providing enclosing quotes in the format string.

Vector_oformat (FO_QUOTE_C_STRING, "%s", "a'b\\c\"d\0\7e")

-> a\'b\\c\"d\000\007e

Global_FO_QUOTE_LISP_STRING

CommonLisp quotation: this is like a simple C quotation: basically, only " and \ need quotation.

Vector_oformat (FO_QUOTE_C_STRING, "%s", "a'b\\c\"d")

-> "a'b\\c\"d"

Global_FO_QUOTE_IN_LISP_STRING

Same as before without enclosing double quotes.

Vector_oformat (FO_QUOTE_C_STRING, "%s", "a'b\\c\"d")

-> a'b\\c\"d

Global_FO_QUOTE_FORMAT

Quote to be suitable as a printf format string. I.e., % is quoted as %%. Note that this does not include a C quotation, so when you have a literal string, and want to print a format string in C, you'll need to first quote for format, and then again for C.

Vector_oformat (FO_QUOTE_FORMAT, "%s", "%s")

-> %%s

Global_FO_QUOTE_USER1 ... USER3

User quotation: can be defined by the application by Vector_set_quotation_method().

Of the above, one can be selected: all %s and %c commands will quote their argument according to the given quotation.

Note

Quotation is only done for %s and %c, not for anything else!

Further Note

because it appeared to happened too often, to mix quotation and non-quotation in one format string, you can specify left adjustment without giving a minimal width to switch off quotation. So to switch off quotation for some %s, use %-s.

Note

This will only work if the minimal with is not given at all to prevent confusion:

Vector_oformat (FO_QUOTE_C_STRING, "%s.%-s.%s", "b", "c", "d")

This will append: "b".c."d"

Global_FO_SEP_AT(position)

Position is a number between 0 and 15.

Put commas into a number. E.g.

oformat (Global_FO_SEP_AT(3), "%d", 10000000)

-> 10,000,000

This is equivalent to using "%'d" for an appropriate locale.

The number defines at how many digits this should happen. So Chinese people would perhaps want it between blocks of four digits:

oformat(Global_FO_SEP_AT(4), "%d", 10000000)

-> 1000,0000

(since 1000,0000 = qian1 wan4; qian1 (=1000) wan4 (=10000))

(For some unknown reason, however, it seems that Asian languages with base words up to 10000 (instead of 1000 as most Western European languages) still use separators at all three digits. Why?)

Global_FO_USE_SEP('.')

Define which character to use for digit separation:

E.g Germans might want to format their numbers like this:

oformat(Global_FO_USE_SEP('.') |
        Global_FO_SEP_AT(3), "%d", 10000000)

-> 10.000.000

Format specifiers

- %n: writes the current length of the vector into the given int* pointer. (or short* or long* or long long* if this is indicated by s, l or q).

Note

it writes the absolute length of the vector, NOT the relative length wrt. to the starting length!

Chopping behaviour with quoted strings

When using both width arguments, characters will never be output in halves (or other pieces). Instead, the string is tried to be kept shorter. Sometimes this is not possible (e.g. when the length of the prefix + suffix exceeds the total width). In rare cases the string will therefore be longer. This behaviour is useful for breaking strings over several lines.

If you specify the exact length argument, the string will still not be expanded or chopped. (e.g. %80.78s will produce lines which are always 80 characters wide and which contain at most 78 characters representing a string and which will be padded with spaces to the right):

Example

Vector_oformat(Global_FO_SHELL_QUOTE, "%7.5s", "Du da!")
  // This means: max. 5 chars, min.7 resulting in padding.)

appends Du\ d  

The number of characters read from the input string can be retrieved by using Vector_roformat() or Vector_rovformat() and reading it from the resulting info structure.

E.g. the following loop generates a C parsable string which does not exceed 78 characters on each line:

int print_c_string (Vector_t *v, char const *c)
{
    Vector_format_info_t info;
    do {
        Vector_roformat (&info, Global_FO_QUOTE_C_STRING, v, "%.78s\n", c);
        c+= info.pos;
    } while (Global_VECTOR_IS_OK(Global_vector_errno) && *c != '\0');
}

If more than one l, q, h and Z flag is given, the last one will be used.

Note

float and double formatations are passed to the standard library. So whether e.g. long double is implemented depends on your clib. This includes the `a' and `A' conversions (GNU).

Further Note

oType_ZERO will be used! This means that if it is != '\0', the %s argument will terminate printing at the first character equal to oType_ZERO.

Global_ERWIN_EXPORT void Vector_ovformat (Vector_t * self, unsigned long int options, Tchar const * format, va_list arguments)

See Vector_oformat.

Global_ERWIN_EXPORT void Vector_format_info_init (Vector_format_info_t *)

Initialises a Vector_format_info_t structure. Only required for C code. In C++, the constructor is used for this.

A Vector_format_info_t structure must be initialised before invoking Vector_rovformat() with a pointer to it.

Global_ERWIN_EXPORT void Vector_format_info_done (Vector_format_info_t *)

Sweeps a Vector_format_info_t structure. Only required for C code. In C++, the destructor is used for this.

A Vector_format_info_t structure must be sweeps before deallocation.

Global_ERWIN_EXPORT void Vector_roformat (Vector_format_info_t * info, Vector_t * self, unsigned long int options, Tchar const * format, ... arguments)

Additional to Vector_oformat it stores information about the performed formatting in info. Use this in favour of Vector_format_quoted to retrieve information you need.

Global_ERWIN_EXPORT void Vector_rovformat (Vector_format_info_t * info, Vector_t * self, unsigned long int options, Tchar const * format, va_list arguments)

Additional to Vector_ovformat it stores information about the performed formatting in info. Use this in favour of Vector_format_quoted to retrieve information you need.

Global_ERWIN_EXPORT Global_ERWIN_BOOL Vector_format_quoted ()

DEPRECATED

Use

Vector_roformat (&info, FO_CHECK ...

Was quotation ever necessary during the format?

This function is not thread safe. It uses global variables. Therefore, this function is not available when you compile with thread support (Global_ERWIN_THREAD_SAFE). Use Vector_rovformat or Vector_roformat.

Global_ERWIN_EXPORT Vector_index_t Vector_format_pos ()

DEPRECATED

Use

Vector_roformat (&info, FO_CHECK ...

Returns how many characters were read from the last %s command.

This function is not thread safe. It uses global variables. Therefore, this function is not available when you compile with thread support (Global_ERWIN_THREAD_SAFE). Use Vector_rovformat or Vector_roformat.

ERWIN_WRAPPER Vector_t * Global_erwin_ptr_of (Vector_t * x)

ERWIN_WRAPPER Vector_t * Global_erwin_ptr_of (Vector_t & x)

ERWIN_WRAPPER Vector_t const * Global_erwin_ptr_const_of (Vector_t const * x)

ERWIN_WRAPPER Vector_t const * Global_erwin_ptr_const_of (Vector_t const & x)

ERWIN_WRAPPER Vector_index_t * Vector_pos_ptr (Vector_t *)

ERWIN_WRAPPER Vector_index_t * Vector_pos_ptr (Vector_t * x)

ERWIN_WRAPPER Vector_index_t Vector_pos (Vector_t *)

ERWIN_WRAPPER Vector_index_t Vector_pos (Vector_t * x)

ERWIN_WRAPPER void Vector_set_pos (Vector_t *, Vector_index_t)

ERWIN_WRAPPER void Vector_set_pos (Vector_t * x, Vector_index_t y)

ERWIN_STATIC_INLINE oTypeResult Vector_nth (Vector_t const * self, Vector_index_t idx)

ERWIN_STATIC_INLINE Vector_cnt_t Vector_nentries (Vector_t const * self)

ERWIN_STATIC_INLINE Global_ERWIN_BOOL Vector_empty (Vector_t const * self)

Global_ERWIN_EXPORT Map_t * Map_new ()

--BEGIN-C--

Return a new map with default settings. I.e., with the default zero element Map_ZERO and the default initial hash table size of Map_INITIAL_SIZE.

Error Codes (errno)

• In case of operation, OK is signalled.
• If memory is exhausted, ERR_NOMEM is signalled. If the option NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Global_ERWIN_EXPORT Map_t * Map_new_with_initial_size (int initial_size)

Create a new map with a given initial hash table. This is useful whenever you know how many entries you will have.

The number you pass is interpreted as the number of elements. The real hash size that will be used will be computed in such a way that no rehash will occur when inserting the number of elements given. Note that a single deletion of an element may still trigger a rehash, only when only inserting the elements, no rehash is guaranteed.

If initial_size < 0 the default size Map_INITIAL_SIZE will be used. If initial_size == 0 but Map_MINIMAL_SIZE > 0, a size of 1 will be used.

With the default value of the re-hash parameters, a re-hash will be done when the map has more than 80% entries compared to the hash table size. So if you intend to insert 80 entries, you must specify more than 100 for the initial size. To be precise, you must specify more than Map_TRIGGER_NUMERATOR * 80 / Map_TRIGGER_DENOMINATOR.

Error Codes (errno)

• In case of operation, OK is signalled.
• If memory is exhausted, ERR_NOMEM is signalled. If the option NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Global_ERWIN_EXPORT Map_t * Map_new_with_zero (oTypeTouched zero)

zero will eventually be tried to be copied! So if you provide oType_OCOPY, make sure it handles the zero element appropriately.

Error Codes (errno)

• In case of operation, OK is signalled.
• If memory is exhausted, ERR_NOMEM is signalled. If the option NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Global_ERWIN_EXPORT Map_t * Map_new_with_zero_and_initial_size (oTypeTouched zero, int initial_size)

Create a new, empty map. The first form uses Global_oType_zero as the zero element.

If initial_size < 0 the default size Map_INITIAL_SIZE will be used. If initial_size == 0 but Map_MINIMAL_SIZE > 0, a size of 1 will be used.

Error Codes (errno)

• In case of operation, OK is signalled.
• If memory is exhausted, ERR_NOMEM is signalled. If the option NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Global_ERWIN_EXPORT int Map_init (Map_t * self)

This is for initialising non-heap Map_t objects.

Invoking this function manually is usually discouraged. It is thought to be for nesting data structures. However, if you need to optimise heap usage, it is ok to use this function.

Error Codes (errno)

• In case of operation, OK is signalled.
• If memory is exhausted, ERR_NOMEM is signalled. If the option NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Global_ERWIN_EXPORT int Map_init_with_zero_and_initial_size (Map_t * self, oTypeTouched zero, int initial_size)

This is for initialising non-heap Map_t objects that are allocated manually (thus, not via Map_new).

Invoking this function manually is usually discouraged. It is thought to be for nesting data structures. However, if you need to optimise heap usage, it is ok to use this function.

Error Codes (errno)

• In case of operation, OK is signalled.
• If memory is exhausted, ERR_NOMEM is signalled. If the option NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Global_ERWIN_EXPORT int Map_init_with_initial_size (Map_t * self, int initial_size)

This is for initialising non-heap Map_t objects.

Invoking this function manually is usually discouraged. It is thought to be for nesting data structures. However, if you need to optimise heap usage, it is ok to use this function.

Error Codes (errno)

• In case of operation, OK is signalled.
• If memory is exhausted, ERR_NOMEM is signalled. If the option NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Global_ERWIN_EXPORT void Map_destroy (Map_t * self)

This is for deleting non-heap Map_t objects.

Invoking this function manually is usually discouraged. It is thought to be for nesting data structures. However, if you need to optimise heap usage, it is ok to use this function.

Error Codes (errno)

• In case of operation, OK is signalled.

Global_ERWIN_EXPORT void Map_destroy_flags (Map_t * self, Global_ERWIN_BOOL destroy_keys, Global_ERWIN_BOOL destroy_values)

Same as Map_destroy with the possiblity to determine what to destroy.

Invoking this function manually is usually discouraged. It is thought to be for nesting data structures. However, if you need to optimise heap usage, it is ok to use this function.

Error Codes (errno)

• In case of operation, OK is signalled.

Global_ERWIN_EXPORT int Map_errno (Map_t const *)

If the library was compiled with Global_ERWIN_THREAD_SAFE, this is the way to retrieve the status code of a map.

If you do not have a thread-safe Erwin library, there is a macro with the same name as this function.

Error Codes

The operation is always successful (not thinking of assertion failures).

Global_ERWIN_EXPORT Map_t * Map_copy (Map_t const * self)

Copies the map with all its keys and elements

NULL is allowed and passed through.

Don't use as a copy function for other Erwin structures. Use _copy_err instead.

Error Codes (errno)

• In case of operation, OK is signalled.
• REHASH_*
• If memory is exhausted, ERR_NOMEM is signalled. If the option NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Global_ERWIN_EXPORT Map_t * Map_copy_err (Map_t const * self, int * err)

Copies the map with all its keys and elements. *err will be set to 1 if an error occurs.

Error Codes (errno)

• In case of operation, OK is signalled.
• REHASH_*
• If memory is exhausted, ERR_NOMEM is signalled. If the option NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Global_ERWIN_EXPORT void Map_delete (Map_t * self)

Deletes everything in the map and the map structure itself

Error Codes (errno)

• In case of operation, OK is signalled.

Global_ERWIN_EXPORT void Map_delete_flags (Map_t * self, Global_ERWIN_BOOL destroy_keys, Global_ERWIN_BOOL destroy_values)

Deletes only the map structure, not the entries. This is useful if you got the entries via Map_get_{values|keys}. Map_delete_flat (a, true, true) is the same as Map_delete (a);

Error Codes (errno)

• In case of operation, OK is signalled.

Global_ERWIN_EXPORT int Map_insert (Map_t * self, iTypeTouched key)

Global_ERWIN_EXPORT int Map_find_any_pair (Map_key_result_t *, Map_t const * self)

Global_ERWIN_EXPORT oTypeVar Map_remove_no_resize (Map_t * self, iTypeTouched index)

Like Map_remove, but does not shrink the internal hash table.

Error Codes (errno)

• In case of operation, OK is signalled.
• WARN_KEYNOTFOUND

Note that a warning means that the operation was successfully completed.

Global_ERWIN_EXPORT int Map_erase_no_resize (Map_t * self, iTypeTouched index)

Same as Map_erase, but does not shrink the internal hash table.

Error Codes (errno)

• In case of operation, OK is signalled.
• WARN_KEYNOTFOUND

Note that a warning means that the operation was successfully completed.

Global_ERWIN_EXPORT int Map_erase_map_no_resize (Map_t * self, Map_t const * other)

Like Map_erase_map, but does not shrink the internal hash table.

Error Codes (errno)

• In case of operation, OK is signalled.
• WARN_KEYNOTFOUND

Note that a warning means that the operation was successfully completed.

Global_ERWIN_EXPORT int Map_poke (iType * key_out, Map_t * self, iTypeTouched key, Global_ERWIN_BOOL introduce)

Global_ERWIN_EXPORT int Map_poke_no_icopy (iType * key_out, Map_t * self, iTypeVarParam key, Global_ERWIN_BOOL introduce)

Global_ERWIN_EXPORT int Map_cmp_keys (Map_t const * self, Map_t const * other)

Returns whether the set of keys in the map is equal.

Note

This operation is quite expensive. Use keys_equal if that is sufficient.

Further Note

Calling this results in a runtime error if either Global_iType_CMP is not defined.

Error Codes (errno)

• In case of operation, OK is signalled.
• If memory is exhausted, ERR_NOMEM is signalled. If the option NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Global_ERWIN_EXPORT Global_ERWIN_BOOL Map_equal_keys (Map_t const * self, Map_t const * other)

Returns whether the set of keys in the map is equal.

Note

This operation is quite expensive but less expensive than Map_keys_cmp

Error Codes (errno)

• In case of operation, OK is signalled.

ERWIN_WRAPPER Global_hashval_t Map_hash (Map_t const *)

Same as Map_hash_raw() now that hash_raw() is good enough.

Global_ERWIN_EXPORT void Map_clear_flags_no_resize (Map_t * self, Global_ERWIN_BOOL destroy_keys, Global_ERWIN_BOOL destroy_values)

Like Map_clear_flags, but does not shrink the internal hash table.

Error Codes (errno)

• In case of operation, OK is signalled.

Global_ERWIN_EXPORT Global_ERWIN_BOOL Map_expect_size (Map_t * self, int newsize)

Declare that the immediately following action will insert or delete elements so that the new number of elements will be newsize. This will possibly rehash to a hash size that requires no rehashes during the following operation. Note: this only works if you consistently insert or consistently delete elements. If you mix the operations, further rehashes might occur.

Returns whether a rehash was performed.

Error Codes (errno)

• In case of operation, OK is signalled.
• REHASH_*

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

ERWIN_WRAPPER Map_t * Global_erwin_ptr_of (Map_t * x)

ERWIN_WRAPPER Map_t * Global_erwin_ptr_of (Map_t & x)

ERWIN_WRAPPER Map_t const * Global_erwin_ptr_const_of (Map_t const * x)

ERWIN_WRAPPER Map_t const * Global_erwin_ptr_const_of (Map_t const & x)

Global_ERWIN_EXPORT List_t * List_new ()

Create a new list with default values. I.e., with the default zero element List_ZERO and the default initial hash table size of List_INITIAL_SIZE.

Global_ERWIN_EXPORT List_t * List_new_with_zero (oTypeTouched zero)

Create a list specifying the zero element.

Global_ERWIN_EXPORT oTypeResult List_zero (List_t const * self)

Global_ERWIN_EXPORT int List_errno (List_t const *)

If you compiled Erwin with Global_ERWIN_THREAD_SAFE, this is the way to get the status code of a given list.

If you do not have a thread-safe Erwin library, there is a macro with the same name as this function.

Error Codes

The operation is always successful (not thinking of assertion failures).

Global_ERWIN_EXPORT List_t * List_copy (List_t const * self)

Copies a list with all its elements and returns that copy.

Global_ERWIN_EXPORT List_t * List_copy_err (List_t const * self, int * err)

Like List_copy but sets *err to 1 on failure.

Global_ERWIN_EXPORT void List_delete (List_t * self)

Deletes everything in the list and the list structure itself. List_delete is NULL safe (self may be NULL without crash or failed assertion).

Global_ERWIN_EXPORT Global_list_key_t List_previous_raw (Global_list_key_t key)

Returns the previous element in the list or NULL if non exists.

If key == Global_LIST_KEY_ZERO, this function cannot return List_back(), because the list pointer is not given. Instead, it returns Global_LIST_KEY_ZERO again.

Global_ERWIN_EXPORT Global_list_key_t List_next_raw (Global_list_key_t key)

Returns the next element in the list or NULL if non exists

If key == Global_LIST_KEY_ZERO, this function cannot return List_front(), because the list pointer is not given. Instead, it returns Global_LIST_KEY_ZERO again.

Global_ERWIN_EXPORT oTypeResult List_value_raw (Global_list_key_t key)

Returns the value for the given key or the zero element.

Invocation is only valid for key != Global_LIST_KEY_ZERO.

Global_ERWIN_EXPORT Global_hashval_t List_hash_raw (List_t const *)

Returns a hash value, which is derived from hash values for oType.

Note

Usually you want hash values if you work with maps. So you should define the hash value in such a way that both the map header as well as the list header find them.

Further Note

This will only be implemented if Global_oType_HASH_RAW is defined.

ERWIN_WRAPPER Global_hashval_t List_hash (List_t const *)

Same as List_hash_raw() now that hash_raw() is good enough.

ERWIN_WRAPPER Global_hashval_t List_hash (List_t const * x)

ERWIN_WRAPPER List_t * Global_erwin_ptr_of (List_t * x)

ERWIN_WRAPPER List_t * Global_erwin_ptr_of (List_t & x)

ERWIN_WRAPPER List_t const * Global_erwin_ptr_const_of (List_t const * x)

ERWIN_WRAPPER List_t const * Global_erwin_ptr_const_of (List_t const & x)

extern char Global_char_to_upper (char)

These are in base.c but are needed here already.

extern char Global_char_to_lower (char)

ERWIN_WRAPPER Global_hashval_t Global_char_hash (unsigned char x)

ERWIN_WRAPPER Global_hashval_t Global_char_hash (unsigned char x)

ERWIN_WRAPPER Global_hashval_t Global_char_hash2 (unsigned char x)

ERWIN_WRAPPER Global_hashval_t Global_char_hash2 (unsigned char x)

ERWIN_WRAPPER Global_hashval_t Global_char_hash3 (unsigned char x)

ERWIN_WRAPPER Global_hashval_t Global_char_hash3 (unsigned char x)

ERWIN_WRAPPER Global_hashval_t Global_char_hash4 (unsigned char x)

ERWIN_WRAPPER Global_hashval_t Global_char_hash4 (unsigned char x)

ERWIN_WRAPPER Global_hashval_t Global_erwin_mul9 (Global_hashval_t x)

Internal function, do not use! It may change or disappear without notice!

ERWIN_WRAPPER Global_hashval_t Global_erwin_mul9 (Global_hashval_t x)

ERWIN_WRAPPER Global_hashval_t Global_erwin_mul_x1 (Global_hashval_t x)

Internal function, do not use! It may change or disappear without notice!

ERWIN_WRAPPER Global_hashval_t Global_erwin_mul_x1 (Global_hashval_t x)

ERWIN_WRAPPER Global_hashval_t Global_erwin_u16_hash (ERWIN_U16 x)

ERWIN_WRAPPER Global_hashval_t Global_erwin_u16_hash (ERWIN_U16 x)

ERWIN_WRAPPER Global_hashval_t Global_erwin_u32_hash (ERWIN_U32 x)

ERWIN_WRAPPER Global_hashval_t Global_erwin_u32_hash (ERWIN_U32 x)

ERWIN_WRAPPER Global_hashval_t Global_erwin_u64_hash (ERWIN_U64 x)

ERWIN_WRAPPER Global_hashval_t Global_erwin_u64_hash (ERWIN_U64 x)

ERWIN_WRAPPER Global_hashval_t Global_short_hash (unsigned short x)