If you spot a problem with this page, click here to create a GitHub issue.

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

License:

Apache-2.0

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(T)(T[] array); auto rcslice(T, I)(I[] array) if (!isImplicitlyConvertible!(I[], T[])); 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.rc.array: RCI;
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!(RCI!T, N) uninitRCslice(T, size_t N)(size_t[N] lengths...);

Allocates an n-dimensional reference-counted (thread-safe) slice without memory initialisation.

Parameters:

size_t[N] lengths List of lengths for each dimension.

Returns:

n-dimensional slice

Examples:

import mir.ndslice.slice: Slice;
import mir.rc.array: RCI;
auto tensor = uninitRCslice!int(5, 6, 7);
tensor[] = 1;
assert(tensor.length == 5);
assert(tensor.elementCount == 5 * 6 * 7);
static assert(is(typeof(tensor) == Slice!(RCI!int, 3)));

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:

bitwise .

Examples:

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:

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 mir.date: 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:

bitwise .

Examples:

auto bitarray = bitSlice(100); // allocates 16 bytes total
assert(bitarray.shape == [100]);
assert(bitarray[72] == false);
bitarray[72] = true;
assert(bitarray[72] == true);

Examples:

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

See Also:

stdcSlice, stdcFreeSlice

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

See Also:

stdcUninitSlice, stdcFreeSlice

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

See Also:

stdcSlice, stdcUninitSlice

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:

import mir.ndslice.slice: Slice;
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

See Also:

stdcSlice, stdcUninitSlice

Library Reference

mir.ndslice.allocation

Common utilities

GC Allocation utilities

Ref counted allocation utilities

Custom allocation utilities

CRuntime allocation utilities

Aligned allocation utilities