Package org.ghotibeaun.json.util

Class ByteSequence

java.lang.Object
org.ghotibeaun.json.util.ByteSequence
public class ByteSequence
extends Object
A sequence of ByteRange objects that represent a sequential set of characters that have to appear in a certain order. This uses a builder pattern that initiates a ByteSequence from either an emptySequence() or one of several static *start* methods to initiate the sequence, all of which return a ByteSequence instance with the set of byte values for the first sequence item. Additional sequences of ByteRanges can be applied with one of the followedBy* methods that append the additional bytes to a subsequent sequence item. Note: it doesn't attempt to remove duplicate values. Once a Sequence is built, the matches(byte) or matches(byte[]) can be used to evaluate if a byte value matches the selected sequence. For example, assume that we want to evaluate whether an array of byte values is the equivalent to a true boolean value. We could build a sequence like this: 
 ByteSequence.startsWith(ByteConstants.t).followedBy(ByteConstants.r).followedBy(ByteConstants.u.followedBy(ByteConstants.e);
Alternatively, you could use String.getBytes() and use the withStartingSequence(byte[]) instead 
 byte[] trueBytes = "true".getBytes();
 ByteSequence.withStartingSequence(trueBytes);
Note that there is a difference between withStartingSequence(byte[]), and startsWithAnyOf(byte...) or startsWithRange(ByteRange). The first creates individual sequence items for each byte element; the latter two methods only create the initial sequence item, with ByteRanges of byte values that can appear in the first sequence item.
Author:
Jim Earley

  • Method Details

    • emptySequence

      public static ByteSequence emptySequence()
      Creates a new ByteSequence with no sequence items
      Returns:
      a new ByteSequence

    • startsWith

      public static ByteSequence startsWith​(byte b)
      Initializes a ByteSequence with the first sequence item as a single byte value
      Parameters:
      b - the byte value to add to the first sequence item
      Returns:
      the ByteSequence

    • withStartingSequence

      public static ByteSequence withStartingSequence​(byte[] byteSequence)
      Initializes a new ByteSequence with each element in the byte array as separate sequence items. This is the equivalant to 
       ByteSequence.startsWith(byteValue[0]).followedBy(byteValue[1]).followedBy(byteValue[n])...
      Parameters:
      byteSequence - the byte array to build the sequence items.
      Returns:
      the current ByteSequence initialized with a set of sequence items corresponding to the byte array elements

    • startsWith

      public static ByteSequence startsWith​(ByteSequence sequence)
      Initializes a new ByteSequence using another ByteSequence's items
      Parameters:
      sequence - The ByteSequence used to populate this instance
      Returns:
      a new ByteSequence

    • startsWithRange

      public static ByteSequence startsWithRange​(ByteRange range)
      Initializes a new ByteSequence with a ByteRange of byte values. All of the values in that range will be included in the first sequence item.
      Parameters:
      range - The ByteRange containing the byte values to include in the first sequence item
      Returns:
      a new ByteSequence.

    • startsWithRangeFrom

      public static ByteSequence startsWithRangeFrom​(byte start, byte end)
      Initializesa new ByteSequence by creating a first sequence item containing byte values starting from one value up to an end byte value, inclusive. This is the equivalent of creating a new ByteRange using ByteRange.startWith(byte, byte) and including it using startsWithRange(ByteRange). Example: Assume a starting byte for 'a' (0x61), and an ending byte for 'z' (0x7a). This creates a ByteRange containing byte values for a through z inclusively.
      Parameters:
      start - the starting byte value
      end - the ending byte value. The value must be greater than the starting by.
      Returns:
      A new ByteSequence

    • startsWithAnyOf

      public static ByteSequence startsWithAnyOf​(byte... anyOf)
      Initializes a new ByteSequence containing a variable number of byte values
      Parameters:
      anyOf - a variable number of byte values that will be included as a single ByteRange in the first sequence
      Returns:
      the initialized ByteSequence

    • followedBy

      public ByteSequence followedBy​(byte b)
      Adds a new ByteRange sequence to an existing ByteSequence
      Parameters:
      b - the byte value to be used in the ByteRange for the new sequence
      Returns:
      the existing ByteSequence with the new sequence added

    • followedByAnyOf

      public ByteSequence followedByAnyOf​(byte... anyOf)
      Adds a new ByteRange sequence to an existing ByteSequence
      Parameters:
      anyOf - a variable number of byte values that will be included as a single ByteRange in the current sequence
      Returns:
      the existing ByteSequence with the new sequence added

    • followedByRangeFrom

      public ByteSequence followedByRangeFrom​(byte start, byte end)
      Adds a new ByteRange sequence containing all bytes from a given start and end value to an existing ByteSequence
      Parameters:
      start - The starting byte value
      end - The ending byte value. Byte value must be greater than the starting byte value
      Returns:
      the existing ByteSequence with the new sequence added

    • followedBySequenceOf

      public ByteSequence followedBySequenceOf​(ByteSequence sequence)
      Appends all of the sequence items from another ByteSequence into the current ByteSequence
      Parameters:
      sequence - The other ByteSequence
      Returns:
      the existing ByteSequence with the new sequences from the other ByteSequence added

    • followedByRange

      public ByteSequence followedByRange​(ByteRange range)
      Adds a new ByteRange sequence to the existing ByteSequence
      Parameters:
      range - The ByteRange
      Returns:
      the existing ByteSequence with the new sequence added

    • matches

      public boolean matches​(byte b)
      Matches the byte against the current sequence
      Parameters:
      b - the byte to match
      Returns:
      true if the sequence only has one item AND, the byte value is found in that sequence's ByteRange. Otherwise, it will return false

    • matches

      public boolean matches​(byte[] bytes)
      Matches a sequence of bytes in order against the ByteSequence for a match
      Parameters:
      bytes - the byte array containing the sequence of bytes to match
      Returns:
      true if the ByteSequence size matches the length the byte array AND, if all byte array elements are contained in the corresponding sequence's ByteRange

    • toString

      public String toString()
      Overrides:
      toString in class Object