Merge remote-tracking branch 'origin/upstream'

22 files changed, 4105 insertions, 0 deletions

diff --git a/.cargo_vcs_info.json b/.cargo_vcs_info.json
new file mode 100644
index 0000000..b7892a0
--- /dev/null
+++ b/.cargo_vcs_info.json
@@ -0,0 +1,6 @@
+{
+  "git": {
+    "sha1": "421259f7e9ba101fbab04babab9757736da1a419"
+  },
+  "path_in_vcs": ""
+}
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..96ef6c0
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,2 @@
+/target
+Cargo.lock
diff --git a/Android.bp b/Android.bp
new file mode 100644
index 0000000..43249d6
--- /dev/null
+++ b/Android.bp
@@ -0,0 +1,19 @@
+// This file is generated by cargo_embargo.
+// Do not modify this file as changes will be overridden on upgrade.
+
+// TODO: Add license.
+rust_library {
+    name: "libcamino",
+    host_supported: true,
+    crate_name: "camino",
+    cargo_env_compat: true,
+    cargo_pkg_version: "1.1.6",
+    srcs: ["src/lib.rs"],
+    edition: "2018",
+    apex_available: [
+        "//apex_available:platform",
+        "//apex_available:anyapex",
+    ],
+    product_available: true,
+    vendor_available: true,
+}
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..7558c70
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,149 @@
+# Changelog
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.6] - 2023-07-11
+
+### Added
+
+- Implement `Deserialize` for `Box<Utf8Path>`.
+
+## [1.1.5] - 2023-07-11
+
+(This release was not published due to an internal issue.)
+
+## [1.1.4] - 2023-03-09
+
+### Added
+
+- Implement `DerefMut` for `Utf8PathBuf` on Rust 1.68 and above.
+
+## [1.1.3] - 2023-02-21
+
+### Added
+
+- New method `Utf8DirEntry::into_path` to return an owned `Utf8PathBuf`.
+
+## [1.1.2] - 2022-08-12
+
+### Added
+
+- New convenience methods [`FromPathBufError::into_io_error`] and
+  [`FromPathError::into_io_error`].
+
+## [1.1.1] - 2022-08-12
+
+### Fixed
+
+- Fixed a build regression on older nightlies in the 1.63 series
+  ([#22](https://github.com/camino-rs/camino/issues/22)).
+- Documentation fixes.
+
+## [1.1.0] - 2022-08-11
+
+### Added
+
+- New methods, mirroring those in recent versions of Rust:
+  - `Utf8Path::try_exists` checks whether a path exists. Note that while `std::path::Path` only provides this method for Rust 1.58 and above, `camino` backfills the method for all Rust versions it supports.
+  - `Utf8PathBuf::shrink_to` shrinks a `Utf8PathBuf` to a given size. This was added in, and is gated on, Rust 1.56+.
+  - `Utf8PathBuf::try_reserve` and `Utf8PathBuf::try_reserve_exact` implement fallible allocations. These were added in, and are gated on, Rust 1.63+.
+- A number of `#[must_use]` annotations to APIs, mirroring those added to `Path` and `PathBuf` in recent versions of Rust. The minor version bump is due to this change.
+
+## [1.0.9] - 2022-05-19
+
+### Fixed
+
+- Documentation fixes.
+
+## [1.0.8] - 2022-05-09
+
+### Added
+
+- New methods `canonicalize_utf8`, `read_link_utf8` and `read_dir_utf8` return `Utf8PathBuf`s, erroring out if a resulting path is not valid UTF-8.
+- New feature `proptest1` introduces proptest `Arbitrary` impls for `Utf8PathBuf` and
+  `Box<Utf8Path>` ([#18], thanks [mcronce](https://github.com/mcronce) for your first contribution!)
+  
+[#18]: https://github.com/camino-rs/camino/pull/18
+
+## [1.0.7] - 2022-01-16
+
+### Added
+
+- `Utf8Path::is_symlink` checks whether a path is a symlink. Note that while `std::path::Path` only
+  provides this method for version 1.58 and above, `camino` backfills the method for all Rust versions
+  it supports.
+
+### Changed
+
+- Update repository links to new location [camino-rs/camino](https://github.com/camino-rs/camino).
+- Update `structopt` example to clap 3's builtin derive feature.
+  (camino continues to work with structopt as before.)
+
+## [1.0.6] - 2022-01-16
+
+(This release was yanked due to a publishing issue.)
+
+## [1.0.5] - 2021-07-27
+
+### Added
+
+- `Utf8PathBuf::into_std_path_buf` converts a `Utf8PathBuf` to a `PathBuf`; equivalent to the
+  `From<Utf8PathBuf> for PathBuf` impl, but may aid in type inference.
+- `Utf8Path::as_std_path` converts a `Utf8Path` to a `Path`; equivalent to the
+  `AsRef<&Path> for &Utf8Path` impl, but may aid in type inference.
+
+## [1.0.4] - 2021-03-19
+
+### Fixed
+
+- `Hash` impls for `Utf8PathBuf` and `Utf8Path` now match as required by the `Borrow` contract ([#9]).
+
+[#9]: https://github.com/camino-rs/camino/issues/9
+
+## [1.0.3] - 2021-03-11
+
+### Added
+
+- `TryFrom<PathBuf> for Utf8PathBuf` and `TryFrom<&Path> for &Utf8Path`, both of which return new error types ([#6]).
+- `AsRef<Utf8Path>`, `AsRef<Path>`, `AsRef<str>` and `AsRef<OsStr>` impls for `Utf8Components`, `Utf8Component` and
+  `Iter`.
+
+[#6]: https://github.com/camino-rs/camino/issues/6
+
+## [1.0.2] - 2021-03-02
+
+### Added
+
+- `From` impls for converting a `&Utf8Path` or a `Utf8PathBuf` into `Box<Path>`, `Rc<Path>`, `Arc<Path>` and `Cow<'a, Path>`.
+- `PartialEq` and `PartialOrd` implementations comparing `Utf8Path` and `Utf8PathBuf` with `Path`, `PathBuf` and its
+  variants, and comparing `OsStr`, `OsString` and its variants.
+
+## [1.0.1] - 2021-02-25
+
+### Added
+
+- More `PartialEq` and `PartialOrd` implementations.
+- MSRV lowered to 1.34.
+
+## [1.0.0] - 2021-02-23
+
+Initial release.
+
+[1.1.6]: https://github.com/camino-rs/camino/releases/tag/camino-1.1.6
+[1.1.5]: https://github.com/camino-rs/camino/releases/tag/camino-1.1.5
+[1.1.4]: https://github.com/camino-rs/camino/releases/tag/camino-1.1.4
+[1.1.3]: https://github.com/camino-rs/camino/releases/tag/camino-1.1.3
+[1.1.2]: https://github.com/camino-rs/camino/releases/tag/camino-1.1.2
+[1.1.1]: https://github.com/camino-rs/camino/releases/tag/camino-1.1.1
+[1.1.0]: https://github.com/camino-rs/camino/releases/tag/camino-1.1.0
+[1.0.9]: https://github.com/camino-rs/camino/releases/tag/camino-1.0.9
+[1.0.8]: https://github.com/camino-rs/camino/releases/tag/camino-1.0.8
+[1.0.7]: https://github.com/camino-rs/camino/releases/tag/camino-1.0.7
+[1.0.6]: https://github.com/camino-rs/camino/releases/tag/camino-1.0.6
+[1.0.5]: https://github.com/camino-rs/camino/releases/tag/camino-1.0.5
+[1.0.4]: https://github.com/camino-rs/camino/releases/tag/camino-1.0.4
+[1.0.3]: https://github.com/camino-rs/camino/releases/tag/camino-1.0.3
+[1.0.2]: https://github.com/camino-rs/camino/releases/tag/camino-1.0.2
+[1.0.1]: https://github.com/camino-rs/camino/releases/tag/camino-1.0.1
+[1.0.0]: https://github.com/camino-rs/camino/releases/tag/camino-1.0.0
diff --git a/Cargo.toml b/Cargo.toml
new file mode 100644
index 0000000..b0bfabd
--- /dev/null
+++ b/Cargo.toml
@@ -0,0 +1,64 @@
+# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO
+#
+# When uploading crates to the registry Cargo will automatically
+# "normalize" Cargo.toml files for maximal compatibility
+# with all versions of Cargo and also rewrite `path` dependencies
+# to registry (e.g., crates.io) dependencies.
+#
+# If you are reading this file be aware that the original Cargo.toml
+# will likely look very different (and much more reasonable).
+# See Cargo.toml.orig for the original contents.
+
+[package]
+edition = "2018"
+name = "camino"
+version = "1.1.6"
+authors = [
+    "Without Boats <saoirse@without.boats>",
+    "Ashley Williams <ashley666ashley@gmail.com>",
+    "Steve Klabnik <steve@steveklabnik.com>",
+    "Rain <rain@sunshowers.io>",
+]
+exclude = [
+    ".cargo/**/*",
+    ".github/**/*",
+]
+description = "UTF-8 paths"
+documentation = "https://docs.rs/camino"
+readme = "README.md"
+keywords = [
+    "paths",
+    "utf8",
+    "unicode",
+    "filesystem",
+]
+categories = [
+    "development-tools",
+    "filesystem",
+    "os",
+]
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/camino-rs/camino"
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg=doc_cfg"]
+
+[dependencies.proptest]
+version = "1.0.0"
+optional = true
+
+[dependencies.serde]
+version = "1"
+features = ["derive"]
+optional = true
+
+[dev-dependencies.bincode]
+version = "1"
+
+[dev-dependencies.serde_bytes]
+version = "0.11.8"
+
+[features]
+proptest1 = ["proptest"]
+serde1 = ["serde"]
diff --git a/LICENSE b/LICENSE
new file mode 120000
index 0000000..6b579aa
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1 @@
+LICENSE-APACHE
\ No newline at end of file
diff --git a/LICENSE-APACHE b/LICENSE-APACHE
new file mode 100644
index 0000000..16fe87b
--- /dev/null
+++ b/LICENSE-APACHE
@@ -0,0 +1,201 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+	http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
diff --git a/LICENSE-MIT b/LICENSE-MIT
new file mode 100644
index 0000000..31aa793
--- /dev/null
+++ b/LICENSE-MIT
@@ -0,0 +1,23 @@
+Permission is hereby granted, free of charge, to any
+person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the
+Software without restriction, including without
+limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions
+of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
diff --git a/METADATA b/METADATA
new file mode 100644
index 0000000..cc39c21
--- /dev/null
+++ b/METADATA
@@ -0,0 +1,21 @@
+name: "camino"
+description: "UTF-8 paths"
+third_party {
+  identifier {
+    type: "crates.io"
+    value: "camino"
+  }
+  identifier {
+    type: "Archive"
+    value: "https://static.crates.io/crates/camino/camino-1.1.6.crate"
+    primary_source: true
+  }
+  version: "1.1.6"
+  # Dual-licensed, using the least restrictive per go/thirdpartylicenses#same.
+  license_type: NOTICE
+  last_upgrade_date {
+    year: 2024
+    month: 3
+    day: 21
+  }
+}
diff --git a/MODULE_LICENSE_APACHE2 b/MODULE_LICENSE_APACHE2
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/MODULE_LICENSE_APACHE2
diff --git a/OWNERS b/OWNERS
new file mode 100644
index 0000000..48bea6e
--- /dev/null
+++ b/OWNERS
@@ -0,0 +1,2 @@
+# Bug component: 688011
+include platform/prebuilts/rust:main:/OWNERS
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..82c03e4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,132 @@
+# camino - UTF-8 paths
+
+[![camino on crates.io](https://img.shields.io/crates/v/camino)](https://crates.io/crates/camino)
+[![crates.io download count](https://img.shields.io/crates/d/camino)](https://crates.io/crates/camino)
+[![Documentation (latest release)](https://img.shields.io/badge/docs-latest%20version-brightgreen.svg)](https://docs.rs/camino)
+[![Documentation (main)](https://img.shields.io/badge/docs-main-purple.svg)](https://camino-rs.github.io/camino/rustdoc/camino/)
+[![License](https://img.shields.io/badge/license-Apache-green.svg)](LICENSE-APACHE)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE-MIT)
+
+This repository contains the source code for `camino`, an extension of the `std::path` module that adds new
+[`Utf8PathBuf`] and [`Utf8Path`] types.
+
+## What is camino?
+
+`camino`'s [`Utf8PathBuf`] and [`Utf8Path`] types are like the standard library's [`PathBuf`] and [`Path`] types, except
+they  are guaranteed to only contain UTF-8 encoded data. Therefore, they expose the ability to get their
+contents as strings, they implement `Display`, etc.
+
+The `std::path` types are not guaranteed to be valid UTF-8. This is the right decision for the standard library,
+since it must be as general as possible. However, on all platforms, non-Unicode paths are vanishingly uncommon for a
+number of reasons:
+* Unicode won. There are still some legacy codebases that store paths in encodings like [Shift JIS], but most
+  have been converted to Unicode at this point.
+* Unicode is the common subset of supported paths across Windows and Unix platforms. (On Windows, Rust stores paths
+  as [an extension to UTF-8](https://simonsapin.github.io/wtf-8/), and converts them to UTF-16 at Win32
+  API boundaries.)
+* There are already many systems, such as Cargo, that only support UTF-8 paths. If your own tool interacts with any such
+  system, you can assume that paths are valid UTF-8 without creating any additional burdens on consumers.
+* The ["makefile problem"](https://www.mercurial-scm.org/wiki/EncodingStrategy#The_.22makefile_problem.22) asks: given a
+  Makefile or other metadata file (such as `Cargo.toml`) that lists the names of other files, how should the names in
+  the Makefile be matched with the ones on disk? This has *no general, cross-platform solution* in systems that support
+  non-UTF-8 paths. However, restricting paths to UTF-8 eliminates this problem.
+
+[Shift JIS]: https://en.wikipedia.org/wiki/Shift_JIS
+
+Therefore, many programs that want to manipulate paths *do* assume they contain UTF-8 data, and convert them to `str`s
+as  necessary. However, because this invariant is not encoded in the `Path` type, conversions such as
+`path.to_str().unwrap()` need to be repeated again and again, creating a frustrating experience.
+
+Instead, `camino` allows you to check that your paths are UTF-8 *once*, and then manipulate them
+as valid UTF-8 from there on, avoiding repeated lossy and confusing conversions.
+
+## Examples
+
+The documentation for [`Utf8PathBuf`] and [`Utf8Path`] contains several examples.
+
+For examples of how to use `camino` with other libraries like `serde` and `clap`, see the [`camino-examples`] directory.
+
+## API design
+
+`camino` is a very thin wrapper around `std::path`. [`Utf8Path`] and [`Utf8PathBuf`] are drop-in replacements
+for [`Path`] and [`PathBuf`].
+
+Most APIs are the same, but those at the boundary with `str` are different. Some examples:
+* `Path::to_str() -> Option<&str>` has been renamed to `Utf8Path::as_str() -> &str`.
+* [`Utf8Path`] implements `Display`, and `Path::display()` has been removed.
+* Iterating over a [`Utf8Path`] returns `&str`, not `&OsStr`.
+
+Every [`Utf8Path`] is a valid [`Path`], so [`Utf8Path`] implements `AsRef<Path>`. Any APIs that accept `impl AsRef<Path>`
+will continue to work with [`Utf8Path`] instances.
+
+## Should you use camino?
+
+`camino` trades off some utility for a great deal of simplicity. Whether `camino` is appropriate for a project or not
+is ultimately a case-by-case decision. Here are some general guidelines that may help.
+
+*You should consider using camino if...*
+
+* **You're building portable, cross-platform software.** While both Unix and Windows platforms support different kinds
+  of non-Unicode paths, Unicode is the common subset that's supported across them.
+* **Your system has files that contain the names of other files.** If you don't use UTF-8 paths, you will run into the
+  makefile problem described above, which has no general, cross-platform solution.
+* **You're interacting with existing systems that already assume UTF-8 paths.** In that case you won't be adding any new
+  burdens on downstream consumers.
+* **You're building something brand new and are willing to ask your users to rename their paths if necessary.** Projects
+  that don't have to worry about legacy compatibility have more flexibility in choosing what paths they support.
+  
+In general, using camino is the right choice for most projects.
+
+*You should **NOT** use camino, if...*
+
+* **You're writing a core system utility.** If you're writing, say, an `mv` or `cat` replacement, you should
+  **not** use camino. Instead, use [`std::path::Path`] and add extensive tests for non-UTF-8 paths.
+* **You have legacy compatibility constraints.** For example, Git supports non-UTF-8 paths. If your tool needs to handle
+  arbitrary Git repositories, it should use its own path type that's a wrapper around `Vec<u8>`. 
+  * [`std::path::Path`] supports arbitrary bytestrings [on Unix] but not on Windows.
+* **There's some other reason you need to support non-UTF-8 paths.** Some tools like disk recovery utilities need to
+  handle potentially corrupt filenames: only being able to handle UTF-8 paths would greatly diminish their utility.
+
+[on Unix]: https://doc.rust-lang.org/std/os/unix/ffi/index.html
+
+## Optional features
+
+By default, `camino` has **no dependencies** other than `std`. There are some optional features that enable
+dependencies:
+* `serde1` adds serde [`Serialize`] and [`Deserialize`] impls for [`Utf8PathBuf`] and [`Utf8Path`]
+  (zero-copy).
+* `proptest1` adds [proptest](https://altsysrq.github.io/proptest-book/) [`Arbitrary`]
+  implementations for [`Utf8PathBuf`] and `Box<Utf8Path>`.
+
+## Rust version support
+
+The minimum supported Rust version (MSRV) for `camino` with default features is **1.34**. This project is tested in CI
+against the latest stable version of Rust and the MSRV.
+* *Stable APIs* added in later Rust versions are supported either through conditional compilation in `build.rs`, or through backfills that also work on older versions.
+* *Deprecations* are kept in sync with the version of Rust they're added in.
+* *Unstable APIs* are currently not supported. Please
+  [file an issue on GitHub](https://github.com/camino-rs/camino/issues/new) if you need an unstable API.
+
+`camino` is designed to be a core library and has a conservative MSRV policy. MSRV increases will only happen for
+a compelling enough reason, and will involve at least a minor version bump.
+
+Optional features may pull in dependencies that require a newer version of Rust.
+
+## License
+
+This project is available under the terms of either the [Apache 2.0 license](LICENSE-APACHE) or the [MIT
+license](LICENSE-MIT).
+
+This project's documentation is adapted from [The Rust Programming Language](https://github.com/rust-lang/rust/), which is
+available under the terms of either the [Apache 2.0 license](https://github.com/rust-lang/rust/blob/master/LICENSE-APACHE)
+or the [MIT license](https://github.com/rust-lang/rust/blob/master/LICENSE-MIT).
+
+[`Utf8PathBuf`]: https://docs.rs/camino/*/camino/struct.Utf8PathBuf.html
+[`Utf8Path`]: https://docs.rs/camino/*/camino/struct.Utf8Path.html
+[`PathBuf`]: https://doc.rust-lang.org/std/path/struct.PathBuf.html
+[`Path`]: https://doc.rust-lang.org/std/path/struct.Path.html
+[`std::path::Path`]: https://doc.rust-lang.org/std/path/struct.Path.html
+[`Serialize`]: https://docs.rs/serde/1/serde/trait.Serialize.html
+[`Deserialize`]: https://docs.rs/serde/1/serde/trait.Deserialize.html
+[`camino-examples`]: https://github.com/camino-rs/camino/tree/main/camino-examples
+[`Arbitrary`]: https://docs.rs/proptest/1/proptest/arbitrary/trait.Arbitrary.html
diff --git a/build.rs b/build.rs
new file mode 100644
index 0000000..c24fc8e
--- /dev/null
+++ b/build.rs
@@ -0,0 +1,74 @@
+// Copyright (c) The camino Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! Adapted from
+//! https://github.com/dtolnay/syn/blob/a54fb0098c6679f1312113ae2eec0305c51c7390/build.rs.
+
+use std::{env, process::Command, str};
+
+// The rustc-cfg strings below are *not* public API. Please let us know by
+// opening a GitHub issue if your build environment requires some way to enable
+// these cfgs other than by executing our build script.
+fn main() {
+    let compiler = match rustc_version() {
+        Some(compiler) => compiler,
+        None => return,
+    };
+
+    // NOTE:
+    // Adding a new cfg gated by Rust version MUST be accompanied by an addition to the matrix in
+    // .github/workflows/ci.yml.
+    if compiler.minor >= 44 {
+        println!("cargo:rustc-cfg=path_buf_capacity");
+    }
+    if compiler.minor >= 56 {
+        println!("cargo:rustc-cfg=shrink_to");
+    }
+    // NOTE: the below checks use == rather than `matches!`. This is because `matches!` isn't stable
+    // on Rust 1.34.
+    // try_reserve_2 was added in a 1.63 nightly.
+    if (compiler.minor >= 63
+        && (compiler.channel == ReleaseChannel::Stable || compiler.channel == ReleaseChannel::Beta))
+        || compiler.minor >= 64
+    {
+        println!("cargo:rustc-cfg=try_reserve_2");
+    }
+    // path_buf_deref_mut was added in a 1.68 nightly.
+    if (compiler.minor >= 68
+        && (compiler.channel == ReleaseChannel::Stable || compiler.channel == ReleaseChannel::Beta))
+        || compiler.minor >= 69
+    {
+        println!("cargo:rustc-cfg=path_buf_deref_mut");
+    }
+}
+
+struct Compiler {
+    minor: u32,
+    channel: ReleaseChannel,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+enum ReleaseChannel {
+    Stable,
+    Beta,
+    Nightly,
+}
+
+fn rustc_version() -> Option<Compiler> {
+    let rustc = env::var_os("RUSTC")?;
+    let output = Command::new(rustc).arg("--version").output().ok()?;
+    let version = str::from_utf8(&output.stdout).ok()?;
+    let mut pieces = version.split('.');
+    if pieces.next() != Some("rustc 1") {
+        return None;
+    }
+    let minor = pieces.next()?.parse().ok()?;
+    let channel = if version.contains("nightly") {
+        ReleaseChannel::Nightly
+    } else if version.contains("beta") {
+        ReleaseChannel::Beta
+    } else {
+        ReleaseChannel::Stable
+    };
+    Some(Compiler { minor, channel })
+}
diff --git a/cargo_embargo.json b/cargo_embargo.json
new file mode 100644
index 0000000..cb908d7
--- /dev/null
+++ b/cargo_embargo.json
@@ -0,0 +1,3 @@
+{
+  "run_cargo": false
+}
diff --git a/clippy.toml b/clippy.toml
new file mode 100644
index 0000000..b32f6d5
--- /dev/null
+++ b/clippy.toml
@@ -0,0 +1 @@
+msrv = "1.34.0"
diff --git a/release.toml b/release.toml
new file mode 100644
index 0000000..b7977ba
--- /dev/null
+++ b/release.toml
@@ -0,0 +1,8 @@
+sign-tag = true
+# Required for templates below to work
+consolidate-commits = false
+pre-release-commit-message = "[{{crate_name}}] version {{version}}"
+tag-message = "[{{crate_name}}] version {{version}}"
+tag-name = "camino-{{version}}"
+publish = false
+dependent-version = "upgrade"
diff --git a/rustfmt.toml b/rustfmt.toml
new file mode 100644
index 0000000..80eeb40
--- /dev/null
+++ b/rustfmt.toml
@@ -0,0 +1,2 @@
+edition = "2018"
+use_field_init_shorthand = true
diff --git a/src/lib.rs b/src/lib.rs
new file mode 100644
index 0000000..7a5c61c
--- /dev/null
+++ b/src/lib.rs
@@ -0,0 +1,2954 @@
+// Copyright (c) The camino Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+#![warn(missing_docs)]
+#![cfg_attr(doc_cfg, feature(doc_cfg, doc_auto_cfg))]
+
+//! UTF-8 encoded paths.
+//!
+//! `camino` is an extension of the `std::path` module that adds new [`Utf8PathBuf`] and [`Utf8Path`]
+//! types. These are like the standard library's [`PathBuf`] and [`Path`] types, except they are
+//! guaranteed to only contain UTF-8 encoded data. Therefore, they expose the ability to get their
+//! contents as strings, they implement `Display`, etc.
+//!
+//! The `std::path` types are not guaranteed to be valid UTF-8. This is the right decision for the standard library,
+//! since it must be as general as possible. However, on all platforms, non-Unicode paths are vanishingly uncommon for a
+//! number of reasons:
+//! * Unicode won. There are still some legacy codebases that store paths in encodings like Shift-JIS, but most
+//!   have been converted to Unicode at this point.
+//! * Unicode is the common subset of supported paths across Windows and Unix platforms. (On Windows, Rust stores paths
+//!   as [an extension to UTF-8](https://simonsapin.github.io/wtf-8/), and converts them to UTF-16 at Win32
+//!   API boundaries.)
+//! * There are already many systems, such as Cargo, that only support UTF-8 paths. If your own tool interacts with any such
+//!   system, you can assume that paths are valid UTF-8 without creating any additional burdens on consumers.
+//! * The ["makefile problem"](https://www.mercurial-scm.org/wiki/EncodingStrategy#The_.22makefile_problem.22)
+//!   (which also applies to `Cargo.toml`, and any other metadata file that lists the names of other files) has *no general,
+//!   cross-platform solution* in systems that support non-UTF-8 paths. However, restricting paths to UTF-8 eliminates
+//!   this problem.
+//!
+//! Therefore, many programs that want to manipulate paths *do* assume they contain UTF-8 data, and convert them to `str`s
+//! as  necessary. However, because this invariant is not encoded in the `Path` type, conversions such as
+//! `path.to_str().unwrap()` need to be repeated again and again, creating a frustrating experience.
+//!
+//! Instead, `camino` allows you to check that your paths are UTF-8 *once*, and then manipulate them
+//! as valid UTF-8 from there on, avoiding repeated lossy and confusing conversions.
+
+use std::{
+    borrow::{Borrow, Cow},
+    cmp::Ordering,
+    convert::{Infallible, TryFrom, TryInto},
+    error,
+    ffi::{OsStr, OsString},
+    fmt,
+    fs::{self, Metadata},
+    hash::{Hash, Hasher},
+    io,
+    iter::FusedIterator,
+    ops::Deref,
+    path::*,
+    rc::Rc,
+    str::FromStr,
+    sync::Arc,
+};
+
+#[cfg(feature = "proptest1")]
+mod proptest_impls;
+#[cfg(feature = "serde1")]
+mod serde_impls;
+#[cfg(test)]
+mod tests;
+
+/// An owned, mutable UTF-8 path (akin to [`String`]).
+///
+/// This type provides methods like [`push`] and [`set_extension`] that mutate
+/// the path in place. It also implements [`Deref`] to [`Utf8Path`], meaning that
+/// all methods on [`Utf8Path`] slices are available on `Utf8PathBuf` values as well.
+///
+/// [`push`]: Utf8PathBuf::push
+/// [`set_extension`]: Utf8PathBuf::set_extension
+///
+/// # Examples
+///
+/// You can use [`push`] to build up a `Utf8PathBuf` from
+/// components:
+///
+/// ```
+/// use camino::Utf8PathBuf;
+///
+/// let mut path = Utf8PathBuf::new();
+///
+/// path.push(r"C:\");
+/// path.push("windows");
+/// path.push("system32");
+///
+/// path.set_extension("dll");
+/// ```
+///
+/// However, [`push`] is best used for dynamic situations. This is a better way
+/// to do this when you know all of the components ahead of time:
+///
+/// ```
+/// use camino::Utf8PathBuf;
+///
+/// let path: Utf8PathBuf = [r"C:\", "windows", "system32.dll"].iter().collect();
+/// ```
+///
+/// We can still do better than this! Since these are all strings, we can use
+/// `From::from`:
+///
+/// ```
+/// use camino::Utf8PathBuf;
+///
+/// let path = Utf8PathBuf::from(r"C:\windows\system32.dll");
+/// ```
+///
+/// Which method works best depends on what kind of situation you're in.
+// NB: Internal PathBuf must only contain utf8 data
+#[derive(Clone, Default)]
+#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
+#[cfg_attr(feature = "serde1", serde(transparent))]
+#[repr(transparent)]
+pub struct Utf8PathBuf(PathBuf);
+
+impl Utf8PathBuf {
+    /// Allocates an empty `Utf8PathBuf`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8PathBuf;
+    ///
+    /// let path = Utf8PathBuf::new();
+    /// ```
+    #[must_use]
+    pub fn new() -> Utf8PathBuf {
+        Utf8PathBuf(PathBuf::new())
+    }
+
+    /// Creates a new `Utf8PathBuf` from a `PathBuf` containing valid UTF-8 characters.
+    ///
+    /// Errors with the original `PathBuf` if it is not valid UTF-8.
+    ///
+    /// For a version that returns a type that implements [`std::error::Error`], use the
+    /// `TryFrom<PathBuf>` impl.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8PathBuf;
+    /// use std::ffi::OsStr;
+    /// # #[cfg(unix)]
+    /// use std::os::unix::ffi::OsStrExt;
+    /// use std::path::PathBuf;
+    ///
+    /// let unicode_path = PathBuf::from("/valid/unicode");
+    /// Utf8PathBuf::from_path_buf(unicode_path).expect("valid Unicode path succeeded");
+    ///
+    /// // Paths on Unix can be non-UTF-8.
+    /// # #[cfg(unix)]
+    /// let non_unicode_str = OsStr::from_bytes(b"\xFF\xFF\xFF");
+    /// # #[cfg(unix)]
+    /// let non_unicode_path = PathBuf::from(non_unicode_str);
+    /// # #[cfg(unix)]
+    /// Utf8PathBuf::from_path_buf(non_unicode_path).expect_err("non-Unicode path failed");
+    /// ```
+    pub fn from_path_buf(path: PathBuf) -> Result<Utf8PathBuf, PathBuf> {
+        match path.into_os_string().into_string() {
+            Ok(string) => Ok(Utf8PathBuf::from(string)),
+            Err(os_string) => Err(PathBuf::from(os_string)),
+        }
+    }
+
+    /// Converts a `Utf8PathBuf` to a [`PathBuf`].
+    ///
+    /// This is equivalent to the `From<Utf8PathBuf> for PathBuf` impl, but may aid in type
+    /// inference.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8PathBuf;
+    /// use std::path::PathBuf;
+    ///
+    /// let utf8_path_buf = Utf8PathBuf::from("foo.txt");
+    /// let std_path_buf = utf8_path_buf.into_std_path_buf();
+    /// assert_eq!(std_path_buf.to_str(), Some("foo.txt"));
+    ///
+    /// // Convert back to a Utf8PathBuf.
+    /// let new_utf8_path_buf = Utf8PathBuf::from_path_buf(std_path_buf).unwrap();
+    /// assert_eq!(new_utf8_path_buf, "foo.txt");
+    /// ```
+    #[must_use = "`self` will be dropped if the result is not used"]
+    pub fn into_std_path_buf(self) -> PathBuf {
+        self.into()
+    }
+
+    /// Creates a new `Utf8PathBuf` with a given capacity used to create the internal [`PathBuf`].
+    /// See [`with_capacity`] defined on [`PathBuf`].
+    ///
+    /// *Requires Rust 1.44 or newer.*
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8PathBuf;
+    ///
+    /// let mut path = Utf8PathBuf::with_capacity(10);
+    /// let capacity = path.capacity();
+    ///
+    /// // This push is done without reallocating
+    /// path.push(r"C:\");
+    ///
+    /// assert_eq!(capacity, path.capacity());
+    /// ```
+    ///
+    /// [`with_capacity`]: PathBuf::with_capacity
+    #[cfg(path_buf_capacity)]
+    #[must_use]
+    pub fn with_capacity(capacity: usize) -> Utf8PathBuf {
+        Utf8PathBuf(PathBuf::with_capacity(capacity))
+    }
+
+    /// Coerces to a [`Utf8Path`] slice.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::{Utf8Path, Utf8PathBuf};
+    ///
+    /// let p = Utf8PathBuf::from("/test");
+    /// assert_eq!(Utf8Path::new("/test"), p.as_path());
+    /// ```
+    #[must_use]
+    pub fn as_path(&self) -> &Utf8Path {
+        // SAFETY: every Utf8PathBuf constructor ensures that self is valid UTF-8
+        unsafe { Utf8Path::assume_utf8(&self.0) }
+    }
+
+    /// Extends `self` with `path`.
+    ///
+    /// If `path` is absolute, it replaces the current path.
+    ///
+    /// On Windows:
+    ///
+    /// * if `path` has a root but no prefix (e.g., `\windows`), it
+    ///   replaces everything except for the prefix (if any) of `self`.
+    /// * if `path` has a prefix but no root, it replaces `self`.
+    ///
+    /// # Examples
+    ///
+    /// Pushing a relative path extends the existing path:
+    ///
+    /// ```
+    /// use camino::Utf8PathBuf;
+    ///
+    /// let mut path = Utf8PathBuf::from("/tmp");
+    /// path.push("file.bk");
+    /// assert_eq!(path, Utf8PathBuf::from("/tmp/file.bk"));
+    /// ```
+    ///
+    /// Pushing an absolute path replaces the existing path:
+    ///
+    /// ```
+    /// use camino::Utf8PathBuf;
+    ///
+    /// let mut path = Utf8PathBuf::from("/tmp");
+    /// path.push("/etc");
+    /// assert_eq!(path, Utf8PathBuf::from("/etc"));
+    /// ```
+    pub fn push(&mut self, path: impl AsRef<Utf8Path>) {
+        self.0.push(&path.as_ref().0)
+    }
+
+    /// Truncates `self` to [`self.parent`].
+    ///
+    /// Returns `false` and does nothing if [`self.parent`] is [`None`].
+    /// Otherwise, returns `true`.
+    ///
+    /// [`self.parent`]: Utf8Path::parent
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::{Utf8Path, Utf8PathBuf};
+    ///
+    /// let mut p = Utf8PathBuf::from("/spirited/away.rs");
+    ///
+    /// p.pop();
+    /// assert_eq!(Utf8Path::new("/spirited"), p);
+    /// p.pop();
+    /// assert_eq!(Utf8Path::new("/"), p);
+    /// ```
+    pub fn pop(&mut self) -> bool {
+        self.0.pop()
+    }
+
+    /// Updates [`self.file_name`] to `file_name`.
+    ///
+    /// If [`self.file_name`] was [`None`], this is equivalent to pushing
+    /// `file_name`.
+    ///
+    /// Otherwise it is equivalent to calling [`pop`] and then pushing
+    /// `file_name`. The new path will be a sibling of the original path.
+    /// (That is, it will have the same parent.)
+    ///
+    /// [`self.file_name`]: Utf8Path::file_name
+    /// [`pop`]: Utf8PathBuf::pop
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8PathBuf;
+    ///
+    /// let mut buf = Utf8PathBuf::from("/");
+    /// assert_eq!(buf.file_name(), None);
+    /// buf.set_file_name("bar");
+    /// assert_eq!(buf, Utf8PathBuf::from("/bar"));
+    /// assert!(buf.file_name().is_some());
+    /// buf.set_file_name("baz.txt");
+    /// assert_eq!(buf, Utf8PathBuf::from("/baz.txt"));
+    /// ```
+    pub fn set_file_name(&mut self, file_name: impl AsRef<str>) {
+        self.0.set_file_name(file_name.as_ref())
+    }
+
+    /// Updates [`self.extension`] to `extension`.
+    ///
+    /// Returns `false` and does nothing if [`self.file_name`] is [`None`],
+    /// returns `true` and updates the extension otherwise.
+    ///
+    /// If [`self.extension`] is [`None`], the extension is added; otherwise
+    /// it is replaced.
+    ///
+    /// [`self.file_name`]: Utf8Path::file_name
+    /// [`self.extension`]: Utf8Path::extension
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::{Utf8Path, Utf8PathBuf};
+    ///
+    /// let mut p = Utf8PathBuf::from("/feel/the");
+    ///
+    /// p.set_extension("force");
+    /// assert_eq!(Utf8Path::new("/feel/the.force"), p.as_path());
+    ///
+    /// p.set_extension("dark_side");
+    /// assert_eq!(Utf8Path::new("/feel/the.dark_side"), p.as_path());
+    /// ```
+    pub fn set_extension(&mut self, extension: impl AsRef<str>) -> bool {
+        self.0.set_extension(extension.as_ref())
+    }
+
+    /// Consumes the `Utf8PathBuf`, yielding its internal [`String`] storage.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8PathBuf;
+    ///
+    /// let p = Utf8PathBuf::from("/the/head");
+    /// let s = p.into_string();
+    /// assert_eq!(s, "/the/head");
+    /// ```
+    #[must_use = "`self` will be dropped if the result is not used"]
+    pub fn into_string(self) -> String {
+        self.into_os_string().into_string().unwrap()
+    }
+
+    /// Consumes the `Utf8PathBuf`, yielding its internal [`OsString`] storage.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8PathBuf;
+    /// use std::ffi::OsStr;
+    ///
+    /// let p = Utf8PathBuf::from("/the/head");
+    /// let s = p.into_os_string();
+    /// assert_eq!(s, OsStr::new("/the/head"));
+    /// ```
+    #[must_use = "`self` will be dropped if the result is not used"]
+    pub fn into_os_string(self) -> OsString {
+        self.0.into_os_string()
+    }
+
+    /// Converts this `Utf8PathBuf` into a [boxed](Box) [`Utf8Path`].
+    #[must_use = "`self` will be dropped if the result is not used"]
+    pub fn into_boxed_path(self) -> Box<Utf8Path> {
+        let ptr = Box::into_raw(self.0.into_boxed_path()) as *mut Utf8Path;
+        // SAFETY:
+        // * self is valid UTF-8
+        // * ptr was constructed by consuming self so it represents an owned path
+        // * Utf8Path is marked as #[repr(transparent)] so the conversion from *mut Path to
+        //   *mut Utf8Path is valid
+        unsafe { Box::from_raw(ptr) }
+    }
+
+    /// Invokes [`capacity`] on the underlying instance of [`PathBuf`].
+    ///
+    /// *Requires Rust 1.44 or newer.*
+    ///
+    /// [`capacity`]: PathBuf::capacity
+    #[cfg(path_buf_capacity)]
+    #[must_use]
+    pub fn capacity(&self) -> usize {
+        self.0.capacity()
+    }
+
+    /// Invokes [`clear`] on the underlying instance of [`PathBuf`].
+    ///
+    /// *Requires Rust 1.44 or newer.*
+    ///
+    /// [`clear`]: PathBuf::clear
+    #[cfg(path_buf_capacity)]
+    pub fn clear(&mut self) {
+        self.0.clear()
+    }
+
+    /// Invokes [`reserve`] on the underlying instance of [`PathBuf`].
+    ///
+    /// *Requires Rust 1.44 or newer.*
+    ///
+    /// [`reserve`]: PathBuf::reserve
+    #[cfg(path_buf_capacity)]
+    pub fn reserve(&mut self, additional: usize) {
+        self.0.reserve(additional)
+    }
+
+    /// Invokes [`try_reserve`] on the underlying instance of [`PathBuf`].
+    ///
+    /// *Requires Rust 1.63 or newer.*
+    ///
+    /// [`try_reserve`]: PathBuf::try_reserve
+    #[cfg(try_reserve_2)]
+    #[inline]
+    pub fn try_reserve(
+        &mut self,
+        additional: usize,
+    ) -> Result<(), std::collections::TryReserveError> {
+        self.0.try_reserve(additional)
+    }
+
+    /// Invokes [`reserve_exact`] on the underlying instance of [`PathBuf`].
+    ///
+    /// *Requires Rust 1.44 or newer.*
+    ///
+    /// [`reserve_exact`]: PathBuf::reserve_exact
+    #[cfg(path_buf_capacity)]
+    pub fn reserve_exact(&mut self, additional: usize) {
+        self.0.reserve_exact(additional)
+    }
+
+    /// Invokes [`try_reserve_exact`] on the underlying instance of [`PathBuf`].
+    ///
+    /// *Requires Rust 1.63 or newer.*
+    ///
+    /// [`try_reserve_exact`]: PathBuf::try_reserve_exact
+    #[cfg(try_reserve_2)]
+    #[inline]
+    pub fn try_reserve_exact(
+        &mut self,
+        additional: usize,
+    ) -> Result<(), std::collections::TryReserveError> {
+        self.0.try_reserve_exact(additional)
+    }
+
+    /// Invokes [`shrink_to_fit`] on the underlying instance of [`PathBuf`].
+    ///
+    /// *Requires Rust 1.44 or newer.*
+    ///
+    /// [`shrink_to_fit`]: PathBuf::shrink_to_fit
+    #[cfg(path_buf_capacity)]
+    pub fn shrink_to_fit(&mut self) {
+        self.0.shrink_to_fit()
+    }
+
+    /// Invokes [`shrink_to`] on the underlying instance of [`PathBuf`].
+    ///
+    /// *Requires Rust 1.56 or newer.*
+    ///
+    /// [`shrink_to`]: PathBuf::shrink_to
+    #[cfg(shrink_to)]
+    #[inline]
+    pub fn shrink_to(&mut self, min_capacity: usize) {
+        self.0.shrink_to(min_capacity)
+    }
+}
+
+impl Deref for Utf8PathBuf {
+    type Target = Utf8Path;
+
+    fn deref(&self) -> &Utf8Path {
+        self.as_path()
+    }
+}
+
+/// *Requires Rust 1.68 or newer.*
+#[cfg(path_buf_deref_mut)]
+impl std::ops::DerefMut for Utf8PathBuf {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        unsafe { Utf8Path::assume_utf8_mut(&mut self.0) }
+    }
+}
+
+impl fmt::Debug for Utf8PathBuf {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        fmt::Debug::fmt(&**self, f)
+    }
+}
+
+impl fmt::Display for Utf8PathBuf {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        fmt::Display::fmt(self.as_str(), f)
+    }
+}
+
+impl<P: AsRef<Utf8Path>> Extend<P> for Utf8PathBuf {
+    fn extend<I: IntoIterator<Item = P>>(&mut self, iter: I) {
+        for path in iter {
+            self.push(path);
+        }
+    }
+}
+
+/// A slice of a UTF-8 path (akin to [`str`]).
+///
+/// This type supports a number of operations for inspecting a path, including
+/// breaking the path into its components (separated by `/` on Unix and by either
+/// `/` or `\` on Windows), extracting the file name, determining whether the path
+/// is absolute, and so on.
+///
+/// This is an *unsized* type, meaning that it must always be used behind a
+/// pointer like `&` or [`Box`]. For an owned version of this type,
+/// see [`Utf8PathBuf`].
+///
+/// # Examples
+///
+/// ```
+/// use camino::Utf8Path;
+///
+/// // Note: this example does work on Windows
+/// let path = Utf8Path::new("./foo/bar.txt");
+///
+/// let parent = path.parent();
+/// assert_eq!(parent, Some(Utf8Path::new("./foo")));
+///
+/// let file_stem = path.file_stem();
+/// assert_eq!(file_stem, Some("bar"));
+///
+/// let extension = path.extension();
+/// assert_eq!(extension, Some("txt"));
+/// ```
+// NB: Internal Path must only contain utf8 data
+#[repr(transparent)]
+pub struct Utf8Path(Path);
+
+impl Utf8Path {
+    /// Directly wraps a string slice as a `Utf8Path` slice.
+    ///
+    /// This is a cost-free conversion.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// Utf8Path::new("foo.txt");
+    /// ```
+    ///
+    /// You can create `Utf8Path`s from `String`s, or even other `Utf8Path`s:
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// let string = String::from("foo.txt");
+    /// let from_string = Utf8Path::new(&string);
+    /// let from_path = Utf8Path::new(&from_string);
+    /// assert_eq!(from_string, from_path);
+    /// ```
+    pub fn new(s: &(impl AsRef<str> + ?Sized)) -> &Utf8Path {
+        let path = Path::new(s.as_ref());
+        // SAFETY: s is a str which means it is always valid UTF-8
+        unsafe { Utf8Path::assume_utf8(path) }
+    }
+
+    /// Converts a [`Path`] to a `Utf8Path`.
+    ///
+    /// Returns `None` if the path is not valid UTF-8.
+    ///
+    /// For a version that returns a type that implements [`std::error::Error`], use the
+    /// `TryFrom<&Path>` impl.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    /// use std::ffi::OsStr;
+    /// # #[cfg(unix)]
+    /// use std::os::unix::ffi::OsStrExt;
+    /// use std::path::Path;
+    ///
+    /// let unicode_path = Path::new("/valid/unicode");
+    /// Utf8Path::from_path(unicode_path).expect("valid Unicode path succeeded");
+    ///
+    /// // Paths on Unix can be non-UTF-8.
+    /// # #[cfg(unix)]
+    /// let non_unicode_str = OsStr::from_bytes(b"\xFF\xFF\xFF");
+    /// # #[cfg(unix)]
+    /// let non_unicode_path = Path::new(non_unicode_str);
+    /// # #[cfg(unix)]
+    /// assert!(Utf8Path::from_path(non_unicode_path).is_none(), "non-Unicode path failed");
+    /// ```
+    pub fn from_path(path: &Path) -> Option<&Utf8Path> {
+        path.as_os_str().to_str().map(Utf8Path::new)
+    }
+
+    /// Converts a `Utf8Path` to a [`Path`].
+    ///
+    /// This is equivalent to the `AsRef<&Path> for &Utf8Path` impl, but may aid in type inference.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    /// use std::path::Path;
+    ///
+    /// let utf8_path = Utf8Path::new("foo.txt");
+    /// let std_path: &Path = utf8_path.as_std_path();
+    /// assert_eq!(std_path.to_str(), Some("foo.txt"));
+    ///
+    /// // Convert back to a Utf8Path.
+    /// let new_utf8_path = Utf8Path::from_path(std_path).unwrap();
+    /// assert_eq!(new_utf8_path, "foo.txt");
+    /// ```
+    pub fn as_std_path(&self) -> &Path {
+        self.as_ref()
+    }
+
+    /// Yields the underlying [`str`] slice.
+    ///
+    /// Unlike [`Path::to_str`], this always returns a slice because the contents of a `Utf8Path`
+    /// are guaranteed to be valid UTF-8.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// let s = Utf8Path::new("foo.txt").as_str();
+    /// assert_eq!(s, "foo.txt");
+    /// ```
+    ///
+    /// [`str`]: str
+    #[must_use]
+    pub fn as_str(&self) -> &str {
+        // SAFETY: every Utf8Path constructor ensures that self is valid UTF-8
+        unsafe { assume_utf8(self.as_os_str()) }
+    }
+
+    /// Yields the underlying [`OsStr`] slice.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// let os_str = Utf8Path::new("foo.txt").as_os_str();
+    /// assert_eq!(os_str, std::ffi::OsStr::new("foo.txt"));
+    /// ```
+    #[must_use]
+    pub fn as_os_str(&self) -> &OsStr {
+        self.0.as_os_str()
+    }
+
+    /// Converts a `Utf8Path` to an owned [`Utf8PathBuf`].
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::{Utf8Path, Utf8PathBuf};
+    ///
+    /// let path_buf = Utf8Path::new("foo.txt").to_path_buf();
+    /// assert_eq!(path_buf, Utf8PathBuf::from("foo.txt"));
+    /// ```
+    #[must_use = "this returns the result of the operation, \
+                  without modifying the original"]
+    pub fn to_path_buf(&self) -> Utf8PathBuf {
+        Utf8PathBuf(self.0.to_path_buf())
+    }
+
+    /// Returns `true` if the `Utf8Path` is absolute, i.e., if it is independent of
+    /// the current directory.
+    ///
+    /// * On Unix, a path is absolute if it starts with the root, so
+    /// `is_absolute` and [`has_root`] are equivalent.
+    ///
+    /// * On Windows, a path is absolute if it has a prefix and starts with the
+    /// root: `c:\windows` is absolute, while `c:temp` and `\temp` are not.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// assert!(!Utf8Path::new("foo.txt").is_absolute());
+    /// ```
+    ///
+    /// [`has_root`]: Utf8Path::has_root
+    #[must_use]
+    pub fn is_absolute(&self) -> bool {
+        self.0.is_absolute()
+    }
+
+    /// Returns `true` if the `Utf8Path` is relative, i.e., not absolute.
+    ///
+    /// See [`is_absolute`]'s documentation for more details.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// assert!(Utf8Path::new("foo.txt").is_relative());
+    /// ```
+    ///
+    /// [`is_absolute`]: Utf8Path::is_absolute
+    #[must_use]
+    pub fn is_relative(&self) -> bool {
+        self.0.is_relative()
+    }
+
+    /// Returns `true` if the `Utf8Path` has a root.
+    ///
+    /// * On Unix, a path has a root if it begins with `/`.
+    ///
+    /// * On Windows, a path has a root if it:
+    ///     * has no prefix and begins with a separator, e.g., `\windows`
+    ///     * has a prefix followed by a separator, e.g., `c:\windows` but not `c:windows`
+    ///     * has any non-disk prefix, e.g., `\\server\share`
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// assert!(Utf8Path::new("/etc/passwd").has_root());
+    /// ```
+    #[must_use]
+    pub fn has_root(&self) -> bool {
+        self.0.has_root()
+    }
+
+    /// Returns the `Path` without its final component, if there is one.
+    ///
+    /// Returns [`None`] if the path terminates in a root or prefix.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// let path = Utf8Path::new("/foo/bar");
+    /// let parent = path.parent().unwrap();
+    /// assert_eq!(parent, Utf8Path::new("/foo"));
+    ///
+    /// let grand_parent = parent.parent().unwrap();
+    /// assert_eq!(grand_parent, Utf8Path::new("/"));
+    /// assert_eq!(grand_parent.parent(), None);
+    /// ```
+    #[must_use]
+    pub fn parent(&self) -> Option<&Utf8Path> {
+        self.0.parent().map(|path| {
+            // SAFETY: self is valid UTF-8, so parent is valid UTF-8 as well
+            unsafe { Utf8Path::assume_utf8(path) }
+        })
+    }
+
+    /// Produces an iterator over `Utf8Path` and its ancestors.
+    ///
+    /// The iterator will yield the `Utf8Path` that is returned if the [`parent`] method is used zero
+    /// or more times. That means, the iterator will yield `&self`, `&self.parent().unwrap()`,
+    /// `&self.parent().unwrap().parent().unwrap()` and so on. If the [`parent`] method returns
+    /// [`None`], the iterator will do likewise. The iterator will always yield at least one value,
+    /// namely `&self`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// let mut ancestors = Utf8Path::new("/foo/bar").ancestors();
+    /// assert_eq!(ancestors.next(), Some(Utf8Path::new("/foo/bar")));
+    /// assert_eq!(ancestors.next(), Some(Utf8Path::new("/foo")));
+    /// assert_eq!(ancestors.next(), Some(Utf8Path::new("/")));
+    /// assert_eq!(ancestors.next(), None);
+    ///
+    /// let mut ancestors = Utf8Path::new("../foo/bar").ancestors();
+    /// assert_eq!(ancestors.next(), Some(Utf8Path::new("../foo/bar")));
+    /// assert_eq!(ancestors.next(), Some(Utf8Path::new("../foo")));
+    /// assert_eq!(ancestors.next(), Some(Utf8Path::new("..")));
+    /// assert_eq!(ancestors.next(), Some(Utf8Path::new("")));
+    /// assert_eq!(ancestors.next(), None);
+    /// ```
+    ///
+    /// [`parent`]: Utf8Path::parent
+    pub fn ancestors(&self) -> Utf8Ancestors<'_> {
+        Utf8Ancestors(self.0.ancestors())
+    }
+
+    /// Returns the final component of the `Utf8Path`, if there is one.
+    ///
+    /// If the path is a normal file, this is the file name. If it's the path of a directory, this
+    /// is the directory name.
+    ///
+    /// Returns [`None`] if the path terminates in `..`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// assert_eq!(Some("bin"), Utf8Path::new("/usr/bin/").file_name());
+    /// assert_eq!(Some("foo.txt"), Utf8Path::new("tmp/foo.txt").file_name());
+    /// assert_eq!(Some("foo.txt"), Utf8Path::new("foo.txt/.").file_name());
+    /// assert_eq!(Some("foo.txt"), Utf8Path::new("foo.txt/.//").file_name());
+    /// assert_eq!(None, Utf8Path::new("foo.txt/..").file_name());
+    /// assert_eq!(None, Utf8Path::new("/").file_name());
+    /// ```
+    #[must_use]
+    pub fn file_name(&self) -> Option<&str> {
+        self.0.file_name().map(|s| {
+            // SAFETY: self is valid UTF-8, so file_name is valid UTF-8 as well
+            unsafe { assume_utf8(s) }
+        })
+    }
+
+    /// Returns a path that, when joined onto `base`, yields `self`.
+    ///
+    /// # Errors
+    ///
+    /// If `base` is not a prefix of `self` (i.e., [`starts_with`]
+    /// returns `false`), returns [`Err`].
+    ///
+    /// [`starts_with`]: Utf8Path::starts_with
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::{Utf8Path, Utf8PathBuf};
+    ///
+    /// let path = Utf8Path::new("/test/haha/foo.txt");
+    ///
+    /// assert_eq!(path.strip_prefix("/"), Ok(Utf8Path::new("test/haha/foo.txt")));
+    /// assert_eq!(path.strip_prefix("/test"), Ok(Utf8Path::new("haha/foo.txt")));
+    /// assert_eq!(path.strip_prefix("/test/"), Ok(Utf8Path::new("haha/foo.txt")));
+    /// assert_eq!(path.strip_prefix("/test/haha/foo.txt"), Ok(Utf8Path::new("")));
+    /// assert_eq!(path.strip_prefix("/test/haha/foo.txt/"), Ok(Utf8Path::new("")));
+    ///
+    /// assert!(path.strip_prefix("test").is_err());
+    /// assert!(path.strip_prefix("/haha").is_err());
+    ///
+    /// let prefix = Utf8PathBuf::from("/test/");
+    /// assert_eq!(path.strip_prefix(prefix), Ok(Utf8Path::new("haha/foo.txt")));
+    /// ```
+    pub fn strip_prefix(&self, base: impl AsRef<Path>) -> Result<&Utf8Path, StripPrefixError> {
+        self.0.strip_prefix(base).map(|path| {
+            // SAFETY: self is valid UTF-8, and strip_prefix returns a part of self (or an empty
+            // string), so it is valid UTF-8 as well.
+            unsafe { Utf8Path::assume_utf8(path) }
+        })
+    }
+
+    /// Determines whether `base` is a prefix of `self`.
+    ///
+    /// Only considers whole path components to match.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// let path = Utf8Path::new("/etc/passwd");
+    ///
+    /// assert!(path.starts_with("/etc"));
+    /// assert!(path.starts_with("/etc/"));
+    /// assert!(path.starts_with("/etc/passwd"));
+    /// assert!(path.starts_with("/etc/passwd/")); // extra slash is okay
+    /// assert!(path.starts_with("/etc/passwd///")); // multiple extra slashes are okay
+    ///
+    /// assert!(!path.starts_with("/e"));
+    /// assert!(!path.starts_with("/etc/passwd.txt"));
+    ///
+    /// assert!(!Utf8Path::new("/etc/foo.rs").starts_with("/etc/foo"));
+    /// ```
+    #[must_use]
+    pub fn starts_with(&self, base: impl AsRef<Path>) -> bool {
+        self.0.starts_with(base)
+    }
+
+    /// Determines whether `child` is a suffix of `self`.
+    ///
+    /// Only considers whole path components to match.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// let path = Utf8Path::new("/etc/resolv.conf");
+    ///
+    /// assert!(path.ends_with("resolv.conf"));
+    /// assert!(path.ends_with("etc/resolv.conf"));
+    /// assert!(path.ends_with("/etc/resolv.conf"));
+    ///
+    /// assert!(!path.ends_with("/resolv.conf"));
+    /// assert!(!path.ends_with("conf")); // use .extension() instead
+    /// ```
+    #[must_use]
+    pub fn ends_with(&self, base: impl AsRef<Path>) -> bool {
+        self.0.ends_with(base)
+    }
+
+    /// Extracts the stem (non-extension) portion of [`self.file_name`].
+    ///
+    /// [`self.file_name`]: Utf8Path::file_name
+    ///
+    /// The stem is:
+    ///
+    /// * [`None`], if there is no file name;
+    /// * The entire file name if there is no embedded `.`;
+    /// * The entire file name if the file name begins with `.` and has no other `.`s within;
+    /// * Otherwise, the portion of the file name before the final `.`
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// assert_eq!("foo", Utf8Path::new("foo.rs").file_stem().unwrap());
+    /// assert_eq!("foo.tar", Utf8Path::new("foo.tar.gz").file_stem().unwrap());
+    /// ```
+    #[must_use]
+    pub fn file_stem(&self) -> Option<&str> {
+        self.0.file_stem().map(|s| {
+            // SAFETY: self is valid UTF-8, so file_stem is valid UTF-8 as well
+            unsafe { assume_utf8(s) }
+        })
+    }
+
+    /// Extracts the extension of [`self.file_name`], if possible.
+    ///
+    /// The extension is:
+    ///
+    /// * [`None`], if there is no file name;
+    /// * [`None`], if there is no embedded `.`;
+    /// * [`None`], if the file name begins with `.` and has no other `.`s within;
+    /// * Otherwise, the portion of the file name after the final `.`
+    ///
+    /// [`self.file_name`]: Utf8Path::file_name
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// assert_eq!("rs", Utf8Path::new("foo.rs").extension().unwrap());
+    /// assert_eq!("gz", Utf8Path::new("foo.tar.gz").extension().unwrap());
+    /// ```
+    #[must_use]
+    pub fn extension(&self) -> Option<&str> {
+        self.0.extension().map(|s| {
+            // SAFETY: self is valid UTF-8, so extension is valid UTF-8 as well
+            unsafe { assume_utf8(s) }
+        })
+    }
+
+    /// Creates an owned [`Utf8PathBuf`] with `path` adjoined to `self`.
+    ///
+    /// See [`Utf8PathBuf::push`] for more details on what it means to adjoin a path.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::{Utf8Path, Utf8PathBuf};
+    ///
+    /// assert_eq!(Utf8Path::new("/etc").join("passwd"), Utf8PathBuf::from("/etc/passwd"));
+    /// ```
+    #[must_use]
+    pub fn join(&self, path: impl AsRef<Utf8Path>) -> Utf8PathBuf {
+        Utf8PathBuf(self.0.join(&path.as_ref().0))
+    }
+
+    /// Creates an owned [`PathBuf`] with `path` adjoined to `self`.
+    ///
+    /// See [`PathBuf::push`] for more details on what it means to adjoin a path.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    /// use std::path::PathBuf;
+    ///
+    /// assert_eq!(Utf8Path::new("/etc").join_os("passwd"), PathBuf::from("/etc/passwd"));
+    /// ```
+    #[must_use]
+    pub fn join_os(&self, path: impl AsRef<Path>) -> PathBuf {
+        self.0.join(path)
+    }
+
+    /// Creates an owned [`Utf8PathBuf`] like `self` but with the given file name.
+    ///
+    /// See [`Utf8PathBuf::set_file_name`] for more details.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::{Utf8Path, Utf8PathBuf};
+    ///
+    /// let path = Utf8Path::new("/tmp/foo.txt");
+    /// assert_eq!(path.with_file_name("bar.txt"), Utf8PathBuf::from("/tmp/bar.txt"));
+    ///
+    /// let path = Utf8Path::new("/tmp");
+    /// assert_eq!(path.with_file_name("var"), Utf8PathBuf::from("/var"));
+    /// ```
+    #[must_use]
+    pub fn with_file_name(&self, file_name: impl AsRef<str>) -> Utf8PathBuf {
+        Utf8PathBuf(self.0.with_file_name(file_name.as_ref()))
+    }
+
+    /// Creates an owned [`Utf8PathBuf`] like `self` but with the given extension.
+    ///
+    /// See [`Utf8PathBuf::set_extension`] for more details.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::{Utf8Path, Utf8PathBuf};
+    ///
+    /// let path = Utf8Path::new("foo.rs");
+    /// assert_eq!(path.with_extension("txt"), Utf8PathBuf::from("foo.txt"));
+    ///
+    /// let path = Utf8Path::new("foo.tar.gz");
+    /// assert_eq!(path.with_extension(""), Utf8PathBuf::from("foo.tar"));
+    /// assert_eq!(path.with_extension("xz"), Utf8PathBuf::from("foo.tar.xz"));
+    /// assert_eq!(path.with_extension("").with_extension("txt"), Utf8PathBuf::from("foo.txt"));
+    /// ```
+    pub fn with_extension(&self, extension: impl AsRef<str>) -> Utf8PathBuf {
+        Utf8PathBuf(self.0.with_extension(extension.as_ref()))
+    }
+
+    /// Produces an iterator over the [`Utf8Component`]s of the path.
+    ///
+    /// When parsing the path, there is a small amount of normalization:
+    ///
+    /// * Repeated separators are ignored, so `a/b` and `a//b` both have
+    ///   `a` and `b` as components.
+    ///
+    /// * Occurrences of `.` are normalized away, except if they are at the
+    ///   beginning of the path. For example, `a/./b`, `a/b/`, `a/b/.` and
+    ///   `a/b` all have `a` and `b` as components, but `./a/b` starts with
+    ///   an additional [`CurDir`] component.
+    ///
+    /// * A trailing slash is normalized away, `/a/b` and `/a/b/` are equivalent.
+    ///
+    /// Note that no other normalization takes place; in particular, `a/c`
+    /// and `a/b/../c` are distinct, to account for the possibility that `b`
+    /// is a symbolic link (so its parent isn't `a`).
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::{Utf8Component, Utf8Path};
+    ///
+    /// let mut components = Utf8Path::new("/tmp/foo.txt").components();
+    ///
+    /// assert_eq!(components.next(), Some(Utf8Component::RootDir));
+    /// assert_eq!(components.next(), Some(Utf8Component::Normal("tmp")));
+    /// assert_eq!(components.next(), Some(Utf8Component::Normal("foo.txt")));
+    /// assert_eq!(components.next(), None)
+    /// ```
+    ///
+    /// [`CurDir`]: Utf8Component::CurDir
+    pub fn components(&self) -> Utf8Components {
+        Utf8Components(self.0.components())
+    }
+
+    /// Produces an iterator over the path's components viewed as [`str`]
+    /// slices.
+    ///
+    /// For more information about the particulars of how the path is separated
+    /// into components, see [`components`].
+    ///
+    /// [`components`]: Utf8Path::components
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// let mut it = Utf8Path::new("/tmp/foo.txt").iter();
+    /// assert_eq!(it.next(), Some(std::path::MAIN_SEPARATOR.to_string().as_str()));
+    /// assert_eq!(it.next(), Some("tmp"));
+    /// assert_eq!(it.next(), Some("foo.txt"));
+    /// assert_eq!(it.next(), None)
+    /// ```
+    pub fn iter(&self) -> Iter<'_> {
+        Iter {
+            inner: self.components(),
+        }
+    }
+
+    /// Queries the file system to get information about a file, directory, etc.
+    ///
+    /// This function will traverse symbolic links to query information about the
+    /// destination file.
+    ///
+    /// This is an alias to [`fs::metadata`].
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use camino::Utf8Path;
+    ///
+    /// let path = Utf8Path::new("/Minas/tirith");
+    /// let metadata = path.metadata().expect("metadata call failed");
+    /// println!("{:?}", metadata.file_type());
+    /// ```
+    pub fn metadata(&self) -> io::Result<fs::Metadata> {
+        self.0.metadata()
+    }
+
+    /// Queries the metadata about a file without following symlinks.
+    ///
+    /// This is an alias to [`fs::symlink_metadata`].
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use camino::Utf8Path;
+    ///
+    /// let path = Utf8Path::new("/Minas/tirith");
+    /// let metadata = path.symlink_metadata().expect("symlink_metadata call failed");
+    /// println!("{:?}", metadata.file_type());
+    /// ```
+    pub fn symlink_metadata(&self) -> io::Result<fs::Metadata> {
+        self.0.symlink_metadata()
+    }
+
+    /// Returns the canonical, absolute form of the path with all intermediate
+    /// components normalized and symbolic links resolved.
+    ///
+    /// This returns a [`PathBuf`] because even if a symlink is valid Unicode, its target may not
+    /// be. For a version that returns a [`Utf8PathBuf`], see
+    /// [`canonicalize_utf8`](Self::canonicalize_utf8).
+    ///
+    /// This is an alias to [`fs::canonicalize`].
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use camino::Utf8Path;
+    /// use std::path::PathBuf;
+    ///
+    /// let path = Utf8Path::new("/foo/test/../test/bar.rs");
+    /// assert_eq!(path.canonicalize().unwrap(), PathBuf::from("/foo/test/bar.rs"));
+    /// ```
+    pub fn canonicalize(&self) -> io::Result<PathBuf> {
+        self.0.canonicalize()
+    }
+
+    /// Returns the canonical, absolute form of the path with all intermediate
+    /// components normalized and symbolic links resolved.
+    ///
+    /// This method attempts to convert the resulting [`PathBuf`] into a [`Utf8PathBuf`]. For a
+    /// version that does not attempt to do this conversion, see
+    /// [`canonicalize`](Self::canonicalize).
+    ///
+    /// # Errors
+    ///
+    /// The I/O operation may return an error: see the [`fs::canonicalize`]
+    /// documentation for more.
+    ///
+    /// If the resulting path is not UTF-8, an [`io::Error`] is returned with the
+    /// [`ErrorKind`](io::ErrorKind) set to `InvalidData` and the payload set to a
+    /// [`FromPathBufError`].
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use camino::{Utf8Path, Utf8PathBuf};
+    ///
+    /// let path = Utf8Path::new("/foo/test/../test/bar.rs");
+    /// assert_eq!(path.canonicalize_utf8().unwrap(), Utf8PathBuf::from("/foo/test/bar.rs"));
+    /// ```
+    pub fn canonicalize_utf8(&self) -> io::Result<Utf8PathBuf> {
+        self.canonicalize()
+            .and_then(|path| path.try_into().map_err(FromPathBufError::into_io_error))
+    }
+
+    /// Reads a symbolic link, returning the file that the link points to.
+    ///
+    /// This returns a [`PathBuf`] because even if a symlink is valid Unicode, its target may not
+    /// be. For a version that returns a [`Utf8PathBuf`], see
+    /// [`read_link_utf8`](Self::read_link_utf8).
+    ///
+    /// This is an alias to [`fs::read_link`].
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use camino::Utf8Path;
+    ///
+    /// let path = Utf8Path::new("/laputa/sky_castle.rs");
+    /// let path_link = path.read_link().expect("read_link call failed");
+    /// ```
+    pub fn read_link(&self) -> io::Result<PathBuf> {
+        self.0.read_link()
+    }
+
+    /// Reads a symbolic link, returning the file that the link points to.
+    ///
+    /// This method attempts to convert the resulting [`PathBuf`] into a [`Utf8PathBuf`]. For a
+    /// version that does not attempt to do this conversion, see [`read_link`](Self::read_link).
+    ///
+    /// # Errors
+    ///
+    /// The I/O operation may return an error: see the [`fs::read_link`]
+    /// documentation for more.
+    ///
+    /// If the resulting path is not UTF-8, an [`io::Error`] is returned with the
+    /// [`ErrorKind`](io::ErrorKind) set to `InvalidData` and the payload set to a
+    /// [`FromPathBufError`].
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use camino::Utf8Path;
+    ///
+    /// let path = Utf8Path::new("/laputa/sky_castle.rs");
+    /// let path_link = path.read_link_utf8().expect("read_link call failed");
+    /// ```
+    pub fn read_link_utf8(&self) -> io::Result<Utf8PathBuf> {
+        self.read_link()
+            .and_then(|path| path.try_into().map_err(FromPathBufError::into_io_error))
+    }
+
+    /// Returns an iterator over the entries within a directory.
+    ///
+    /// The iterator will yield instances of [`io::Result`]`<`[`fs::DirEntry`]`>`. New
+    /// errors may be encountered after an iterator is initially constructed.
+    ///
+    /// This is an alias to [`fs::read_dir`].
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use camino::Utf8Path;
+    ///
+    /// let path = Utf8Path::new("/laputa");
+    /// for entry in path.read_dir().expect("read_dir call failed") {
+    ///     if let Ok(entry) = entry {
+    ///         println!("{:?}", entry.path());
+    ///     }
+    /// }
+    /// ```
+    pub fn read_dir(&self) -> io::Result<fs::ReadDir> {
+        self.0.read_dir()
+    }
+
+    /// Returns an iterator over the entries within a directory.
+    ///
+    /// The iterator will yield instances of [`io::Result`]`<`[`Utf8DirEntry`]`>`. New
+    /// errors may be encountered after an iterator is initially constructed.
+    ///
+    /// # Errors
+    ///
+    /// The I/O operation may return an error: see the [`fs::read_dir`]
+    /// documentation for more.
+    ///
+    /// If a directory entry is not UTF-8, an [`io::Error`] is returned with the
+    /// [`ErrorKind`](io::ErrorKind) set to `InvalidData` and the payload set to a
+    /// [`FromPathBufError`].
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use camino::Utf8Path;
+    ///
+    /// let path = Utf8Path::new("/laputa");
+    /// for entry in path.read_dir_utf8().expect("read_dir call failed") {
+    ///     if let Ok(entry) = entry {
+    ///         println!("{}", entry.path());
+    ///     }
+    /// }
+    /// ```
+    #[inline]
+    pub fn read_dir_utf8(&self) -> io::Result<ReadDirUtf8> {
+        self.0.read_dir().map(|inner| ReadDirUtf8 { inner })
+    }
+
+    /// Returns `true` if the path points at an existing entity.
+    ///
+    /// Warning: this method may be error-prone, consider using [`try_exists()`] instead!
+    /// It also has a risk of introducing time-of-check to time-of-use (TOCTOU) bugs.
+    ///
+    /// This function will traverse symbolic links to query information about the
+    /// destination file. In case of broken symbolic links this will return `false`.
+    ///
+    /// If you cannot access the directory containing the file, e.g., because of a
+    /// permission error, this will return `false`.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use camino::Utf8Path;
+    /// assert!(!Utf8Path::new("does_not_exist.txt").exists());
+    /// ```
+    ///
+    /// # See Also
+    ///
+    /// This is a convenience function that coerces errors to false. If you want to
+    /// check errors, call [`fs::metadata`].
+    ///
+    /// [`try_exists()`]: Self::try_exists
+    #[must_use]
+    pub fn exists(&self) -> bool {
+        self.0.exists()
+    }
+
+    /// Returns `Ok(true)` if the path points at an existing entity.
+    ///
+    /// This function will traverse symbolic links to query information about the
+    /// destination file. In case of broken symbolic links this will return `Ok(false)`.
+    ///
+    /// As opposed to the [`exists()`] method, this one doesn't silently ignore errors
+    /// unrelated to the path not existing. (E.g. it will return `Err(_)` in case of permission
+    /// denied on some of the parent directories.)
+    ///
+    /// Note that while this avoids some pitfalls of the `exists()` method, it still can not
+    /// prevent time-of-check to time-of-use (TOCTOU) bugs. You should only use it in scenarios
+    /// where those bugs are not an issue.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use camino::Utf8Path;
+    /// assert!(!Utf8Path::new("does_not_exist.txt").try_exists().expect("Can't check existence of file does_not_exist.txt"));
+    /// assert!(Utf8Path::new("/root/secret_file.txt").try_exists().is_err());
+    /// ```
+    ///
+    /// [`exists()`]: Self::exists
+    #[inline]
+    pub fn try_exists(&self) -> io::Result<bool> {
+        // Note: this block is written this way rather than with a pattern guard to appease Rust
+        // 1.34.
+        match fs::metadata(self) {
+            Ok(_) => Ok(true),
+            Err(error) => {
+                if error.kind() == io::ErrorKind::NotFound {
+                    Ok(false)
+                } else {
+                    Err(error)
+                }
+            }
+        }
+    }
+
+    /// Returns `true` if the path exists on disk and is pointing at a regular file.
+    ///
+    /// This function will traverse symbolic links to query information about the
+    /// destination file. In case of broken symbolic links this will return `false`.
+    ///
+    /// If you cannot access the directory containing the file, e.g., because of a
+    /// permission error, this will return `false`.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use camino::Utf8Path;
+    /// assert_eq!(Utf8Path::new("./is_a_directory/").is_file(), false);
+    /// assert_eq!(Utf8Path::new("a_file.txt").is_file(), true);
+    /// ```
+    ///
+    /// # See Also
+    ///
+    /// This is a convenience function that coerces errors to false. If you want to
+    /// check errors, call [`fs::metadata`] and handle its [`Result`]. Then call
+    /// [`fs::Metadata::is_file`] if it was [`Ok`].
+    ///
+    /// When the goal is simply to read from (or write to) the source, the most
+    /// reliable way to test the source can be read (or written to) is to open
+    /// it. Only using `is_file` can break workflows like `diff <( prog_a )` on
+    /// a Unix-like system for example. See [`fs::File::open`] or
+    /// [`fs::OpenOptions::open`] for more information.
+    #[must_use]
+    pub fn is_file(&self) -> bool {
+        self.0.is_file()
+    }
+
+    /// Returns `true` if the path exists on disk and is pointing at a directory.
+    ///
+    /// This function will traverse symbolic links to query information about the
+    /// destination file. In case of broken symbolic links this will return `false`.
+    ///
+    /// If you cannot access the directory containing the file, e.g., because of a
+    /// permission error, this will return `false`.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use camino::Utf8Path;
+    /// assert_eq!(Utf8Path::new("./is_a_directory/").is_dir(), true);
+    /// assert_eq!(Utf8Path::new("a_file.txt").is_dir(), false);
+    /// ```
+    ///
+    /// # See Also
+    ///
+    /// This is a convenience function that coerces errors to false. If you want to
+    /// check errors, call [`fs::metadata`] and handle its [`Result`]. Then call
+    /// [`fs::Metadata::is_dir`] if it was [`Ok`].
+    #[must_use]
+    pub fn is_dir(&self) -> bool {
+        self.0.is_dir()
+    }
+
+    /// Returns `true` if the path exists on disk and is pointing at a symbolic link.
+    ///
+    /// This function will not traverse symbolic links.
+    /// In case of a broken symbolic link this will also return true.
+    ///
+    /// If you cannot access the directory containing the file, e.g., because of a
+    /// permission error, this will return false.
+    ///
+    /// # Examples
+    ///
+    #[cfg_attr(unix, doc = "```no_run")]
+    #[cfg_attr(not(unix), doc = "```ignore")]
+    /// use camino::Utf8Path;
+    /// use std::os::unix::fs::symlink;
+    ///
+    /// let link_path = Utf8Path::new("link");
+    /// symlink("/origin_does_not_exist/", link_path).unwrap();
+    /// assert_eq!(link_path.is_symlink(), true);
+    /// assert_eq!(link_path.exists(), false);
+    /// ```
+    ///
+    /// # See Also
+    ///
+    /// This is a convenience function that coerces errors to false. If you want to
+    /// check errors, call [`Utf8Path::symlink_metadata`] and handle its [`Result`]. Then call
+    /// [`fs::Metadata::is_symlink`] if it was [`Ok`].
+    #[must_use]
+    pub fn is_symlink(&self) -> bool {
+        self.symlink_metadata()
+            .map(|m| m.file_type().is_symlink())
+            .unwrap_or(false)
+    }
+
+    /// Converts a `Box<Utf8Path>` into a [`Utf8PathBuf`] without copying or allocating.
+    #[must_use = "`self` will be dropped if the result is not used"]
+    pub fn into_path_buf(self: Box<Utf8Path>) -> Utf8PathBuf {
+        let ptr = Box::into_raw(self) as *mut Path;
+        // SAFETY:
+        // * self is valid UTF-8
+        // * ptr was constructed by consuming self so it represents an owned path.
+        // * Utf8Path is marked as #[repr(transparent)] so the conversion from a *mut Utf8Path to a
+        //   *mut Path is valid.
+        let boxed_path = unsafe { Box::from_raw(ptr) };
+        Utf8PathBuf(boxed_path.into_path_buf())
+    }
+
+    // invariant: Path must be guaranteed to be utf-8 data
+    unsafe fn assume_utf8(path: &Path) -> &Utf8Path {
+        // SAFETY: Utf8Path is marked as #[repr(transparent)] so the conversion from a
+        // *const Path to a *const Utf8Path is valid.
+        &*(path as *const Path as *const Utf8Path)
+    }
+
+    #[cfg(path_buf_deref_mut)]
+    unsafe fn assume_utf8_mut(path: &mut Path) -> &mut Utf8Path {
+        &mut *(path as *mut Path as *mut Utf8Path)
+    }
+}
+
+impl Clone for Box<Utf8Path> {
+    fn clone(&self) -> Self {
+        let boxed: Box<Path> = self.0.into();
+        let ptr = Box::into_raw(boxed) as *mut Utf8Path;
+        // SAFETY:
+        // * self is valid UTF-8
+        // * ptr was created by consuming a Box<Path> so it represents an rced pointer
+        // * Utf8Path is marked as #[repr(transparent)] so the conversion from *mut Path to
+        //   *mut Utf8Path is valid
+        unsafe { Box::from_raw(ptr) }
+    }
+}
+
+impl fmt::Display for Utf8Path {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        fmt::Display::fmt(self.as_str(), f)
+    }
+}
+
+impl fmt::Debug for Utf8Path {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        fmt::Debug::fmt(self.as_str(), f)
+    }
+}
+
+/// An iterator over [`Utf8Path`] and its ancestors.
+///
+/// This `struct` is created by the [`ancestors`] method on [`Utf8Path`].
+/// See its documentation for more.
+///
+/// # Examples
+///
+/// ```
+/// use camino::Utf8Path;
+///
+/// let path = Utf8Path::new("/foo/bar");
+///
+/// for ancestor in path.ancestors() {
+///     println!("{}", ancestor);
+/// }
+/// ```
+///
+/// [`ancestors`]: Utf8Path::ancestors
+#[derive(Copy, Clone)]
+#[must_use = "iterators are lazy and do nothing unless consumed"]
+#[repr(transparent)]
+pub struct Utf8Ancestors<'a>(Ancestors<'a>);
+
+impl<'a> fmt::Debug for Utf8Ancestors<'a> {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        fmt::Debug::fmt(&self.0, f)
+    }
+}
+
+impl<'a> Iterator for Utf8Ancestors<'a> {
+    type Item = &'a Utf8Path;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        self.0.next().map(|path| {
+            // SAFETY: Utf8Ancestors was constructed from a Utf8Path, so it is guaranteed to
+            // be valid UTF-8
+            unsafe { Utf8Path::assume_utf8(path) }
+        })
+    }
+}
+
+impl<'a> FusedIterator for Utf8Ancestors<'a> {}
+
+/// An iterator over the [`Utf8Component`]s of a [`Utf8Path`].
+///
+/// This `struct` is created by the [`components`] method on [`Utf8Path`].
+/// See its documentation for more.
+///
+/// # Examples
+///
+/// ```
+/// use camino::Utf8Path;
+///
+/// let path = Utf8Path::new("/tmp/foo/bar.txt");
+///
+/// for component in path.components() {
+///     println!("{:?}", component);
+/// }
+/// ```
+///
+/// [`components`]: Utf8Path::components
+#[derive(Clone, Eq, Ord, PartialEq, PartialOrd)]
+#[must_use = "iterators are lazy and do nothing unless consumed"]
+pub struct Utf8Components<'a>(Components<'a>);
+
+impl<'a> Utf8Components<'a> {
+    /// Extracts a slice corresponding to the portion of the path remaining for iteration.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// let mut components = Utf8Path::new("/tmp/foo/bar.txt").components();
+    /// components.next();
+    /// components.next();
+    ///
+    /// assert_eq!(Utf8Path::new("foo/bar.txt"), components.as_path());
+    /// ```
+    #[must_use]
+    pub fn as_path(&self) -> &'a Utf8Path {
+        // SAFETY: Utf8Components was constructed from a Utf8Path, so it is guaranteed to be valid
+        // UTF-8
+        unsafe { Utf8Path::assume_utf8(self.0.as_path()) }
+    }
+}
+
+impl<'a> Iterator for Utf8Components<'a> {
+    type Item = Utf8Component<'a>;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        self.0.next().map(|component| {
+            // SAFETY: Utf8Component was constructed from a Utf8Path, so it is guaranteed to be
+            // valid UTF-8
+            unsafe { Utf8Component::new(component) }
+        })
+    }
+}
+
+impl<'a> FusedIterator for Utf8Components<'a> {}
+
+impl<'a> DoubleEndedIterator for Utf8Components<'a> {
+    fn next_back(&mut self) -> Option<Self::Item> {
+        self.0.next_back().map(|component| {
+            // SAFETY: Utf8Component was constructed from a Utf8Path, so it is guaranteed to be
+            // valid UTF-8
+            unsafe { Utf8Component::new(component) }
+        })
+    }
+}
+
+impl<'a> fmt::Debug for Utf8Components<'a> {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        fmt::Debug::fmt(&self.0, f)
+    }
+}
+
+impl AsRef<Utf8Path> for Utf8Components<'_> {
+    fn as_ref(&self) -> &Utf8Path {
+        self.as_path()
+    }
+}
+
+impl AsRef<Path> for Utf8Components<'_> {
+    fn as_ref(&self) -> &Path {
+        self.as_path().as_ref()
+    }
+}
+
+impl AsRef<str> for Utf8Components<'_> {
+    fn as_ref(&self) -> &str {
+        self.as_path().as_ref()
+    }
+}
+
+impl AsRef<OsStr> for Utf8Components<'_> {
+    fn as_ref(&self) -> &OsStr {
+        self.as_path().as_os_str()
+    }
+}
+
+/// An iterator over the [`Utf8Component`]s of a [`Utf8Path`], as [`str`] slices.
+///
+/// This `struct` is created by the [`iter`] method on [`Utf8Path`].
+/// See its documentation for more.
+///
+/// [`iter`]: Utf8Path::iter
+#[derive(Clone)]
+#[must_use = "iterators are lazy and do nothing unless consumed"]
+pub struct Iter<'a> {
+    inner: Utf8Components<'a>,
+}
+
+impl fmt::Debug for Iter<'_> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        struct DebugHelper<'a>(&'a Utf8Path);
+
+        impl fmt::Debug for DebugHelper<'_> {
+            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+                f.debug_list().entries(self.0.iter()).finish()
+            }
+        }
+
+        f.debug_tuple("Iter")
+            .field(&DebugHelper(self.as_path()))
+            .finish()
+    }
+}
+
+impl<'a> Iter<'a> {
+    /// Extracts a slice corresponding to the portion of the path remaining for iteration.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// let mut iter = Utf8Path::new("/tmp/foo/bar.txt").iter();
+    /// iter.next();
+    /// iter.next();
+    ///
+    /// assert_eq!(Utf8Path::new("foo/bar.txt"), iter.as_path());
+    /// ```
+    #[must_use]
+    pub fn as_path(&self) -> &'a Utf8Path {
+        self.inner.as_path()
+    }
+}
+
+impl AsRef<Utf8Path> for Iter<'_> {
+    fn as_ref(&self) -> &Utf8Path {
+        self.as_path()
+    }
+}
+
+impl AsRef<Path> for Iter<'_> {
+    fn as_ref(&self) -> &Path {
+        self.as_path().as_ref()
+    }
+}
+
+impl AsRef<str> for Iter<'_> {
+    fn as_ref(&self) -> &str {
+        self.as_path().as_ref()
+    }
+}
+
+impl AsRef<OsStr> for Iter<'_> {
+    fn as_ref(&self) -> &OsStr {
+        self.as_path().as_os_str()
+    }
+}
+
+impl<'a> Iterator for Iter<'a> {
+    type Item = &'a str;
+
+    fn next(&mut self) -> Option<&'a str> {
+        self.inner.next().map(|component| component.as_str())
+    }
+}
+
+impl<'a> DoubleEndedIterator for Iter<'a> {
+    fn next_back(&mut self) -> Option<&'a str> {
+        self.inner.next_back().map(|component| component.as_str())
+    }
+}
+
+impl FusedIterator for Iter<'_> {}
+
+/// A single component of a path.
+///
+/// A `Utf8Component` roughly corresponds to a substring between path separators
+/// (`/` or `\`).
+///
+/// This `enum` is created by iterating over [`Utf8Components`], which in turn is
+/// created by the [`components`](Utf8Path::components) method on [`Utf8Path`].
+///
+/// # Examples
+///
+/// ```rust
+/// use camino::{Utf8Component, Utf8Path};
+///
+/// let path = Utf8Path::new("/tmp/foo/bar.txt");
+/// let components = path.components().collect::<Vec<_>>();
+/// assert_eq!(&components, &[
+///     Utf8Component::RootDir,
+///     Utf8Component::Normal("tmp"),
+///     Utf8Component::Normal("foo"),
+///     Utf8Component::Normal("bar.txt"),
+/// ]);
+/// ```
+#[derive(Copy, Clone, Eq, PartialEq, Hash, Ord, PartialOrd)]
+pub enum Utf8Component<'a> {
+    /// A Windows path prefix, e.g., `C:` or `\\server\share`.
+    ///
+    /// There is a large variety of prefix types, see [`Utf8Prefix`]'s documentation
+    /// for more.
+    ///
+    /// Does not occur on Unix.
+    Prefix(Utf8PrefixComponent<'a>),
+
+    /// The root directory component, appears after any prefix and before anything else.
+    ///
+    /// It represents a separator that designates that a path starts from root.
+    RootDir,
+
+    /// A reference to the current directory, i.e., `.`.
+    CurDir,
+
+    /// A reference to the parent directory, i.e., `..`.
+    ParentDir,
+
+    /// A normal component, e.g., `a` and `b` in `a/b`.
+    ///
+    /// This variant is the most common one, it represents references to files
+    /// or directories.
+    Normal(&'a str),
+}
+
+impl<'a> Utf8Component<'a> {
+    unsafe fn new(component: Component<'a>) -> Utf8Component<'a> {
+        match component {
+            Component::Prefix(prefix) => Utf8Component::Prefix(Utf8PrefixComponent(prefix)),
+            Component::RootDir => Utf8Component::RootDir,
+            Component::CurDir => Utf8Component::CurDir,
+            Component::ParentDir => Utf8Component::ParentDir,
+            Component::Normal(s) => Utf8Component::Normal(assume_utf8(s)),
+        }
+    }
+
+    /// Extracts the underlying [`str`] slice.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// let path = Utf8Path::new("./tmp/foo/bar.txt");
+    /// let components: Vec<_> = path.components().map(|comp| comp.as_str()).collect();
+    /// assert_eq!(&components, &[".", "tmp", "foo", "bar.txt"]);
+    /// ```
+    #[must_use]
+    pub fn as_str(&self) -> &'a str {
+        // SAFETY: Utf8Component was constructed from a Utf8Path, so it is guaranteed to be
+        // valid UTF-8
+        unsafe { assume_utf8(self.as_os_str()) }
+    }
+
+    /// Extracts the underlying [`OsStr`] slice.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// let path = Utf8Path::new("./tmp/foo/bar.txt");
+    /// let components: Vec<_> = path.components().map(|comp| comp.as_os_str()).collect();
+    /// assert_eq!(&components, &[".", "tmp", "foo", "bar.txt"]);
+    /// ```
+    #[must_use]
+    pub fn as_os_str(&self) -> &'a OsStr {
+        match *self {
+            Utf8Component::Prefix(prefix) => prefix.as_os_str(),
+            Utf8Component::RootDir => Component::RootDir.as_os_str(),
+            Utf8Component::CurDir => Component::CurDir.as_os_str(),
+            Utf8Component::ParentDir => Component::ParentDir.as_os_str(),
+            Utf8Component::Normal(s) => OsStr::new(s),
+        }
+    }
+}
+
+impl<'a> fmt::Debug for Utf8Component<'a> {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        fmt::Debug::fmt(self.as_os_str(), f)
+    }
+}
+
+impl<'a> fmt::Display for Utf8Component<'a> {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        fmt::Display::fmt(self.as_str(), f)
+    }
+}
+
+impl AsRef<Utf8Path> for Utf8Component<'_> {
+    fn as_ref(&self) -> &Utf8Path {
+        self.as_str().as_ref()
+    }
+}
+
+impl AsRef<Path> for Utf8Component<'_> {
+    fn as_ref(&self) -> &Path {
+        self.as_os_str().as_ref()
+    }
+}
+
+impl AsRef<str> for Utf8Component<'_> {
+    fn as_ref(&self) -> &str {
+        self.as_str()
+    }
+}
+
+impl AsRef<OsStr> for Utf8Component<'_> {
+    fn as_ref(&self) -> &OsStr {
+        self.as_os_str()
+    }
+}
+
+/// Windows path prefixes, e.g., `C:` or `\\server\share`.
+///
+/// Windows uses a variety of path prefix styles, including references to drive
+/// volumes (like `C:`), network shared folders (like `\\server\share`), and
+/// others. In addition, some path prefixes are "verbatim" (i.e., prefixed with
+/// `\\?\`), in which case `/` is *not* treated as a separator and essentially
+/// no normalization is performed.
+///
+/// # Examples
+///
+/// ```
+/// use camino::{Utf8Component, Utf8Path, Utf8Prefix};
+/// use camino::Utf8Prefix::*;
+///
+/// fn get_path_prefix(s: &str) -> Utf8Prefix {
+///     let path = Utf8Path::new(s);
+///     match path.components().next().unwrap() {
+///         Utf8Component::Prefix(prefix_component) => prefix_component.kind(),
+///         _ => panic!(),
+///     }
+/// }
+///
+/// # if cfg!(windows) {
+/// assert_eq!(Verbatim("pictures"), get_path_prefix(r"\\?\pictures\kittens"));
+/// assert_eq!(VerbatimUNC("server", "share"), get_path_prefix(r"\\?\UNC\server\share"));
+/// assert_eq!(VerbatimDisk(b'C'), get_path_prefix(r"\\?\c:\"));
+/// assert_eq!(DeviceNS("BrainInterface"), get_path_prefix(r"\\.\BrainInterface"));
+/// assert_eq!(UNC("server", "share"), get_path_prefix(r"\\server\share"));
+/// assert_eq!(Disk(b'C'), get_path_prefix(r"C:\Users\Rust\Pictures\Ferris"));
+/// # }
+/// ```
+#[derive(Copy, Clone, Debug, Hash, PartialOrd, Ord, PartialEq, Eq)]
+pub enum Utf8Prefix<'a> {
+    /// Verbatim prefix, e.g., `\\?\cat_pics`.
+    ///
+    /// Verbatim prefixes consist of `\\?\` immediately followed by the given
+    /// component.
+    Verbatim(&'a str),
+
+    /// Verbatim prefix using Windows' _**U**niform **N**aming **C**onvention_,
+    /// e.g., `\\?\UNC\server\share`.
+    ///
+    /// Verbatim UNC prefixes consist of `\\?\UNC\` immediately followed by the
+    /// server's hostname and a share name.
+    VerbatimUNC(&'a str, &'a str),
+
+    /// Verbatim disk prefix, e.g., `\\?\C:`.
+    ///
+    /// Verbatim disk prefixes consist of `\\?\` immediately followed by the
+    /// drive letter and `:`.
+    VerbatimDisk(u8),
+
+    /// Device namespace prefix, e.g., `\\.\COM42`.
+    ///
+    /// Device namespace prefixes consist of `\\.\` immediately followed by the
+    /// device name.
+    DeviceNS(&'a str),
+
+    /// Prefix using Windows' _**U**niform **N**aming **C**onvention_, e.g.
+    /// `\\server\share`.
+    ///
+    /// UNC prefixes consist of the server's hostname and a share name.
+    UNC(&'a str, &'a str),
+
+    /// Prefix `C:` for the given disk drive.
+    Disk(u8),
+}
+
+impl<'a> Utf8Prefix<'a> {
+    /// Determines if the prefix is verbatim, i.e., begins with `\\?\`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Prefix::*;
+    ///
+    /// assert!(Verbatim("pictures").is_verbatim());
+    /// assert!(VerbatimUNC("server", "share").is_verbatim());
+    /// assert!(VerbatimDisk(b'C').is_verbatim());
+    /// assert!(!DeviceNS("BrainInterface").is_verbatim());
+    /// assert!(!UNC("server", "share").is_verbatim());
+    /// assert!(!Disk(b'C').is_verbatim());
+    /// ```
+    #[must_use]
+    pub fn is_verbatim(&self) -> bool {
+        use Utf8Prefix::*;
+        match self {
+            Verbatim(_) | VerbatimDisk(_) | VerbatimUNC(..) => true,
+            _ => false,
+        }
+    }
+}
+
+/// A structure wrapping a Windows path prefix as well as its unparsed string
+/// representation.
+///
+/// In addition to the parsed [`Utf8Prefix`] information returned by [`kind`],
+/// `Utf8PrefixComponent` also holds the raw and unparsed [`str`] slice,
+/// returned by [`as_str`].
+///
+/// Instances of this `struct` can be obtained by matching against the
+/// [`Prefix` variant] on [`Utf8Component`].
+///
+/// Does not occur on Unix.
+///
+/// # Examples
+///
+/// ```
+/// # if cfg!(windows) {
+/// use camino::{Utf8Component, Utf8Path, Utf8Prefix};
+/// use std::ffi::OsStr;
+///
+/// let path = Utf8Path::new(r"c:\you\later\");
+/// match path.components().next().unwrap() {
+///     Utf8Component::Prefix(prefix_component) => {
+///         assert_eq!(Utf8Prefix::Disk(b'C'), prefix_component.kind());
+///         assert_eq!("c:", prefix_component.as_str());
+///     }
+///     _ => unreachable!(),
+/// }
+/// # }
+/// ```
+///
+/// [`as_str`]: Utf8PrefixComponent::as_str
+/// [`kind`]: Utf8PrefixComponent::kind
+/// [`Prefix` variant]: Utf8Component::Prefix
+#[repr(transparent)]
+#[derive(Clone, Copy, Eq, PartialEq, Hash, Ord, PartialOrd)]
+pub struct Utf8PrefixComponent<'a>(PrefixComponent<'a>);
+
+impl<'a> Utf8PrefixComponent<'a> {
+    /// Returns the parsed prefix data.
+    ///
+    /// See [`Utf8Prefix`]'s documentation for more information on the different
+    /// kinds of prefixes.
+    #[must_use]
+    pub fn kind(&self) -> Utf8Prefix<'a> {
+        // SAFETY for all the below unsafe blocks: the path self was originally constructed from was
+        // UTF-8 so any parts of it are valid UTF-8
+        match self.0.kind() {
+            Prefix::Verbatim(prefix) => Utf8Prefix::Verbatim(unsafe { assume_utf8(prefix) }),
+            Prefix::VerbatimUNC(server, share) => {
+                let server = unsafe { assume_utf8(server) };
+                let share = unsafe { assume_utf8(share) };
+                Utf8Prefix::VerbatimUNC(server, share)
+            }
+            Prefix::VerbatimDisk(drive) => Utf8Prefix::VerbatimDisk(drive),
+            Prefix::DeviceNS(prefix) => Utf8Prefix::DeviceNS(unsafe { assume_utf8(prefix) }),
+            Prefix::UNC(server, share) => {
+                let server = unsafe { assume_utf8(server) };
+                let share = unsafe { assume_utf8(share) };
+                Utf8Prefix::UNC(server, share)
+            }
+            Prefix::Disk(drive) => Utf8Prefix::Disk(drive),
+        }
+    }
+
+    /// Returns the [`str`] slice for this prefix.
+    #[must_use]
+    pub fn as_str(&self) -> &'a str {
+        // SAFETY: Utf8PrefixComponent was constructed from a Utf8Path, so it is guaranteed to be
+        // valid UTF-8
+        unsafe { assume_utf8(self.as_os_str()) }
+    }
+
+    /// Returns the raw [`OsStr`] slice for this prefix.
+    #[must_use]
+    pub fn as_os_str(&self) -> &'a OsStr {
+        self.0.as_os_str()
+    }
+}
+
+impl<'a> fmt::Debug for Utf8PrefixComponent<'a> {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        fmt::Debug::fmt(&self.0, f)
+    }
+}
+
+impl<'a> fmt::Display for Utf8PrefixComponent<'a> {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        fmt::Display::fmt(self.as_str(), f)
+    }
+}
+
+// ---
+// read_dir_utf8
+// ---
+
+/// Iterator over the entries in a directory.
+///
+/// This iterator is returned from [`Utf8Path::read_dir_utf8`] and will yield instances of
+/// <code>[io::Result]<[Utf8DirEntry]></code>. Through a [`Utf8DirEntry`] information like the entry's path
+/// and possibly other metadata can be learned.
+///
+/// The order in which this iterator returns entries is platform and filesystem
+/// dependent.
+///
+/// # Errors
+///
+/// This [`io::Result`] will be an [`Err`] if there's some sort of intermittent
+/// IO error during iteration.
+///
+/// If a directory entry is not UTF-8, an [`io::Error`] is returned with the
+/// [`ErrorKind`](io::ErrorKind) set to `InvalidData` and the payload set to a [`FromPathBufError`].
+#[derive(Debug)]
+pub struct ReadDirUtf8 {
+    inner: fs::ReadDir,
+}
+
+impl Iterator for ReadDirUtf8 {
+    type Item = io::Result<Utf8DirEntry>;
+
+    fn next(&mut self) -> Option<io::Result<Utf8DirEntry>> {
+        self.inner
+            .next()
+            .map(|entry| entry.and_then(Utf8DirEntry::new))
+    }
+}
+
+/// Entries returned by the [`ReadDirUtf8`] iterator.
+///
+/// An instance of `Utf8DirEntry` represents an entry inside of a directory on the filesystem. Each
+/// entry can be inspected via methods to learn about the full path or possibly other metadata.
+#[derive(Debug)]
+pub struct Utf8DirEntry {
+    inner: fs::DirEntry,
+    path: Utf8PathBuf,
+}
+
+impl Utf8DirEntry {
+    fn new(inner: fs::DirEntry) -> io::Result<Self> {
+        let path = inner
+            .path()
+            .try_into()
+            .map_err(|err| io::Error::new(io::ErrorKind::InvalidData, err))?;
+        Ok(Self { inner, path })
+    }
+
+    /// Returns the full path to the file that this entry represents.
+    ///
+    /// The full path is created by joining the original path to `read_dir`
+    /// with the filename of this entry.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use camino::Utf8Path;
+    ///
+    /// fn main() -> std::io::Result<()> {
+    ///     for entry in Utf8Path::new(".").read_dir_utf8()? {
+    ///         let dir = entry?;
+    ///         println!("{}", dir.path());
+    ///     }
+    ///     Ok(())
+    /// }
+    /// ```
+    ///
+    /// This prints output like:
+    ///
+    /// ```text
+    /// ./whatever.txt
+    /// ./foo.html
+    /// ./hello_world.rs
+    /// ```
+    ///
+    /// The exact text, of course, depends on what files you have in `.`.
+    #[inline]
+    pub fn path(&self) -> &Utf8Path {
+        &self.path
+    }
+
+    /// Returns the metadata for the file that this entry points at.
+    ///
+    /// This function will not traverse symlinks if this entry points at a symlink. To traverse
+    /// symlinks use [`Utf8Path::metadata`] or [`fs::File::metadata`].
+    ///
+    /// # Platform-specific behavior
+    ///
+    /// On Windows this function is cheap to call (no extra system calls
+    /// needed), but on Unix platforms this function is the equivalent of
+    /// calling `symlink_metadata` on the path.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// if let Ok(entries) = Utf8Path::new(".").read_dir_utf8() {
+    ///     for entry in entries {
+    ///         if let Ok(entry) = entry {
+    ///             // Here, `entry` is a `Utf8DirEntry`.
+    ///             if let Ok(metadata) = entry.metadata() {
+    ///                 // Now let's show our entry's permissions!
+    ///                 println!("{}: {:?}", entry.path(), metadata.permissions());
+    ///             } else {
+    ///                 println!("Couldn't get metadata for {}", entry.path());
+    ///             }
+    ///         }
+    ///     }
+    /// }
+    /// ```
+    #[inline]
+    pub fn metadata(&self) -> io::Result<Metadata> {
+        self.inner.metadata()
+    }
+
+    /// Returns the file type for the file that this entry points at.
+    ///
+    /// This function will not traverse symlinks if this entry points at a
+    /// symlink.
+    ///
+    /// # Platform-specific behavior
+    ///
+    /// On Windows and most Unix platforms this function is free (no extra
+    /// system calls needed), but some Unix platforms may require the equivalent
+    /// call to `symlink_metadata` to learn about the target file type.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// if let Ok(entries) = Utf8Path::new(".").read_dir_utf8() {
+    ///     for entry in entries {
+    ///         if let Ok(entry) = entry {
+    ///             // Here, `entry` is a `DirEntry`.
+    ///             if let Ok(file_type) = entry.file_type() {
+    ///                 // Now let's show our entry's file type!
+    ///                 println!("{}: {:?}", entry.path(), file_type);
+    ///             } else {
+    ///                 println!("Couldn't get file type for {}", entry.path());
+    ///             }
+    ///         }
+    ///     }
+    /// }
+    /// ```
+    #[inline]
+    pub fn file_type(&self) -> io::Result<fs::FileType> {
+        self.inner.file_type()
+    }
+
+    /// Returns the bare file name of this directory entry without any other
+    /// leading path component.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use camino::Utf8Path;
+    ///
+    /// if let Ok(entries) = Utf8Path::new(".").read_dir_utf8() {
+    ///     for entry in entries {
+    ///         if let Ok(entry) = entry {
+    ///             // Here, `entry` is a `DirEntry`.
+    ///             println!("{}", entry.file_name());
+    ///         }
+    ///     }
+    /// }
+    /// ```
+    pub fn file_name(&self) -> &str {
+        self.path
+            .file_name()
+            .expect("path created through DirEntry must have a filename")
+    }
+
+    /// Returns the original [`fs::DirEntry`] within this [`Utf8DirEntry`].
+    #[inline]
+    pub fn into_inner(self) -> fs::DirEntry {
+        self.inner
+    }
+
+    /// Returns the full path to the file that this entry represents.
+    ///
+    /// This is analogous to [`path`], but moves ownership of the path.
+    ///
+    /// [`path`]: struct.Utf8DirEntry.html#method.path
+    #[inline]
+    #[must_use = "`self` will be dropped if the result is not used"]
+    pub fn into_path(self) -> Utf8PathBuf {
+        self.path
+    }
+}
+
+impl From<String> for Utf8PathBuf {
+    fn from(string: String) -> Utf8PathBuf {
+        Utf8PathBuf(string.into())
+    }
+}
+
+impl FromStr for Utf8PathBuf {
+    type Err = Infallible;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Ok(Utf8PathBuf(s.into()))
+    }
+}
+
+// ---
+// From impls: borrowed -> borrowed
+// ---
+
+impl<'a> From<&'a str> for &'a Utf8Path {
+    fn from(s: &'a str) -> &'a Utf8Path {
+        Utf8Path::new(s)
+    }
+}
+
+// ---
+// From impls: borrowed -> owned
+// ---
+
+impl<T: ?Sized + AsRef<str>> From<&T> for Utf8PathBuf {
+    fn from(s: &T) -> Utf8PathBuf {
+        Utf8PathBuf::from(s.as_ref().to_owned())
+    }
+}
+
+impl<T: ?Sized + AsRef<str>> From<&T> for Box<Utf8Path> {
+    fn from(s: &T) -> Box<Utf8Path> {
+        Utf8PathBuf::from(s).into_boxed_path()
+    }
+}
+
+impl From<&'_ Utf8Path> for Arc<Utf8Path> {
+    fn from(path: &Utf8Path) -> Arc<Utf8Path> {
+        let arc: Arc<Path> = Arc::from(AsRef::<Path>::as_ref(path));
+        let ptr = Arc::into_raw(arc) as *const Utf8Path;
+        // SAFETY:
+        // * path is valid UTF-8
+        // * ptr was created by consuming an Arc<Path> so it represents an arced pointer
+        // * Utf8Path is marked as #[repr(transparent)] so the conversion from *const Path to
+        //   *const Utf8Path is valid
+        unsafe { Arc::from_raw(ptr) }
+    }
+}
+
+impl From<&'_ Utf8Path> for Rc<Utf8Path> {
+    fn from(path: &Utf8Path) -> Rc<Utf8Path> {
+        let rc: Rc<Path> = Rc::from(AsRef::<Path>::as_ref(path));
+        let ptr = Rc::into_raw(rc) as *const Utf8Path;
+        // SAFETY:
+        // * path is valid UTF-8
+        // * ptr was created by consuming an Rc<Path> so it represents an rced pointer
+        // * Utf8Path is marked as #[repr(transparent)] so the conversion from *const Path to
+        //   *const Utf8Path is valid
+        unsafe { Rc::from_raw(ptr) }
+    }
+}
+
+impl<'a> From<&'a Utf8Path> for Cow<'a, Utf8Path> {
+    fn from(path: &'a Utf8Path) -> Cow<'a, Utf8Path> {
+        Cow::Borrowed(path)
+    }
+}
+
+impl From<&'_ Utf8Path> for Box<Path> {
+    fn from(path: &Utf8Path) -> Box<Path> {
+        AsRef::<Path>::as_ref(path).into()
+    }
+}
+
+impl From<&'_ Utf8Path> for Arc<Path> {
+    fn from(path: &Utf8Path) -> Arc<Path> {
+        AsRef::<Path>::as_ref(path).into()
+    }
+}
+
+impl From<&'_ Utf8Path> for Rc<Path> {
+    fn from(path: &Utf8Path) -> Rc<Path> {
+        AsRef::<Path>::as_ref(path).into()
+    }
+}
+
+impl<'a> From<&'a Utf8Path> for Cow<'a, Path> {
+    fn from(path: &'a Utf8Path) -> Cow<'a, Path> {
+        Cow::Borrowed(path.as_ref())
+    }
+}
+
+// ---
+// From impls: owned -> owned
+// ---
+
+impl From<Box<Utf8Path>> for Utf8PathBuf {
+    fn from(path: Box<Utf8Path>) -> Utf8PathBuf {
+        path.into_path_buf()
+    }
+}
+
+impl From<Utf8PathBuf> for Box<Utf8Path> {
+    fn from(path: Utf8PathBuf) -> Box<Utf8Path> {
+        path.into_boxed_path()
+    }
+}
+
+impl<'a> From<Cow<'a, Utf8Path>> for Utf8PathBuf {
+    fn from(path: Cow<'a, Utf8Path>) -> Utf8PathBuf {
+        path.into_owned()
+    }
+}
+
+impl From<Utf8PathBuf> for String {
+    fn from(path: Utf8PathBuf) -> String {
+        path.into_string()
+    }
+}
+
+impl From<Utf8PathBuf> for OsString {
+    fn from(path: Utf8PathBuf) -> OsString {
+        path.into_os_string()
+    }
+}
+
+impl<'a> From<Utf8PathBuf> for Cow<'a, Utf8Path> {
+    fn from(path: Utf8PathBuf) -> Cow<'a, Utf8Path> {
+        Cow::Owned(path)
+    }
+}
+
+impl From<Utf8PathBuf> for Arc<Utf8Path> {
+    fn from(path: Utf8PathBuf) -> Arc<Utf8Path> {
+        let arc: Arc<Path> = Arc::from(path.0);
+        let ptr = Arc::into_raw(arc) as *const Utf8Path;
+        // SAFETY:
+        // * path is valid UTF-8
+        // * ptr was created by consuming an Arc<Path> so it represents an arced pointer
+        // * Utf8Path is marked as #[repr(transparent)] so the conversion from *const Path to
+        //   *const Utf8Path is valid
+        unsafe { Arc::from_raw(ptr) }
+    }
+}
+
+impl From<Utf8PathBuf> for Rc<Utf8Path> {
+    fn from(path: Utf8PathBuf) -> Rc<Utf8Path> {
+        let rc: Rc<Path> = Rc::from(path.0);
+        let ptr = Rc::into_raw(rc) as *const Utf8Path;
+        // SAFETY:
+        // * path is valid UTF-8
+        // * ptr was created by consuming an Rc<Path> so it represents an rced pointer
+        // * Utf8Path is marked as #[repr(transparent)] so the conversion from *const Path to
+        //   *const Utf8Path is valid
+        unsafe { Rc::from_raw(ptr) }
+    }
+}
+
+impl From<Utf8PathBuf> for PathBuf {
+    fn from(path: Utf8PathBuf) -> PathBuf {
+        path.0
+    }
+}
+
+impl From<Utf8PathBuf> for Box<Path> {
+    fn from(path: Utf8PathBuf) -> Box<Path> {
+        PathBuf::from(path).into_boxed_path()
+    }
+}
+
+impl From<Utf8PathBuf> for Arc<Path> {
+    fn from(path: Utf8PathBuf) -> Arc<Path> {
+        PathBuf::from(path).into()
+    }
+}
+
+impl From<Utf8PathBuf> for Rc<Path> {
+    fn from(path: Utf8PathBuf) -> Rc<Path> {
+        PathBuf::from(path).into()
+    }
+}
+
+impl<'a> From<Utf8PathBuf> for Cow<'a, Path> {
+    fn from(path: Utf8PathBuf) -> Cow<'a, Path> {
+        PathBuf::from(path).into()
+    }
+}
+
+// ---
+// TryFrom impls
+// ---
+
+impl TryFrom<PathBuf> for Utf8PathBuf {
+    type Error = FromPathBufError;
+
+    fn try_from(path: PathBuf) -> Result<Utf8PathBuf, Self::Error> {
+        Utf8PathBuf::from_path_buf(path).map_err(|path| FromPathBufError {
+            path,
+            error: FromPathError(()),
+        })
+    }
+}
+
+impl<'a> TryFrom<&'a Path> for &'a Utf8Path {
+    type Error = FromPathError;
+
+    fn try_from(path: &'a Path) -> Result<&'a Utf8Path, Self::Error> {
+        Utf8Path::from_path(path).ok_or(FromPathError(()))
+    }
+}
+
+/// A possible error value while converting a [`PathBuf`] to a [`Utf8PathBuf`].
+///
+/// Produced by the `TryFrom<PathBuf>` implementation for [`Utf8PathBuf`].
+///
+/// # Examples
+///
+/// ```
+/// use camino::{Utf8PathBuf, FromPathBufError};
+/// use std::convert::{TryFrom, TryInto};
+/// use std::ffi::OsStr;
+/// # #[cfg(unix)]
+/// use std::os::unix::ffi::OsStrExt;
+/// use std::path::PathBuf;
+///
+/// let unicode_path = PathBuf::from("/valid/unicode");
+/// let utf8_path_buf: Utf8PathBuf = unicode_path.try_into().expect("valid Unicode path succeeded");
+///
+/// // Paths on Unix can be non-UTF-8.
+/// # #[cfg(unix)]
+/// let non_unicode_str = OsStr::from_bytes(b"\xFF\xFF\xFF");
+/// # #[cfg(unix)]
+/// let non_unicode_path = PathBuf::from(non_unicode_str);
+/// # #[cfg(unix)]
+/// let err: FromPathBufError = Utf8PathBuf::try_from(non_unicode_path.clone())
+///     .expect_err("non-Unicode path failed");
+/// # #[cfg(unix)]
+/// assert_eq!(err.as_path(), &non_unicode_path);
+/// # #[cfg(unix)]
+/// assert_eq!(err.into_path_buf(), non_unicode_path);
+/// ```
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct FromPathBufError {
+    path: PathBuf,
+    error: FromPathError,
+}
+
+impl FromPathBufError {
+    /// Returns the [`Path`] slice that was attempted to be converted to [`Utf8PathBuf`].
+    pub fn as_path(&self) -> &Path {
+        &self.path
+    }
+
+    /// Returns the [`PathBuf`] that was attempted to be converted to [`Utf8PathBuf`].
+    pub fn into_path_buf(self) -> PathBuf {
+        self.path
+    }
+
+    /// Fetches a [`FromPathError`] for more about the conversion failure.
+    ///
+    /// At the moment this struct does not contain any additional information, but is provided for
+    /// completeness.
+    pub fn from_path_error(&self) -> FromPathError {
+        self.error
+    }
+
+    /// Converts self into a [`std::io::Error`] with kind
+    /// [`InvalidData`](io::ErrorKind::InvalidData).
+    ///
+    /// Many users of `FromPathBufError` will want to convert it into an `io::Error`. This is a
+    /// convenience method to do that.
+    pub fn into_io_error(self) -> io::Error {
+        // NOTE: we don't currently implement `From<FromPathBufError> for io::Error` because we want
+        // to ensure the user actually desires that conversion.
+        io::Error::new(io::ErrorKind::InvalidData, self)
+    }
+}
+
+impl fmt::Display for FromPathBufError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "PathBuf contains invalid UTF-8: {}", self.path.display())
+    }
+}
+
+impl error::Error for FromPathBufError {
+    fn source(&self) -> Option<&(dyn error::Error + 'static)> {
+        Some(&self.error)
+    }
+}
+
+/// A possible error value while converting a [`Path`] to a [`Utf8Path`].
+///
+/// Produced by the `TryFrom<&Path>` implementation for [`&Utf8Path`](Utf8Path).
+///
+///
+/// # Examples
+///
+/// ```
+/// use camino::{Utf8Path, FromPathError};
+/// use std::convert::{TryFrom, TryInto};
+/// use std::ffi::OsStr;
+/// # #[cfg(unix)]
+/// use std::os::unix::ffi::OsStrExt;
+/// use std::path::Path;
+///
+/// let unicode_path = Path::new("/valid/unicode");
+/// let utf8_path: &Utf8Path = unicode_path.try_into().expect("valid Unicode path succeeded");
+///
+/// // Paths on Unix can be non-UTF-8.
+/// # #[cfg(unix)]
+/// let non_unicode_str = OsStr::from_bytes(b"\xFF\xFF\xFF");
+/// # #[cfg(unix)]
+/// let non_unicode_path = Path::new(non_unicode_str);
+/// # #[cfg(unix)]
+/// let err: FromPathError = <&Utf8Path>::try_from(non_unicode_path)
+///     .expect_err("non-Unicode path failed");
+/// ```
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct FromPathError(());
+
+impl FromPathError {
+    /// Converts self into a [`std::io::Error`] with kind
+    /// [`InvalidData`](io::ErrorKind::InvalidData).
+    ///
+    /// Many users of `FromPathError` will want to convert it into an `io::Error`. This is a
+    /// convenience method to do that.
+    pub fn into_io_error(self) -> io::Error {
+        // NOTE: we don't currently implement `From<FromPathBufError> for io::Error` because we want
+        // to ensure the user actually desires that conversion.
+        io::Error::new(io::ErrorKind::InvalidData, self)
+    }
+}
+
+impl fmt::Display for FromPathError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "Path contains invalid UTF-8")
+    }
+}
+
+impl error::Error for FromPathError {
+    fn source(&self) -> Option<&(dyn error::Error + 'static)> {
+        None
+    }
+}
+
+// ---
+// AsRef impls
+// ---
+
+impl AsRef<Utf8Path> for Utf8Path {
+    fn as_ref(&self) -> &Utf8Path {
+        self
+    }
+}
+
+impl AsRef<Utf8Path> for Utf8PathBuf {
+    fn as_ref(&self) -> &Utf8Path {
+        self.as_path()
+    }
+}
+
+impl AsRef<Utf8Path> for str {
+    fn as_ref(&self) -> &Utf8Path {
+        Utf8Path::new(self)
+    }
+}
+
+impl AsRef<Utf8Path> for String {
+    fn as_ref(&self) -> &Utf8Path {
+        Utf8Path::new(self)
+    }
+}
+
+impl AsRef<Path> for Utf8Path {
+    fn as_ref(&self) -> &Path {
+        &self.0
+    }
+}
+
+impl AsRef<Path> for Utf8PathBuf {
+    fn as_ref(&self) -> &Path {
+        &self.0
+    }
+}
+
+impl AsRef<str> for Utf8Path {
+    fn as_ref(&self) -> &str {
+        self.as_str()
+    }
+}
+
+impl AsRef<str> for Utf8PathBuf {
+    fn as_ref(&self) -> &str {
+        self.as_str()
+    }
+}
+
+impl AsRef<OsStr> for Utf8Path {
+    fn as_ref(&self) -> &OsStr {
+        self.as_os_str()
+    }
+}
+
+impl AsRef<OsStr> for Utf8PathBuf {
+    fn as_ref(&self) -> &OsStr {
+        self.as_os_str()
+    }
+}
+
+// ---
+// Borrow and ToOwned
+// ---
+
+impl Borrow<Utf8Path> for Utf8PathBuf {
+    fn borrow(&self) -> &Utf8Path {
+        self.as_path()
+    }
+}
+
+impl ToOwned for Utf8Path {
+    type Owned = Utf8PathBuf;
+
+    fn to_owned(&self) -> Utf8PathBuf {
+        self.to_path_buf()
+    }
+}
+
+impl<P: AsRef<Utf8Path>> std::iter::FromIterator<P> for Utf8PathBuf {
+    fn from_iter<I: IntoIterator<Item = P>>(iter: I) -> Utf8PathBuf {
+        let mut buf = Utf8PathBuf::new();
+        buf.extend(iter);
+        buf
+    }
+}
+
+// ---
+// [Partial]Eq, [Partial]Ord, Hash
+// ---
+
+impl PartialEq for Utf8PathBuf {
+    fn eq(&self, other: &Utf8PathBuf) -> bool {
+        self.components() == other.components()
+    }
+}
+
+impl Eq for Utf8PathBuf {}
+
+impl Hash for Utf8PathBuf {
+    fn hash<H: Hasher>(&self, state: &mut H) {
+        self.as_path().hash(state)
+    }
+}
+
+impl PartialOrd for Utf8PathBuf {
+    fn partial_cmp(&self, other: &Utf8PathBuf) -> Option<Ordering> {
+        self.components().partial_cmp(other.components())
+    }
+}
+
+impl Ord for Utf8PathBuf {
+    fn cmp(&self, other: &Utf8PathBuf) -> Ordering {
+        self.components().cmp(other.components())
+    }
+}
+
+impl PartialEq for Utf8Path {
+    fn eq(&self, other: &Utf8Path) -> bool {
+        self.components().eq(other.components())
+    }
+}
+
+impl Eq for Utf8Path {}
+
+impl Hash for Utf8Path {
+    fn hash<H: Hasher>(&self, state: &mut H) {
+        for component in self.components() {
+            component.hash(state)
+        }
+    }
+}
+
+impl PartialOrd for Utf8Path {
+    fn partial_cmp(&self, other: &Utf8Path) -> Option<Ordering> {
+        self.components().partial_cmp(other.components())
+    }
+}
+
+impl Ord for Utf8Path {
+    fn cmp(&self, other: &Utf8Path) -> Ordering {
+        self.components().cmp(other.components())
+    }
+}
+
+impl<'a> IntoIterator for &'a Utf8PathBuf {
+    type Item = &'a str;
+    type IntoIter = Iter<'a>;
+    fn into_iter(self) -> Iter<'a> {
+        self.iter()
+    }
+}
+
+impl<'a> IntoIterator for &'a Utf8Path {
+    type Item = &'a str;
+    type IntoIter = Iter<'a>;
+    fn into_iter(self) -> Iter<'a> {
+        self.iter()
+    }
+}
+
+macro_rules! impl_cmp {
+    ($lhs:ty, $rhs: ty) => {
+        #[allow(clippy::extra_unused_lifetimes)]
+        impl<'a, 'b> PartialEq<$rhs> for $lhs {
+            #[inline]
+            fn eq(&self, other: &$rhs) -> bool {
+                <Utf8Path as PartialEq>::eq(self, other)
+            }
+        }
+
+        #[allow(clippy::extra_unused_lifetimes)]
+        impl<'a, 'b> PartialEq<$lhs> for $rhs {
+            #[inline]
+            fn eq(&self, other: &$lhs) -> bool {
+                <Utf8Path as PartialEq>::eq(self, other)
+            }
+        }
+
+        #[allow(clippy::extra_unused_lifetimes)]
+        impl<'a, 'b> PartialOrd<$rhs> for $lhs {
+            #[inline]
+            fn partial_cmp(&self, other: &$rhs) -> Option<Ordering> {
+                <Utf8Path as PartialOrd>::partial_cmp(self, other)
+            }
+        }
+
+        #[allow(clippy::extra_unused_lifetimes)]
+        impl<'a, 'b> PartialOrd<$lhs> for $rhs {
+            #[inline]
+            fn partial_cmp(&self, other: &$lhs) -> Option<Ordering> {
+                <Utf8Path as PartialOrd>::partial_cmp(self, other)
+            }
+        }
+    };
+}
+
+impl_cmp!(Utf8PathBuf, Utf8Path);
+impl_cmp!(Utf8PathBuf, &'a Utf8Path);
+impl_cmp!(Cow<'a, Utf8Path>, Utf8Path);
+impl_cmp!(Cow<'a, Utf8Path>, &'b Utf8Path);
+impl_cmp!(Cow<'a, Utf8Path>, Utf8PathBuf);
+
+macro_rules! impl_cmp_std_path {
+    ($lhs:ty, $rhs: ty) => {
+        #[allow(clippy::extra_unused_lifetimes)]
+        impl<'a, 'b> PartialEq<$rhs> for $lhs {
+            #[inline]
+            fn eq(&self, other: &$rhs) -> bool {
+                <Path as PartialEq>::eq(self.as_ref(), other)
+            }
+        }
+
+        #[allow(clippy::extra_unused_lifetimes)]
+        impl<'a, 'b> PartialEq<$lhs> for $rhs {
+            #[inline]
+            fn eq(&self, other: &$lhs) -> bool {
+                <Path as PartialEq>::eq(self, other.as_ref())
+            }
+        }
+
+        #[allow(clippy::extra_unused_lifetimes)]
+        impl<'a, 'b> PartialOrd<$rhs> for $lhs {
+            #[inline]
+            fn partial_cmp(&self, other: &$rhs) -> Option<std::cmp::Ordering> {
+                <Path as PartialOrd>::partial_cmp(self.as_ref(), other)
+            }
+        }
+
+        #[allow(clippy::extra_unused_lifetimes)]
+        impl<'a, 'b> PartialOrd<$lhs> for $rhs {
+            #[inline]
+            fn partial_cmp(&self, other: &$lhs) -> Option<std::cmp::Ordering> {
+                <Path as PartialOrd>::partial_cmp(self, other.as_ref())
+            }
+        }
+    };
+}
+
+impl_cmp_std_path!(Utf8PathBuf, Path);
+impl_cmp_std_path!(Utf8PathBuf, &'a Path);
+impl_cmp_std_path!(Utf8PathBuf, Cow<'a, Path>);
+impl_cmp_std_path!(Utf8PathBuf, PathBuf);
+impl_cmp_std_path!(Utf8Path, Path);
+impl_cmp_std_path!(Utf8Path, &'a Path);
+impl_cmp_std_path!(Utf8Path, Cow<'a, Path>);
+impl_cmp_std_path!(Utf8Path, PathBuf);
+impl_cmp_std_path!(&'a Utf8Path, Path);
+impl_cmp_std_path!(&'a Utf8Path, Cow<'b, Path>);
+impl_cmp_std_path!(&'a Utf8Path, PathBuf);
+// NOTE: impls for Cow<'a, Utf8Path> cannot be defined because of the orphan rule (E0117)
+
+macro_rules! impl_cmp_str {
+    ($lhs:ty, $rhs: ty) => {
+        #[allow(clippy::extra_unused_lifetimes)]
+        impl<'a, 'b> PartialEq<$rhs> for $lhs {
+            #[inline]
+            fn eq(&self, other: &$rhs) -> bool {
+                <Utf8Path as PartialEq>::eq(self, Utf8Path::new(other))
+            }
+        }
+
+        #[allow(clippy::extra_unused_lifetimes)]
+        impl<'a, 'b> PartialEq<$lhs> for $rhs {
+            #[inline]
+            fn eq(&self, other: &$lhs) -> bool {
+                <Utf8Path as PartialEq>::eq(Utf8Path::new(self), other)
+            }
+        }
+
+        #[allow(clippy::extra_unused_lifetimes)]
+        impl<'a, 'b> PartialOrd<$rhs> for $lhs {
+            #[inline]
+            fn partial_cmp(&self, other: &$rhs) -> Option<std::cmp::Ordering> {
+                <Utf8Path as PartialOrd>::partial_cmp(self, Utf8Path::new(other))
+            }
+        }
+
+        #[allow(clippy::extra_unused_lifetimes)]
+        impl<'a, 'b> PartialOrd<$lhs> for $rhs {
+            #[inline]
+            fn partial_cmp(&self, other: &$lhs) -> Option<std::cmp::Ordering> {
+                <Utf8Path as PartialOrd>::partial_cmp(Utf8Path::new(self), other)
+            }
+        }
+    };
+}
+
+impl_cmp_str!(Utf8PathBuf, str);
+impl_cmp_str!(Utf8PathBuf, &'a str);
+impl_cmp_str!(Utf8PathBuf, Cow<'a, str>);
+impl_cmp_str!(Utf8PathBuf, String);
+impl_cmp_str!(Utf8Path, str);
+impl_cmp_str!(Utf8Path, &'a str);
+impl_cmp_str!(Utf8Path, Cow<'a, str>);
+impl_cmp_str!(Utf8Path, String);
+impl_cmp_str!(&'a Utf8Path, str);
+impl_cmp_str!(&'a Utf8Path, Cow<'b, str>);
+impl_cmp_str!(&'a Utf8Path, String);
+// NOTE: impls for Cow<'a, Utf8Path> cannot be defined because of the orphan rule (E0117)
+
+macro_rules! impl_cmp_os_str {
+    ($lhs:ty, $rhs: ty) => {
+        #[allow(clippy::extra_unused_lifetimes)]
+        impl<'a, 'b> PartialEq<$rhs> for $lhs {
+            #[inline]
+            fn eq(&self, other: &$rhs) -> bool {
+                <Path as PartialEq>::eq(self.as_ref(), other.as_ref())
+            }
+        }
+
+        #[allow(clippy::extra_unused_lifetimes)]
+        impl<'a, 'b> PartialEq<$lhs> for $rhs {
+            #[inline]
+            fn eq(&self, other: &$lhs) -> bool {
+                <Path as PartialEq>::eq(self.as_ref(), other.as_ref())
+            }
+        }
+
+        #[allow(clippy::extra_unused_lifetimes)]
+        impl<'a, 'b> PartialOrd<$rhs> for $lhs {
+            #[inline]
+            fn partial_cmp(&self, other: &$rhs) -> Option<std::cmp::Ordering> {
+                <Path as PartialOrd>::partial_cmp(self.as_ref(), other.as_ref())
+            }
+        }
+
+        #[allow(clippy::extra_unused_lifetimes)]
+        impl<'a, 'b> PartialOrd<$lhs> for $rhs {
+            #[inline]
+            fn partial_cmp(&self, other: &$lhs) -> Option<std::cmp::Ordering> {
+                <Path as PartialOrd>::partial_cmp(self.as_ref(), other.as_ref())
+            }
+        }
+    };
+}
+
+impl_cmp_os_str!(Utf8PathBuf, OsStr);
+impl_cmp_os_str!(Utf8PathBuf, &'a OsStr);
+impl_cmp_os_str!(Utf8PathBuf, Cow<'a, OsStr>);
+impl_cmp_os_str!(Utf8PathBuf, OsString);
+impl_cmp_os_str!(Utf8Path, OsStr);
+impl_cmp_os_str!(Utf8Path, &'a OsStr);
+impl_cmp_os_str!(Utf8Path, Cow<'a, OsStr>);
+impl_cmp_os_str!(Utf8Path, OsString);
+impl_cmp_os_str!(&'a Utf8Path, OsStr);
+impl_cmp_os_str!(&'a Utf8Path, Cow<'b, OsStr>);
+impl_cmp_os_str!(&'a Utf8Path, OsString);
+// NOTE: impls for Cow<'a, Utf8Path> cannot be defined because of the orphan rule (E0117)
+
+// invariant: OsStr must be guaranteed to be utf8 data
+unsafe fn assume_utf8(string: &OsStr) -> &str {
+    &*(string as *const OsStr as *const str)
+}
diff --git a/src/proptest_impls.rs b/src/proptest_impls.rs
new file mode 100644
index 0000000..81776f2
--- /dev/null
+++ b/src/proptest_impls.rs
@@ -0,0 +1,60 @@
+// Copyright (c) The camino Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! [proptest::Arbitrary](Arbitrary) implementation for `Utf8PathBuf` and `Box<Utf8Path>`.  Note
+//! that implementions for `Rc<Utf8Path>` and `Arc<Utf8Path>` are not currently possible due to
+//! orphan rules - this crate doesn't define `Rc`/`Arc` nor `Arbitrary`, so it can't define those
+//! implementations.
+
+// NOTE: #[cfg(feature = "proptest1")] is specified here to work with `doc_cfg`.
+
+use crate::{Utf8Path, Utf8PathBuf};
+use proptest::{arbitrary::StrategyFor, prelude::*, strategy::MapInto};
+
+/// The [`Arbitrary`] impl for `Utf8PathBuf` returns a path with between 0 and 8 components,
+/// joined by the [`MAIN_SEPARATOR`](std::path::MAIN_SEPARATOR) for the platform. (Each component is
+/// randomly generated, and may itself contain one or more separators.)
+///
+/// On Unix, this generates an absolute path half of the time and a relative path the other half.
+///
+/// On Windows, this implementation doesn't currently generate
+/// [`Utf8PrefixComponent`](crate::Utf8PrefixComponent) instances, though in the future it might.
+#[cfg(feature = "proptest1")]
+impl Arbitrary for Utf8PathBuf {
+    type Parameters = <String as Arbitrary>::Parameters;
+    type Strategy = BoxedStrategy<Self>;
+
+    fn arbitrary_with(args: Self::Parameters) -> Self::Strategy {
+        (
+            any::<bool>(),
+            prop::collection::vec(any_with::<String>(args), 0..8),
+        )
+            .prop_map(|(is_relative, components)| {
+                let initial_component =
+                    is_relative.then(|| format!("{}", std::path::MAIN_SEPARATOR));
+                initial_component
+                    .into_iter()
+                    .chain(components.into_iter())
+                    .collect()
+            })
+            .boxed()
+    }
+}
+
+/// The [`Arbitrary`] impl for `Box<Utf8Path>` returns a path with between 0 and 8 components,
+/// joined by the [`MAIN_SEPARATOR`](std::path::MAIN_SEPARATOR) for the platform. (Each component is
+/// randomly generated, and may itself contain one or more separators.)
+///
+/// On Unix, this generates an absolute path half of the time and a relative path the other half.
+///
+/// On Windows, this implementation doesn't currently generate
+/// [`Utf8PrefixComponent`](crate::Utf8PrefixComponent) instances, though in the future it might.
+#[cfg(feature = "proptest1")]
+impl Arbitrary for Box<Utf8Path> {
+    type Parameters = <Utf8PathBuf as Arbitrary>::Parameters;
+    type Strategy = MapInto<StrategyFor<Utf8PathBuf>, Self>;
+
+    fn arbitrary_with(args: Self::Parameters) -> Self::Strategy {
+        any_with::<Utf8PathBuf>(args).prop_map_into()
+    }
+}
diff --git a/src/serde_impls.rs b/src/serde_impls.rs
new file mode 100644
index 0000000..1a7fa1b
--- /dev/null
+++ b/src/serde_impls.rs
@@ -0,0 +1,214 @@
+// Copyright (c) The camino Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! Serde implementations for `Utf8Path`.
+//!
+//! The Serde implementations for `Utf8PathBuf` are derived, but `Utf8Path` is an unsized type which
+//! the derive impls can't handle. Implement these by hand.
+
+use crate::{Utf8Path, Utf8PathBuf};
+use serde::{de, Deserialize, Deserializer, Serialize, Serializer};
+use std::fmt;
+
+struct Utf8PathVisitor;
+
+impl<'a> de::Visitor<'a> for Utf8PathVisitor {
+    type Value = &'a Utf8Path;
+
+    fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
+        formatter.write_str("a borrowed path")
+    }
+
+    fn visit_borrowed_str<E>(self, v: &'a str) -> Result<Self::Value, E>
+    where
+        E: de::Error,
+    {
+        Ok(v.as_ref())
+    }
+
+    fn visit_borrowed_bytes<E>(self, v: &'a [u8]) -> Result<Self::Value, E>
+    where
+        E: de::Error,
+    {
+        std::str::from_utf8(v)
+            .map(AsRef::as_ref)
+            .map_err(|_| de::Error::invalid_value(de::Unexpected::Bytes(v), &self))
+    }
+}
+
+impl<'de: 'a, 'a> Deserialize<'de> for &'a Utf8Path {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        deserializer.deserialize_str(Utf8PathVisitor)
+    }
+}
+
+impl Serialize for Utf8Path {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        self.as_str().serialize(serializer)
+    }
+}
+
+impl<'de> Deserialize<'de> for Box<Utf8Path> {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        Ok(Utf8PathBuf::deserialize(deserializer)?.into())
+    }
+}
+
+// impl Serialize for Box<Utf8Path> comes from impl Serialize for Utf8Path.
+
+// Can't provide impls for Arc/Rc due to orphan rule issues, but we could provide
+// `with` impls in the future as requested.
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::Utf8PathBuf;
+    use serde_bytes::ByteBuf;
+
+    #[test]
+    fn valid_utf8() {
+        let valid_utf8 = &["", "bar", "💩"];
+        for input in valid_utf8 {
+            let encode = Encode {
+                path: ByteBuf::from(*input),
+            };
+            let encoded = bincode::serialize(&encode).expect("encoded correctly");
+
+            assert_valid_utf8::<DecodeOwned>(input, &encoded);
+            assert_valid_utf8::<DecodeBorrowed>(input, &encoded);
+            assert_valid_utf8::<DecodeBoxed>(input, &encoded);
+        }
+    }
+
+    fn assert_valid_utf8<'de, T: TestTrait<'de>>(input: &str, encoded: &'de [u8]) {
+        let output = bincode::deserialize::<T>(encoded).expect("valid UTF-8 should be fine");
+        assert_eq!(
+            output.path(),
+            input,
+            "for input, with {}, paths should match",
+            T::description()
+        );
+        let roundtrip = bincode::serialize(&output).expect("message should roundtrip");
+        assert_eq!(roundtrip, encoded, "encoded path matches");
+    }
+
+    #[test]
+    fn invalid_utf8() {
+        let invalid_utf8: &[(&[u8], _, _)] = &[
+            (b"\xff", 0, 1),
+            (b"foo\xfe", 3, 1),
+            (b"a\xC3\xA9 \xED\xA0\xBD\xF0\x9F\x92\xA9", 4, 1),
+        ];
+
+        for (input, valid_up_to, error_len) in invalid_utf8 {
+            let encode = Encode {
+                path: ByteBuf::from(*input),
+            };
+            let encoded = bincode::serialize(&encode).expect("encoded correctly");
+
+            assert_invalid_utf8::<DecodeOwned>(input, &encoded, *valid_up_to, *error_len);
+            assert_invalid_utf8::<DecodeBorrowed>(input, &encoded, *valid_up_to, *error_len);
+            assert_invalid_utf8::<DecodeBoxed>(input, &encoded, *valid_up_to, *error_len);
+        }
+    }
+
+    fn assert_invalid_utf8<'de, T: TestTrait<'de>>(
+        input: &[u8],
+        encoded: &'de [u8],
+        valid_up_to: usize,
+        error_len: usize,
+    ) {
+        let error = bincode::deserialize::<T>(encoded).expect_err("invalid UTF-8 should error out");
+        let utf8_error = match *error {
+            bincode::ErrorKind::InvalidUtf8Encoding(utf8_error) => utf8_error,
+            other => panic!(
+                "for input {:?}, with {}, expected ErrorKind::InvalidUtf8Encoding, found: {}",
+                input,
+                T::description(),
+                other
+            ),
+        };
+        assert_eq!(
+            utf8_error.valid_up_to(),
+            valid_up_to,
+            "for input {:?}, with {}, valid_up_to didn't match",
+            input,
+            T::description(),
+        );
+        assert_eq!(
+            utf8_error.error_len(),
+            Some(error_len),
+            "for input {:?}, with {}, error_len didn't match",
+            input,
+            T::description(),
+        );
+    }
+
+    #[derive(Serialize, Debug)]
+    struct Encode {
+        path: ByteBuf,
+    }
+
+    trait TestTrait<'de>: Serialize + Deserialize<'de> + fmt::Debug {
+        fn description() -> &'static str;
+        fn path(&self) -> &Utf8Path;
+    }
+
+    #[derive(Serialize, Deserialize, Debug)]
+    #[allow(unused)]
+    struct DecodeOwned {
+        path: Utf8PathBuf,
+    }
+
+    impl<'de> TestTrait<'de> for DecodeOwned {
+        fn description() -> &'static str {
+            "DecodeOwned"
+        }
+
+        fn path(&self) -> &Utf8Path {
+            &self.path
+        }
+    }
+
+    #[derive(Serialize, Deserialize, Debug)]
+    #[allow(unused)]
+    struct DecodeBorrowed<'a> {
+        #[serde(borrow)]
+        path: &'a Utf8Path,
+    }
+
+    impl<'de> TestTrait<'de> for DecodeBorrowed<'de> {
+        fn description() -> &'static str {
+            "DecodeBorrowed"
+        }
+
+        fn path(&self) -> &Utf8Path {
+            self.path
+        }
+    }
+
+    #[derive(Serialize, Deserialize, Debug)]
+    #[allow(unused)]
+    struct DecodeBoxed {
+        path: Box<Utf8Path>,
+    }
+
+    impl<'de> TestTrait<'de> for DecodeBoxed {
+        fn description() -> &'static str {
+            "DecodeBoxed"
+        }
+
+        fn path(&self) -> &Utf8Path {
+            &self.path
+        }
+    }
+}
diff --git a/src/tests.rs b/src/tests.rs
new file mode 100644
index 0000000..e84c227
--- /dev/null
+++ b/src/tests.rs
@@ -0,0 +1,54 @@
+// Copyright (c) The camino Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+// Test that all required impls exist.
+
+use crate::{Utf8Path, Utf8PathBuf};
+use std::{
+    borrow::Cow,
+    path::{Path, PathBuf},
+    rc::Rc,
+    sync::Arc,
+};
+
+macro_rules! all_into {
+    ($t:ty, $x:ident) => {
+        test_into::<$t, Utf8PathBuf>($x.clone());
+        test_into::<$t, Box<Utf8Path>>($x.clone());
+        test_into::<$t, Arc<Utf8Path>>($x.clone());
+        test_into::<$t, Rc<Utf8Path>>($x.clone());
+        test_into::<$t, Cow<'_, Utf8Path>>($x.clone());
+        test_into::<$t, PathBuf>($x.clone());
+        test_into::<$t, Box<Path>>($x.clone());
+        test_into::<$t, Arc<Path>>($x.clone());
+        test_into::<$t, Rc<Path>>($x.clone());
+        test_into::<$t, Cow<'_, Path>>($x.clone());
+    };
+}
+
+#[test]
+fn test_borrowed_into() {
+    let utf8_path = Utf8Path::new("test/path");
+    all_into!(&Utf8Path, utf8_path);
+}
+
+#[test]
+fn test_owned_into() {
+    let utf8_path_buf = Utf8PathBuf::from("test/path");
+    all_into!(Utf8PathBuf, utf8_path_buf);
+}
+
+fn test_into<T, U>(orig: T)
+where
+    T: Into<U>,
+{
+    let _ = orig.into();
+}
+
+#[cfg(path_buf_deref_mut)]
+#[test]
+fn test_deref_mut() {
+    // This test is mostly for miri.
+    let mut path_buf = Utf8PathBuf::from("foobar");
+    let _: &mut Utf8Path = &mut path_buf;
+}
diff --git a/tests/integration_tests.rs b/tests/integration_tests.rs
new file mode 100644
index 0000000..190ba82
--- /dev/null
+++ b/tests/integration_tests.rs
@@ -0,0 +1,115 @@
+// Copyright (c) The camino Contributors
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+use camino::{Utf8Path, Utf8PathBuf};
+use std::{
+    collections::hash_map::DefaultHasher,
+    hash::{Hash, Hasher},
+    path::Path,
+};
+
+static PATH_CORPUS: &[&str] = &[
+    "",
+    "foo",
+    "foo/bar",
+    "foo//bar",
+    "foo/bar/baz",
+    "foo/bar/./baz",
+    "foo/bar/../baz",
+    "../foo/bar/./../baz",
+    "/foo",
+    "/foo/bar",
+    "/",
+    "///",
+    // ---
+    // Windows-only paths
+    // ---
+    #[cfg(windows)]
+    "foo\\bar",
+    #[cfg(windows)]
+    "\\foo\\bar",
+    #[cfg(windows)]
+    "C:\\foo",
+    #[cfg(windows)]
+    "C:foo\\bar",
+    #[cfg(windows)]
+    "C:\\foo\\..\\.\\bar",
+    #[cfg(windows)]
+    "\\\\server\\foo\\bar",
+    #[cfg(windows)]
+    "\\\\.\\C:\\foo\\bar.txt",
+];
+
+#[test]
+fn test_borrow_eq_ord() {
+    // Utf8PathBuf implements Borrow<Utf8Path> so equality and ordering comparisons should
+    // match.
+    for (idx, &path1) in PATH_CORPUS.iter().enumerate() {
+        for &path2 in &PATH_CORPUS[idx..] {
+            let borrowed1 = Utf8Path::new(path1);
+            let borrowed2 = Utf8Path::new(path2);
+            let owned1 = Utf8PathBuf::from(path1);
+            let owned2 = Utf8PathBuf::from(path2);
+
+            assert_eq!(
+                borrowed1 == borrowed2,
+                owned1 == owned2,
+                "Eq impls match: {} == {}",
+                borrowed1,
+                borrowed2
+            );
+            assert_eq!(
+                borrowed1.cmp(borrowed2),
+                owned1.cmp(&owned2),
+                "Ord impls match: {} and {}",
+                borrowed1,
+                borrowed2
+            );
+
+            // Also check against std paths.
+            let std1 = Path::new(path1);
+            let std2 = Path::new(path2);
+            assert_eq!(
+                borrowed1, std1,
+                "Eq between Path and Utf8Path: {}",
+                borrowed1
+            );
+            assert_eq!(
+                borrowed1 == borrowed2,
+                std1 == std2,
+                "Eq impl matches Path: {} == {}",
+                borrowed1,
+                borrowed2
+            );
+            assert_eq!(
+                borrowed1.cmp(borrowed2),
+                std1.cmp(std2),
+                "Ord impl matches Path: {} and {}",
+                borrowed1,
+                borrowed2
+            );
+        }
+    }
+}
+
+#[test]
+fn test_borrow_hash() {
+    // Utf8PathBuf implements Borrow<Utf8Path> so hash comparisons should match.
+    fn hash_output(x: impl Hash) -> u64 {
+        let mut hasher = DefaultHasher::new();
+        x.hash(&mut hasher);
+        hasher.finish()
+    }
+
+    for &path in PATH_CORPUS {
+        let borrowed = Utf8Path::new(path);
+        let owned = Utf8PathBuf::from(path);
+
+        assert_eq!(
+            hash_output(owned),
+            hash_output(borrowed),
+            "consistent Hash: {}",
+            borrowed
+        );
+    }
+}