Skip to content

sequence.h#

Array and Vector objects interface.

Authors#

TheSilvered

Sequence creation format types#

  • I: Int from a 64-bit integer
  • i: Int from a 32-bit integer
  • f, F: Real from a double
  • b: Bool from a boolean (promoted to an int)
  • B: Byte from a 8-bit integer
  • s: Str from a NUL-terminated string
  • S: Str from a Nst_StrView
  • o: an already existing object to take one reference from
  • O: an already existing object to add one reference to
  • n: null, the vararg can be any pointer as its value is ignored but NULL is preferred

Note

The fmt string cannot contain whitespace.

Macros#

_Nst_VECTOR_MIN_CAP#

Description:

The minimum capacity of a Vector object.

_Nst_VECTOR_GROWTH_RATIO#

Description:

Growth ratio of a Vector object.

Functions#

Nst_array_new#

Synopsis:

Nst_ObjRef *Nst_array_new(usize len)

Description:

Create a new Array object of the specified length. The slots are filled with null values.

Parameters:

  • len: the length of the array to create

Returns:

The new object on success or NULL on failure. The error is set.

Nst_vector_new#

Synopsis:

Nst_ObjRef *Nst_vector_new(usize len)

Description:

Create a new Vector object of the specified length. The slots are filled with null values.

Parameters:

  • len: the length of the vector to create

Returns:

The new object on success or NULL on failure. The error is set.

Nst_array_from_objs#

Synopsis:

Nst_ObjRef *Nst_array_from_objs(usize len, Nst_Obj **objs)

Description:

Create a new Array object given an array of objects. A reference is added to each object.

Parameters:

  • len: the number of objects in objs
  • objs: the objects to use to initialize the array

Returns:

The new object on success and NULL on failure. The error is set.

Nst_vector_from_objs#

Synopsis:

Nst_ObjRef *Nst_vector_from_objs(usize len, Nst_Obj **objs)

Description:

Create a new Vector object given an array of objects. A reference is added to each object.

Parameters:

  • len: the number of objects in objs
  • objs: the objects to use to initialize the array

Returns:

The new object on success and NULL on failure. The error is set.

Nst_array_from_objsn#

Synopsis:

Nst_ObjRef *Nst_array_from_objsn(usize len, Nst_ObjRef **objs)

Description:

Create a new Array object given an array of objects. A reference is taken from each object.

Parameters:

  • len: the number of objects in objs
  • objs: the objects to use to initialize the array

Returns:

The new object on success and NULL on failure. The error is set.

Nst_vector_from_objsn#

Synopsis:

Nst_ObjRef *Nst_vector_from_objsn(usize len, Nst_ObjRef **objs)

Description:

Create a new Vector object given an array of objects. A reference is taken from each object.

Parameters:

  • len: the number of objects in objs
  • objs: the objects to use to initialize the array

Returns:

The new object on success and NULL on failure. The error is set.

Nst_array_create#

Synopsis:

Nst_ObjRef *Nst_array_create(usize len, ...)

Description:

Create a new Array object of the length specified, inserting the objects inside.

The number of varargs passed to the function must match the number given in the len parameter.

Parameters:

  • len: the length of the array to create
  • ...: the objects to insert in the array, a reference is taken from each object

Returns:

The new array on success or NULL on failure. The error is set.

Nst_vector_create#

Synopsis:

Nst_ObjRef *Nst_vector_create(usize len, ...)

Description:

Create a new Vector object of the length specified, inserting the objects inside.

The number of varargs passed to the function must match the number given in the len parameter.

Parameters:

  • len: the length of the vector to create
  • ...: the objects to insert in the vector, a reference is taken from each object

Returns:

The new vector on success or NULL on failure. The error is set.

Nst_array_create_c#

Synopsis:

Nst_ObjRef *Nst_array_create_c(const char *fmt, ...)

Description:

Create a new Array object, creating the contained objects from C values.

The number of varargs passed to the function must match the number of types in the fmt argument. For more information about the fmt argument check the documentation in sequence.h

Parameters:

  • fmt: the types of the values passed to the function
  • ...: the values passed to the function used to create the objects

Returns:

The new array on success or NULL on failure. The error is set.

Nst_vector_create_c#

Synopsis:

Nst_ObjRef *Nst_vector_create_c(const char *fmt, ...)

Description:

Creates a new Vector object, creating the contained objects from C values.

The number of varargs passed to the function must match the number of types in the fmt argument. For more information about the fmt argument check the documentation in sequence.h

Parameters:

  • fmt: the types of the values passed to the function
  • ...: the values passed to the function used to create the objects

Returns:

The new array on success or NULL on failure. The error is set.

Nst_seq_copy#

Synopsis:

Nst_ObjRef *Nst_seq_copy(Nst_Obj *seq)

Description:

Create a shallow copy of a sequence.

Parameters:

  • seq: the sequence to copy

Returns:

The new sequence or NULL on failure. The error is set.

_Nst_seq_traverse#

Synopsis:

void _Nst_seq_traverse(Nst_Obj *seq)

Description:

