Home | History | Annotate | Download | only in util 
      1 /*
      2  * Copyright (C) 2007 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package com.android.dx.util;
     18 
     19 /**
     20  * Interface for a sink for binary output. This is similar to
     21  * {@code java.util.DataOutput}, but no {@code IOExceptions}
     22  * are declared, and multibyte output is defined to be little-endian.
     23  */
     24 public interface Output {
     25     /**
     26      * Gets the current cursor position. This is the same as the number of
     27      * bytes written to this instance.
     28      *
     29      * @return {@code >= 0;} the cursor position
     30      */
     31     public int getCursor();
     32 
     33     /**
     34      * Asserts that the cursor is the given value.
     35      *
     36      * @param expectedCursor the expected cursor value
     37      * @throws RuntimeException thrown if {@code getCursor() !=
     38      * expectedCursor}
     39      */
     40     public void assertCursor(int expectedCursor);
     41 
     42     /**
     43      * Writes a {@code byte} to this instance.
     44      *
     45      * @param value the value to write; all but the low 8 bits are ignored
     46      */
     47     public void writeByte(int value);
     48 
     49     /**
     50      * Writes a {@code short} to this instance.
     51      *
     52      * @param value the value to write; all but the low 16 bits are ignored
     53      */
     54     public void writeShort(int value);
     55 
     56     /**
     57      * Writes an {@code int} to this instance.
     58      *
     59      * @param value the value to write
     60      */
     61     public void writeInt(int value);
     62 
     63     /**
     64      * Writes a {@code long} to this instance.
     65      *
     66      * @param value the value to write
     67      */
     68     public void writeLong(long value);
     69 
     70     /**
     71      * Writes a DWARFv3-style unsigned LEB128 integer. For details,
     72      * see the "Dalvik Executable Format" document or DWARF v3 section
     73      * 7.6.
     74      *
     75      * @param value value to write, treated as an unsigned value
     76      * @return {@code 1..5;} the number of bytes actually written
     77      */
     78     public int writeUnsignedLeb128(int value);
     79 
     80     /**
     81      * Writes a DWARFv3-style unsigned LEB128 integer. For details,
     82      * see the "Dalvik Executable Format" document or DWARF v3 section
     83      * 7.6.
     84      *
     85      * @param value value to write
     86      * @return {@code 1..5;} the number of bytes actually written
     87      */
     88     public int writeSignedLeb128(int value);
     89 
     90     /**
     91      * Writes a {@link ByteArray} to this instance.
     92      *
     93      * @param bytes {@code non-null;} the array to write
     94      */
     95     public void write(ByteArray bytes);
     96 
     97     /**
     98      * Writes a portion of a {@code byte[]} to this instance.
     99      *
    100      * @param bytes {@code non-null;} the array to write
    101      * @param offset {@code >= 0;} offset into {@code bytes} for the first
    102      * byte to write
    103      * @param length {@code >= 0;} number of bytes to write
    104      */
    105     public void write(byte[] bytes, int offset, int length);
    106 
    107     /**
    108      * Writes a {@code byte[]} to this instance. This is just
    109      * a convenient shorthand for {@code write(bytes, 0, bytes.length)}.
    110      *
    111      * @param bytes {@code non-null;} the array to write
    112      */
    113     public void write(byte[] bytes);
    114 
    115     /**
    116      * Writes the given number of {@code 0} bytes.
    117      *
    118      * @param count {@code >= 0;} the number of zeroes to write
    119      */
    120     public void writeZeroes(int count);
    121 
    122     /**
    123      * Adds extra bytes if necessary (with value {@code 0}) to
    124      * force alignment of the output cursor as given.
    125      *
    126      * @param alignment {@code > 0;} the alignment; must be a power of two
    127      */
    128     public void alignTo(int alignment);
    129 }
    130