Package dlinklist :: Module linklist :: Class DLinklist
[hide private]
[frames] | no frames]

Class DLinklist

source code


This class provides thin wrappers around the functions in my doubly linklist C library.

  1. Initialization Methods
  2. Status and State Methods
  3. Pointer Manipulation Methods
  4. List Update Methods
  5. Search and Retrieval Methods
  6. Input/Output Methods
  7. Miscellaneous Helper Methods
Instance Methods [hide private]
 
__init__(self, logname='', disableLogging=False)
The constructor creates logging and instantiates the library object.
source code
ctypes POINTER
create(self, infoSize)
Creates and initializes the link list.
source code
ctypes POINTER
createList(self)
Creates the List object in memory.
source code
 
initialize(self, infoSize)
Initializes the List class with the user's Info class size parameters.
source code
 
destroyList(self)
Deallocates the memory of all Nodes and the Info objects then deallocates the memory used by the List object.
source code
str
version(self)
Get the version information and a list of contributors to this project.
source code
bool
isListEmpty(self)
Check if the list is empty.
source code
bool
isListFull(self)
Check if the list is full, meaning memory is exhausted.
source code
int
getNumberOfRecords(self)
Get the number of records in the link list.
source code
tuple
setSearchModes(self, origin, dir)
Sets the search origin and dir modes and returns the previously set modes.
source code
tuple
getSearchModes(self)
Get the search modes, a tuple of origin and direction.
source code
int
getCurrentIndex(self)
Get the current index value.
source code
 
currentPointerToHead(self)
Moves the current pointer to the head of the list.
source code
 
currentPointerToTail(self)
Moves the current pointer to the tail of the list.
source code
 
incrementCurrentPointer(self)
Moves the current pointer to the next Node.
source code
 
decrementCurrentPointer(self)
Moves the current pointer to the prior Node.
source code
 
storeCurrentPointer(self)
Store the current pointer in the control List class.
source code
 
restoreCurrentPointer(self)
Restore the current pointer from the control List class.
source code
 
addRecord(self, info, pFun=None)
Adds a record to the link list.
source code
 
insertRecord(self, info, dir)
Inserts a record relative to the current pointer and is determined by the dir.
source code
 
swapRecord(self, dir)
Swaps current record up or down one position in the list.
source code
 
updateCurrentRecord(self, record)
Updates the current record.
source code
 
deleteCurrentRecord(self)
Delete a record from the list.
source code
 
deleteAllNodes(self)
Deletes all the Info and their Node objects from the list then reinitializes the control List for continued use.
source code
Info
findRecord(self, record, match, pFun=None)
Find a record in the list with search criteria passed into match.
source code
Info
findNthRecord(self, record, skip)
Returns the Nth record in the list based on the setting of origin and direction values in the control List.
source code
Info
getCurrentRecord(self, record)
Return the current record.
source code
Info
getPriorRecord(self, record)
Return the prior record relative to the current pointer.
source code
Info
getNextRecord(self, record)
Return the next record relative to the current pointer.
source code
 
saveList(self, path)
Save list to disk.
source code
 
loadList(self, path, pFun=None)
Load list from disk.
source code
ctypes POINTER
compare(self)
A basic compare function.
source code
 
checkInfoType(self, info)
Utility method to check that the Info object is valid.
source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Class Variables [hide private]
  __LIBRARY = ('../src/libdll.so', '/home/cnobile/src/linklist/l...
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, logname='', disableLogging=False)
(Constructor)

source code 

The constructor creates logging and instantiates the library object.

Parameters:
  • logname (str) - The logging name used in your application, defaults to the root logger.
  • disableLogging (bool) - Turns logging on or off. The default False turns logging on, and True turns logging off.
Raises:
Overrides: object.__init__

create(self, infoSize)

source code 

Creates and initializes the link list. This method should be used instead of the createList and initialize methods unless you need to reuse the List class.

Parameters:
  • infoSize (int) - The size of the user defined Info class.
Returns: ctypes POINTER
A pointer to the top level List class. This return value can be disregarded in most situations as it is not needed for normal use.
Raises:

