seglist.c File Reference

Segmented list data type and operations. More...

#include "pm.h"

Defines
#define	__FILE_ID__   0x10
#define	SEGLIST_CLEAR_SEGMENTS   1
Functions
PmReturn_t	seglist_appendItem (pSeglist_t pseglist, pPmObj_t pobj)
PmReturn_t	seglist_clear (pSeglist_t pseglist)
PmReturn_t	seglist_findEqual (pSeglist_t pseglist, pPmObj_t pobj, int16_t *r_index)
PmReturn_t	seglist_getItem (pSeglist_t pseglist, int16_t index, pPmObj_t *r_pobj)
PmReturn_t	seglist_insertItem (pSeglist_t pseglist, pPmObj_t pobj, int16_t index)
PmReturn_t	seglist_new (pSeglist_t *r_pseglist)
PmReturn_t	seglist_setItem (pSeglist_t pseglist, pPmObj_t pobj, int16_t index)
PmReturn_t	seglist_removeItem (pSeglist_t pseglist, uint16_t index)

---

Detailed Description

Segmented list data type and operations.

The segmented list is used to implement the Python List and Dict data types. The segmented list is used in preference to the linked list in order to reduce the memory overhead.

Unused slots in the segments are expected to contain C_NULL.

List implementation: When used in a List, the Seglist.currseg field points to the last segment in the list. The function seglist_appendItem() should be used to append items to the List. Inserting and deleting List items is a more complicated matter.

Dict implementation: The currseg field is meaningless since rootseg always points to the current active segment. The function seglist_pushItem() should be used to put items in the Dict. A Dict uses one Seglist for keys and another for values. A Dict entry's (key, value) pair share the same index in the Seglist.

---

Define Documentation

#define SEGLIST_CLEAR_SEGMENTS   1

Set this to 1 if seglist_clear() should manually free its segments. Set this to 0 if seglist_clear() should do nothing and let the GC reclaim objects.

---

Function Documentation

PmReturn_t seglist_appendItem	(	pSeglist_t	pseglist,
		pPmObj_t	pobj
	)

Puts the new object at the end of the list. This is intended for the List type where the List index matches the order of the Seglist index. Make room if necessary by adding new segments.

Parameters:

	pseglist	Ptr to seglist to scan
	indx	Index of object to obtain

Returns:

Return status

PmReturn_t seglist_clear

(

pSeglist_t

pseglist

)

Clears the the seglist by unlinking the root segment.

Parameters:

pseglist

Ptr to seglist to empty

PmReturn_t seglist_findEqual	(	pSeglist_t	pseglist,
		pPmObj_t	pobj,
		int16_t *	r_index
	)

Finds the first obj equal to pobj in the seglist. Starts searching the list at the given segnum and indx.

Parameters:

	pseglist	The seglist to search
	pobj	The object to match
	r_index	Return arg; the index of where to start the search. If a match is found, return the index by reference. If no match is found, this value is undefined.

Returns:

Return status; PM_RET_OK means a matching object was found. PM_RET_ERR otherwise.

PmReturn_t seglist_getItem	(	pSeglist_t	pseglist,
		int16_t	index,
		pPmObj_t *	r_pobj
	)

Gets the item in the seglist at the given coordinates. The segment number and the index within the segment are the coordinates of the object to get.

Parameters:

	pseglist	Ptr to seglist to scan
	index	Index of item to get
	r_pobj	Return arg; Ptr to object at the index

Returns:

Return status; PM_RET_OK if object found. PM_RET_ERR otherwise.

PmReturn_t seglist_insertItem	(	pSeglist_t	pseglist,
		pPmObj_t	pobj,
		int16_t	index
	)

Puts the item in the next available slot in the first available segment. This is intended for the Dict type where the Seglist index is insignificant. Pushing an object assures it will be found early during a call to seglist_findEqual().

Parameters:

	pseglist	Ptr to seglist in which object is placed.
	pobj	Ptr to object which is inserted.
	index	Index into seglist before which item is inserted

Returns:

Return status; PM_RET_OK if the item was inserted. Any error condition comes from heap_getChunk.

PmReturn_t seglist_new

(

pSeglist_t *

r_pseglist

)

Allocates a new empty seglist

Parameters:

r_pseglist

return; Address of ptr to new seglist

Returns:

Return status

PmReturn_t seglist_removeItem	(	pSeglist_t	pseglist,
		uint16_t	index
	)

Removes the item at the given index.

Parameters:

	pseglist	Ptr to seglist in which object is removed.
	index	Index into seglist of where to put object.

Returns:

Return status

PmReturn_t seglist_setItem	(	pSeglist_t	pseglist,
		pPmObj_t	pobj,
		int16_t	index
	)

Puts the item in the designated slot and segment. This is intended to be used after seglist_findEqual() returns the proper indeces.

Parameters:

	pseglist	Ptr to seglist in which object is placed.
	pobj	Ptr to object which is set.
	index	Index into seglist of where to put object.

Returns:

Return status; PM_RET_OK if object is set. PM_RET_ERR otherwise.