/**
 * @file   libft.h
 * @brief  Reimplementations of standard C library functions.
 *
 * Every function mirrors its libc counterpart unless noted otherwise.
 * Functions that operate on raw memory interpret bytes as unsigned char.
 * BSD extensions (strlcpy, strlcat, strnstr) follow the OpenBSD semantics.
 */

#ifndef LIBFT_H
#define LIBFT_H

#include <stddef.h>

/* ======================================
 *  Character classification & conversion
 * ====================================== */

/** @brief Return non-zero if @p c is an alphabetic letter. */
int ft_isalpha (int c);
/** @brief Return non-zero if @p c is a decimal digit. */
int ft_isdigit (int c);
/** @brief Return non-zero if @p c is alphanumeric. */
int ft_isalnum (int c);
/** @brief Return non-zero if @p c is a 7-bit ASCII value. */
int ft_isascii (int c);
/** @brief Return non-zero if @p c is a printable character. */
int ft_isprint (int c);
/** @brief Convert @p c to uppercase if it is a lowercase letter. */
int ft_toupper (int c);
/** @brief Convert @p c to lowercase if it is an uppercase letter. */
int ft_tolower (int c);

/* ======================================
 *  String examination
 * ====================================== */

/** @brief Return the length of the string @p s. */
size_t ft_strlen (const char *s);
/**
 * @brief Compare at most @p n bytes of @p s1 and @p s2.
 * @return Negative, zero, or positive integer.
 */
int ft_strncmp (const char *s1, const char *s2, size_t n);
/** @brief Return a pointer to the first occurrence of @p c in @p s. */
char *ft_strchr (const char *s, int c);
/** @brief Return a pointer to the last occurrence of @p c in @p s. */
char *ft_strrchr (const char *s, int c);
/**
 * @brief Locate @p little in @p big, searching at most @p len bytes.
 * @note  BSD extension — not available in glibc.
 */
char *ft_strnstr (const char *big, const char *little, size_t len);
/** @brief Convert the initial portion of @p nptr to int. */
int ft_atoi (const char *nptr);

/* ======================================
 *  String manipulation
 * ====================================== */

/**
 * @brief Copy @p src into @p dst, NUL-terminating the result.
 * @return Length of @p src.
 * @note   BSD extension — not available in glibc.
 */
size_t ft_strlcpy (char *dst, const char *src, size_t size);
/**
 * @brief Append @p src to @p dst, NUL-terminating the result.
 * @return Intended total length (dst_len + src_len).
 * @note   BSD extension — not available in glibc.
 */
size_t ft_strlcat (char *dst, const char *src, size_t size);
/** @brief Return a malloc'd duplicate of @p s. */
char *ft_strdup (const char *s);
/**
 * @brief Allocate a substring from @p s starting at @p start, at most @p len
 * chars.
 */
char *ft_substr (char const *s, unsigned int start, size_t len);
/** @brief Allocate the concatenation of @p s1 and @p s2. */
char *ft_strjoin (char const *s1, char const *s2);
/** @brief Trim characters in @p set from both ends of @p s1. */
char *ft_strtrim (char const *s1, char const *set);
/**
 * @brief Split @p s by delimiter @p c into a NULL-terminated array of strings.
 */
char **ft_split (char const *s, char c);
/** @brief Allocate the decimal string representation of @p n. */
char *ft_itoa (int n);
/** @brief Apply @p f to each character of @p s, returning a new string. */
char *ft_strmapi (char const *s, char (*f) (unsigned int, char));
/** @brief Apply @p f to each character of @p s in place, passing its index. */
void ft_striteri (char *s, void (*f) (unsigned int, char *));

/* ======================================
 *  Memory operations
 * ====================================== */

/** @brief Fill @p n bytes of @p s with the byte @p c. */
void *ft_memset (void *s, int c, size_t n);
/** @brief Zero @p n bytes starting at @p s. */
void ft_bzero (void *s, size_t n);
/** @brief Copy @p n bytes from @p src to @p dest (no overlap). */
void *ft_memcpy (void *dest, const void *src, size_t n);
/** @brief Copy @p n bytes from @p src to @p dest (overlap-safe). */
void *ft_memmove (void *dest, const void *src, size_t n);
/** @brief Scan @p n bytes of @p s for the byte @p c. */
void *ft_memchr (const void *s, int c, size_t n);
/**
 * @brief Compare @p n bytes of @p s1 and @p s2.
 * @return Negative, zero, or positive integer.
 */
int ft_memcmp (const void *s1, const void *s2, size_t n);

/* ======================================
 *  Memory allocation
 * ====================================== */

/**
 * @brief Allocate zeroed memory for @p nmemb elements of @p size bytes.
 * @return NULL on overflow or allocation failure.
 */
void *ft_calloc (size_t nmemb, size_t size);

/* ======================================
 *  File descriptor output
 * ====================================== */

/** @brief Write character @p c to file descriptor @p fd. */
void ft_putchar_fd (char c, int fd);
/** @brief Write string @p s to file descriptor @p fd. */
void ft_putstr_fd (char *s, int fd);
/** @brief Write string @p s followed by a newline to @p fd. */
void ft_putendl_fd (char *s, int fd);
/** @brief Write integer @p n in decimal to @p fd. */
void ft_putnbr_fd (int n, int fd);

#endif