src/main/java/jp/sfjp/mikutoga/bin/parser/BinParser.java

   1 /*
   2  * binary parser interface
   3  *
   4  * License : The MIT License
   5  * Copyright(c) 2013 MikuToga Partners
   6  */
   7
   8 package jp.sfjp.mikutoga.bin.parser;
   9
  10 import java.io.IOException;
  11
  12 /**
  13  * バイナリパーサの共通インタフェース。
  14  * <p>バイト列、各種プリミティブ型値およびエンコードされた文字列を読み込む。
  15  * <p>long,double、およびビッグエンディアン形式のデータは未サポート。
  16  */
  17 public interface BinParser {
  18
  19     /**
  20      * 入力ソースの読み込み位置を返す。
  21      * @return 入力ソースの読み込み位置。単位はbyte。
  22      */
  23     long getPosition();
  24
  25     /**
  26      * 入力ソースにまだデータが残っているか判定する。
  27      * @return まだ読み込んでいないデータが残っていればtrue
  28      * @throws IOException IOエラー
  29      */
  30     boolean hasMore() throws IOException;
  31
  32     /**
  33      * 入力ソースを読み飛ばす。
  34      * @param skipLength 読み飛ばすバイト数。
  35      * @throws IOException IOエラー
  36      * @throws MmdEofException 読み飛ばす途中でストリーム終端に達した。
  37      * @see java.io.InputStream#skip(long)
  38      */
  39     void skip(long skipLength) throws IOException, MmdEofException;
  40
  41     /**
  42      * byte配列を読み込む。
  43      * @param dst 格納先配列
  44      * @param off 読み込み開始オフセット
  45      * @param length 読み込みバイト数
  46      * @throws NullPointerException 配列がnull
  47      * @throws IndexOutOfBoundsException 引数が配列属性と矛盾
  48      * @throws IOException IOエラー
  49      * @throws MmdEofException 読み込む途中でストリーム終端に達した。
  50      * @see java.io.InputStream#read(byte[], int, int)
  51      */
  52     void parseByteArray(byte[] dst, int off, int length)
  53             throws NullPointerException,
  54                    IndexOutOfBoundsException,
  55                    IOException,
  56                    MmdEofException;
  57
  58     /**
  59      * byte配列を読み込む。
  60      * <p>配列要素全ての読み込みが試みられる。
  61      * @param dst 格納先配列
  62      * @throws NullPointerException 配列がnull
  63      * @throws IOException IOエラー
  64      * @throws MmdEofException 読み込む途中でストリーム終端に達した。
  65      * @see java.io.InputStream#read(byte[])
  66      */
  67     void parseByteArray(byte[] dst)
  68             throws NullPointerException, IOException, MmdEofException;
  69
  70     /**
  71      * byte値を読み込む。
  72      * @return 読み込んだbyte値
  73      * @throws IOException IOエラー
  74      * @throws MmdEofException 読み込む途中でストリーム終端に達した。
  75      */
  76     byte parseByte() throws IOException, MmdEofException;
  77
  78     /**
  79      * 符号無し値としてbyte値を読み込み、int型に変換して返す。
  80      * <p>符号は拡張されない。(0xffは0x000000ffとなる)
  81      * @return 読み込まれた値のint値
  82      * @throws IOException IOエラー
  83      * @throws MmdEofException 読み込む途中でストリーム終端に達した。
  84      */
  85     int parseUByteAsInt() throws IOException, MmdEofException;
  86
  87     /**
  88      * byte値を読み込み、boolean型に変換して返す。
  89      * <p>0x00は偽、それ以外は真と解釈される。
  90      * @return 読み込まれた値のboolean値
  91      * @throws IOException IOエラー
  92      * @throws MmdEofException 読み込む途中でストリーム終端に達した。
  93      */
  94     boolean parseBoolean() throws IOException, MmdEofException;
  95
  96     /**
  97      * short値を読み込む。
  98      * <p>short値はリトルエンディアンで格納されていると仮定される。
  99      * @return 読み込んだshort値
 100      * @throws IOException IOエラー
 101      * @throws MmdEofException 読み込む途中でストリーム終端に達した。
 102      */
 103     short parseLeShort() throws IOException, MmdEofException;
 104
 105     /**
 106      * 符号無し値としてshort値を読み込み、int型に変換して返す。
 107      * <p>符号は拡張されない。(0xffffは0x0000ffffとなる)
 108      * <p>short値はリトルエンディアンで格納されていると仮定される。
 109      * @return 読み込まれた値のint値
 110      * @throws IOException IOエラー
 111      * @throws MmdEofException 読み込む途中でストリーム終端に達した。
 112      */
 113     int parseLeUShortAsInt() throws IOException, MmdEofException;
 114
 115     /**
 116      * int値を読み込む。
 117      * <p>int値はリトルエンディアンで格納されていると仮定される。
 118      * @return 読み込んだint値
 119      * @throws IOException IOエラー
 120      * @throws MmdEofException 読み込む途中でストリーム終端に達した。
 121      */
 122     int parseLeInt() throws IOException, MmdEofException;
 123
 124     /**
 125      * float値を読み込む。
 126      * <p>float値はリトルエンディアンで格納されていると仮定される。
 127      * @return 読み込んだfloat値
 128      * @throws IOException IOエラー
 129      * @throws MmdEofException 読み込む途中でストリーム終端に達した。
 130      */
 131     float parseLeFloat() throws IOException, MmdEofException;
 132
 133     /**
 134      * 固定バイト長の文字列を読み込む。
 135      * @param decoder 文字デコーダ
 136      * @param byteLen 読み込む固定バイト長
 137      * @return 文字列
 138      * @throws IOException 入力エラー
 139      * @throws MmdEofException 固定長バイト列を読む前に末端に達した。
 140      * @throws MmdFormatException 文字エンコーディングに関するエラー
 141      */
 142     String parseString(TextDecoder decoder, int byteLen)
 143             throws IOException, MmdEofException, MmdFormatException;
 144
 145 }