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
17package com.android.dx.util;
18
19import com.android.dex.util.ByteOutput;
20
21/**
22 * Interface for a sink for binary output. This is similar to
23 * {@code java.util.DataOutput}, but no {@code IOExceptions}
24 * are declared, and multibyte output is defined to be little-endian.
25 */
26public interface Output extends ByteOutput {
27    /**
28     * Gets the current cursor position. This is the same as the number of
29     * bytes written to this instance.
30     *
31     * @return {@code >= 0;} the cursor position
32     */
33    public int getCursor();
34
35    /**
36     * Asserts that the cursor is the given value.
37     *
38     * @param expectedCursor the expected cursor value
39     * @throws RuntimeException thrown if {@code getCursor() !=
40     * expectedCursor}
41     */
42    public void assertCursor(int expectedCursor);
43
44    /**
45     * Writes a {@code byte} to this instance.
46     *
47     * @param value the value to write; all but the low 8 bits are ignored
48     */
49    @Override
50    public void writeByte(int value);
51
52    /**
53     * Writes a {@code short} to this instance.
54     *
55     * @param value the value to write; all but the low 16 bits are ignored
56     */
57    public void writeShort(int value);
58
59    /**
60     * Writes an {@code int} to this instance.
61     *
62     * @param value the value to write
63     */
64    public void writeInt(int value);
65
66    /**
67     * Writes a {@code long} to this instance.
68     *
69     * @param value the value to write
70     */
71    public void writeLong(long value);
72
73    /**
74     * Writes a DWARFv3-style unsigned LEB128 integer. For details,
75     * see the "Dalvik Executable Format" document or DWARF v3 section
76     * 7.6.
77     *
78     * @param value value to write, treated as an unsigned value
79     * @return {@code 1..5;} the number of bytes actually written
80     */
81    public int writeUleb128(int value);
82
83    /**
84     * Writes a DWARFv3-style unsigned LEB128 integer. For details,
85     * see the "Dalvik Executable Format" document or DWARF v3 section
86     * 7.6.
87     *
88     * @param value value to write
89     * @return {@code 1..5;} the number of bytes actually written
90     */
91    public int writeSleb128(int value);
92
93    /**
94     * Writes a {@link ByteArray} to this instance.
95     *
96     * @param bytes {@code non-null;} the array to write
97     */
98    public void write(ByteArray bytes);
99
100    /**
101     * Writes a portion of a {@code byte[]} to this instance.
102     *
103     * @param bytes {@code non-null;} the array to write
104     * @param offset {@code >= 0;} offset into {@code bytes} for the first
105     * byte to write
106     * @param length {@code >= 0;} number of bytes to write
107     */
108    public void write(byte[] bytes, int offset, int length);
109
110    /**
111     * Writes a {@code byte[]} to this instance. This is just
112     * a convenient shorthand for {@code write(bytes, 0, bytes.length)}.
113     *
114     * @param bytes {@code non-null;} the array to write
115     */
116    public void write(byte[] bytes);
117
118    /**
119     * Writes the given number of {@code 0} bytes.
120     *
121     * @param count {@code >= 0;} the number of zeroes to write
122     */
123    public void writeZeroes(int count);
124
125    /**
126     * Adds extra bytes if necessary (with value {@code 0}) to
127     * force alignment of the output cursor as given.
128     *
129     * @param alignment {@code > 0;} the alignment; must be a power of two
130     */
131    public void alignTo(int alignment);
132}
133