net.sf.okapi.common

## Class MemMappedCharSequence

- java.lang.Object
- - net.sf.okapi.common.MemMappedCharSequence

- All Implemented Interfaces:
    java.lang.CharSequence

      public final class MemMappedCharSequence
      extends java.lang.Object
      implements java.lang.CharSequence

  Represents the text from the source document that is to be parsed.

  This class is normally only of interest to users who wish to create custom tag types.

  The parse text is defined as the entire text of the source document in lower case, with all `Segment.ignoreWhenParsing()` ignored} segments replaced by space characters.

  The text is stored in lower case to make case insensitive parsing as efficient as possible.

  This class provides many methods which are also provided by the `java.lang.String` class, but adds an extra parameter called `breakAtIndex` to the various `indexOf` methods. This parameter allows a search on only a specified segment of the text, which is not possible using the normal `String` class.

  `ParseText` instances are obtained using the `Source.getParseText()` method.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `NO_BREAK` A value to use as the `breakAtIndex` argument in certain methods to indicate that the search should continue to the start or end of the parse text.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MemMappedCharSequence(java.io.InputStream inputSource, java.lang.String encoding)` Constructs a new `ParseText` object based on the specified file name, for a given encoding.
    `MemMappedCharSequence(java.io.InputStream inputSource, java.lang.String encoding, boolean lowercase)` Constructs a new `ParseText` object based on the specified file name, for a given encoding, and optionally converts it into lowercase characters.
    `MemMappedCharSequence(java.io.Reader inputSource)` Constructs a new `ParseText` object based on the specified file name.
    `MemMappedCharSequence(java.io.Reader inputSource, boolean lowercase)` Constructs a new `ParseText` object based on the specified file name, and optionally converts it into lowercase characters.
    `MemMappedCharSequence(java.lang.String string)`
    `MemMappedCharSequence(java.lang.String string, boolean lowercase)` Constructs a new `ParseText` object based on the specified string.
    `MemMappedCharSequence(java.net.URL inputSource, java.lang.String encoding)` Constructs a new `ParseText` object based on the specified file name, in a given encoding.
    `MemMappedCharSequence(java.net.URL inputSource, java.lang.String encoding, boolean lowercase)` Constructs a new `ParseText` object based on the specified file name, in a given encoding, and optionally converts it into lowercase characters.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `char[]` | `array()`
    `char` | `charAt(int index)` Returns the character at the specified index.
    `void` | `close()`
    `boolean` | `containsAt(java.lang.String str, int pos)` Indicates whether this parse text contains the specified string at the specified position.
    `static void` | `decodeChannel(java.nio.channels.ReadableByteChannel source, java.io.Writer writer, java.nio.charset.Charset charset)` General purpose static method which reads bytes from a Channel, decodes them according to the given charset
    `int` | `indexOf(char[] searchCharArray, int fromIndex)` Returns the index within this parse text of the first occurrence of the specified character array, starting the search at the position specified by `fromIndex`.
    `int` | `indexOf(char[] searchCharArray, int fromIndex, int breakAtIndex)` Returns the index within this parse text of the first occurrence of the specified character array, starting the search at the position specified by `fromIndex`, and breaking the search at the index specified by `breakAtIndex`.
    `int` | `indexOf(char searchChar, int fromIndex)` Returns the index within this parse text of the first occurrence of the specified character, starting the search at the position specified by `fromIndex`.
    `int` | `indexOf(char searchChar, int fromIndex, int breakAtIndex)` Returns the index within this parse text of the first occurrence of the specified character, starting the search at the position specified by `fromIndex`, and breaking the search at the index specified by `breakAtIndex`.
    `int` | `indexOf(java.lang.String searchString, int fromIndex)` Returns the index within this parse text of the first occurrence of the specified string, starting the search at the position specified by `fromIndex`.
    `int` | `indexOf(java.lang.String searchString, int fromIndex, int breakAtIndex)` Returns the index within this parse text of the first occurrence of the specified string, starting the search at the position specified by `fromIndex`, and breaking the search at the index specified by `breakAtIndex`.
    `int` | `lastIndexOf(char[] searchCharArray, int fromIndex)` Returns the index within this parse text of the last occurrence of the specified character array, searching backwards starting at the position specified by `fromIndex`.
    `int` | `lastIndexOf(char[] searchCharArray, int fromIndex, int breakAtIndex)` Returns the index within this parse text of the last occurrence of the specified character array, searching backwards starting at the position specified by `fromIndex`, and breaking the search at the index specified by `breakAtIndex`.
    `int` | `lastIndexOf(char searchChar, int fromIndex)` Returns the index within this parse text of the last occurrence of the specified character, searching backwards starting at the position specified by `fromIndex`.
    `int` | `lastIndexOf(char searchChar, int fromIndex, int breakAtIndex)` Returns the index within this parse text of the last occurrence of the specified character, searching backwards starting at the position specified by `fromIndex`, and breaking the search at the index specified by `breakAtIndex`.
    `int` | `lastIndexOf(java.lang.String searchString, int fromIndex)` Returns the index within this parse text of the last occurrence of the specified string, searching backwards starting at the position specified by `fromIndex`.
    `int` | `lastIndexOf(java.lang.String searchString, int fromIndex, int breakAtIndex)` Returns the index within this parse text of the last occurrence of the specified string, searching backwards starting at the position specified by `fromIndex`, and breaking the search at the index specified by `breakAtIndex`.
    `int` | `length()` Returns the length of the parse text.
    `java.lang.CharSequence` | `subSequence(int beginIndex, int endIndex)` Returns a new character sequence that is a subsequence of this sequence.
    `java.lang.String` | `substring(int beginIndex, int endIndex)` Returns a new string that is a substring of this parse text.
    `void` | `toLowercase()`
    `java.lang.String` | `toString()` Returns the content of the parse text as a `String`.

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

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

- - ### Field Detail

    - #### NO_BREAK

          public static final int NO_BREAK

      A value to use as the `breakAtIndex` argument in certain methods to indicate that the search should continue to the start or end of the parse text.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### MemMappedCharSequence

          public MemMappedCharSequence(java.lang.String string,
                               boolean lowercase)

      Constructs a new `ParseText` object based on the specified string. Convert the char[] to CharBuffer to be compatible with buffered case.
      Parameters:
        `string` - the string upon which the parse text is based.
        `lowercase` - true to also convert the string to lowercase.

    - #### MemMappedCharSequence

          public MemMappedCharSequence(java.lang.String string)

    - #### MemMappedCharSequence

          public MemMappedCharSequence(java.io.Reader inputSource)

      Constructs a new `ParseText` object based on the specified file name. The file is assumed to be encoded as UTF-16BE.
      Parameters:
        `inputSource` - the reader to use for the input.

    - #### MemMappedCharSequence

          public MemMappedCharSequence(java.io.Reader inputSource,
                               boolean lowercase)

      Constructs a new `ParseText` object based on the specified file name, and optionally converts it into lowercase characters. The file is assumed to be encoded as UTF-16BE.
      Parameters:
        `inputSource` - the reader to use for the input.
        `lowercase` - true if the content should be converted to lowercases.

    - #### MemMappedCharSequence

          public MemMappedCharSequence(java.io.InputStream inputSource,
                               java.lang.String encoding)

      Constructs a new `ParseText` object based on the specified file name, for a given encoding.
      Parameters:
        `inputSource` - the reader to use for the input.
        `encoding` - the encoding to use.

    - #### MemMappedCharSequence

          public MemMappedCharSequence(java.io.InputStream inputSource,
                               java.lang.String encoding,
                               boolean lowercase)

      Constructs a new `ParseText` object based on the specified file name, for a given encoding, and optionally converts it into lowercase characters.
      Parameters:
        `inputSource` - the reader to use for the input.
        `encoding` - the encoding to use.
        `lowercase` - true if the content should be converted to lowercases.

    - #### MemMappedCharSequence

          public MemMappedCharSequence(java.net.URL inputSource,
                               java.lang.String encoding)

      Constructs a new `ParseText` object based on the specified file name, in a given encoding.
      Parameters:
        `inputSource` - the URL of the input upon which the parse text is based.
        `encoding` - the encoding to use.

    - #### MemMappedCharSequence

          public MemMappedCharSequence(java.net.URL inputSource,
                               java.lang.String encoding,
                               boolean lowercase)

      Constructs a new `ParseText` object based on the specified file name, in a given encoding, and optionally converts it into lowercase characters.
      Parameters:
        `inputSource` - the URL of the input upon which the parse text is based.
        `encoding` - the encoding to use.
        `lowercase` - true if the content should be converted to lowercases.

  - ### Method Detail

    - #### containsAt

          public boolean containsAt(java.lang.String str,
                           int pos)

      Indicates whether this parse text contains the specified string at the specified position.

      This method is analogous to the `java.lang.String.startsWith(String prefix, int toffset)` method.

      Parameters:
        `str` - a string.
        `pos` - the position (index) in this parse text at which to check for the specified string.
      Returns:
        `true` if this parse text contains the specified string at the specified position, otherwise `false`.

    - #### charAt

          public char charAt(int index)

      Returns the character at the specified index.
      Specified by:
        `charAt` in interface `java.lang.CharSequence`
      Parameters:
        `index` - the index of the character.
      Returns:
        the character at the specified index, which is always in lower case.

    - #### indexOf

          public int indexOf(char searchChar,
                    int fromIndex)

      Returns the index within this parse text of the first occurrence of the specified character, starting the search at the position specified by `fromIndex`.

      If the specified character is not found then -1 is returned.

      Parameters:
        `searchChar` - a character.
        `fromIndex` - the index to start the search from.
      Returns:
        the index within this parse text of the first occurrence of the specified character within the specified range, or -1 if the character is not found.

    - #### indexOf

          public int indexOf(char searchChar,
                    int fromIndex,
                    int breakAtIndex)

      Returns the index within this parse text of the first occurrence of the specified character, starting the search at the position specified by `fromIndex`, and breaking the search at the index specified by `breakAtIndex`.

      The position specified by `breakAtIndex` is not included in the search.

      If the search is to continue to the end of the text, the value `ParseText.NO_BREAK` should be specified as the `breakAtIndex`.

      If the specified character is not found then -1 is returned.

      Parameters:
        `searchChar` - a character.
        `fromIndex` - the index to start the search from.
        `breakAtIndex` - the index at which to break off the search, or `NO_BREAK` if the search is to continue to the end of the text.
      Returns:
        the index within this parse text of the first occurrence of the specified character within the specified range, or -1 if the character is not found.

    - #### lastIndexOf

          public int lastIndexOf(char searchChar,
                        int fromIndex)

      Returns the index within this parse text of the last occurrence of the specified character, searching backwards starting at the position specified by `fromIndex`.

      If the specified character is not found then -1 is returned.

      Parameters:
        `searchChar` - a character.
        `fromIndex` - the index to start the search from.
      Returns:
        the index within this parse text of the last occurrence of the specified character within the specified range, or -1 if the character is not found.

    - #### lastIndexOf

          public int lastIndexOf(char searchChar,
                        int fromIndex,
                        int breakAtIndex)

      Returns the index within this parse text of the last occurrence of the specified character, searching backwards starting at the position specified by `fromIndex`, and breaking the search at the index specified by `breakAtIndex`.

      The position specified by `breakAtIndex` is not included in the search.

      If the search is to continue to the start of the text, the value `ParseText.NO_BREAK` should be specified as the `breakAtIndex`.

      If the specified character is not found then -1 is returned.

      Parameters:
        `searchChar` - a character.
        `fromIndex` - the index to start the search from.
        `breakAtIndex` - the index at which to break off the search, or `NO_BREAK` if the search is to continue to the start of the text.
      Returns:
        the index within this parse text of the last occurrence of the specified character within the specified range, or -1 if the character is not found.

    - #### indexOf

          public int indexOf(java.lang.String searchString,
                    int fromIndex)

      Returns the index within this parse text of the first occurrence of the specified string, starting the search at the position specified by `fromIndex`.

      If the specified string is not found then -1 is returned.

      Parameters:
        `searchString` - a string.
        `fromIndex` - the index to start the search from.
      Returns:
        the index within this parse text of the first occurrence of the specified string within the specified range, or -1 if the string is not found.

    - #### indexOf

          public int indexOf(char[] searchCharArray,
                    int fromIndex)

      Returns the index within this parse text of the first occurrence of the specified character array, starting the search at the position specified by `fromIndex`.

      If the specified character array is not found then -1 is returned.

      Parameters:
        `searchCharArray` - a character array.
        `fromIndex` - the index to start the search from.
      Returns:
        the index within this parse text of the first occurrence of the specified character array within the specified range, or -1 if the character array is not found.

    - #### indexOf

          public int indexOf(java.lang.String searchString,
                    int fromIndex,
                    int breakAtIndex)

      Returns the index within this parse text of the first occurrence of the specified string, starting the search at the position specified by `fromIndex`, and breaking the search at the index specified by `breakAtIndex`.

      The position specified by `breakAtIndex` is not included in the search.

      If the search is to continue to the end of the text, the value `ParseText.NO_BREAK` should be specified as the `breakAtIndex`.

      If the specified string is not found then -1 is returned.

      Parameters:
        `searchString` - a string.
        `fromIndex` - the index to start the search from.
        `breakAtIndex` - the index at which to break off the search, or `NO_BREAK` if the search is to continue to the end of the text.
      Returns:
        the index within this parse text of the first occurrence of the specified string within the specified range, or -1 if the string is not found.

    - #### indexOf

          public int indexOf(char[] searchCharArray,
                    int fromIndex,
                    int breakAtIndex)

      Returns the index within this parse text of the first occurrence of the specified character array, starting the search at the position specified by `fromIndex`, and breaking the search at the index specified by `breakAtIndex`.

      The position specified by `breakAtIndex` is not included in the search.

      If the search is to continue to the end of the text, the value `ParseText.NO_BREAK` should be specified as the `breakAtIndex`.

      If the specified character array is not found then -1 is returned.

      Parameters:
        `searchCharArray` - a character array.
        `fromIndex` - the index to start the search from.
        `breakAtIndex` - the index at which to break off the search, or `NO_BREAK` if the search is to continue to the end of the text.
      Returns:
        the index within this parse text of the first occurrence of the specified character array within the specified range, or -1 if the character array is not found.

    - #### lastIndexOf

          public int lastIndexOf(java.lang.String searchString,
                        int fromIndex)

      Returns the index within this parse text of the last occurrence of the specified string, searching backwards starting at the position specified by `fromIndex`.

      If the specified string is not found then -1 is returned.

      Parameters:
        `searchString` - a string.
        `fromIndex` - the index to start the search from.
      Returns:
        the index within this parse text of the last occurrence of the specified string within the specified range, or -1 if the string is not found.

    - #### lastIndexOf

          public int lastIndexOf(char[] searchCharArray,
                        int fromIndex)

      Returns the index within this parse text of the last occurrence of the specified character array, searching backwards starting at the position specified by `fromIndex`.

      If the specified character array is not found then -1 is returned.

      Parameters:
        `searchCharArray` - a character array.
        `fromIndex` - the index to start the search from.
      Returns:
        the index within this parse text of the last occurrence of the specified character array within the specified range, or -1 if the character array is not found.

    - #### lastIndexOf

          public int lastIndexOf(java.lang.String searchString,
                        int fromIndex,
                        int breakAtIndex)

      Returns the index within this parse text of the last occurrence of the specified string, searching backwards starting at the position specified by `fromIndex`, and breaking the search at the index specified by `breakAtIndex`.

      The position specified by `breakAtIndex` is not included in the search.

      If the search is to continue to the start of the text, the value `ParseText.NO_BREAK` should be specified as the `breakAtIndex`.

      If the specified string is not found then -1 is returned.

      Parameters:
        `searchString` - a string.
        `fromIndex` - the index to start the search from.
        `breakAtIndex` - the index at which to break off the search, or `NO_BREAK` if the search is to continue to the start of the text.
      Returns:
        the index within this parse text of the last occurrence of the specified string within the specified range, or -1 if the string is not found.

    - #### lastIndexOf

          public int lastIndexOf(char[] searchCharArray,
                        int fromIndex,
                        int breakAtIndex)

      Returns the index within this parse text of the last occurrence of the specified character array, searching backwards starting at the position specified by `fromIndex`, and breaking the search at the index specified by `breakAtIndex`.

      The position specified by `breakAtIndex` is not included in the search.

      If the search is to continue to the start of the text, the value `ParseText.NO_BREAK` should be specified as the `breakAtIndex`.

      If the specified character array is not found then -1 is returned.

      Parameters:
        `searchCharArray` - a character array.
        `fromIndex` - the index to start the search from.
        `breakAtIndex` - the index at which to break off the search, or `NO_BREAK` if the search is to continue to the start of the text.
      Returns:
        the index within this parse text of the last occurrence of the specified character array within the specified range, or -1 if the character array is not found.

    - #### length

          public int length()

      Returns the length of the parse text.
      Specified by:
        `length` in interface `java.lang.CharSequence`
      Returns:
        the length of the parse text.

    - #### substring

          public java.lang.String substring(int beginIndex,
                                   int endIndex)

      Returns a new string that is a substring of this parse text.

      The substring begins at the specified `beginIndex` and extends to the character at index `endIndex` - 1. Thus the length of the substring is `endIndex-beginIndex`.

      Parameters:
        `beginIndex` - the begin index, inclusive.
        `endIndex` - the end index, exclusive.
      Returns:
        a new string that is a substring of this parse text.

    - #### subSequence

          public java.lang.CharSequence subSequence(int beginIndex,
                                           int endIndex)

      Returns a new character sequence that is a subsequence of this sequence.

      This is equivalent to `substring(beginIndex,endIndex)`.

      Specified by:
        `subSequence` in interface `java.lang.CharSequence`
      Parameters:
        `beginIndex` - the begin index, inclusive.
        `endIndex` - the end index, exclusive.
      Returns:
        a new character sequence that is a subsequence of this sequence.

    - #### toString

          public java.lang.String toString()

      Returns the content of the parse text as a `String`.
      Specified by:
        `toString` in interface `java.lang.CharSequence`
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        the content of the parse text as a `String`.

    - #### toLowercase

          public void toLowercase()

    - #### array

          public char[] array()

    - #### decodeChannel

          public static void decodeChannel(java.nio.channels.ReadableByteChannel source,
                           java.io.Writer writer,
                           java.nio.charset.Charset charset)
                                    throws java.nio.charset.UnsupportedCharsetException,
                                           java.io.IOException

      General purpose static method which reads bytes from a Channel, decodes them according to the given charset
      Parameters:
        `source` - A ReadableByteChannel object which will be read to EOF as a source of encoded bytes.
        `writer` - A Writer object to which decoded chars will be written.
        `charset` - A Charset object, whose CharsetDecoder will be used to do the character set decoding.
      Throws:
        `java.io.IOException` - if an I/O error occurs.
        `java.nio.charset.UnsupportedCharsetException` - if the requested `Charset` is not supported.

    - #### close

          public void close()