createList(self)

source code 

Creates the List object in memory.

The C function doc string:

 List *DLL_CreateList(List **list);

 Arguments: list -- Pointer to a pointer to a name of a structure to
                    create.
 Returns  : Pointer to created structure NULL if unsuccessful}
Returns: ctypes POINTER
A pointer to the top level List class. This return value can be disregarded in most situations as it is not needed for normal use.
Raises:
  • APIException - If a low level error occurred in the C code.

initialize(self, infoSize)

source code 

Initializes the List class with the user's Info class size parameters.

The C function doc string:

 DLL_Return DLL_InitializeList(List *list, size_t infosize);

 Arguments: list          -- Pointer to type List
            infosize      -- Size of user Info
 Returns  : DLL_NORMAL    -- Initialization was done successfully
            DLL_ZERO_INFO -- sizeof(Info) is zero
            DLL_NULL_LIST -- Info is NULL
Parameters:
  • infoSize (int) - The size of the user defined Info class.
Returns:
None
Raises:

destroyList(self)

source code 

Deallocates the memory of all Nodes and the Info objects then deallocates the memory used by the List object.

The C function doc string:

 void DLL_DestroyList(List **list);

 Arguments: list -- Pointer to a pointer to a name of a structure to
                    destroy.
 Returns  : void
Returns:
None
Raises:
  • APIException - If a low level error occurred in the C code.

version(self)

source code 

Get the version information and a list of contributors to this project.

The C function doc string:

 DLL_Version() : Returns a pointer to version information

 Arguments: void

 Return   : char * -- Pointer to version info
Returns: str
A printable string.
Raises:
  • APIException - If a low level error occurred in the C code.

isListEmpty(self)

source code 

Check if the list is empty.

The C function doc string:

 DLL_Boolean DLL_IsListEmpty(List *list);

 Arguments: list      -- Pointer to type List
 Returns  : DLL_TRUE  -- List is empty
            DLL_FALSE -- List has items in it
Returns: bool
If the list is empty return True else return False.
Raises:
  • APIException - If a low level error occurred in the C code.

isListFull(self)

source code 

Check if the list is full, meaning memory is exhausted.

The C function doc string:

 DLL_Boolean DLL_IsListFull(List *list);

 Arguments: list      -- Pointer to type List
 Returns  : DLL_TRUE  -- List is full (memory dependent)
            DLL_FALSE -- List is empty or partially full
Returns: bool
If the list is full return True else return False.
Raises:
  • APIException - If a low level error occurred in the C code.

getNumberOfRecords(self)

source code 

Get the number of records in the link list.

The C function doc string:

 unsigned long DLL_GetNumberOfRecords(List *list);

 Arguments: list -- Pointer to type List
 Returns  : Number of records in list
Returns: int
The number of records in the link list.
Raises:
  • APIException - If a low level error occurred in the C code.

setSearchModes(self, origin, dir)

source code 

Sets the search origin and dir modes and returns the previously set modes.

The C function doc string:

 DLL_Return DLL_SetSearchModes(List *list, DLL_SrchOrigin origin,
                               DLL_SrchDir dir);

 Arguments: list             -- Pointer to type List
            origin           -- Indicates the start search pointer to
                                use
            dir              -- Indicates the direction to search in
 Returns  : DLL_NORMAL       -- Values assigned were accepted
            DLL_NOT_MODIFIED -- Values were not assigned--invalid type
                                (previous values are still in place)
Parameters:
  • origin (int) - A value from the SrchOrigin class.
  • dir (int) - A value from the SrchDir class.
Returns: tuple
The previously set modes: (origin, direction)
Raises:

getSearchModes(self)

source code 

Get the search modes, a tuple of origin and direction.

The C function doc string:

 DLL_SearchModes DLL_GetSearchModes(List *list, DLL_SearchModes *ssp);

 Arguments: list -- Pointer to type List
            ssp  -- Save structure pointer
 Returns  : Pointer to type DLL_SearchModes
Returns: tuple
The search modes in a tuple (origin, direction).
Raises:
  • APIException - If a low level error occurred in the C code.

