Sitemap

 

Description

The Vector Class

This class implements dynamically resizable arrays.

Throughout the documentation, the following prefixes will be used:

Global_

The library prefix: for applications, this is typically empty, for an xyz-Library, this is either XYZ_, xyz_ or Xyz, depending on the identifier in occurs in.

	Template		Instantiation
	Global_VECTOR_OK		XYZ_VECTOR_OK
	Global_vector_new		xyz_vector_new

Vector_

This is equivalent to Global_vector_oType, or the name that was set with -name=... for this data structure. The case and underbar convention is adjusted, too.

Assuming a library prefix xyz and oType == char, you get:

	Template		Instantiation
	Vector_t		xyz_vector_char_t
	Vector_ALLOW_NULL		XYZ_VECTOR_CHAR_ALLOW_NULL

Vector_class

This is the name of the data structure type in C++: capitalised and with underbars removed:

	Vector_t		Vector_class
	vector_char_t		VectorChar

Conventions

It was tried to keep the argument order consistent, with some rules:

• for functions returning multiple values into pointer arguments, these are always before input arguments. (e.g. Vector_locate (output, self, ...)). (Mnemonic: like memcpy, strcpy, assignment statement etc.)

  Global_ERWIN_BOOL Vector_locate (int *i, Vector_t const *, ...)
  ^output                          ^output ^input            ^input
                                           ^first input = self

• the self argument is always the first input argument.

