Report a bug
If you spot a problem with this page, click here to create a Github issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

mir.ndslice.allocation

This is a submodule of mir.ndslice.
It contains allocation utilities.

GC Allocation utilities

Function Name Description
slice Allocates a slice using GC.
shape Returns a shape of a common n-dimensional array.
ndarray Allocates a common n-dimensional array from a slice.
uninitSlice Allocates an uninitialized slice using GC.

Custom allocation utilities

Function Name Description
makeNdarray Allocates a common n-dimensional array from a slice using an allocator.
makeSlice Allocates a slice using an allocator.
makeUninitSlice Allocates an uninitialized slice using an allocator.

CRuntime allocation utilities

Function Name Description
stdcSlice Allocates a slice copy using core.stdc.stdlib.malloc
stdcUninitSlice Allocates an uninitialized slice using core.stdc.stdlib.malloc.
stdcFreeSlice Frees memory using core.stdc.stdlib.free

Aligned allocation utilities

Function Name Description
uninitAlignedSlice Allocates an uninitialized aligned slice using GC.
stdcUninitAlignedSlice Allocates an uninitialized aligned slice using CRuntime.
stdcFreeAlignedSlice Frees memory using CRuntime
Authors:
Ilya Yaroshenko
Slice!(T*, N) slice(T, size_t N)(size_t[N] lengths...);

Slice!(T*, N) slice(T, size_t N)(size_t[N] lengths, T init);

auto slice(Iterator, size_t N, SliceKind kind)(Slice!(Iterator, N, kind) slice);

auto slice(size_t dim, Slices...)(Concatenation!(dim, Slices) concatenation);
Allocates an an n-dimensional slice.
Parameters:
size_t[N] lengths List of lengths for each dimension.
T init Value to initialize with (optional).
Slice!(Iterator, N, kind) slice Slice to copy shape and data from (optional).
Returns:
n-dimensional slice
Examples:
auto tensor = slice!int(5, 6, 7);
assert(tensor.length == 5);
assert(tensor.elementCount == 5 * 6 * 7);
static assert(is(typeof(tensor) == Slice!(int*, 3)));

// creates duplicate using `slice`
auto dup = tensor.slice;
assert(dup == tensor);
Examples:
auto tensor = slice([2, 3], 5);
assert(tensor.elementCount == 2 * 3);
assert(tensor[1, 1] == 5);
Slice!(FieldIterator!(BitField!(size_t*)), N) bitSlice(size_t N)(size_t[N] lengths...);
Allocates a packed n-dimensional bit-array.
Parameters:
size_t[N] lengths List of lengths for each dimension.
Returns:
n-dimensional bitwise slice
See Also:
Examples:
1D
auto bitarray = bitSlice(100); // allocates 16 bytes total
assert(bitarray.shape == [100]);
assert(bitarray[72] == false);
bitarray[72] = true;
assert(bitarray[72] == true);
Examples:
2D
auto bitmatrix = bitSlice(20, 6); // allocates 16 bytes total
assert(bitmatrix.shape == [20, 6]);
assert(bitmatrix[3, 4] == false);
bitmatrix[3, 4] = true;
assert(bitmatrix[3, 4] == true);
auto uninitSlice(T, size_t N)(size_t[N] lengths...);
Allocates an uninitialized an n-dimensional slice.
Parameters:
size_t[N] lengths list of lengths for each dimension
Returns:
contiguous uninitialized n-dimensional slice
Examples:
auto tensor = uninitSlice!int(5, 6, 7);
assert(tensor.length == 5);
assert(tensor.elementCount == 5 * 6 * 7);
static assert(is(typeof(tensor) == Slice!(int*, 3)));
@system auto uninitAlignedSlice(T, size_t N)(size_t[N] lengths, uint alignment);
Allocates an uninitialized aligned an n-dimensional slice.
Parameters:
size_t[N] lengths list of lengths for each dimension
uint alignment memory alignment (bytes)
Returns:
contiguous uninitialized n-dimensional slice
Examples:
auto tensor = uninitAlignedSlice!double([5, 6, 7], 64);
tensor[] = 0;
assert(tensor.length == 5);
assert(tensor.elementCount == 5 * 6 * 7);
assert(cast(size_t)(tensor.ptr) % 64 == 0);
static assert(is(typeof(tensor) == Slice!(double*, 3)));
auto makeSlice(Allocator, size_t N, Iterator)(auto ref Allocator alloc, Slice!(N, Iterator) slice);

Slice!(T*, N) makeSlice(T, Allocator, size_t N)(auto ref Allocator alloc, size_t[N] lengths...);

Slice!(T*, N) makeSlice(T, Allocator, size_t N)(auto ref Allocator alloc, size_t[N] lengths, T init);

auto makeSlice(Allocator, Iterator, size_t N, SliceKind kind)(auto ref Allocator allocator, Slice!(Iterator, N, kind) slice);
Allocates an array through a specified allocator and creates an n-dimensional slice over it. See also allocator.html">std.experimental.allocator.
Parameters:
Allocator alloc allocator
size_t[N] lengths list of lengths for each dimension
T init default value for array initialization
Slice!(N, Iterator) slice slice to copy shape and data from
Returns:
a structure with fields array and slice

Note makeSlice always returns slice with mutable elements

Examples:
Initialization with default value
import std.experimental.allocator;
import std.experimental.allocator.mallocator;
import mir.algorithm.iteration: all;
import mir.ndslice.topology: map;