Nst_ObjTrav function for Array and Vector objects.

Nst_seq_len#

Synopsis:

usize Nst_seq_len(Nst_Obj *seq)

Returns:

The length of a sequence.

Nst_vector_cap#

Synopsis:

usize Nst_vector_cap(Nst_Obj *vect)

Returns:

The capacity of a vector.

Nst_seq_objs#

Synopsis:

Nst_Obj **Nst_seq_objs(Nst_Obj *seq)

Returns:

The object array of a sequence.

Nst_seq_set#

Synopsis:

bool Nst_seq_set(Nst_Obj *seq, i64 idx, Nst_Obj *val)

Description:

Change the value of an index in a sequence. Adds a reference to val.

idx can be negative in which case it is subtracted from the length of the sequence to get the new index.

Parameters:

  • seq: the sequence to modify
  • idx: the index to update
  • val: the value to set the index to

Returns:

true on success and false on failure. The error is set. This function fails when the index is outside the sequence.

Nst_seq_setf#

Synopsis:

void Nst_seq_setf(Nst_Obj *seq, usize idx, Nst_Obj *val)

Description:

Change the value of an index in a sequence quickly. Adds a reference to val. Negative indices are not supported.

Warning

Use this function only if you are certain that idx is inside seq. Bound checks are only performed in debug builds.

Parameters:

  • seq: the sequence to modify
  • idx: the index to update
  • val: the value to set the index to

Nst_seq_setn#

Synopsis:

bool Nst_seq_setn(Nst_Obj *seq, i64 idx, Nst_ObjRef *val)

Description:

Change the value of an index in a sequence. Takes a reference from val.

idx can be negative in which case it is subtracted from the length of the sequence to get the new index.

Parameters:

  • seq: the sequence to modify
  • idx: the index to update
  • val: the value to set the index to

Returns:

true on success and false on failure. The error is set. This function fails when the index is outside the sequence.

Nst_seq_setnf#

Synopsis:

void Nst_seq_setnf(Nst_Obj *seq, usize idx, Nst_ObjRef *val)

Description:

Change the value of an index in a sequence quickly. Takes a reference from val. Negative indices are not supported.

Warning

Use this function only if you are certain that idx is inside seq. Bound checks are only performed in debug builds.

Parameters:

  • seq: the sequence to modify
  • idx: the index to update
  • val: the value to set the index to

Nst_seq_get#

Synopsis:

Nst_ObjRef *Nst_seq_get(Nst_Obj *seq, i64 idx)

Description:

Get a reference to a value in a sequence.

Parameters:

  • seq: the sequence to get the value from
  • idx: the index of the value to get

Returns:

A new reference to the object at idx on success and NULL on failure. The error is set. The function fails when the index is outside the sequence.

Nst_seq_getf#

Synopsis:

Nst_ObjRef *Nst_seq_getf(Nst_Obj *seq, usize idx)

Description:

Get a reference to a value in a sequence quickly.

Warning

Use this function only if you are certain that idx is inside seq. Bound checks are only performed in debug builds.

Parameters:

  • seq: the sequence to get the value from
  • idx: the index of the value to get

Returns:

A new reference to the object at idx.

Nst_seq_getn#

Synopsis:

Nst_Obj *Nst_seq_getn(Nst_Obj *seq, i64 idx)

Description:

Get a value in a sequence without taking a reference.

Parameters:

  • seq: the sequence to get the value from
  • idx: the index of the value to get

Returns:

A pointer to the object at idx on success and NULL on failure. The error is set. The function fails when the index is outside the sequence.

Nst_seq_getnf#

Synopsis:

Nst_Obj *Nst_seq_getnf(Nst_Obj *seq, usize idx)

Description:

Get a value in a sequence without taking a reference quickly.

Warning

Use this function only if you are certain that idx is inside seq. Bound checks are only performed in debug mode.

Parameters:

  • seq: the sequence to get the value from
  • idx: the index of the value to get

Returns:

A pointer to the object at idx.

Nst_vector_append#

Synopsis:

bool Nst_vector_append(Nst_Obj *vect, Nst_Obj *val)

Description:

Append a value to the end of a vector adding a reference to val.

Parameters:

  • vect: the vector to append the value to
  • val: the value to append

Returns:

true on success and false on failure. The error is set.

Nst_vector_remove#

Synopsis:

bool Nst_vector_remove(Nst_Obj *vect, Nst_Obj *val)

Description:

Remove the first occurrence of a value inside a vector.

Parameters:

  • vect: the vector to remove the value from
  • val: an object that is equal to the value to remove, the equality is checked with Nst_obj_eq

Returns:

true if the object was removed and false if there was no object that matched. No error is set.

Nst_vector_pop#

Synopsis:

Nst_ObjRef *Nst_vector_pop(Nst_Obj *vect, usize quantity)

Description:

Pop a certain number of values from the end of a vector.

If the quantity is greater than the length of the vector, it is adapted and the function does not fail.

Parameters:

  • vect: the vector to pop the values from
  • quantity: the number of values to pop

Returns:

The last value popped or NULL if no value was popped. No error is set.