org.eclipse.january.dataset

## Class Slice

- java.lang.Object
- - org.eclipse.january.dataset.Slice

- All Implemented Interfaces:
    Serializable, Cloneable

      public class Slice
      extends Object
      implements Cloneable, Serializable

  The `Slice` class represents the set of indices (start, stop, step), that are used to extract specifics subsets of `Dataset`.
  The start argument default to 0, stop argument default to the stop argument default to the end of the dimension that the slice is applied to, and the default argument for the step is 1.
  The start index is inclusive, for example, if we want to get data from index 1, so sliceData will be [2,3] :

       final Dataset onedData = DatasetFactory.createFromObject(new int[]{1,2,3});
       Dataset sliceData = onedData.getSlice(new Slice(1, null, null));

  If Slice is specified with only one argument, this will be the stop index which is exclusive. In this case sliceData will be [1,2] :

       final Dataset onedData = DatasetFactory.createFromObject(new int[]{1,2,3});
       Dataset sliceData = onedData.getSlice(new Slice(2));

  To create a 1D Slice, so sliceData is : [6, 5, 4], we will do :

       final Dataset sliceData = DatasetFactory.createFromObject(new int[]{10,9,8,7,6,5,4,3,2,1,0});
       Dataset newOnedData = sliceData.getSlice(new Slice(4, 7, 1));

  For more informations, see the sliceFrom1D example in SlicingExamples.
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Slice()` Constructs a Slice object with the start and the stop value representing the entirety of the sliced dimension of the Dataset.
    `Slice(Integer stop)` Constructs a Slice object with, by default the start set to 0 and with a step of 1.
    `Slice(Integer start, Integer stop)` Constructs a Slice object with, by default a step of 1.
    `Slice(Integer start, Integer stop, Integer step)` Constructs a Slice object on which it is possible to chooe the start, the stop and the step.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `appendSliceToString(StringBuilder s, int len, int beg, int end, int del)` Append a string representation of the Slice comparable to the Python representation.
    `Slice` | `clone()` Creates a deep copy of the Slice.
    `static void` | `convertFromSlice(Slice[] slice, int[] shape, int[] start, int[] stop, int[] step)` Populates given start, stop, step arrays from given slice array
    `static Slice[]` | `convertFromString(String sliceString)` Converts string in a Slice array
    `static Slice[]` | `convertToSlice(int[] start, int[] stop, int[] step)` Converts a set of integer arrays in a slice array
    `static String` | `createString(int[] shape, int[] start, int[] stop, int[] step)` Creates a string representing the slice taken from given shape
    `static String` | `createString(Slice... slices)` Creates a string representation of slices.
    `Slice` | `flip()` Flips the Slice direction, after this operation, the slice begins at previous end point, steps in the opposite direction, and finishes at the previous start point.
    `int` | `getEnd()` Returns the last value inside of Slice.
    `int` | `getLength()` Returns the maximum value of the slice.
    `int` | `getNumSteps()` Returns the number of steps inside of the Slice
    `int` | `getNumSteps(int beg, int end)` Returns the number of steps inside of the Slice from a point to an other point minus 1 because this is an exclusive index
    `int` | `getPosition(int n)` Returns the index of the n-th step inside of the slice
    `Integer` | `getStart()` Returns the starting index of the slice.
    `int` | `getStep()` Returns the step of the slice.
    `Integer` | `getStop()` Returns the stopping index of the slice.
    `boolean` | `isSliceComplete()` Returns `true` if the slice has a maximum size equal to the current size, else `false`.
    `Slice` | `setLength(int length)` Sets the maximal dimensions length of the Slice.
    `boolean` | `setPosition(int beg)` Move the start and end to an other index keeping the same step and the same gap between the two values
    `void` | `setStart(Integer start)` Set the starting index of the slice.
    `void` | `setStep(int step)` Set the step size inside of the Slice.
    `void` | `setStop(Integer stop)` Set the stopping index of the slice.
    `String` | `toString()` Returns a string construction of the slice with the Python form.

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Slice

          public Slice()

      Constructs a Slice object with the start and the stop value representing the entirety of the sliced dimension of the Dataset.

    - #### Slice

          public Slice(Integer stop)

      Constructs a Slice object with, by default the start set to 0 and with a step of 1. If the stop point of the Slice is `null`, it will be set to the stop argument default to the end of the dimension that the slice is applied to.
      Parameters:
        `stop` - the stop point of the Slice

    - #### Slice

          public Slice(Integer start,
                       Integer stop)

      Constructs a Slice object with, by default a step of 1. If the start point of the Slice is `null`, it will be set automatically to 0. If the stop point of the Slice is `null`, it will be set to the stop argument default to the end of the dimension that the slice is applied to.
      Parameters:
        `start` - the start point of the Slice
        `stop` - the stop point of the Slice

    - #### Slice

          public Slice(Integer start,
                       Integer stop,
                       Integer step)

      Constructs a Slice object on which it is possible to chooe the start, the stop and the step. If the start point of the Slice is `null`, it will be set automatically to 0. If the stop point of the Slice is `null`, it will be set to the stop argument default to the end of the dimension that the slice is applied to. If the the wanted step is set to `null`, it will be set by default to 1.
      Parameters:
        `start` - the start point of the Slice, may be `null`
        `stop` - the stop point of the Slice, may be `null`
        `step` - the step wanted to browse the Dataset, may be `null`

  - ### Method Detail

    - #### clone

          public Slice clone()

      Creates a deep copy of the Slice.
      Overrides:
        `clone` in class `Object`
      Returns:
        New Slice with the current Slice properties

    - #### setLength

          public Slice setLength(int length)

      Sets the maximal dimensions length of the Slice.
      Parameters:
        `length` - Wanted size of dimensions
      Returns:
        The Slice which the method is called on

    - #### isSliceComplete

          public boolean isSliceComplete()

      Returns `true` if the slice has a maximum size equal to the current size, else `false`.
      Returns:
        `true` if slice represents complete dimension, `false` in the other case.

    - #### getLength

          public int getLength()

      Returns the maximum value of the slice.
      Returns:
        Maximum value of the slice

    - #### getStart

          public Integer getStart()

      Returns the starting index of the slice.
      Returns:
        Start point of the slice

    - #### getStop

          public Integer getStop()

      Returns the stopping index of the slice.
      Returns:
        Stop point of the slice

    - #### getStep

          public int getStep()

      Returns the step of the slice.
      Returns:
        Step of the slice

    - #### setStart

          public void setStart(Integer start)

      Set the starting index of the slice. If the start point of the Slice is `null`, it will be set automatically to 0.
      Parameters:
        `start` - Starting index of the Slice, may be `null`

    - #### setStop

          public void setStop(Integer stop)

      Set the stopping index of the slice. If the stop point of the Slice is `null`, it will be set to the stop argument default to the end of the dimension that the slice is applied to.
      Parameters:
        `stop` - Stopping index of the Slice, may be `null`

    - #### setPosition

          public boolean setPosition(int beg)

      Move the start and end to an other index keeping the same step and the same gap between the two values
      Parameters:
        `beg` - New starting point
      Returns:
        Return `true` if the end was reached, `false` in the other case.

    - #### getPosition

          public int getPosition(int n)

      Returns the index of the n-th step inside of the slice
      Parameters:
        `n` - Wanted step index in the slice
      Returns:
        Return the index of the step inside of the Slice

    - #### setStep

          public void setStep(int step)

      Set the step size inside of the Slice. If the the wanted step is set to `null`, it will be set by default to 1.
      Parameters:
        `step` - New wanted step, may be `null`

    - #### appendSliceToString

          public static void appendSliceToString(StringBuilder s,
                                                 int len,
                                                 int beg,
                                                 int end,
                                                 int del)

      Append a string representation of the Slice comparable to the Python representation.
      Parameters:
        `s` - String builder
        `len` - Maximal length of the Slice, or -1 if not set
        `beg` - Start index of the Slice
        `end` - Stop index of the Slice
        `del` - Step of the Slice

    - #### toString

          public String toString()

      Returns a string construction of the slice with the Python form.
      Overrides:
        `toString` in class `Object`
      Returns:
        Constructed String.

    - #### getNumSteps

          public int getNumSteps()

      Returns the number of steps inside of the Slice
      Returns:
        Number of steps inside of the Slice

    - #### getNumSteps

          public int getNumSteps(int beg,
                                 int end)

      Returns the number of steps inside of the Slice from a point to an other point minus 1 because this is an exclusive index
      Parameters:
        `beg` - Starting point
        `end` - (exclusive) Stopping point
      Returns:
        Numbers of steps between the 2 limits.

    - #### getEnd

          public int getEnd()

      Returns the last value inside of Slice.
      Returns:
        Last value in the slice, it can be a lower value than the start if the step is going backward

    - #### flip

          public Slice flip()

      Flips the Slice direction, after this operation, the slice begins at previous end point, steps in the opposite direction, and finishes at the previous start point.

      Note : the stop value may not be preserved across two flips

      Returns:
        Flipped Slice.

    - #### convertFromSlice

          public static void convertFromSlice(Slice[] slice,
                                              int[] shape,
                                              int[] start,
                                              int[] stop,
                                              int[] step)

      Populates given start, stop, step arrays from given slice array
      Parameters:
        `slice` - Input array of Slices wanted to convert
        `shape` - Input array of Slices shapes
        `start` - Output array of Slices starts
        `stop` - Output array of Slices stops
        `step` - Output array of Slices steps

    - #### convertToSlice

          public static Slice[] convertToSlice(int[] start,
                                               int[] stop,
                                               int[] step)

      Converts a set of integer arrays in a slice array
      Parameters:
        `start` - Array of Slices starts
        `stop` - Array of Slices stops
        `step` - Array of Slices steps
      Returns:
        Slice array corresponding to the starts, stops and steps arrays entered.

    - #### convertFromString

          public static Slice[] convertFromString(String sliceString)

      Converts string in a Slice array
      Parameters:
        `sliceString` - String of the Slice array
      Returns:
        Slice array created from the given string

    - #### createString

          public static String createString(int[] shape,
                                            int[] start,
                                            int[] stop,
                                            int[] step)

      Creates a string representing the slice taken from given shape
      Parameters:
        `shape` - Array of Slices shapes
        `start` - Array of Slices starts
        `stop` - Array of Slices stops
        `step` - Array of Slices steps
      Returns:
        String representation of the Slice

    - #### createString

          public static String createString(Slice... slices)

      Creates a string representation of slices.
      Parameters:
        `slices` - Wanted Slices to put inside of the string representation
      Returns:
        Return the string representation of the Slices entered.

Copyright © 2014–2022 Eclipse Foundation. All rights reserved.