s2list.h File Reference

The list type. More...

#include "s2obj.h"
#include "s2containers.h"

Macros
#define	s2_is_list(obj)
#define	s2list_shift_T(membertype)
#define	s2list_pop_T(membertype)
#define	s2list_get_T(membertype)
#define	S2_LIST_SEEK_SET   1
	Seek relative to the beginning of the list.
#define	S2_LIST_SEEK_END   2
	Seek relative to the end of the list.
#define	S2_LIST_SEEK_CUR   3
	Displace the cursor on the list.

Typedefs
typedef T	s2list_t
	the working context for the 'list' type s2list_t. In the following prose, s2list_t will be abbreviated as T.
typedef int(*	s2func_sort_cmp_t) (s2obj_t *a, s2obj_t *b)
	total order predicate.
typedef struct s2ctx_list_iter	s2list_iter_t
	the list iterator type that enumerates members in order.

Functions
T *	s2list_create ()
	Creates and returns an empty list.
int	s2list_insert (T *list, s2obj_t *obj, int semantic)
	Inserts an element at the cursor without advancing it.
int	s2list_push (T *list, s2obj_t *obj, int semantic)
	Inserts an element at the cursor and advance it.
int	s2list_shift (T *list, s2obj_t **out)
	Removes the item at the cursor from the list and place it in out.
int	s2list_pop (T *list, s2obj_t **out)
	Removes the item just before the cursor and place it in *out.
int	s2list_get (T *list, s2obj_t **out)
	Retrieves object at current cursor position.
int	s2list_put (T *list, s2obj_t *obj, int semantic)
	Puts an object at the current position, the old value is replaced.
ptrdiff_t	s2list_pos (T *list)
ptrdiff_t	s2list_len (T *list)
ptrdiff_t	s2list_seek (T *list, ptrdiff_t offset, int whence)
	reposition the cursor on the list.
T *	s2list_sort (T *list, s2func_sort_cmp_t cmpfunc)
	insert sort of list with total order predicate compfunc.

Detailed Description

The list type.

Macro Definition Documentation

s2_is_list

#define s2_is_list

(

obj

)

Value:

(((s2obj_t *)obj)->type == S2_OBJ_TYPE_LIST)

Parameters

obj	the object handle the type of which is being checked.

Returns

true if the object handle of list type, false otherwise.

s2list_get_T

#define s2list_get_T

(

membertype

)

Value:

    ((int (*)(s2list_t *list, membertype **out))s2list_get)

Parameters

membertype

the type of the object the handle would point to.

The type-safe method to get a value object without type casting. Invoked as s2list_get_T(type)(list, out). Defined as a marcro in terms of s2dict_get.

s2list_pop_T

#define s2list_pop_T

(

membertype

)

Value:

    ((int (*)(s2list_t *list, membertype **out))s2list_pop)

Parameters

membertype

the type of the object the handle would point to.

The type-safe method to get a value object without type casting. Invoked as s2list_pop_T(type)(list, out). Defined as a marcro in terms of s2list_pop.

s2list_shift_T

#define s2list_shift_T

(

membertype

)

Value:

    ((int (*)(s2list_t *list, membertype **out))s2list_shift)

Parameters

membertype

the type of the object the handle would point to.

The type-safe method to get a value object without type casting. Invoked as s2list_shift_T(type)(list, out). Defined as a marcro in terms of s2list_shift.

Typedef Documentation

s2func_sort_cmp_t

typedef int(* s2func_sort_cmp_t) (s2obj_t *a, s2obj_t *b)

total order predicate.

Returns

less than 0 if a<b, 0 if a==b, and 1 if a>b.

Parameters

a	the first object.
b	the second object.

The implmentations of this function computes the total order predicate of its operands.

s2list_t

typedef T s2list_t

the working context for the 'list' type s2list_t. In the following prose, s2list_t will be abbreviated as T.

As there's no silver bullet for a type to support both fast arbitrary indexed access, and fast arbitrary slicing, the direction of the design decision lean towards more primitive operations that can readily compose into useful sequential operations.

The list consist of

• an ordered sequence of values derived from s2obj_t,
• a cursor positioned at one of the element on the sequence.

Function Documentation

s2list_create()

T * s2list_create

(

)

Creates and returns an empty list.

Returns

a pointer to the list object handle, or NULL on error.

s2list_get()

int s2list_get	(	T *	list,
		s2obj_t **	out )

Retrieves object at current cursor position.

Parameters

list	the list object handle.
out	the pointer to the object handle where the retrieved object will be stored.

Reference and kept counts're not changed.

s2list_insert()

int s2list_insert	(	T *	list,
		s2obj_t *	obj,
		int	semantic )

Inserts an element at the cursor without advancing it.

Parameters

list	the list object handle.
obj	the element to insert.
semantic	the setter semantic to use (see s2containers.h).

Returns

one of the access return values (see s2containers.h).

s2list_len()

ptrdiff_t s2list_len

(

T *

list

)

Parameters

list	the list object handle.

Returns

the length of the list.

s2list_pop()

int s2list_pop	(	T *	list,
		s2obj_t **	out )

Removes the item just before the cursor and place it in *out.

Parameters

list	the list object handle.
out	the pointer to the object handle where the retrieved object will be stored.

Returns

one of the access return values (see s2containers.h).

This function decreases the kept count and increases the reference count both by 1, as the retrieved object is no longer in the list at where it was.

Implementation note: this function is found redundant and anti-logical, adding the fact that it's implemented in terms of s2list_shift, this function is probably inefficient and its use is better avoided.

s2list_pos()

ptrdiff_t s2list_pos

(

T *

list

)

Parameters

list	the list object handle.

Returns

the current cursor position in the list.

s2list_push()

int s2list_push	(	T *	list,
		s2obj_t *	obj,
		int	semantic )

Inserts an element at the cursor and advance it.

Parameters

list	the list object handle.
obj	the element to insert.
semantic	the setter semantic to use (see s2containers.h).

Returns

one of the access return values (see s2containers.h).

s2list_put()

int s2list_put	(	T *	list,
		s2obj_t *	obj,
		int	semantic )

Puts an object at the current position, the old value is replaced.

Parameters

list	the list object handle.
obj	the element to put to the current cursor position.
semantic	the setter semantic to use (see s2containers.h).

Returns

one of the access return values (see s2containers.h).

s2list_seek()

ptrdiff_t s2list_seek	(	T *	list,
		ptrdiff_t	offset,
		int	whence )

reposition the cursor on the list.

Parameters

list	the list object handle.
offset	the offset to add relative to whence.
whence	the anchor relative to which to offset (see S2_LIST_SEEK_* constants).

Returns

The new cursor position in the list. If any error occurs (e.g. out-of-bound position), -1 is returned.

s2list_shift()

int s2list_shift	(	T *	list,
		s2obj_t **	out )

Removes the item at the cursor from the list and place it in out.

Parameters

list	the list object handle.
out	the pointer to the object handle where the retrieved object will be stored.

Returns

one of the access return values (see s2containers.h).

This function decreases the kept count and increases the reference count both by 1, as the retrieved object is no longer in the list at where it was.

s2list_sort()

T * s2list_sort	(	T *	list,
		s2func_sort_cmp_t	cmpfunc )

insert sort of list with total order predicate compfunc.

Returns

list.