Project

General

Profile

Utility Classes and Methods » History » Version 3

Sergey Smolov, 05/13/2016 12:33 PM

1 1 Sergey Smolov
h1. Utility Classes and Methods
2
3 2 Sergey Smolov
{{toc}}
4
5 1 Sergey Smolov
The HDL Retrascope project includes several classes for utility methods. It is supposed to use these methods for solving common small problems, like reading the file line by line, solving the constraint and so on.
6
This page contains a list of such method signatures with Javadoc headers sorted by classes.
7
8
h2. NodeUtils
9
10
Utility methods for operating with @ru.ispras.fortress.expression.Node@ class objects and it''s descendants.
11
12
<pre><code class="java">
13
  /**
14
   * Returns an equation {@code (nodes[0] == ... == nodes[n - 1])} expression
15
   * of the specified nodes.
16
   *
17
   * @param nodes Expressions to be combined.
18
   *
19
   * @return An equation of the specified nodes.
20
   *
21
   * @throws IllegalArgumentException when argument is either {@code null} or empty.
22
   */
23
  public static Node getEquation(final Node ... nodes)
24
</code></pre>
25
26
<pre><code class="java">
27
  /**
28
   * Returns a collection of names for variables from the specified collection.
29
   *
30
   * @param nodes Collection of nodes.
31
   *
32
   * @return Collection of names for variable nodes from the specified collection.
33
   *
34
   * @throws IllegalArgumentException when argument is {@code null}.
35
   */
36
  public static Collection<String> getVariableNames(final Collection<? extends Node> nodes)
37
</code></pre>
38
<pre><code class="java">
39
/**
40
   * Casts the specified node to the specified data type.
41
   *
42
   * @param node Expression to be casted.
43
   * @param dataType Type to which the expression to be casted to.
44
   *
45
   * @return An expression which is equivalent to the specified node and has the specified type.
46
   *
47
   * @throws IllegalArgumentException when any of arguments is {@code null}.
48
   */
49
  public static Node castToDataType(final Node node, final DataType dataType)
50
</code></pre>
51
52
h2. ReadWriteUtils
53
54
Utility methods for reading from file, stream etc. and for writing to it.
55
56
<pre><code class="java">
57
/**
58
   * Returns reader for the specified stream object.
59
   * <p>Default charset is used for reading.</p>
60
   * @param stream Stream to be read.
61
   * @return Reader for the specified stream object.
62
   * @throws IllegalArgumentException when argument is {@code null}.
63
   */
64
  public static BufferedReader newBufferedReader(final InputStream stream)
65
</code></pre>
66
<pre><code class="java">
67
/**
68 3 Sergey Smolov
   * Returns reader for the specified path object.
69
   * <p>Default charset is used for reading.</p>
70
   * @param path Path from which data to be read.
71
   * @return Reader for the specified path object.
72
   * @throws IllegalArgumentException when argument is {@code null}.
73
   * @throws RetrascopeRuntimeException when I/O error occurred.
74
   */
75
  public static BufferedReader newBufferedReader(final Path path)
76
</code></pre>
77
<pre><code class="java">
78
/**
79 1 Sergey Smolov
   * Returns writer to the specified stream object.
80
   * <p>Default charset is used for writing.</p>
81
   * @param stream Stream to write to.
82
   * @return Writer to the specified stream object.
83
   * @throws IllegalArgumentException when argument is {@code null}.
84
   */
85
  public static BufferedWriter newBufferedWriter(final OutputStream stream)
86
</code></pre>
87
<pre><code class="java">
88
/**
89
   * Returns writer to the specified file object.
90
   * <p>Default charset is used for writing.</p>
91
   * @param file File to write to.
92
   * @return Writer to the specified file object.
93
   * @throws IllegalArgumentException when argument is {@code null}.
94
   * @throws RetrascopeRuntimeException when the specified file already contains data
95
   *         or when I/O error occurred.
96
   */
97
  public static BufferedWriter newBufferedWriter(final File file)
