struct Slice(T)
inherits Struct
¶
A Slice is a Pointer with an associated size.
While a pointer is unsafe because no bound checks are performed when reading from and writing to it,
reading from and writing to a slice involve bound checks.
In this way, a slice is a safe alternative to Pointer.
A Slice can be created as read-only: trying to write to it
will raise. For example the slice of bytes returned by
String#to_slice is read-only.
Included modules
Comparable
Indexable
Class methods¶
.new(pointer : Pointer(T), size : Int, *, read_only = false)
¶
(pointer : Pointer(T), size : Int, *, read_only = false)
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"
.new(size : Int, value : T, *, read_only = false)
¶
(size : Int, value : T, *, read_only = false)
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]
.new(size : Int, *, read_only = false)
¶
(size : Int, *, read_only = false)
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]
.new(size : Int, *, read_only = false
¶
(size : Int, *, read_only = false
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]
Methods¶
#+(offset : Int)
¶
(offset : Int)
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]
#<=>(other : Slice(U)) forall U
¶
(other : Slice(U)) forall U
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
#==(other : Slice(U)) : Bool forall U
¶
(other : Slice(U)) : Bool forall U
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
#[](range : Range)
¶
(range : Range)
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.
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
#[](start : Int, count : Int)
¶
(start : Int, count : Int)
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
#[]=(index : Int, value : T)
¶
(index : Int, value : T)
Sets the given value at the given index.
Negative indices can be used to start counting from the end of the slice.
Raises IndexError if trying to set an element outside the slice's range.
slice = Slice.new(5) { |i| i + 10 }
slice[0] = 20
slice[-1] = 30
slice # => Slice[20, 11, 12, 13, 30]
slice[10] = 1 # raises IndexError
#[]?(start : Int, count : Int)
¶
(start : Int, count : Int)
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
#[]?(range : Range)
¶
(range : Range)
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
#clone
¶
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.
#copy_from(source : self)
¶
(source : self)
Copies the contents of source into this slice.
Raises IndexError if the destination slice cannot fit the data being transferred.
#copy_to(target : self)
¶
(target : self)
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
#dup
¶
Returns a shallow copy of this slice.
This method allocates memory for the slice copy and duplicates the values.
#hexdump
¶
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"
#hexdump(io : IO)
¶
(io : IO)
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>?..
#hexstring
¶
Returns a hexstring representation of this slice, assuming it's
a Slice(UInt8).
slice = UInt8.slice(97, 62, 63, 8, 255)
slice.hexstring # => "613e3f08ff"
#inspect(io : IO) : Nil
¶
(io : IO) : Nil
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)"
#map(*, read_only = false, &block : T -> U) forall U
¶
(*, read_only = false, &block : T -> U) forall U
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"]
#map!
¶
Invokes the given block for each element of self, replacing the element
with the value returned by the block. Returns self.
slice = Slice[1, 2, 3]
slice.map! { |x| x * x }
slice # => Slice[1, 4, 9]
#map_with_index(offset = 0, *, read_only = false, &block : T, Int32 -> U) forall U
¶
(offset = 0, *, read_only = false, &block : T, Int32 -> U) forall U
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.
#map_with_index!(offset = 0, &block : T, Int32 -> T)
¶
(offset = 0, &block : T, Int32 -> T)
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.
#move_from(source : self)
¶
(source : self)
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.
#move_to(target : self)
¶
(target : self)
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.
#sort : Slice(T)
¶
: Slice(T)
Returns a new slice with all elements sorted based on the return value of
their comparison method <=>
a = Slice[3, 1, 2]
a.sort # => Slice[1, 2, 3]
a # => Slice[3, 1, 2]
#sort(&block : T, T -> U) : Slice(T) forall U
¶
(&block : T, T -> U) : Slice(T) forall U
Returns a new slice with all elements sorted based on the comparator in the given block.
The block must implement a comparison between two elements a and b,
where a < b returns -1, a == b returns 0, and a > b returns 1.
The comparison operator <=> can be used for this.
a = Slice[3, 1, 2]
b = a.sort { |a, b| b <=> a }
b # => Slice[3, 2, 1]
a # => Slice[3, 1, 2]
#sort! : Slice(T)
¶
: Slice(T)
Modifies self by sorting all elements based on the return value of their
comparison method <=>
a = Slice[3, 1, 2]
a.sort!
a # => Slice[1, 2, 3]
#sort!(&block : T, T -> U) : Slice(T) forall U
¶
(&block : T, T -> U) : Slice(T) forall U
Modifies self by sorting all elements based on the comparator in the given
block.
The given block must implement a comparison between two elements
a and b, where a < b returns -1, a == b returns 0,
and a > b returns 1.
The comparison operator <=> can be used for this.
a = Slice[3, 1, 2]
a.sort! { |a, b| b <=> a }
a # => Slice[3, 2, 1]
#sort_by(&block : T -> _) : Slice(T)
¶
(&block : T -> _) : Slice(T)
Returns a new array with all elements sorted. 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"]
b = a.sort_by { |word| word.size }
b # => Slice["fig", "pear", "apple"]
a # => Slice["apple", "pear", "fig"]
#sort_by!(&block : T -> _) : Slice(T)
¶
(&block : T -> _) : Slice(T)
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"]
#to_a
¶
Returns an Array with all the elements in the collection.
{1, 2, 3}.to_a # => [1, 2, 3]
#to_unsafe : Pointer(T)
¶
: Pointer(T)
Returns this slice's pointer.
slice = Slice.new(3, 10)
slice.to_unsafe[0] # => 10
#unsafe_fetch(index : Int)
¶
(index : Int)
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.
Macros¶
[](*args, read_only = false)
¶
(*args, read_only = false)
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.