diff options
| -rw-r--r-- | README.md | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..03eaa18 --- /dev/null +++ b/README.md @@ -0,0 +1,190 @@ +*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. |