Update docs (#36)

README.md

@@ -47,25 +47,25 @@ func main() {
 
 * No expiration means that the entry will never expire.
 * Absolute expiration means that the entry will expire after a certain time.
-* Sliding expiration means that the entry will expire after a certain time if it hasn't been accessed. The expiration time is reset every time the entry is accessed.
+* Sliding expiration means that the entry will expire after a certain time if it hasn't been accessed. The expiration time is reset every time the entry is accessed. In other words the expiration time is slided to now + sliding expiration time where now is the time when the entry was accessed (read or write).
 
 ```go
 // Set a new value with no expiration time.
 // The entry will never expire.
 c.Set(1, "one", imcache.WithNoExpiration())
-// Set a new value with a sliding expiration time.
-// If the entry hasn't been accessed in the last 1 second, it will be evicted,
-// otherwise the expiration time will be extended by 1 second from the last access time.
-c.Set(2, "two", imcache.WithSlidingExpiration(time.Second))
 // Set a new value with an absolute expiration time set to 1 second from now.
 // The entry will expire after 1 second.
-c.Set(3, "three", imcache.WithExpiration(time.Second))
+c.Set(2, "two", imcache.WithExpiration(time.Second))
 // Set a new value with an absolute expiration time set to a specific date.
 // The entry will expire at the given date.
-c.Set(4, "four", imcache.WithExpirationDate(time.Now().Add(time.Second)))
+c.Set(3, "three", imcache.WithExpirationDate(time.Now().Add(time.Second)))
+// Set a new value with a sliding expiration time.
+// If the entry hasn't been accessed in the last 1 second, it will be evicted,
+// otherwise the expiration time will be extended by 1 second from the last access time.
+c.Set(4, "four", imcache.WithSlidingExpiration(time.Second))
 ```
 
-If you want to use default expiration time for the given cache instance, you can use the `WithDefaultExpiration` `Expiration` option. By default the default expiration time is set to no expiration. You can set the default expiration time when creating a new `Cache` or a `Sharded` instance. More on sharding can be found in the [Sharding](#sharding) section.
+If you want to use default expiration time for the given cache instance, you can use the `WithDefaultExpiration` `Expiration` option. By default the default expiration time is set to no expiration. You can set the default expiration time when creating a new `Cache` or `Sharded` instance. More on sharding can be found in the [Sharding](#sharding) section.
 
 ```go
 // Create a new non-sharded cache instance with default absolute expiration time equal to 1 second.
@@ -92,7 +92,7 @@ _ = c.StartCleaner(5 * time.Minute)
 defer c.StopCleaner()
 ```
 
-To be notified when an entry is evicted from the cache, you can use the `EvictionCallback`. It's a function that accepts the key and value of the evicted entry along with the reason why the entry was evicted. `EvictionCallback` can be configured when creating a new `Cache` or a `Sharded` instance.
+To be notified when an entry is evicted from the cache, you can use the `EvictionCallback`. It's a function that accepts the key and value of the evicted entry along with the reason why the entry was evicted. `EvictionCallback` can be configured when creating a new `Cache` or `Sharded` instance.
 
 ```go
 package main
@@ -126,16 +126,16 @@ func main() {
 
 ### Max entries limit
 
-`imcache` supports max entries limit. If the max entries limit is set, the cache evicts the least recently used entry when the max entries limit is reached. The least recently used entry is evicted regardless of the entry's expiration time. This allows `imcache` to remain simple and efficient.
+`imcache` supports max entries limit. It uses simple LRU eviction policy. If the max entries limit is set, the cache evicts the least recently used entry when the max entries limit is reached. The least recently used entry is evicted regardless of the entry's expiration time. This allows `imcache` to remain simple and efficient.
 
-LRU eviction is implemented using a doubly linked list. The list is ordered by the time of the last access to the entry. The most recently used entry is always at the head of the list. The least recently used entry is always at the tail of the list. It means that if the max entries limit is set, `Cache` maintains another data structure in addition to the map of entries. As a result, it increases memory usage and slightly decreases performance.
-
-The max entries limit can be configured when creating a new `Cache` instance.
+The max entries limit can be configured when creating a new `Cache` or `Sharded` instance.
 
 ```go
 c := imcache.New[uint32, string](imcache.WithMaxEntriesOption[uint32, string](1000))
 ```
 
+Note that for the `Sharded` type the max entries limit is applied to each shard separately.
+
 ### Sharding
 
 `imcache` supports sharding. It's possible to create a new cache instance with a given number of shards. Each shard is a separate `Cache` instance. A shard for a given key is selected by computing the hash of the key and taking the modulus of the number of shards. `imcache` exposes the `Hasher64` interface that wraps `Sum64` accepting a key and returning a 64-bit hash of the input key. It can be used to implement custom sharding algorithms.

imcache.go

@@ -20,16 +20,16 @@ import (
 //
 // Option(s) can be used to customize the returned Cache.
 func New[K comparable, V any](opts ...Option[K, V]) *Cache[K, V] {
-	s := &Cache[K, V]{
+	c := &Cache[K, V]{
 		m:          make(map[K]entry[K, V]),
 		defaultExp: -1,
 		cleaner:    newCleaner(),
 		queue:      &nopq[K]{},
 	}
 	for _, opt := range opts {
-		opt.apply(s)
+		opt.apply(c)
 	}
-	return s
+	return c
 }
 
 // Cache is a non-sharded in-memory cache.

imcache_test.go

@@ -455,7 +455,6 @@ func TestImcache_ReplaceWithFunc(t *testing.T) {
 		c       func() imcache[string, int32]
 		key     string
 		f       func(int32) int32
-		want    bool
 		val     int32
 		present bool
 	}{
@@ -468,7 +467,6 @@ func TestImcache_ReplaceWithFunc(t *testing.T) {
 			},
 			key:     "foo",
 			f:       Increment[int32],
-			want:    true,
 			val:     998,
 			present: true,
 		},
@@ -501,7 +499,6 @@ func TestImcache_ReplaceWithFunc(t *testing.T) {
 			},
 			key:     "foo",
 			f:       Decrement[int32],
-			want:    true,
 			val:     996,
 			present: true,
 		},

option.go

@@ -2,7 +2,7 @@ package imcache
 
 import "time"
 
-// Option is a Cache option.
+// Option configures the cache.
 type Option[K comparable, V any] interface {
 	apply(*Cache[K, V])
 }
@@ -14,15 +14,15 @@ func (f optionf[K, V]) apply(c *Cache[K, V]) {
 	f(c)
 }
 
-// WithEvictionCallbackOption returns an Option that sets the Cache
+// WithEvictionCallbackOption returns an Option that sets the cache
 // eviction callback.
 func WithEvictionCallbackOption[K comparable, V any](f EvictionCallback[K, V]) Option[K, V] {
 	return optionf[K, V](func(c *Cache[K, V]) {
 		c.onEviction = f
 	})
 }
 
-// WithDefaultExpirationOption returns an Option that sets the Cache
+// WithDefaultExpirationOption returns an Option that sets the cache
 // default expiration.
 func WithDefaultExpirationOption[K comparable, V any](d time.Duration) Option[K, V] {
 	return optionf[K, V](func(c *Cache[K, V]) {
@@ -33,7 +33,7 @@ func WithDefaultExpirationOption[K comparable, V any](d time.Duration) Option[K,
 	})
 }
 
-// WithDefaultSlidingExpirationOption returns an Option that sets the Cache
+// WithDefaultSlidingExpirationOption returns an Option that sets the cache
 // default sliding expiration.
 func WithDefaultSlidingExpirationOption[K comparable, V any](d time.Duration) Option[K, V] {
 	return optionf[K, V](func(c *Cache[K, V]) {
@@ -45,7 +45,7 @@ func WithDefaultSlidingExpirationOption[K comparable, V any](d time.Duration) Op
 	})
 }
 
-// WithMaxEntriesOption returns an Option that sets the Cache maximum number
+// WithMaxEntriesOption returns an Option that sets the cache maximum number
 // of entries. When the maximum number of entries is exceeded, the least
 // recently used entry is evicted regardless of the entry's expiration time.
 //