struct Slice(T)

Creates an empty slice.

slice = Slice(UInt8).empty
slice.size # => 0

Creates a slice to the given pointer, bounded by the given size. This method does not allocate heap memory.

ptr = Pointer.malloc(9) { |i| ('a'.ord + i).to_u8 }

slice = Slice.new(ptr, 3)
slice.size # => 3
slice      # => Bytes[97, 98, 99]

String.new(slice) # => "abc"

Allocates size * sizeof(T) bytes of heap memory initialized to value and returns a slice pointing to that memory.

The memory is allocated by the GC, so when there are no pointers to this memory, it will be automatically freed.

slice = Slice.new(3, 10)
slice # => Slice[10, 10, 10]

Allocates size * sizeof(T) bytes of heap memory initialized to zero and returns a slice pointing to that memory.

The memory is allocated by the GC, so when there are no pointers to this memory, it will be automatically freed.

Only works for primitive integers and floats (UInt8, Int32, Float64, etc.)

slice = Slice(UInt8).new(3)
slice # => Bytes[0, 0, 0]

Allocates size * sizeof(T) bytes of heap memory initialized to the value returned by the block (which is invoked once with each index in the range 0...size) and returns a slice pointing to that memory.

The memory is allocated by the GC, so when there are no pointers to this memory, it will be automatically freed.

slice = Slice.new(3) { |i| i + 10 }
slice # => Slice[10, 11, 12]

Returns a new slice that is offset elements apart from this slice.

slice = Slice.new(5) { |i| i + 10 }
slice # => Slice[10, 11, 12, 13, 14]

slice2 = slice + 2
slice2 # => Slice[12, 13, 14]

Combined comparison operator.

Returns a negative number, 0, or a positive number depending on whether self is less than other, equals other.

It compares the elements of both slices in the same position using the #<=> operator. As soon as one of such comparisons returns a non-zero value, that result is the return value of the comparison.

If all elements are equal, the comparison is based on the size of the arrays.

Bytes[8] <=> Bytes[1, 2, 3] # => 7
Bytes[2] <=> Bytes[4, 2, 3] # => -2
Bytes[1, 2] <=> Bytes[1, 2] # => 0

Returns true if self and other have the same size and all their elements are equal, false otherwise.

Bytes[1, 2] == Bytes[1, 2]    # => true
Bytes[1, 3] == Bytes[1, 2]    # => false
Bytes[1, 2] == Bytes[1, 2, 3] # => false

Returns a new slice that starts at start elements from this slice's start, and of count size.

Raises IndexError if the new slice falls outside this slice.

slice = Slice.new(5) { |i| i + 10 }
slice # => Slice[10, 11, 12, 13, 14]

slice[1, 3]  # => Slice[11, 12, 13]
slice[1, 33] # raises IndexError

Returns a new slice with the elements in the given range.

The first element in the returned slice is self[range.begin] followed by the next elements up to index range.end (or self[range.end - 1] if the range is exclusive). If there are fewer elements in self, the returned slice is shorter than range.size.

a = Slice["a", "b", "c", "d", "e"]
a[1..3] # => Slice["b", "c", "d"]

Negative indices count backward from the end of the slice (-1 is the last element). Additionally, an empty slice is returned when the starting index for an element range is at the end of the slice.

Raises IndexError if the new slice falls outside this slice.

slice = Slice.new(5) { |i| i + 10 }
slice # => Slice[10, 11, 12, 13, 14]

slice[1..3]  # => Slice[11, 12, 13]
slice[1..33] # raises IndexError

Sets the given value at the given index. Returns value.

Negative indices can be used to start counting from the end of the container. Raises IndexError if trying to set an element outside the container's range.

ary = [1, 2, 3]
ary[0] = 5
ary # => [5, 2, 3]

ary[3] = 5 # raises IndexError

Raises if this slice is read-only.

Returns a new slice that starts at start elements from this slice's start, and of count size.

Returns nil if the new slice falls outside this slice.

slice = Slice.new(5) { |i| i + 10 }
slice # => Slice[10, 11, 12, 13, 14]

slice[1, 3]?  # => Slice[11, 12, 13]
slice[1, 33]? # => nil

Returns a new slice with the elements in the given range.

Negative indices count backward from the end of the slice (-1 is the last element). Additionally, an empty slice is returned when the starting index for an element range is at the end of the slice.

Returns nil if the new slice falls outside this slice.

slice = Slice.new(5) { |i| i + 10 }
slice # => Slice[10, 11, 12, 13, 14]

slice[1..3]?  # => Slice[11, 12, 13]
slice[1..33]? # => nil

Returns a deep copy of this slice.

