*This project has been created as part of the 42 curriculum by tvanbesi*

# Libft

## Description

Libft is a C static library that reimplements a selection of standard C library
functions, along with additional utility functions not found in libc. The goal
is to understand how these foundational functions work internally by coding them
from scratch, and to produce a reusable library for future 42 projects.

The library is organized in three parts:

- **Part 1** — Reimplementations of common libc functions (`strlen`, `memcpy`,
  `atoi`, `calloc`, etc.), including several BSD extensions (`strlcpy`,
  `strlcat`, `strnstr`).
- **Part 2** — Additional utility functions for string manipulation (`split`,
  `substr`, `strjoin`, `strtrim`, `itoa`), higher-order string operations
  (`strmapi`, `striteri`), and file-descriptor output (`putchar_fd`,
  `putstr_fd`, `putendl_fd`, `putnbr_fd`).
- **Part 3** — A singly-linked list implementation with creation, insertion,
  deletion, iteration, and mapping operations.

All functions are prefixed with `ft_` and exposed through a single header,
`libft.h`.

## Instructions

### Requirements

- A C compiler (the Makefile uses `cc`)
- `make`
- `ar` (for building the static archive)
- [`jq`](https://jqlang.github.io/jq/) (only needed for `compile_commands.json` generation)

### Building the library

```sh
make        # compiles lib/libft.a
```

### Using the library in your project

1. Copy or link the `src/`, `inc/`, and `Makefile` into your project tree.
2. Include the header in your source files:
   ```c
   #include "libft.h"
   ```
3. Compile and link against the archive:
   ```sh
   cc -Wall -Wextra -Werror -I inc my_program.c -L lib -lft -o my_program
   ```

### Makefile targets

| Target                  | Description                                          |
|-------------------------|------------------------------------------------------|
| `make` / `make all`     | Build `lib/libft.a`                                  |
| `make clean`            | Remove object files                                  |
| `make fclean`           | Remove object files and the library archive          |
| `make re`               | Full rebuild (`fclean` + `all`)                      |
| `make test`             | Build the library then compile and run all tests     |
| `make sanitize`         | Rebuild with AddressSanitizer and run tests          |
| `make compile_commands.json` | Generate `compile_commands.json` for clangd     |

### clangd support

To enable editor features like autocompletion and diagnostics via
[clangd](https://clangd.llvm.org/), generate the compilation database:

```sh
make compile_commands.json            # for library sources
make -C tests compile_commands.json   # for test sources
```

This requires `jq` to be installed. Regenerate after adding or removing source
files.

### Running the tests

```sh
make test
```

Each test binary compares the `ft_` function against its libc counterpart
(where one exists) using both edge-case and randomized inputs. NULL-pointer
crash behavior is verified via `fork()` + `WIFSIGNALED()`.

## Function reference

### Character classification & conversion

| Function       | Description                                  |
|----------------|----------------------------------------------|
| `ft_isalpha`   | Check for an alphabetic character            |
| `ft_isdigit`   | Check for a decimal digit                    |
| `ft_isalnum`   | Check for an alphanumeric character          |
| `ft_isascii`   | Check for a 7-bit ASCII character            |
| `ft_isprint`   | Check for a printable character              |
| `ft_toupper`   | Convert lowercase to uppercase               |
| `ft_tolower`   | Convert uppercase to lowercase               |

### String examination

| Function       | Description                                          |
|----------------|------------------------------------------------------|
| `ft_strlen`    | Return the length of a string                        |
| `ft_strncmp`   | Compare two strings up to *n* bytes                  |
| `ft_strchr`    | Locate first occurrence of a character in a string   |
| `ft_strrchr`   | Locate last occurrence of a character in a string    |
| `ft_strnstr`   | Locate a substring within a bounded region (BSD)     |
| `ft_atoi`      | Convert a string to an integer                       |

### String manipulation

| Function       | Description                                          |
|----------------|------------------------------------------------------|
| `ft_strlcpy`   | Size-bounded string copy (BSD)                       |
| `ft_strlcat`   | Size-bounded string concatenation (BSD)              |
| `ft_strdup`    | Duplicate a string with `malloc`                     |
| `ft_substr`    | Extract a substring                                  |
| `ft_strjoin`   | Concatenate two strings into a new allocation        |
| `ft_strtrim`   | Trim characters from both ends of a string           |
| `ft_split`     | Split a string by a delimiter into an array          |
| `ft_itoa`      | Convert an integer to its decimal string             |
| `ft_strmapi`   | Apply a function to each character, returning a new string |
| `ft_striteri`  | Apply a function to each character in place          |

### Memory operations

| Function       | Description                                  |
|----------------|----------------------------------------------|
| `ft_memset`    | Fill memory with a constant byte             |
| `ft_bzero`     | Zero a byte range                            |
| `ft_memcpy`    | Copy memory (non-overlapping)                |
| `ft_memmove`   | Copy memory (overlap-safe)                   |
| `ft_memchr`    | Scan memory for a byte                       |
| `ft_memcmp`    | Compare two memory regions                   |
| `ft_calloc`    | Allocate zeroed memory                       |

### File descriptor output

| Function         | Description                                |
|------------------|--------------------------------------------|
| `ft_putchar_fd`  | Write a character to a file descriptor     |
| `ft_putstr_fd`   | Write a string to a file descriptor        |
| `ft_putendl_fd`  | Write a string followed by a newline       |
| `ft_putnbr_fd`   | Write an integer in decimal                |

### Linked list

The list node type is:

```c
typedef struct s_list
{
  void          *content;
  struct s_list *next;
} t_list;
```

| Function          | Description                                       |
|-------------------|---------------------------------------------------|
| `ft_lstnew`       | Create a new node                                 |
| `ft_lstadd_front` | Insert a node at the beginning                    |
| `ft_lstadd_back`  | Insert a node at the end                          |
| `ft_lstsize`      | Count the nodes in the list                       |
| `ft_lstlast`      | Return the last node                              |
| `ft_lstdelone`    | Delete a single node                              |
| `ft_lstclear`     | Delete and free an entire list                    |
| `ft_lstiter`      | Apply a function to each node's content           |
| `ft_lstmap`       | Map a function over a list, producing a new list  |

## Resources

- [The C Programming Language](https://en.wikipedia.org/wiki/The_C_Programming_Language) (Kernighan & Ritchie) — the classic reference for C
- [C Standard Library reference (cppreference.com)](https://en.cppreference.com/w/c) — detailed documentation for every standard library function
- Linux man pages (`man 3 strlen`, `man 3 memcpy`, etc.) — authoritative per-function documentation
- [OpenBSD `strlcpy`/`strlcat` paper](https://www.sudo.ws/todd/papers/strlcpy.html) — rationale and specification for the BSD string extensions

### Use of AI

AI (Claude) was used in this project for three purposes:

- **Code comments**: generating and reviewing Doxygen-style documentation
  comments in the header and source files.
- **Git commit messages**: drafting commit messages.
- **This README**: drafting and structuring the content of this file.

All library code was written by the project author.