Add try_decode and make decoders return errors instead of throwing

CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## Unreleased
+
+### Added
+
+- Added `fine::try_decode<T>`, which does not throw when the type does not match.
+
+### Changed
+
+- **(Breaking)** Changed the `Decoder<T>` interface to require `try_decode` instead of `decode`. Custom decoders must return `fine::DecodeResult<T>`.
+
 ## [v0.1.6](https://github.com/elixir-nx/fine/tree/v0.1.6) (2026-04-09)
 
 ### Fixed

README.md

@@ -132,6 +132,22 @@ auto term = fine::encode(env, message);
 auto message = fine::decode<std::string>(env, term);
 ```
 
+`fine::decode<T>` throws `std::invalid_argument` if the term cannot be
+decoded. Use `fine::try_decode<T>` to get a `fine::DecodeResult<T>` instead:
+
+```c++
+auto result = fine::try_decode<int64_t>(env, term);
+if (result) {
+  auto value = std::move(result).value();
+} else {
+  auto message = result.error().message(env);
+}
+```
+
+The result contains either a value or a `fine::DecodeError`.
+`DecodeError::message(env)` formats the error, including the failing term.
+Other exceptions, such as allocation errors, still propagate.
+
 Fine provides implementations for the following types:
 
 | C++ Type                             | Encoder | Decoder | Elixir Type                 |
@@ -216,8 +232,9 @@ the following specializations:
 // Note that the specialization must be defined in the `fine` namespace.
 namespace fine {
   template <> struct Decoder<MyType> {
-    static MyType decode(ErlNifEnv *env, const ERL_NIF_TERM &term) {
-      // ...
+    static DecodeResult<MyType>
+    try_decode(ErlNifEnv *env, const ERL_NIF_TERM &term) {
+      // Return MyType or DecodeError{description, term}.
     }
   };
 
@@ -229,6 +246,9 @@ namespace fine {
 }
 ```
 
+Return `DecodeError{description, term}` for invalid input. Omit `term` to
+use the description as the complete message.
+
 ## Resource objects
 
 Resource objects is a mechanism for passing pointers to C++ data