This method allocates memory for the slice copy and stores the return values from calling #clone on each item.

Copies the contents of source into this slice.

Raises IndexError if the destination slice cannot fit the data being transferred.

Copies the contents of this slice into target.

Raises IndexError if the destination slice cannot fit the data being transferred e.g. dest.size < self.size.

src = Slice['a', 'a', 'a']
dst = Slice['b', 'b', 'b', 'b', 'b']
src.copy_to dst
dst             # => Slice['a', 'a', 'a', 'b', 'b']
dst.copy_to src # raises IndexError

Returns a shallow copy of this slice.

This method allocates memory for the slice copy and duplicates the values.

Replaces every element in self with the given value. Returns self.

array = [1, 2, 3, 4]
array.fill(2) # => [2, 2, 2, 2]
array         # => [2, 2, 2, 2]

Raises if this slice is read-only.

Yields each index of self to the given block and then assigns the block's value in that position. Returns self.

Accepts an optional offset parameter, which tells the block to start counting from there.

array = [2, 1, 1, 1]
array.fill { |i| i * i }            # => [0, 1, 4, 9]
array                               # => [0, 1, 4, 9]
array.fill(offset: 3) { |i| i * i } # => [9, 16, 25, 36]
array                               # => [9, 16, 25, 36]

Raises if this slice is read-only.

See Object#hash(hasher)

Writes a hexdump of this slice, assuming it's a Slice(UInt8), to the given io. This method is specially useful for debugging binary data and incoming/outgoing data in protocols.

Returns the number of bytes written to io.

slice = UInt8.slice(97, 62, 63, 8, 255)
slice.hexdump(STDOUT)

Prints:

00000000  61 3e 3f 08 ff                                    a>?..

Returns a hexdump of this slice, assuming it's a Slice(UInt8). This method is specially useful for debugging binary data and incoming/outgoing data in protocols.

slice = UInt8.slice(97, 62, 63, 8, 255)
slice.hexdump # => "00000000  61 3e 3f 08 ff                                    a>?..\n"

Returns a hexstring representation of this slice, assuming it's a Slice(UInt8).

slice = UInt8.slice(97, 62, 63, 8, 255)
slice.hexstring # => "613e3f08ff"

Returns the index of the first appearance of value in self starting from the given offset, or nil if the value is not in self.

[1, 2, 3, 1, 2, 3].index(2, offset: 2) # => 4

Appends this struct's name and instance variables names and values to the given IO.

struct Point
  def initialize(@x : Int32, @y : Int32)
  end
end

p1 = Point.new 1, 2
p1.to_s    # "Point(@x=1, @y=2)"
p1.inspect # "Point(@x=1, @y=2)"

Returns a new slice where elements are mapped by the given block.

slice = Slice[1, 2.5, "a"]
slice.map &.to_s # => Slice["1", "2.5", "a"]

TODO add as constant

Raises if this slice is read-only.

Like #map, but the block gets passed both the element and its index.

Accepts an optional offset parameter, which tells it to start counting from there.

Like #map!, but the block gets passed both the element and its index.

Accepts an optional offset parameter, which tells it to start counting from there.

gems = ["crystal", "pearl", "diamond"]
gems.map_with_index! { |gem, i| "#{i}: #{gem}" }
gems # => ["0: crystal", "1: pearl", "2: diamond"]

Raises if this slice is read-only.

Moves the contents of source into this slice. source and self may overlap; the copy is always done in a non-destructive manner.

Raises IndexError if the destination slice cannot fit the data being transferred.

Moves the contents of this slice into target. target and self may overlap; the copy is always done in a non-destructive manner.

Raises IndexError if the destination slice cannot fit the data being transferred e.g. dest.size < self.size.

src = Slice['a', 'a', 'a']
dst = Slice['b', 'b', 'b', 'b', 'b']
src.move_to dst
dst             # => Slice['a', 'a', 'a', 'b', 'b']
dst.move_to src # raises IndexError

See also: Pointer#move_to.

Returns true if this slice cannot be written to.

Reverses in-place all the elements of self. Returns self.

Raises if this slice is read-only.

Shifts all elements of self to the left n times. Returns self.

a1 = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
a2 = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
a3 = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

a1.rotate!
a2.rotate!(1)
a3.rotate!(3)

a1 # => [1, 2, 3, 4, 5, 6, 7, 8, 9, 0]
a2 # => [1, 2, 3, 4, 5, 6, 7, 8, 9, 0]
a3 # => [3, 4, 5, 6, 7, 8, 9, 0, 1, 2]

Raises if this slice is read-only.

Modifies self by randomizing the order of elements in the collection using the given random number generator. Returns self.

