Class DLinklist

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:

• LibraryNotFoundException - If the C library cannot be found.

Overrides: object.__init__

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If the status return value is not Return.NORMAL.

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.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If the status return value is not Return.NORMAL.

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.

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.

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.

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.

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.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If the status return value is not Return.NORMAL.

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.

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.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If the status return value is not Return.NORMAL.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If the status return value is not Return.NORMAL.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If the status return value is not Return.NORMAL.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If the status return value is not Return.NORMAL.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If the status return value is not Return.NORMAL.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If the status return value is not Return.NORMAL.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If status return value is not Return.NORMAL.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If status return value is not Return.NORMAL.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If status return value is not Return.NORMAL.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If the status return value is not Return.NORMAL.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If the status return value is not Return.NORMAL.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If the status return value is not Return.NORMAL.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If the status return value is not Return.NORMAL.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If the status return value is not Return.NORMAL.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If the status return value is not Return.NORMAL.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If the status return value is not Return.NORMAL.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If the status return value is not Return.NORMAL.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If the status return value is not Return.NORMAL.

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:

• APIException - If a low level error occurred in the C code.
• FunctionException - If the status return value is not Return.NORMAL.

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

Returns: ctypes POINTER

Function pointer.

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.