• index before element (e.g.,

  Vector_insert (self, position, element)

• count after element(s). E.g.:

  Vector_insert_raw (self, position, elemnt_ptr, count)

• flags last. E.g.:

  Vector_overwrite_flags (self, start, value, count,
                          copy_elems, delete_overwritten)

Results

• if there is no natural result value, C functions return their success, i.e., the value of Global_vector_errno:

  int Vector_erase (Vector_t *self, int pos, int count)

  In these circumstances, C++ functions return the vector itself as a reference:

  Vector_t &Vector_t::erase (int pos, int count = 1)

• if Vector_errno is not interesting, either because it is not set or because only memory overflow or assertion failures may be a possible sources of an error, the C functions return void:

  void Vector_delete (Vector_t *self)

  The C++ functions still return the object reference.

Status Codes

These are undef'ed first because there is only one error code for all the arrays in your program. All the functions returing error codes will both return this error and write it into Global_vector_errno.

In all cases, the consistency of the data structure is guaranteed.

Warnings are only visible in Global_vector_errno; the functions still return VECTOR_OK.

Members

Detailed Descriptions

static void * operator new (size_t)

static void operator delete (void *, size_t)

static void * operator new[] (size_t)

static void operator delete[] (void *, size_t)

[constructor] Vector ()

static Vector_t const & static_zero ()

[constructor] Vector (Vector_cnt_t initial_size)

[constructor] Vector (oTypeTouched)

[constructor] Vector (oTypeTouched, Vector_cnt_t)

[constructor] Vector (Vector_t const *, bool do_copy = true)

[constructor] Vector (Vector_t const *, Vector_index_t, Vector_cnt_t, bool do_copy = true)

[constructor] Vector (oTypeVar const *, bool do_copy = true)

[constructor] Vector (oTypeVar const *, Vector_cnt_t, bool do_copy = true)

[constructor] Vector (oType const *)

[constructor] Vector (oType const *, Vector_cnt_t)

[constructor] Vector (bool must_be_true, oTypeVar * other, Vector_cnt_t count, Vector_cnt_t alloc)

alloc may be -1: see Vector_new_from_raw

[constructor] Vector (bool must_be_true, oTypeVar * other, Vector_cnt_t count, Vector_cnt_t alloc, oTypeTouched zero_element)

alloc may be -1: see Vector_new_from_raw

[constructor] Vector (bool must_be_true, Vector_t * other)

[constructor] Vector (bool must_be_true, Vector_t & other)

void _constructor ()

void _destructor ()

int get_errno () const

void clear_errno () 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 (Global_vector_errno)

• In case of operation, Global_VECTOR_OK is signalled.

static int get_errno ()

static void clear_errno ()

[constructor] Vector (Vector_t const &, bool docopy = true)

[constructor] Vector (Vector_t const &, Vector_index_t, Vector_cnt_t, bool do_copy = true)

Vector_t * copy () const

Vector_t * copy_err (int * err) const

Vector_t * copy_detach ()

This might be strange: it makes a new vector from the contents of the other vector and then detaches the data from the other vector. Its purpose is mainly useful in C++ where you can clone vectors from a static vector by this means. E.g.:

 Vector_class a;
 ...
 return Vector_new_from_vector (a);

Or with the same effect, but without the need to use a long functions name: return a.copy_detach();

A related thing is Vector_xchg(), because the above is also roughly equivalent to:

Vector_t a;
...
Vector_t *b= Vector_new();
Vector_xchg(&a, b);
return b;

Vector_t & xchg (Vector_t * other)

Exchanges the two vectors' contents. No memory allocation is performed; this is a fast O(1) operation for swapping two values.

Vector_t & xchg (Vector_t & other)

Exchanges the two vectors' contents. No memory allocation is performed; this is a fast O(1) operation for swapping two values.

Vector_t * subvector (Vector_index_t b, Vector_cnt_t c) const

Vector_t * subvector (Vector_index_t b, Vector_cnt_t c, bool d) const

Vector_t & operator= (Vector_t const &)

Vector_t & operator= (Vector_t const *)

[destructor] ~Vector ()

Vector_t & detach ()

Clears the vector by initialising a new completely empty table not consuming any memory. The effect is mainly that you can use the value of Vector_as_array and Vector_as_open_array independently from the vector. The old function delete_flat is now a sequence of detach() and delete().

Note

This function should be used when the vector is not needed anymore after a cast to a raw array (e.g. by Vector_as_array).

Compare this function with Vector_detach_as_is(). These functions are important to distinguish if you defined Global_oType_UPDATE_POS.

Note

use Vector_delete_array() to deallocate the memory if you retrieve it with, say, Vector_as_open_array().

Note

See the documentation of Vector_delete_array and Vector INLINE_STORE!

Vector_t & detach_as_is ()

Like Vector_detach_as_is(), but does not invoke Global_oType_UPDATE_POS for all elements to set them to -1.

This function is only different from Vector_detach if you defined Global_oType_UPDATE_POS. Otherwise, it is the same.

operator Vector_t const * () const

operator Vector_t * ()

operator Vector_element_ptr_t () const

operator bool () const

Vector_index_t * pos_ptr ()

Vector_index_t & pos_ref ()

Vector_index_t pos ()

void set_pos (Vector_index_t y)

oTypeResult nth (Vector_index_t i) const

Returns the found element or the zero element on failure. If index is out of range, a message is also output to stderr if you defined Global_ERWIN_VERBOSE.

oTypeResult nth_char (Vector_index_t i) const

Returns the found element or the zero element on failure.

If you access the element just after the end of the vector, then that is regarded legal in this function and the zero element is returned.

If index is out of range, a message is also output to stderr if you defined Global_ERWIN_VERBOSE.

Dev.Note: this is pure: cmp to Vector_nth_char_ptr and see Vector_as_array().

Vector_element_ptr_t nth_ptr_check (Vector_index_t i)

Returns a pointer to the element at index or an signals an error if the index is out of range. (This is the same behaviour towards errors as Vector_nth has)

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

Dev.Note: not pure with ALLOW_OUTOFRANGE option.

oType const * nth_ptr_check (Vector_index_t i) const

Vector_element_ptr_t nth_ptr_char (Vector_index_t i)

Returns a pointer to the element at index if it is in range. If is is one too large, returns a pointer to the element after the end, mimicking string behaviour. That element is guaranteed to be allocated, of couse. If you write to that element, it only is guarateed to have any effect up to the next change to the vector size. Don't change that element, though.

Because this function is so similar to adding an integer to a 'char const *', i.e., to get a suffix string, this function always zero-terminates the vector like Vector_as_array() does. So Vector_nth_ptr_char(self,0) is equivalent to Vector_as_array().

Note

This behaves a bit strange together with ALLOW_OUTOFRANGE: Accesses to any element starting from a[nentries()] make the vector larger for the non-const version! This includes the nentries()th element, which, even if only read with this function, enlarges the vector due to the potential threat of the user writing to it.

In case ALLOW_OUTOFRANGE is off, this never makes the vector larger, but does allow access to nentries()th element. That element is always ensured to be ZERO, however, so you cannot write to it.

This signals an error if the index is out of range. (This is the some behaviour towards errors as Vector_nth_char has.)

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

Dev.Note: not pure, see Vector_as_array().

oType const * nth_ptr_char (Vector_index_t i) const

Vector_element_ptr_t nth_ptr (Vector_index_t i)

Returns a pointer to the element at index or NULL if index is out of range.

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

Dev.Note: not pure with ALLOW_OUTOFRANGE option.