Class Bitspeak


  • public class Bitspeak
    extends Object
    Represents a bitspeak format (BS-6 or BS-8) for encoding a stream of bytes to pronounceable text, and back again.

    A bitspeak format can be retrieved using the factory methods bs6() or bs8(). Then, using a format, convert a byte array to a bitspeak string by calling its encode(byte[]) method. The resulting string can be converted back to the original byte array by calling decode(String).

    It is also possible to convert streams of bitspeak characters or byte arrays using newEncodeStream(InputStream) or newDecodeStream(Reader).

    By default, the BS-6 and BS-8 encoders will insert a word delimiter (-) every 6 characters, and a line delimiter every 160 characters written to the output. This can be configured using withConfig(BitspeakConfig).

    Examples

    Example Output
    Bitspeak.bs6().encode(new byte[] { 1 }) "pak"
    Bitspeak.bs8().encode(new byte[] { 1 }) "pe"
    Bitspeak.bs6().encode(new byte[] { 1, 2 }) "pakat"
    Bitspeak.bs8().encode(new byte[] { 1, 2 }) "pepi"
    Bitspeak.bs6().encode(new byte[] { 1, 2, 3 }) "pakatape"
    Bitspeak.bs8().encode(new byte[] { 1, 2, 3 }) "pepipo"
    Bitspeak.bs6().encode(new byte[] { 1, 2, 3, 4 }) "pakatape-pup"
    Bitspeak.bs8().encode(new byte[] { 1, 2, 3, 4 }) "pepipopu"
    Bitspeak.bs6().encode(new byte[] { -34, -83, -66, -17, 1, 2, 3 }) "nelinizi-semabapi-pam"
    Bitspeak.bs8().encode(new byte[] { -34, -83, -66, -17, 1, 2, 3 }) "yawluir-awsowpep-ipo"
    See Also:
    https://github.com/MaiaVictor/Bitspeak
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static Bitspeak bs6()
      Retrieve a bitspeak format (BS-6) where every 2 characters represents 6 bits of data.
      static Bitspeak bs8()
      Retrieve a bitspeak format where every 8 bits (1 byte) is converted into a consonant and vowel pair, each up two 2 characters in length.
      byte[] decode​(char[] bitspeak)
      Convert the given bitspeak-encoded char array back to the original byte array.
      byte[] decode​(char[] bitspeak, int offset, int length)
      Convert the given bitspeak-encoded char array back to the original byte array.
      byte[] decode​(String bitspeak)
      Convert the given bitspeak-encoded string back to the original byte array.
      long decodeStream​(Reader inputStream, OutputStream outputStream)
      Decode the characters in the given input stream, and write the resulting bytes to the given output stream.
      String encode​(byte[] data)
      Encode all the bytes in the given byte array as bitspeak characters, using the current format.
      String encode​(byte[] data, int offset, int length)
      Encode a range of bytes in the given byte array as bitspeak characters, using the current format.
      long encodeStream​(InputStream inputStream, Writer outputStream)
      Encode the bytes in the given input stream, and write the result to the given output stream.
      int estimateDecodeSize​(int characterCount)
      Estimate the number of bytes needed to store the given character array with this format of bitspeak.
      int estimateEncodeSize​(int byteCount)
      Estimate the number of characters needed to store the given bytes with the current bitspeak format.
      static Collection<Bitspeak> formats()
      Retrieve an unmodifiable view of all the bitspeak formats in the system.
      String name()
      Retrieve the name of the current bitspeak format, either bs6 or bs8.
      BitspeakDecoder newDecoder()
      Create a new bitspeak decoder for the current format.
      InputStream newDecodeStream​(Reader reader)
      Stream the bits represented by the bitspeak characters in the given reader as an input stream.
      InputStream newDecodeStream​(Reader reader, int bufferSize)
      Stream the bits represented by the bitspeak characters in the given reader as an input stream.
      InputStream newDecodeStream​(Reader reader, int byteBufferSize, int charBufferSize)
      Stream the bits represented by the bitspeak characters in the given reader as an input stream.
      BitspeakEncoder newEncoder()
      Create a new bitspeak encoder for the current format.
      Reader newEncodeStream​(InputStream input)
      Create a new stream of bitspeak characters, using the bytes in the given input stream and the current bitspeak format.
      Reader newEncodeStream​(InputStream input, int bufferSize)
      Create a new stream of bitspeak characters, using the bytes in the given input stream and the current bitspeak format.
      Reader newEncodeStream​(InputStream input, int byteBufferSize, int charBufferSize)
      Create a new stream of bitspeak characters, using the bytes in the given input stream and the current bitspeak format.
      String toString()  
      Bitspeak withConfig​(BitspeakConfig configuration)
      Retrieve a bitspeak format with the given configuration.
    • Method Detail

      • formats

        public static Collection<Bitspeak> formats()
        Retrieve an unmodifiable view of all the bitspeak formats in the system.
        Returns:
        Collection with every bitspeak format.
      • bs6

        public static Bitspeak bs6()
        Retrieve a bitspeak format (BS-6) where every 2 characters represents 6 bits of data.

        The format uses the following lookup tables to convert between bits and characters. The first bits will be converted using the consonant table, then the vowel table, and so on, alternating until the last chunk of bits.

        If the bit stream is not evenly divisible by 6, it might end with less bits than required by the current lookup table- for instance, the final two bits might be "11", which cannot be represented in the consonant table. In that case, the bit stream is padded with zeroes to the right, until the last bits have the length required by the lookup table. In the previous example, the last two bits "11" would be turned into "1100", as the table requires 4 bits.

        Consonants lookup table:

        Bits Character
        0000 p
        0001 b
        0010 t
        0011 d
        0100 k
        0101 g
        0110 x
        0111 j
        1000 f
        1001 v
        1010 l
        1011 r
        1100 m
        1101 n
        1110 s
        1111 z

        Vowels lookup table:

        Bits Character
        00 a
        01 u
        10 i
        11 e
        Returns:
        A BS-6 bitspeak format.
      • bs8

        public static Bitspeak bs8()
        Retrieve a bitspeak format where every 8 bits (1 byte) is converted into a consonant and vowel pair, each up two 2 characters in length. The high-order of the byte is converted to a consonant, while the lower order is converted to a vowel, using the following lookup tables.

        Lookup tables:

        Bits Consonant Vowel
        0000 p a
        0001 b e
        0010 t i
        0011 d o
        0100 k u
        0101 g an
        0110 ch en
        0111 j in
        1000 f un
        1001 v on
        1010 l ai
        1011 r ei
        1100 m oi
        1101 y ui
        1110 s aw
        1111 z ow
        Returns:
        A BS-8 bitspeak format.
      • withConfig

        public Bitspeak withConfig​(BitspeakConfig configuration)
        Retrieve a bitspeak format with the given configuration.
        Parameters:
        configuration - the configuration, cannot be NULL.
        Returns:
        The bitspeak format instance with this configuration.
      • decode

        public byte[] decode​(String bitspeak)
        Convert the given bitspeak-encoded string back to the original byte array.
        Parameters:
        bitspeak - the bitspeak string.
        Returns:
        The original byte array.
      • decode

        public byte[] decode​(char[] bitspeak)
        Convert the given bitspeak-encoded char array back to the original byte array.
        Parameters:
        bitspeak - the bitspeak char array.
        Returns:
        The original byte array.
      • decode

        public byte[] decode​(char[] bitspeak,
                             int offset,
                             int length)
        Convert the given bitspeak-encoded char array back to the original byte array.
        Parameters:
        bitspeak - the bitspeak char array.
        offset - the position of the first character to read from the array.
        length - the number of characters to decode from the char array.
        Returns:
        The original byte array.
      • decodeStream

        public long decodeStream​(Reader inputStream,
                                 OutputStream outputStream)
                          throws IOException
        Decode the characters in the given input stream, and write the resulting bytes to the given output stream.
        Parameters:
        inputStream - the input stream.
        outputStream - the output stream.
        Returns:
        The number of decoded bytes.
        Throws:
        IOException
      • estimateDecodeSize

        public int estimateDecodeSize​(int characterCount)
        Estimate the number of bytes needed to store the given character array with this format of bitspeak.
        Parameters:
        characterCount - the character count.
        Returns:
        The number of bytes, cannot be negative.
      • newDecoder

        public BitspeakDecoder newDecoder()
        Create a new bitspeak decoder for the current format.
        Returns:
        A new bitspeak decoder.
      • newDecodeStream

        public InputStream newDecodeStream​(Reader reader)
        Stream the bits represented by the bitspeak characters in the given reader as an input stream.
        Parameters:
        reader - the reader.
        Returns:
        The corresponding input stream.
      • newDecodeStream

        public InputStream newDecodeStream​(Reader reader,
                                           int bufferSize)
        Stream the bits represented by the bitspeak characters in the given reader as an input stream.
        Parameters:
        reader - the reader.
        bufferSize - the number of characters to buffer during decoding.
        Returns:
        The corresponding input stream.
      • newDecodeStream

        public InputStream newDecodeStream​(Reader reader,
                                           int byteBufferSize,
                                           int charBufferSize)
        Stream the bits represented by the bitspeak characters in the given reader as an input stream.
        Parameters:
        reader - the reader.
        byteBufferSize - the number of bytes to buffer during decoding.
        charBufferSize - the number of characters to buffer during decoding.
        Returns:
        The corresponding input stream.
      • encode

        public String encode​(byte[] data)
        Encode all the bytes in the given byte array as bitspeak characters, using the current format.
        Parameters:
        data - the bytes to encode.
        Returns:
        The encoded characters.
      • encode

        public String encode​(byte[] data,
                             int offset,
                             int length)
        Encode a range of bytes in the given byte array as bitspeak characters, using the current format.
        Parameters:
        data - the bytes to encode.
        offset - the index of the first byte to encode.
        length - the number of bytes to encode.
        Returns:
        The encoded characters.
      • encodeStream

        public long encodeStream​(InputStream inputStream,
                                 Writer outputStream)
                          throws IOException
        Encode the bytes in the given input stream, and write the result to the given output stream.
        Parameters:
        inputStream - the input stream.
        outputStream - the output stream.
        Returns:
        The number of encoded characters.
        Throws:
        IOException
      • estimateEncodeSize

        public int estimateEncodeSize​(int byteCount)
        Estimate the number of characters needed to store the given bytes with the current bitspeak format.
        Parameters:
        byteCount - the number of bytes.
        Returns:
        The maximum number of characters needed, up to Integer.MAX_VALUE - 64.
      • newEncoder

        public BitspeakEncoder newEncoder()
        Create a new bitspeak encoder for the current format.
        Returns:
        A new bitspeak encoder.
      • newEncodeStream

        public Reader newEncodeStream​(InputStream input)
        Create a new stream of bitspeak characters, using the bytes in the given input stream and the current bitspeak format.
        Parameters:
        input - the input stream.
        Returns:
        A readable stream of bitspeak characters.
      • newEncodeStream

        public Reader newEncodeStream​(InputStream input,
                                      int bufferSize)
        Create a new stream of bitspeak characters, using the bytes in the given input stream and the current bitspeak format.
        Parameters:
        input - the input stream.
        bufferSize - the number of characters to buffer.
        Returns:
        A readable stream of bitspeak characters.
      • newEncodeStream

        public Reader newEncodeStream​(InputStream input,
                                      int byteBufferSize,
                                      int charBufferSize)
        Create a new stream of bitspeak characters, using the bytes in the given input stream and the current bitspeak format.
        Parameters:
        input - the input stream.
        byteBufferSize - the number of bytes to buffer during decoding.
        charBufferSize - the number of characters to buffer during decoding.
        Returns:
        A readable stream of bitspeak characters.
      • name

        public String name()
        Retrieve the name of the current bitspeak format, either bs6 or bs8.
        Returns:
        The name of the format,