getCurrentIndex(self)

source code 

Get the current index value.

The C function doc string:

 unsigned long DLL_GetCurrentIndex(List *list);

 Arguments: list -- Pointer to type List
 Returns  : Current record's index
Returns: int
The index where the first Node is 1.
Raises:
  • APIException - If a low level error occurred in the C code.

currentPointerToHead(self)

source code 

Moves the current pointer to the head of the list.

The C function doc string:

 DLL_Return DLL_CurrentPointerToHead(List *list);

 Arguments: list          -- Pointer to type List
 Returns  : DLL_NORMAL    -- Record found
            DLL_NULL_LIST -- Empty list
Returns:
None
Raises:

currentPointerToTail(self)

source code 

Moves the current pointer to the tail of the list.

The C function doc string:

 DLL_Return DLL_CurrentPointerToTail(List *list);

 Arguments: list          -- Pointer to type List
 Returns  : DLL_NORMAL    -- Record found
            DLL_NULL_LIST -- Empty list
Returns:
None
Raises:

incrementCurrentPointer(self)

source code 

Moves the current pointer to the next Node.

The C function doc string:

 DLL_Return DLL_IncrementCurrentPointer(List *list);

 Arguments: list          -- Pointer to type List
 Returns  : DLL_NORMAL    -- Record found
            DLL_NULL_LIST -- Empty list
            DLL_NOT_FOUND -- Record not found
Returns:
None
Raises:

decrementCurrentPointer(self)

source code 

Moves the current pointer to the prior Node.

The C function doc string:

 DLL_Return DLL_DecrementCurrentPointer(List *list);

 Arguments: list          -- Pointer to type List
 Returns  : DLL_NORMAL    -- Record found
            DLL_NULL_LIST -- Empty list
            DLL_NOT_FOUND -- Record not found
Returns:
None
Raises:

storeCurrentPointer(self)

source code 

Store the current pointer in the control List class.

The C function doc string:

 DLL_Return DLL_StoreCurrentPointer(List *list);

 Arguments: list          -- Pointer to type List
 Returns  : DLL_NORMAL    -- Record found
            DLL_NOT_FOUND -- Record not found
Returns:
None
Raises:

restoreCurrentPointer(self)

source code 

Restore the current pointer from the control List class.

The C function doc string:

 DLL_Return DLL_restoreCurrentPointer(List *list);

 Arguments: list          -- Pointer to type List
 Returns  : DLL_NORMAL    -- Record found
            DLL_NOT_FOUND -- Record not found
Returns:
None
Raises:

addRecord(self, info, pFun=None)

source code 

Adds a record to the link list. If pFun is None new records will be added at the end of the list. If the pFun is a comparison function the added record's position in the list will be determined by this function.

The C function doc string:

 DLL_Return DLL_AddRecord(List *list, Info *info,
                          int (*pFun)(Info *, Info *));

 Arguments: list          -- Pointer to type List
            info          -- Pointer to record to add
            pFun          -- Pointer to search function
 Returns  : DLL_NORMAL    -- Node was added successfully
            DLL_MEM_ERROR -- Memory allocation failed
Parameters:
  • info (Info is defined internally as c_void_p) - The Info class instantiated object.
  • pFun (ctypes CFUNCTYPE) - A CFUNCTYPE object for comparing data in the user Info class. The default is None.
Returns:
None
Raises:

insertRecord(self, info, dir)

source code 

Inserts a record relative to the current pointer and is determined by the dir. If dir is InsertDir.ABOVE the record will be inserted toward the head of the list, if InsertDir.BELOW the record will be inserted toward the tail of the list.

The C function doc string:

 DLL_Return DLL_InsertRecord(List *list, Info *info,
                             DLL_InsertDir dir);

 Arguments: list             -- Pointer to type List
            info             -- Record to add
            dir              -- Direction to insert, can be DLL_ABOVE
                                (toward head) or DLL_BELOW (toward
                                tail)
 Returns  : DLL_NORMAL       -- Node was added successfully
            DLL_MEM_ERROR    -- Memory allocation failed
            DLL_NOT_MODIFIED -- Insert direction is invalid
                                (not DLL_ABOVE or DLL_BELOW)
