Use allocator-api2 as polyfill for allocator API

- Fix a bug where aligning a Range would in some cases cause its length
  to be negative.
- Documentation improvements and fixes.

Signed-off-by: Tin Švagelj <[email protected]>

Author: Caellian

.github/workflows/ci.yml

@@ -18,30 +18,24 @@ jobs:
         unsafe_impl: [true, false]
         ptr_metadata: [true, false]
         error_in_core: [true, false]
-        allocator_api: [true, false]
         exclude:
           - rust: stable
             ptr_metadata: true
           - rust: stable
             error_in_core: true
-          - rust: stable
-            allocator_api: true
           # no point in testing nightly with unstable features disabled
           - rust: nightly
             ptr_metadata: false
           - rust: nightly
             error_in_core: false
-          - rust: nightly
-            allocator_api: false
     runs-on: ${{ matrix.os }}
     name: |
       test - ${{ matrix.os }}; ${{ matrix.rust }} rust; features: {
         no_std: ${{ matrix.no_std }},
         debug: ${{ matrix.debug }},
         unsafe_impl: ${{ matrix.unsafe_impl }},
         ptr_metadata: ${{ matrix.ptr_metadata }},
-        error_in_core: ${{ matrix.error_in_core }},
-        allocator_api: ${{ matrix.allocator_api }}
+        error_in_core: ${{ matrix.error_in_core }}
       }
     env:
       RUST_BACKTRACE: 1 # Emit backtraces on panics.
@@ -62,8 +56,6 @@ jobs:
         run: echo "FEATURES=$FEATURES,ptr_metadata" >> $GITHUB_ENV
       - if: matrix.error_in_core == true
         run: echo "FEATURES=$FEATURES,error_in_core" >> $GITHUB_ENV
-      - if: matrix.allocator_api == true
-        run: echo "FEATURES=$FEATURES,allocator_api" >> $GITHUB_ENV
       - run: cargo test --no-default-features --features=${{ env.FEATURES }} --verbose
 
   lint:

Cargo.toml

@@ -25,20 +25,20 @@ path = "examples/unsafe_impl.rs"
 required-features = ["unsafe_impl"]
 
 [features]
-default = ["unsafe_impl", "debug"]
+default = ["std", "unsafe_impl", "debug"]
 
-no_std = [] # No-std support
-debug = []  # Enable debug attributes
+std = []
+debug = []
 
 # Implementations
 unsafe_impl = []
 
 # Nightly features
 ptr_metadata = []
 error_in_core = []
-allocator_api = []
 
 [dependencies]
+allocator-api2 = "0.3.0"
 sptr = "0.3.2"
 
 [dev-dependencies]

README.md

@@ -25,8 +25,13 @@ the heap to reduce cache misses, but which/how many is determined at runtime.
 - Support for dynamic resizing of allocated memory while keeping the existing
   references functional (for safe implementations).
 - Exhaustively tested with Miri.
-- No downstream dependencies.
-  - ...almost, only [sptr](https://crates.io/crates/sptr) is used to ensure safety.
+- Limited downstream dependencies (only polyfills).
+  - [sptr](https://crates.io/crates/sptr) is used as polyfill for
+    [Strict Provenance](https://doc.rust-lang.org/beta/unstable-book/language-features/strict-provenance.html)
+    and required for MIRI.
+  - [allocator-api2](https://crates.io/crates/allocator-api2)
+    is used as polyfill for the
+    [allocator API](https://doc.rust-lang.org/unstable-book/library-features/allocator-api.html).
 
 ## Getting Started
 
@@ -37,11 +42,11 @@ Add the crate to your dependencies:
 contiguous_mem = { version = "0.5" }
 ```
 
-Optionally enable `no_std` feature to use in `no_std` environment:
+Disable default features (`std` feature) for use in `no_std` environments:
 
 ```toml
 [dependencies]
-contiguous_mem = { version = "0.5", features = ["no_std"] }
+contiguous_mem = { version = "0.5", default-feature = false, features = ["unsafe_impl"] }
 ```
 
 ### Features
@@ -53,8 +58,6 @@ contiguous_mem = { version = "0.5", features = ["no_std"] }
 - [`error_in_core`](https://dev-doc.rust-lang.org/stable/unstable-book/library-features/error-in-core.html)
   <_nightly_> - enables support for `core::error::Error` in `no_std`
   environment
-- [`allocator_api`](https://dev-doc.rust-lang.org/stable/unstable-book/library-features/allocator-api.html)
-  <_nightly_> - enables automatic support for custom allocators
 - `unsafe_impl` (default) - enables `UnsafeContiguousMemory`
 
 ### Usage
@@ -84,7 +87,8 @@ fn main() {
 <sub>* Note that reference types returned by store are inferred and only shown
 here for demonstration purposes.</sub>
 
-References have a similar API as [`RefCell`](https://doc.rust-lang.org/stable/std/cell/struct.RefCell.html).
+Returned references have semantics similar to
+[`RefCell`](https://doc.rust-lang.org/stable/std/cell/struct.RefCell.html).
 
 For more usage examples see the
 [examples](https://github.com/Caellian/contiguous_mem/tree/trunk/examples)

doc/crate.md

@@ -0,0 +1,81 @@
+<table id="feature-table">
+<thead>
+    <tr>
+        <th><h4>Feature</h4></th>
+        <th class="vertical"><h4>Default</h4></th>
+        <th><h4>Description</h4></th>
+    </tr>
+</thead>
+<tbody>
+    <tr>
+        <td><code>std</code></td>
+        <td>&check;</td>
+        <td>enables <code>std</code> types</td>
+    </tr>
+    <tr>
+        <td><code>unsafe_impl</code></td>
+        <td>&check;</td>
+        <td>enables <code>UnsafeContiguousMemory</code></td>
+    </tr>
+    <tr>
+        <td><code>debug</code></td>
+        <td>&cross;</td>
+        <td>enables <code>derive(Debug)</code> on structures unrelated to error handling</td>
+    </tr>
+</tbody>
+<thead>
+    <tr class="category nightly">
+        <th colspan="3"><h5>Nightly</h5></th>
+    </tr>
+</thead>
+<tbody>
+    <tr class="nightly">
+        <td><a href="https://doc.rust-lang.org/beta/unstable-book/library-features/ptr-metadata.html"><code>ptr_metadata</code></a></td>
+        <td>&cross;</td>
+        <td>allows casting references into <code>dyn Trait</code></td>
+    </tr>
+    <tr class="nightly">
+        <td><a href="https://dev-doc.rust-lang.org/stable/unstable-book/library-features/error-in-core.html"><code>error_in_core</code></a></td>
+        <td>&cross;</td>
+        <td>enables support for <code>core::error::Error</code> in <code>no_std</code> environment</td>
+    </tr>
+</tbody>
+</table>
+
+<style>
+#feature-table {
+    .vertical {
+        vertical-align: bottom;
+        text-align: center;
+        width: 2.5em;
+
+        >h4 {
+            writing-mode: vertical-rl;
+            transform: rotate(180deg);
+            white-space: nowrap;
+            margin: auto;
+        }
+    }
+
+    .category {
+        th {
+            padding: .2em;
+            padding-left: 1em;
+        }
+
+        h5 {
+            margin: 0;
+            padding: 0;
+            text-align: left;
+        }
+
+        &.nightly th {
+            background: linear-gradient(60deg,  #771749, #1da8ae);
+            color: #fffe;
+        }
+    }
+
+    tr td:nth-child(1) { text-align: center; }
+    tr td:nth-child(2) { text-align: center; }
+}
+</style>