candycache/README.md

# ![Go](https://img.shields.io/badge/go-%2300ADD8.svg?style=for-the-badge&logo=go&logoColor=white) Candy Cache :candy:

**CandyCache** — это простой и эффективный кэш на языке Go, который позволяет хранить данные с ограниченным временем жизни (TTL). 

# Установка

Для использования CandyCache в вашем проекте, установите его, используя ```go get git.hikan.ru/serr/candycache```, далее просто добавьте в блок импорта.

# Основные возможности

- **Автоматика**: автоматическая очистка устаревших элементов и возможность ее отключения.
- **Возможность ручного управления**.
- **Безопасность**: конкурентный доступ к данным возможен благодаря мьютексам.
- **Гибкость**: кэш может хранить любые типы данных.

# Использование

## Создание кэша

### С автоматической очисткой

Для создания нового экземпляра кэша используйте функцию **Cacher**, передавая интервал очистки в наносекундах.

Если требуется указать интервал в секундах/минутах/часах и т.д. - используйте множители из пакета **time**:
```go
cache := candycache.Cacher(10 * time.Minute) // Очистка каждые 10 минут
```

### Без автоматической очистки

Если автоматичская очистка не нужна - просто передайте параметром любое отрицательное число:

```go
cache := candycache.Cacher(-1) // Кэш не будет очищаться автоматически
```

## Добавление элемента

Для добавления элемента в кэш используйте метод **Add**:
```go
cache.Add("key", "value", 5 * time.Minute) // Элемент будет считаться устаревшим через 5 минут
```
В случае, если по указанном ключу уже что-то хранится, оно будет заменено на новый элемент.

## Получение элемента

Для получения элемента из кэша используйте метод **Get**:

```go
value, found := cache.Get("key") // Получение значения по ключу "key"
```
Если элемент найден, то в переменную **value** будет записано значение, а в **found** - **true**. Если элемент не найден, то в **found** будет записано **false**, а значением вернется **nil**.

## Удаление элемента

Для удаления элемента по ключу используйте метод **Delete**:

```go
err := cache.Delete("key1")
if err != nil {
    fmt.Println("Ошибка:", err) // Не найдено записи по ключу
}
```

Элемент будет удален, не смотря на то, устаревший он или нет.

## Массовое удаление элементов

### Удаление устаревших элементов

Для удаления устаревших элементов используйте метод **Cleanup**:

```go
cache.Cleanup() // Перебирает все элементы кэша, удаляет устаревшие
```

### Удаление всех элементво кэша

Для полной очистки кэша используйте метод **Flush**:

```go
cache.Flush() // Удаляет все элементы кэша, не смотря на то, устаревшие они или нет
```

## Получение информации о кэше

### Получение списка элементов

Для получения списка всех элементов в кэше используйте метод **List**:

```go
items := cache.List() // Список всех элементов кэша
for _, item := range items {
    fmt.Printf("Ключ: %s, Значение: %v, Момент устаревания: %d\n", item.Key, item.Item.Data(), item.Item.DestroyTimestamp())
}
```

### Получение количества элементов

Для получения количества элементов в кэше используйте метод **Count**:

```go
count := cache.Count() // Количество элементов в кэше
```

### Получение размера кэша

Для получения размера всего кэша в байтах используйте метод **Size**:

```go
size := cache.Size() // Размер кэша в байтах
```

Данный метод возвращает корректное значение, если в кэше элементы представлены этими типами данных:

```go
bool
int, int8, int16, int32, int64
uint, uint8, uint16, uint32, uint64, uintptr
float32, float64
complex64, complex128
array, slice, string
map, struct, func
```

И композициями этих типов.