Parameters:
  • info (Info is defined internally as c_void_p) - The Info class instantiated object.
  • dir (int) - A value from the InsertDir class.
Returns:
None
Raises:

swapRecord(self, dir)

source code 

Swaps current record up or down one position in the list. The swapped record will still be current after completion. If dir is InsertDir.ABOVE the record will be swapped toward the head of the list, if InsertDir.BELOW the record will be swapped toward the tail of the list.

The C function doc string:

 DLL_Return DLL_SwapRecord(List *list, DLL_InsertDir dir);

 Arguments: list             -- Pointer to type List
            dir              -- Direction to swap, can be DLL_ABOVE
                                (toward head) or DLL_BELOW (toward
                                tail)
 Returns  : DLL_NORMAL       -- Node was swapped successfully
            DLL_NULL_LIST    -- list->current is NULL
            DLL_NOT_MODIFIED -- Swap direction not DLL_ABOVE or
                                DLL_BELOW
            DLL_NOT_FOUND    -- Current record is already at end of
                                list indicated by dir.
Parameters:
  • dir (int) - A value from the InsertDir class.
Returns:
None
Raises:

updateCurrentRecord(self, record)

source code 

Updates the current record. The entire record is over written.

The C function doc string:

 DLL_Return DLL_UpdateCurrentRecord(List *list, Info *record);

 Arguments: list          -- Pointer to type List
            record        -- Pointer to an Info structure in list
 Returns  : DLL_NORMAL    -- Record updated
            DLL_NULL_LIST -- Empty list
Parameters:
  • record (Info is defined internally as c_void_p) - An Info object with new data.
Returns:
None
Raises:

deleteCurrentRecord(self)

source code 

Delete a record from the list. This removes the Node and Info objects.

The C function doc string:

 DLL_Return DLL_DeleteCurrentRecord(List *list);

 Arguments: list          -- Pointer to type List
 Returns  : DLL_NORMAL    -- Record deleted
            DLL_NULL_LIST -- List is empty
Returns:
None
Raises:

deleteAllNodes(self)

source code 

Deletes all the Info and their Node objects from the list then reinitializes the control List for continued use.

The C function doc string:

 DLL_Return DLL_DeleteEntireList(List *list);

 Arguments: list          -- Pointer to type List
 Returns  : DLL_NORMAL    -- List deleted
            DLL_NULL_LIST -- List is empty
Returns:
None
Raises:

findRecord(self, record, match, pFun=None)

source code 

Find a record in the list with search criteria passed into match. If the pFun is a comparison function the found record will be determined by this function. Return the found record.

The C function doc string:

 DLL_Return DLL_FindRecord(List *list, Info *record, Info *match,
                           int (*pFun)(Info *, Info *));

 Arguments: list              -- Pointer to type List
            record            -- Pointer to an Info structure in list
            match             -- Pointer to an Info structure to match
                                 to Node in list
            pFun              -- Pointer to search function
 Returns  : DLL_NORMAL        -- Record found
            DLL_NULL_LIST     -- Empty list
            DLL_NOT_FOUND     -- Record not found
            DLL_NULL_FUNCTION -- pFun is NULL
Parameters:
  • record (Info is defined internally as c_void_p) - An Info object that will have the retrieved data.
  • match (Info is defined internally as c_void_p) - An Info object with the search criteria.
  • pFun (ctypes CFUNCTYPE) - A CFUNCTYPE object for comparing data in the user Info class. The default is None.
Returns: Info
The found record.
Raises:

findNthRecord(self, record, skip)

source code 

Returns the Nth record in the list based on the setting of origin and direction values in the control List. Return the found record.

The C function doc string:

 DLL_Return DLL_FindNthRecord(List *list, Info *record,
                              unsigned long skip);

 Arguments: list          -- Pointer to type List
            record        -- Record to hold return data
            skip          -- Number of records to skip
                             (Always a positive number)
 Returns  : DLL_NORMAL    -- Node was found successfully
            DLL_NULL_LIST -- list->current is NULL
            DLL_NOT_FOUND -- Index value is too large or wrong dir
                             value (current record index remains
                             unchanged)