98
</code></pre>
99
<pre><code class="java">
100
/**
101
   * Returns writer to the specified path object.
102
   * @param path Path to write to.
103
   * @return Writer to the specified path object.
104
   * @throws IllegalArgumentException is {@code null}.
105
   * @throws RetrascopeRuntimeException when the specified file already exists
106
   *         or when an I/O error occurred.
107
   */
108
  public static BufferedWriter newBufferedWriter(final Path path)
109
</code></pre>
110
<pre><code class="java">
111
/**
112
   * Returns writer to the specified file object.
113
   * <p>Default charset is used for writing.</p>
114
   * @param file File to write to.
115
   * @return Writer to the specified file object.
116
   * @throws IllegalArgumentException when argument is {@code null}.
117
   */
118
  public static PrintWriter newPrintWriter(final File file)
119
</code></pre>
120
121
h2. SolverUtils
122
123
Utility methods for constraint and expression solving.
124
125
<pre><code class="java">
126
/**
127
   * Checks whether the specified expression is satisfiable.
128
   *
129
   * @param node Expression to be checked.
130
   * @return {@code true} if the expression is satisfiable or {@code false} otherwise.
131
   *
132
   */
133
  public static boolean isSat(final Node node)
134
</code></pre>
135
<pre><code class="java">
136
/**
137
   * Checks whether the specified logical expressions are compatible
138
   * {@code (getConjunction(nodes[0], ..., nodes[n-1]) is SAT)}.
139
   *
140
   * @param expressions Logical expressions to be checked.
141
   *
142
   * @return {@code true} if the specified expressions are compatible, {@code false} otherwise.
143
   */
144
  public static boolean areCompatible(final Node... expressions)
145
</code></pre>
146
<pre><code class="java">
147
/**
148
   * Checks whether the specified logical expressions are complete
149
   * {@code (!getComplement(nodes[0], ..., nodes[n-1]) is SAT)}.
150
   *
151
   * @param expressions Logical expressions to be checked.
152
   *
153
   * @return {@code true} if the specified expressions are complete, {@code false} otherwise.
154
   */
155
  public static boolean areComplete(final Node... expressions)
156
</code></pre>
157
<pre><code class="java">
158
/**
159
   * Solves the specified expression.
160
   *
161
   * @param node Expression to be solved.
162
   *
163
   * @return Result of solving.
164
   */
165
  public static SolverResult solve(final Node node)
166
</code></pre>
167
168
h2. TransformerUtils
169
170
Utility methods for transformation of expressions.
171
172
<pre><code class="java">
173
/**
174
   * Replace operations in expression with standard counterparts.
175
   * <p>Transforms nodes of the following kinds:
176
   * <ul>
177
   *   <li> EQ operation with more than 2 operands - to conjunction of 2-operand EQs;
178
   * </ul>
179
   * Wrapping method for {@code Transformer.standardize} method.
180
   * Uses it''s internal rules for additional replacements.</p>
181
   *
182
   * @see Transformer
183
   * @param node Expression to be transformed.
184
   * @return Expression with non-standard operations being replaced.
185
   */
186
  public static Node standardize(final Node node)
187
</code></pre>
188
189
h2. TransformUtils
190
191
Utility methods for models and model components transformation.
192
193
<pre><code class="java">
194
/**
195
   * Performs backward substitution on the specified nodes to the specified expression.
196
   *
197
   * <p>The substitution process moves in a backward direction (from last node of the list
198
   * to the first). The result is an expression where all the target variables that are
199
   * defined at least one {@link AssignmentContainer} node from the specified collection
200
   * will be substituted by the value expressions that are assigned to them.</p>
201
   *
202
   * @param blocks Blocks which should be used as a source of substitution.
203
   * @param node Expression to be transformed.
204
   *
205
   * @return Modified expression.
206
   */
207
  public static Node substituteBackward(
208
      final List<? extends AssignmentContainer> blocks,
209
      final Node node)
210
</code></pre>