a = [1, 2, 3, 4, 5]
a.shuffle!(Random.new(42)) # => [3, 2, 4, 5, 1]
a                          # => [3, 2, 4, 5, 1]

Raises if this slice is read-only.

Returns the size of this slice.

Slice(UInt8).new(3).size # => 3

Returns a new instance with all elements sorted based on the return value of their comparison method T#<=> (see Comparable#<=>), using a stable sort algorithm.

a = Slice[3, 1, 2]
a.sort # => Slice[1, 2, 3]
a      # => Slice[3, 1, 2]

See #sort! for details on the sorting mechanism.

Raises ArgumentError if the comparison between any two elements returns nil.

Returns a new instance with all elements sorted based on the comparator in the given block, using a stable sort algorithm.

a = Slice[3, 1, 2]
b = a.sort { |a, b| b <=> a }

b # => Slice[3, 2, 1]
a # => Slice[3, 1, 2]

See Indexable::Mutable#sort!(&block : T, T -> U) for details on the sorting mechanism.

Raises ArgumentError if for any two elements the block returns nil.

Sorts all elements in self based on the return value of the comparison method T#<=> (see Comparable#<=>), using a stable sort algorithm.

slice = Slice[3, 1, 2]
slice.sort!
slice # => Slice[1, 2, 3]

This sort operation modifies self. See #sort for a non-modifying option that allocates a new instance.

The sort mechanism is implemented as merge sort. It is stable, which is typically a good default.

Stablility means that two elements which compare equal (i.e. a <=> b == 0) keep their original relation. Stable sort guarantees that [a, b].sort! always results in [a, b] (given they compare equal). With unstable sort, the result could also be [b, a].

If stability is expendable, #unstable_sort! provides a performance advantage over stable sort.

Raises ArgumentError if the comparison between any two elements returns nil.

Sorts all elements in self based on the comparator in the given block, using a stable sort algorithm.

slice = Slice[3, 1, 2]
# This is a reverse sort (forward sort would be `a <=> b`)
slice.sort! { |a, b| b <=> a }
slice # => Slice[3, 2, 1]