Parameters:
  • record (Info is defined internally as c_void_p) - An Info object that will have the retrieved data.
  • skip (int) - The number of records to skip over while doing the search.
Returns: Info
The found record.
Raises:

getCurrentRecord(self, record)

source code 

Return the current record.

The C function doc string:

 DLL_Return DLL_GetCurrentRecord(List *list, Info *record);

 Arguments: list          -- Pointer to type List
            record        -- Pointer to an Info structure
 Returns  : DLL_NORMAL    -- Record returned
            DLL_NULL_LIST -- List is empty
Parameters:
  • record (Info is defined internally as c_void_p) - An Info object that will have the retrieved data.
Returns: Info
The current record.
Raises:

getPriorRecord(self, record)

source code 

Return the prior record relative to the current pointer.

The C function doc string:

 DLL_Return DLL_GetPriorRecord(List *list, Info *record);

 Arguments: list          -- Pointer to type List
            record        -- Pointer to an Info structure
 Returns  : DLL_NORMAL    -- Record returned
            DLL_NULL_LIST -- List is empty
            DLL_NOT_FOUND -- Beginning of list
Parameters:
  • record (Info is defined internally as c_void_p) - An Info object that will have the retrieved data.
Returns: Info
The prior record.
Raises:

getNextRecord(self, record)

source code 

Return the next record relative to the current pointer.

The C function doc string:

 DLL_Return DLL_GetNextRecord(List *list, Info *record);

 Arguments: list          -- Pointer to type List
            record        -- Pointer to an Info structure
 Returns  : DLL_NORMAL    -- Record returned
            DLL_NULL_LIST -- List is empty
            DLL_NOT_FOUND -- End of list
Parameters:
  • record (Info is defined internally as c_void_p) - An Info object that will have the retrieved data.
Returns: Info
The next record.
Raises:

saveList(self, path)

source code 

Save list to disk. The file is saved in binary format because the fields in the Info class are save in their entirety causing NULL bytes to be padded after text. It should be trivial to pad the fields with spaces before calling this method thus eliminating any binary data in text files.

The C function doc string:

 DLL_Return DLL_SaveList(List *list, const char *path);

 Arguments: list             -- Pointer to type List
            path             -- Pointer to path and filename
 Return   : DLL_NORMAL       -- File written successfully
            DLL_NULL_LIST    -- List is empty
            DLL_OPEN_ERROR   -- File open error
            DLL_WRITE_ERROR  -- File write error
            DLL_NOT_MODIFIED -- Unmodified list no save was done
Parameters:
  • path (str) - The full path to the data file.
Returns:
None
Raises:

loadList(self, path, pFun=None)

source code 

Load list from disk. When using the pFun keyword argument the function passed will sort the incoming data.

The C function doc string:

 DLL_Return DLL_LoadList(List *list, const char *path,
                         int (*pFun)(Info *, Info *));

 Arguments: list           -- Pointer to type List
            path           -- Pointer to path and filename
            pFun           -- Pointer to search function
 Return   : DLL_NORMAL     -- File written successfully
            DLL_MEM_ERROR  -- Memory allocation failed
            DLL_OPEN_ERROR -- File open error
            DLL_READ_ERROR -- File read error
Parameters:
  • path (str) - The full path to the data file.
  • pFun (ctypes CFUNCTYPE) - A CFUNCTYPE object for comparing data in the user Info class. The default is None.
Returns:
None
Raises:

compare(self)

source code 

A basic compare function. You may need to write your own.

Returns: ctypes POINTER
Function pointer.

checkInfoType(self, info)

source code 

Utility method to check that the Info object is valid.

Parameters:
  • info (Info) - An instance of an Info class.
Raises:
  • APIException - If a low level error occurred in the C code.

Class Variable Details [hide private]

__LIBRARY

Value:
('../src/libdll.so',
 '/home/cnobile/src/linklist/linklist-2.0.0/src/dlinklist/libdll.so',
 '../libdll.so')