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.

Common utilities

shape Returns a shape of a common n-dimensional array.

GC Allocation utilities

Function Name Description
slice Allocates a slice using GC.
bitSlice GC-Allocates a bitwise packed n-dimensional boolean slice.
ndarray Allocates a common n-dimensional array from a slice.
uninitSlice Allocates an uninitialized slice using GC.

Ref counted allocation utilities

rcslice Allocates an n-dimensional reference-counted (thread-safe) slice.
bitRcslice Allocates a bitwise packed n-dimensional reference-counted (thread-safe) boolean slice.
mininitRcslice Allocates a minimally initialized n-dimensional reference-counted (thread-safe) slice.

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!(RCI!T, N) rcslice(T, size_t N)(size_t[N] lengths...);

Slice!(RCI!T, N) rcslice(T, size_t N)(size_t[N] lengths, T init);

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

auto rcslice(size_t dim, Slices...)(Concatenation!(dim, Slices) concatenation);
Allocates an n-dimensional reference-counted (thread-safe) 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:
import mir.ndslice.slice: Slice;
import mir.rc.array: RCI;
auto tensor = rcslice!int(5, 6, 7);
assert(tensor.length == 5);
assert(tensor.elementCount == 5 * 6 * 7);
static assert(is(typeof(tensor) == Slice!(RCI!int, 3)));

// creates duplicate using `rcslice`
auto dup = tensor.rcslice;
assert(dup == tensor);
Examples:
import mir.ndslice.slice: Slice;
import mir.rc.array: RCI;
auto tensor = rcslice([2, 3], 5);
assert(tensor.elementCount == 2 * 3);
assert(tensor[1, 1] == 5);

import mir.rc.array;
static assert(is(typeof(tensor) == Slice!(RCI!int, 2)));
Examples:
import mir.ndslice.slice: Slice;
import mir.ndslice.topology : iota;
import mir.ndslice.concatenation;
auto tensor = concatenation([2, 3].iota, [3].iota(6)).rcslice;
assert(tensor == [3, 3].iota);

static assert(is(typeof(tensor) == Slice!(RCI!ptrdiff_t, 2)));
Slice!(FieldIterator!(BitField!(RCI!size_t)), N) bitRcslice(size_t N)(size_t[N] lengths...);
Allocates a bitwise packed n-dimensional reference-counted (thread-safe) boolean slice.
Parameters:
size_t[N] lengths List of lengths for each dimension.
Returns:
n-dimensional bitwise rcslice
See Also:
Examples:
1D
auto bitarray = 100.bitRcslice; // allocates 16 bytes total (plus RC context)
assert(bitarray.shape == cast(size_t[1])[100]);
assert(bitarray[72] == false);
bitarray[72] = true;
assert(bitarray[72] == true);
Examples:
2D
auto bitmatrix = bitRcslice(20, 6); // allocates 16 bytes total (plus RC context)
assert(bitmatrix.shape == cast(size_t[2])[20, 6]);
assert(bitmatrix[3, 4] == false);
bitmatrix[3, 4] = true;
assert(bitmatrix[3, 4] == true);
Slice!(RCI!T, N) mininitRcslice(T, size_t N)(size_t[N] lengths...);
Allocates a minimally initialized n-dimensional reference-counted (thread-safe) slice.
Parameters:
size_t[N] lengths list of lengths for each dimension
Returns:
contiguous minimally initialized n-dimensional reference-counted (thread-safe) slice
Examples:
import mir.ndslice.slice: Slice;
import mir.rc.array: RCI;
auto tensor = mininitRcslice!int(5, 6, 7);
assert(tensor.length == 5);
assert(tensor.elementCount == 5 * 6 * 7);
static assert(is(typeof(tensor) == Slice!(RCI!int, 3)));
template slice(Args...) if (Args.length)
GC-Allocates an n-dimensional slice.
Examples:
import mir.ndslice.slice: Slice;
auto tensor = slice!int(5, 6, 7);
assert(tensor.length == 5);
assert(tensor.length!1 == 6);
assert(tensor.elementCount == 5 * 6 * 7);
static assert(is(typeof(tensor) == Slice!(int*, 3)));
Examples:
2D DataFrame example
import mir.ndslice.slice;
import mir.ndslice.allocation: slice;

import std.datetime.date;

auto dataframe = slice!(double, Date, string)(4, 3);
assert(dataframe.length == 4);
assert(dataframe.length!1 == 3);
assert(dataframe.elementCount == 4 * 3);

static assert(is(typeof(dataframe) ==
    Slice!(double*, 2, Contiguous, Date*, string*)));

// Dataframe labels are contiguous 1-dimensional slices.

// Fill row labels
dataframe.label[] = [
    Date(2019, 1, 24),
    Date(2019, 2, 2),
    Date(2019, 2, 4),
    Date(2019, 2, 5),
];

assert(dataframe.label!0[2] == Date(2019, 2, 4));

// Fill column labels
dataframe.label!1[] = ["income", "outcome", "balance"];

assert(dataframe.label!1[2] == "balance");

// Change label element
dataframe.label!1[2] = "total";
assert(dataframe.label!1[2] == "total");

// Attach a newly allocated label
dataframe.label!1 = ["Income", "Outcome", "Balance"].sliced;

assert(dataframe.label!1[2] == "Balance");
alias LabelTypes = Args[1 .. __dollar];
alias T = Args[0];
Slice!(T*, N, Contiguous, Pointers!LabelTypes) slice(size_t N)(size_t[N] lengths...)
if (N >= LabelTypes.length);

Slice!(T*, N, Contiguous, Pointers!LabelTypes) slice(size_t N)(size_t[N] lengths, T init)
if (N >= LabelTypes.length);
Parameters:
size_t[N] lengths List of lengths for each dimension.
T init Value to initialize with (optional).
Returns:
initialzed n-dimensional slice
Slice!(T*, N) slice(size_t N, T)(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);
GC-Allocates an n-dimensional slice.
Parameters:
size_t[N] lengths List of lengths for each dimension.
T init Value to initialize with (optional).
Returns:
initialzed n-dimensional slice
Examples:
auto tensor = slice([2, 3], 5);
assert(tensor.elementCount == 2 * 3);
assert(tensor[1, 1] == 5);

// creates duplicate using `slice`
auto dup = tensor.slice;
assert(dup == tensor);
Examples:
import mir.ndslice.slice: Slice;
import mir.ndslice.topology : iota;
import mir.ndslice.concatenation;
auto tensor = concatenation([2, 3].iota, [3].iota(6)).slice;
assert(tensor == [3, 3].iota);

static assert(is(typeof(tensor) == Slice!(ptrdiff_t*, 2)));
Slice!(FieldIterator!(BitField!(size_t*)), N) bitSlice(size_t N)(size_t[N] lengths...);
GC-Allocates a bitwise packed n-dimensional boolean slice.
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...);
GC-Allocates an uninitialized n-dimensional slice.
Parameters:
size_t[N] lengths list of lengths for each dimension
Returns:
contiguous uninitialized n-dimensional slice
Examples:
import mir.ndslice.slice: Slice;
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);
GC-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:
import mir.ndslice.slice: Slice;
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 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