Crate gep

gep, a better pointer arithmetic library.

The name gep comes from LLVM’s getelementptr instruction, the infamous pointer arithmetic operation.

This library provides two new pointer types, Ptr and NonNull, which have very similar APIs; they correspond to *mut T and core::ptr::NonNull, respectively.

It also provides Rusty versions of memcpy, memmove, and memset.

Offsets

The premiere operation provided by this library is Ptr::at(), which is a generalized pointer arithmetic operation. For example, it will accept any integer as input, not just isize (although, like <*mut T>::offset, the offset value must be valid to convert to isize).

let mut ints = [0i32; 6];
let p = Ptr::from(&mut ints).element();

unsafe {
  // Pointer to the 4th element.
  let q = p.at(4);
  q.write(42);

  // Many operations have an `*_at` variant that internally calls .at().
  q.write_at(-1, 55);
}

assert_eq!(ints, [0, 0, 0, 55, 42, 0]);

By default, at() works on multiples of elements. To do a direct byte offset instead, you can use the offset::ByteOffset type instead.

use gep::offset::ByteOffset;

let mut ints = [0i32; 6];
let p = Ptr::from(&mut ints).element();

unsafe {
  p.write_at(ByteOffset(4), 4242);
}

assert_eq!(ints[1], 4242);

It’s also possible to use “field offsets” (via the offset::Field type) for accessing the fields of a struct directly, without creating intermediate references to potentially invalid data.

use gep::offset::Field;

struct Foo {
  a: i32,
  b: [i32; 3],
}

let foo = Foo { a: 0, b: [1, 2, 3] };

let p = Ptr::from(&foo);
let value = unsafe {
  p.read_at(gep::field!(Foo.b[1]))
};

assert_eq!(value, 2);

Modules

offset

Offset measurement types.

Macros

field

Creates a new Field value.

Structs

NonNull

A non-null raw pointer.

Ptr

A nullable raw pointer.

Traits

MutMarker

Implemented for pointer-like types that are marked as mut.

Functions

memcpy^⚠

Performs a memory copy operation.

memmove^⚠

Performs an overlapping memory copy operation.

memset^⚠

Performs a memory set operation.