auto sl = Mallocator.instance.makeSlice([2, 3, 4], 10);
auto ar = sl.field;
assert(sl.all!"a == 10");

auto sl2 = Mallocator.instance.makeSlice(sl.map!"a * 2");
auto ar2 = sl2.field;
assert(sl2.all!"a == 20");

Mallocator.instance.dispose(ar);
Mallocator.instance.dispose(ar2);
Slice!(T*, N) makeUninitSlice(T, Allocator, size_t N)(auto ref Allocator alloc, size_t[N] lengths...)
if (N);
Allocates an uninitialized array through a specified allocator and creates an n-dimensional slice over it. See also std.experimental.allocator.
Parameters:
Allocator alloc allocator
size_t[N] lengths list of lengths for each dimension
Returns:
a structure with fields array and slice
Examples:
import std.experimental.allocator;
import std.experimental.allocator.mallocator;

auto sl = makeUninitSlice!int(Mallocator.instance, 2, 3, 4);
auto ar = sl.field;
assert(ar.ptr is sl.iterator);
assert(ar.length           == 24);
assert(sl.elementCount    == 24);

Mallocator.instance.dispose(ar);
auto ndarray(Iterator, size_t N, SliceKind kind)(Slice!(Iterator, N, kind) slice);
Allocates a common n-dimensional array from a slice.
Parameters:
Slice!(Iterator, N, kind) slice slice
Returns:
multidimensional D array
Examples:
import mir.ndslice.topology : iota;
auto slice = iota(3, 4);
auto m = slice.ndarray;
static assert(is(typeof(m) == sizediff_t[][])); // sizediff_t is long for 64 bit platforms
assert(m == [[0, 1, 2, 3], [4, 5, 6, 7], [8, 9, 10, 11]]);
auto makeNdarray(T, Allocator, Iterator, size_t N, SliceKind kind)(auto ref Allocator alloc, Slice!(Iterator, N, kind) slice);
Allocates a common n-dimensional array using data from a slice.
Parameters:
Allocator alloc allocator (optional)
Slice!(Iterator, N, kind) slice slice
Returns:
multidimensional D array
Examples:
import std.experimental.allocator;
import std.experimental.allocator.mallocator;
import mir.ndslice.topology : iota;

auto slice = iota(3, 4);
auto m = Mallocator.instance.makeNdarray!long(slice);

static assert(is(typeof(m) == long[][]));

static immutable ar = [[0L, 1, 2, 3], [4L, 5, 6, 7], [8L, 9, 10, 11]];
assert(m == ar);

foreach (ref row; m)
    Mallocator.instance.dispose(row);
Mallocator.instance.dispose(m);
auto shape(T)(T[] array, ref int err);
Shape of a common n-dimensional array.
Parameters:
T[] array common n-dimensional array
int err error flag passed by reference
Returns:
static array of dimensions type of size_t[n]
Examples:
int err;
size_t[2] shape = [[1, 2, 3], [4, 5, 6]].shape(err);
assert(err == 0);
assert(shape == [2, 3]);

[[1, 2], [4, 5, 6]].shape(err);
assert(err == 1);
Examples:
Slice from ndarray
import mir.ndslice.allocation: slice, shape;
int err;
auto array = [[1, 2, 3], [4, 5, 6]];
auto s = array.shape(err).slice!int;
s[] = [[1, 2, 3], [4, 5, 6]];
assert(s == array);
Slice!(T*, N) stdcUninitSlice(T, size_t N)(size_t[N] lengths...);
Allocates an uninitialized array using core.stdc.stdlib.malloc and creates an n-dimensional slice over it.
Parameters:
size_t[N] lengths list of lengths for each dimension
Returns:
contiguous uninitialized n-dimensional slice
auto stdcSlice(Iterator, size_t N, SliceKind kind)(Slice!(Iterator, N, kind) slice);
Allocates a copy of a slice using core.stdc.stdlib.malloc.
Parameters:
Slice!(Iterator, N, kind) slice n-dimensional slice
Returns:
contiguous n-dimensional slice
void stdcFreeSlice(T, size_t N)(Slice!(T*, N) slice);
Frees memory using core.stdc.stdlib.free.
Parameters:
Slice!(T*, N) slice n-dimensional slice
Examples:
import mir.ndslice.topology: iota;

auto i = iota(3, 4);
auto s = i.stdcSlice;
auto t = s.shape.stdcUninitSlice!size_t;

t[] = s;

assert(t == i);

s.stdcFreeSlice;
t.stdcFreeSlice;
@system auto stdcUninitAlignedSlice(T, size_t N)(size_t[N] lengths, uint alignment);
Allocates an uninitialized aligned array using core.stdc.stdlib.malloc and creates an n-dimensional slice over it.
Parameters:
size_t[N] lengths list of lengths for each dimension
uint alignment memory alignment (bytes)
Returns:
contiguous uninitialized n-dimensional slice
Examples:
auto tensor = stdcUninitAlignedSlice!double([5, 6, 7], 64);
assert(tensor.length == 5);
assert(tensor.elementCount == 5 * 6 * 7);
assert(cast(size_t)(tensor.ptr) % 64 == 0);
static assert(is(typeof(tensor) == Slice!(double*, 3)));
stdcFreeAlignedSlice(tensor);
void stdcFreeAlignedSlice(T, size_t N)(Slice!(T*, N) slice);
Frees aligned memory allocaged by CRuntime.
Parameters:
Slice!(T*, N) slice n-dimensional slice