Merge pull request #26 from theseus-rs/update-example-documentation

docs: update example documentation

Author: brianheineman

CHANGELOG.md

@@ -35,7 +35,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - update apache name format
 
 ### Other
-- add supported file types to file_type crate reamde
+- add supported file types to file_type crate readme
 
 ## `file_type` - [0.0.3](https://github.com/theseus-rs/file-type/compare/file_type-v0.0.2...file_type-v0.0.3) - 2025-01-03
 

README.md

@@ -23,18 +23,37 @@ use file_type::FileType;
 
 let file_type = FileType::from_bytes(b"\xCA\xFE\xBA\xBE");
 assert_eq!(file_type.name(), "Java Class File");
-assert_eq!(file_type.media_type(), Vec::<String>::new());
+assert_eq!(file_type.media_types(), Vec::<String>::new());
 assert_eq!(file_type.extensions(), vec!["class"]);
 ```
 
-Detect text from bytes:
+Detect the file type from a file:
 ```rust
 use file_type::FileType;
+use std::path::Path;
 
-let file_type = FileType::from_bytes(b"hello, world\n");
-assert_eq!(file_type.name(), "Text");
-assert_eq!(file_type.media_types(), vec!["text/plain"]);
-assert_eq!(file_type.extensions(), Vec::<String>::new());
+#[tokio::main]
+async fn main() {
+    let file_path = Path::new("image.png");
+    let file_type = FileType::try_from_file(file_path).await.expect("file type not found");
+    assert_eq!(file_type.id(), "fmt/11");
+    assert_eq!(file_type.name(), "Portable Network Graphics");
+    assert_eq!(file_type.extensions(), vec!["png"]);
+    assert_eq!(file_type.media_types(), vec!["image/png"]);
+}
+```
+
+Detect the file type from a file synchronously:
+```rust
+use file_type::FileType;
+use std::path::Path;
+
+let file_path = Path::new("image.png");
+let file_type = FileType::try_from_file_sync(file_path).expect("file type not found");
+assert_eq!(file_type.id(), "fmt/11");
+assert_eq!(file_type.name(), "Portable Network Graphics");
+assert_eq!(file_type.extensions(), vec!["png"]);
+assert_eq!(file_type.media_types(), vec!["image/png"]);
 ```
 
 ## Supported File Types

file_type/README.md

@@ -10,7 +10,7 @@
 
 ## Getting Started
 
-A file type.  The file type is determined by examining the file or bytes against known file
+File types are determined by examining a file or bytes against known file
 signatures and file extensions.
 
 Signature, extension and media type data are provided by:
@@ -25,21 +25,38 @@ Detect a Java class file from bytes:
 use file_type::FileType;
 
 let file_type = FileType::from_bytes(b"\xCA\xFE\xBA\xBE");
-assert_eq!(file_type.id(), "x-fmt/415");
 assert_eq!(file_type.name(), "Java Class File");
 assert_eq!(file_type.media_types(), Vec::<String>::new());
 assert_eq!(file_type.extensions(), vec!["class"]);
 ```
 
-Detect text from bytes:
+Detect the file type from a file:
 ```rust
 use file_type::FileType;
+use std::path::Path;
 
-let file_type = FileType::from_bytes(b"hello, world\n");
-assert_eq!(file_type.id(), "default/2");
-assert_eq!(file_type.name(), "Text");
-assert_eq!(file_type.media_types(), vec!["text/plain"]);
-assert_eq!(file_type.extensions(), Vec::<String>::new());
+#[tokio::main]
+async fn main() {
+    let file_path = Path::new("image.png");
+    let file_type = FileType::try_from_file(file_path).await.expect("file type not found");
+    assert_eq!(file_type.id(), "fmt/11");
+    assert_eq!(file_type.name(), "Portable Network Graphics");
+    assert_eq!(file_type.extensions(), vec!["png"]);
+    assert_eq!(file_type.media_types(), vec!["image/png"]);
+}
+```
+
+Detect the file type from a file synchronously:
+```rust
+use file_type::FileType;
+use std::path::Path;
+
+let file_path = Path::new("image.png");
+let file_type = FileType::try_from_file_sync(file_path).expect("file type not found");
+assert_eq!(file_type.id(), "fmt/11");
+assert_eq!(file_type.name(), "Portable Network Graphics");
+assert_eq!(file_type.extensions(), vec!["png"]);
+assert_eq!(file_type.media_types(), vec!["image/png"]);
 ```
 
 ## Supported File Types