The block must implement a comparison between two elements a and b, where a < b outputs a negative value, a == b outputs 0, and a > b outputs a positive value. The comparison operator (Comparable#<=>) can be used for this.

The block's output type must be <= Int32?, but returning an actual nil value is an error.

This sort operation modifies self. See #sort(&block : T, T -> U) for a non-modifying option that allocates a new instance.

The sort mechanism is implemented as merge sort. It is stable, which is typically a good default.

Stablility means that two elements which compare equal (i.e. a <=> b == 0) keep their original relation. Stable sort guarantees that [a, b].sort! always results in [a, b] (given they compare equal). With unstable sort, the result could also be [b, a].

If stability is expendable, #unstable_sort!(&block : T, T -> U) provides a performance advantage over stable sort.

Raises ArgumentError if for any two elements the block returns nil.

Returns a new instance with all elements sorted by the output value of the block. The output values are compared via the comparison method T#<=> (see Comparable#<=>), using a stable sort algorithm.

a = Slice["apple", "pear", "fig"]
b = a.sort_by { |word| word.size }
b # => Slice["fig", "pear", "apple"]
a # => Slice["apple", "pear", "fig"]

If stability is expendable, #unstable_sort_by(&block : T -> _) provides a performance advantage over stable sort.

See Indexable::Mutable#sort_by!(&block : T -> _) for details on the sorting mechanism.

Raises ArgumentError if the comparison between any two comparison values returns nil.

Modifies self by sorting all elements. The given block is called for each element, then the comparison method #<=> is called on the object returned from the block to determine sort order.

a = Slice["apple", "pear", "fig"]
a.sort_by! { |word| word.size }
a # => Slice["fig", "pear", "apple"]

Swaps the elements at index0 and index1. Returns self.

Negative indices can be used to start counting from the end of the container. Raises IndexError if either index is out of bounds.

a = ["first", "second", "third"]
a.swap(1, 2)  # => ["first", "third", "second"]
a             # => ["first", "third", "second"]
a.swap(0, -1) # => ["second", "third", "first"]
a             # => ["second", "third", "first"]
a.swap(2, 3)  # raises IndexError

Raises if this slice is read-only.

Returns an Array with all the elements in the collection.

{1, 2, 3}.to_a # => [1, 2, 3]

Same as #inspect(io).

Returns this slice's pointer.

slice = Slice.new(3, 10)
slice.to_unsafe[0] # => 10

Returns the element at the given index, without doing any bounds check.

Indexable makes sure to invoke this method with index in 0...size, so converting negative indices to positive ones is not needed here.

Clients never invoke this method directly. Instead, they access elements with #[](index) and #[]?(index).

This method should only be directly invoked if you are absolutely sure the index is in bounds, to avoid a bounds check for a small boost of performance.

Sets the element at the given index to value, without doing any bounds check.

Indexable::Mutable makes sure to invoke this method with index in 0...size, so converting negative indices to positive ones is not needed here.

Clients never invoke this method directly. Instead, they modify elements with #[]=(index, value).

This method should only be directly invoked if you are absolutely sure the index is in bounds, to avoid a bounds check for a small boost of performance.

Returns a new instance with all elements sorted based on the return value of their comparison method T#<=> (see Comparable#<=>), using an unstable sort algorithm.

a = Slice[3, 1, 2]
a.sort # => Slice[1, 2, 3]
a      # => Slice[3, 1, 2]

See Indexable::Mutable#unstable_sort! for details on the sorting mechanism.

Raises ArgumentError if the comparison between any two elements returns nil.

Returns a new instance with all elements sorted based on the comparator in the given block, using an unstable sort algorithm.

a = Slice[3, 1, 2]
b = a.unstable_sort { |a, b| b <=> a }

b # => Slice[3, 2, 1]
a # => Slice[3, 1, 2]

See Indexable::Mutable#unstable_sort!(&block : T, T -> U) for details on the sorting mechanism.

Raises ArgumentError if for any two elements the block returns nil.

Sorts all elements in self based on the return value of the comparison method T#<=> (see Comparable#<=>), using an unstable sort algorithm..

slice = Slice[3, 1, 2]
slice.unstable_sort!
slice # => Slice[1, 2, 3]

This sort operation modifies self. See #unstable_sort for a non-modifying option that allocates a new instance.

The sort mechanism is implemented as introsort. It does not guarantee stability between equally comparing elements. This offers higher performance but may be unexpected in some situations.

Stablility means that two elements which compare equal (i.e. a <=> b == 0) keep their original relation. Stable sort guarantees that [a, b].sort! always results in [a, b] (given they compare equal). With unstable sort, the result could also be [b, a].

If stability is necessary, use #sort! instead.

Raises ArgumentError if the comparison between any two elements returns nil.

Sorts all elements in self based on the comparator in the given block, using an unstable sort algorithm.

slice = Slice[3, 1, 2]
# This is a reverse sort (forward sort would be `a <=> b`)
slice.unstable_sort! { |a, b| b <=> a }
slice # => Slice[3, 2, 1]

The block must implement a comparison between two elements a and b, where a < b outputs a negative value, a == b outputs 0, and a > b outputs a positive value. The comparison operator (Comparable#<=>) can be used for this.

The block's output type must be <= Int32?, but returning an actual nil value is an error.

This sort operation modifies self. See #unstable_sort(&block : T, T -> U) for a non-modifying option that allocates a new instance.

The sort mechanism is implemented as introsort. It does not guarantee stability between equally comparing elements. This offers higher performance but may be unexpected in some situations.

Stablility means that two elements which compare equal (i.e. a <=> b == 0) keep their original relation. Stable sort guarantees that [a, b].sort! always results in [a, b] (given they compare equal). With unstable sort, the result could also be [b, a].

If stability is necessary, use #sort!(&block : T, T -> U) instead.

Raises ArgumentError if for any two elements the block returns nil.

Returns a new instance with all elements sorted by the output value of the block. The output values are compared via the comparison method #<=> (see Comparable#<=>), using an unstable sort algorithm.

a = Slice["apple", "pear", "fig"]
b = a.unstable_sort_by { |word| word.size }
b # => Slice["fig", "pear", "apple"]
a # => Slice["apple", "pear", "fig"]

If stability is necessary, use #sort_by(&block : T -> _) instead.

See Indexable::Mutable#unstable_sort!(&block : T -> _) for details on the sorting mechanism.

Raises ArgumentError if the comparison between any two comparison values returns nil.

:ditto:

This method does not guarantee stability between equally sorting elements. Which results in a performance advantage over stable sort.

Yields the current element at the given index and updates the value at that index with the block's value. Returns the new value.

Raises IndexError if trying to set an element outside the array's range.

array = [1, 2, 3]
array.update(1) { |x| x * 2 } # => 4
array                         # => [1, 4, 3]
array.update(5) { |x| x * 2 } # raises IndexError

Raises if this slice is read-only.

Creates a new Slice with the given args. The type of the slice will be the union of the type of the given args.

The slice is allocated on the heap.

slice = Slice[1, 'a']
slice[0]    # => 1
slice[1]    # => 'a'
slice.class # => Slice(Char | Int32)

If T is a Number then this is equivalent to Number.slice (numbers will be coerced to the type T)

See also: Number.slice.