# Doubly Linked List Implementation in C

A comprehensive, production-ready doubly linked list implementation in C with full test coverage and documentation.

## Features

- **Complete API**: Insert, remove, search, and traverse operations
- **Memory Safe**: Proper memory management with no leaks
- **Error Handling**: Robust error checking and validation
- **Well Tested**: Comprehensive test suite with edge cases
- **Standards Compliant**: Follows C99 standard and best practices
- **Documentation**: Fully documented API with examples

## Structure

The doubly linked list consists of:

- **Node Structure**: Contains data and pointers to previous/next nodes
- **List Structure**: Maintains head, tail pointers and size counter
- **API Functions**: Complete set of operations for list manipulation

## API Reference

### Core Operations

```c
// Create and destroy
struct doubly_linked_list *dll_create(void);
void dll_destroy(struct doubly_linked_list *list);

// Insert operations
bool dll_insert_front(struct doubly_linked_list *list, int data);
bool dll_insert_back(struct doubly_linked_list *list, int data);
bool dll_insert_at(struct doubly_linked_list *list, size_t position, int data);

// Remove operations
bool dll_remove_front(struct doubly_linked_list *list);
bool dll_remove_back(struct doubly_linked_list *list);
bool dll_remove_at(struct doubly_linked_list *list, size_t position);
bool dll_remove_data(struct doubly_linked_list *list, int data);

// Access operations
bool dll_get_at(struct doubly_linked_list *list, size_t position, int *data);
size_t dll_search(struct doubly_linked_list *list, int data);

// Utility operations
size_t dll_get_size(struct doubly_linked_list *list);
bool dll_is_empty(struct doubly_linked_list *list);
void dll_clear(struct doubly_linked_list *list);

// Display operations
void dll_print_forward(struct doubly_linked_list *list);
void dll_print_backward(struct doubly_linked_list *list);
```

## Usage Example

```c
#include "doubly_linked_list.h"

int main(void) {
    // Create a new list
    struct doubly_linked_list *list = dll_create();
    
    // Insert some data
    dll_insert_back(list, 10);
    dll_insert_back(list, 20);
    dll_insert_front(list, 5);
    
    // Print the list
    dll_print_forward(list);  // Output: 5 <-> 10 <-> 20
    dll_print_backward(list); // Output: 20 <-> 10 <-> 5
    
    // Search for data
    size_t pos = dll_search(list, 10);
    if (pos != SIZE_MAX) {
        printf("Found 10 at position %zu\n", pos);
    }
    
    // Remove data
    dll_remove_data(list, 10);
    dll_print_forward(list);  // Output: 5 <-> 20
    
    // Clean up
    dll_destroy(list);
    return 0;
}
```

## Building and Testing

### Prerequisites

- GCC compiler with C99 support
- Make utility
- Optional: Valgrind for memory checking
- Optional: cppcheck for static analysis

### Build Commands

```bash
# Build the test program
make -f Makefile_dll

# Build and run tests
make -f Makefile_dll test

# Clean build artifacts
make -f Makefile_dll clean

# Check for memory leaks
make -f Makefile_dll memcheck

# Run static analysis
make -f Makefile_dll static-analysis

# Show all available targets
make -f Makefile_dll help
```

### Expected Test Output

```
=== Doubly Linked List Test Suite ===

Testing list creation and destruction...
✓ Create/destroy test passed

Testing front insertion...
Forward: 30 <-> 20 <-> 10
Backward: 10 <-> 20 <-> 30
✓ Front insertion test passed

Testing back insertion...
Forward: 10 <-> 20 <-> 30
Backward: 30 <-> 20 <-> 10
✓ Back insertion test passed

[... more test output ...]

=== All tests passed! ===
```

## File Structure

```
doubly_linked_list.h          # Header file with API declarations
doubly_linked_list.c          # Implementation file
test_doubly_linked_list.c     # Comprehensive test suite
Makefile_dll                  # Build configuration
README_doubly_linked_list.md  # This documentation
```

## Design Decisions

### Memory Management
- All memory allocation/deallocation is handled internally
- Functions return boolean success/failure indicators
- NULL pointer checks on all public functions
- No memory leaks in normal operation

### Error Handling
- Defensive programming with input validation
- Graceful handling of edge cases (empty lists, invalid positions)
- Clear return values indicating success/failure

### Performance Considerations
- O(1) insertion/removal at front and back
- O(n) insertion/removal at arbitrary positions
- O(n) search operations
- Maintains size counter for O(1) size queries

### Code Style
- Follows established C coding standards
- Consistent naming conventions with prefixes
- Comprehensive documentation
- Clear separation of public and private functions

## Testing Coverage

The test suite covers:

- ✅ Basic creation and destruction
- ✅ Front and back insertion
- ✅ Insertion at arbitrary positions
- ✅ All removal operations
- ✅ Search and data retrieval
- ✅ Edge cases and error conditions
- ✅ Memory management verification
- ✅ Empty list handling

## Limitations

- Currently supports `int` data type only
- Not thread-safe (requires external synchronization)
- No built-in sorting or advanced algorithms

## Future Enhancements

- Generic data type support using void pointers
- Thread-safe operations with mutex protection
- Iterator interface for traversal
- Built-in sorting and searching algorithms
- Serialization/deserialization support

## License

This project is licensed under the Apache License 2.0. See the license headers in source files for details.

## Contributing

When contributing to this project:

1. Follow the established coding style
2. Add tests for new functionality
3. Update documentation as needed
4. Ensure no memory leaks with valgrind
5. Run static analysis before submitting