file_type/src/file_type.rs

@@ -24,14 +24,33 @@ use tokio::runtime::Builder;
 /// assert_eq!(file_type.extensions(), vec!["class"]);
 /// ```
 ///
-/// Detect text from bytes:
+/// Detect the file type from a file:
+/// ```no_run
+/// use file_type::FileType;
+/// use std::path::Path;
+///
+/// #[tokio::main]
+/// async fn main() {
+///     let file_path = Path::new("image.png");
+///     let file_type = FileType::try_from_file(file_path).await.expect("file type not found");
+///     assert_eq!(file_type.id(), "fmt/11");
+///     assert_eq!(file_type.name(), "Portable Network Graphics");
+///     assert_eq!(file_type.extensions(), vec!["png"]);
+///     assert_eq!(file_type.media_types(), vec!["image/png"]);
+/// }
 /// ```
+///
+/// Detect the file type from a file synchronously:
+/// ```no_run
 /// use file_type::FileType;
+/// use std::path::Path;
 ///
-/// let file_type = FileType::from_bytes(b"hello, world\n");
-/// assert_eq!(file_type.name(), "Text");
-/// assert_eq!(file_type.media_types(), vec!["text/plain"]);
-/// assert_eq!(file_type.extensions(), Vec::<String>::new());
+/// let file_path = Path::new("image.png");
+/// let file_type = FileType::try_from_file_sync(file_path).expect("file type not found");
+/// assert_eq!(file_type.id(), "fmt/11");
+/// assert_eq!(file_type.name(), "Portable Network Graphics");
+/// assert_eq!(file_type.extensions(), vec!["png"]);
+/// assert_eq!(file_type.media_types(), vec!["image/png"]);
 /// ```
 #[derive(Clone, Debug)]
 pub struct FileType {

file_type/src/lib.rs

@@ -27,14 +27,33 @@
 //! assert_eq!(file_type.extensions(), vec!["class"]);
 //! ```
 //!
-//! Detect text from bytes:
+//! Detect the file type from a file:
+//! ```no_run
+//! use file_type::FileType;
+//! use std::path::Path;
+//!
+//! #[tokio::main]
+//! async fn main() {
+//!     let file_path = Path::new("image.png");
+//!     let file_type = FileType::try_from_file(file_path).await.expect("file type not found");
+//!     assert_eq!(file_type.id(), "fmt/11");
+//!     assert_eq!(file_type.name(), "Portable Network Graphics");
+//!     assert_eq!(file_type.extensions(), vec!["png"]);
+//!     assert_eq!(file_type.media_types(), vec!["image/png"]);
+//! }
 //! ```
+//!
+//! Detect the file type from a file synchronously:
+//! ```no_run
 //! use file_type::FileType;
+//! use std::path::Path;
 //!
-//! let file_type = FileType::from_bytes(b"hello, world\n");
-//! assert_eq!(file_type.name(), "Text");
-//! assert_eq!(file_type.media_types(), vec!["text/plain"]);
-//! assert_eq!(file_type.extensions(), Vec::<String>::new());
+//! let file_path = Path::new("image.png");
+//! let file_type = FileType::try_from_file_sync(file_path).expect("file type not found");
+//! assert_eq!(file_type.id(), "fmt/11");
+//! assert_eq!(file_type.name(), "Portable Network Graphics");
+//! assert_eq!(file_type.extensions(), vec!["png"]);
+//! assert_eq!(file_type.media_types(), vec!["image/png"]);
 //! ```
 //!
 //! ## Safety