Package org.ghotibeaun.json.util

Class ByteRange

java.lang.Object
org.ghotibeaun.json.util.ByteRange
public class ByteRange
extends Object
A ByteRange is a collection of bytes that can be assembled and used to determine if a given byte value matches a byte value in the collection. This is especially useful when a byte may be used to determine processor behavior. The ByteRange uses a Builder pattern with static startWith* methods to instantiate the ByteRange with one or more byte values and returns the ByteRange instance. Additional byte values can then be appended to the existing ByteRange using the andAdd* class methods. Using one of the contains* methods will evaluate whether a given byte value is contained in the set of byte values.

Example

Assume that we want to determine if a byte matches one of a range of byte values that represent a hexidecimal character (0-9Aa-Ff). 
 ByteRange hexRange = ByteRange.startWith(0x30, 0x39).addAdd(0x41, 0x46).addAdd(0x61, 0x66);

 byte b = 0x32;
 boolean matches = hexRange.contains(b);
 System.out.println(matches);
 //prints true

 byte[] byteArray = new byte[]{0x33, 0x34, 0x66, 0x62};
 matches = hexRange.containsAll(byteArray);
 System.out.println(matches);
 //prints true
Author:
Jim Earley (xml.jim@gmail.com)

  • Method Summary

    Modifier and Type Method Description
    ByteRange andAdd​(byte addByte)
    Apppend a byte to an existing ByteRange
    ByteRange andAdd​(byte[] byteArray)
    Append an array of bytes to an existing ByteRange
    ByteRange andAddFrom​(byte start, byte end)
    Appends a ByteRange with a set of byte values starting with a start byte value to an end byte value inclusive
    boolean contains​(byte b)
    Evaluates if a given byte value is contained in the ByteRange
    boolean contains​(byte... bytes)
    Evaluates if a set of byte values are contained in the ByteRange.
    boolean containsAll​(byte[] byteArray)
    Evaluates if an array of byte values are contained in the ByteRange.
    int containsCount​(byte[] array)
    Gets a count of the number of bytes that match the values in the ByteRange
    boolean containsSome​(byte[] array)
    Evaluates if any or all of the values in a byteArray are contained in the ByteRange.
    static ByteRange empty()
    Creates an empty ByteRange
    int[] getMatchingByteIndexes​(byte[] array)
    Creates an array of indexes that represent all of the positions in a byte array that match any of the values in the ByteRange
    byte[] getMatchingByteValues​(byte[] array)
    Creates a byte array of values that match any of the byte values in the ByteRange
    static ByteRange startWith​(byte addByte)
    Creates a new ByteRange with a single byte in the range value
    static ByteRange startWith​(byte[] byteArray)
    Initializes a ByteRange with an array of byte values.
    static ByteRange startWith​(byte start, byte end)
    Initializes a ByteRange by creating a range array containing all byte values from a starting byte value to an ending byte value inclusive.
    String toString()  

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Method Details

    • empty

      public static ByteRange empty()
      Creates an empty ByteRange
      Returns:
      an empty ByteRange

    • startWith

      public static ByteRange startWith​(byte[] byteArray)
      Initializes a ByteRange with an array of byte values.
      Parameters:
      byteArray - the array of bytes to add to the range
      Returns:
      An instance of the ByteRange contain the array of bytes
      See Also:
      andAdd(byte[])

    • startWith

      public static ByteRange startWith​(byte start, byte end)
      Initializes a ByteRange by creating a range array containing all byte values from a starting byte value to an ending byte value inclusive.

      Example

      Create a range starting from the 'a' byte value through the 'z' byte value 
       ByteRange.startWith(0x61, 0x7a)
      returns a ByteRange containing all byte values from 0x61 through 0x7a
      Parameters:
      start - the starting byte value. Must be smaller than the ending byte value
      end - the ending byte value. Must be larger than the start byte value
      Returns:
      The instantiated ByteRange containing all values from the start byte value through the end byte value
      Throws:
      NegativeArraySizeException - if the end byte value is smaller than the start byte value
      See Also:
      andAddFrom(byte, byte)

    • startWith

      public static ByteRange startWith​(byte addByte)
      Creates a new ByteRange with a single byte in the range value
      Parameters:
      addByte - the byte value to instantiate the ByteRange with
      Returns:
      the new ByteRange
      See Also:
      andAdd(byte)

    • andAddFrom

      public ByteRange andAddFrom​(byte start, byte end)
      Appends a ByteRange with a set of byte values starting with a start byte value to an end byte value inclusive
      Parameters:
      start - the starting byte value
      end - the ending byte value
      Returns:
      The existing ByteRange with the new values appended to it
      Throws:
      NegativeArraySizeException - if the end byte value is smaller than the start byte value
      See Also:
      startWith(byte, byte)

    • andAdd

      public ByteRange andAdd​(byte addByte)
      Apppend a byte to an existing ByteRange
      Parameters:
      addByte - the byte to add
      Returns:
      the exsting ByteRange with the byte value appended
      See Also:
      startWith(byte)

    • andAdd

      public ByteRange andAdd​(byte[] byteArray)
      Append an array of bytes to an existing ByteRange
      Parameters:
      byteArray - the array of bytes to add
      Returns:
      the existing ByteRange with the array of bytes appended
      See Also:
      startWith(byte[])

    • contains

      public boolean contains​(byte b)
      Evaluates if a given byte value is contained in the ByteRange
      Parameters:
      b - the byte value to evaluate
      Returns:
      true if the byte value is found; false otherwise

    • contains

      public boolean contains​(byte... bytes)
      Evaluates if a set of byte values are contained in the ByteRange.
      Parameters:
      bytes - vararg of byte values
      Returns:
      true if all the byte values are found in the range; false otherwise.
      See Also:
      containsAll(byte[])

    • containsAll

      public boolean containsAll​(byte[] byteArray)
      Evaluates if an array of byte values are contained in the ByteRange.
      Parameters:
      byteArray - the array of bytes
      Returns:
      true if all the byte values are found in the range; false otherwise.

    • containsSome

      public boolean containsSome​(byte[] array)
      Evaluates if any or all of the values in a byteArray are contained in the ByteRange.
      Parameters:
      array - the byte array to evaluate
      Returns:
      true if any of the bytes in the array are contained the ByteRange; false if none of the bytes in the array match.

    • containsCount

      public int containsCount​(byte[] array)
      Gets a count of the number of bytes that match the values in the ByteRange
      Parameters:
      array - the array of bytes to evaluate
      Returns:
      a count of the byte values that match.

    • getMatchingByteIndexes

      public int[] getMatchingByteIndexes​(byte[] array)
      Creates an array of indexes that represent all of the positions in a byte array that match any of the values in the ByteRange
      Parameters:
      array - the array of bytes to evaluate
      Returns:
      an array of index positions that correlate to the positions of bytes in the byte array

    • getMatchingByteValues

      public byte[] getMatchingByteValues​(byte[] array)
      Creates a byte array of values that match any of the byte values in the ByteRange
      Parameters:
      array - the byte array to evaluate
      Returns:
      the byte array of values that match any of the byte values in the ByteRange

    • toString

      public String toString()
      Overrides:
      toString in class Object