Project

General

Profile

Utility Classes and Methods » History » Version 2

Sergey Smolov, 05/13/2016 11:43 AM

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
   * Returns writer to the specified stream object.
69
   * <p>Default charset is used for writing.</p>
70
   * @param stream Stream to write to.
71
   * @return Writer to the specified stream object.
72
   * @throws IllegalArgumentException when argument is {@code null}.
73
   */
74
  public static BufferedWriter newBufferedWriter(final OutputStream stream)
75
</code></pre>
76
<pre><code class="java">
77
/**
78
   * Returns writer to the specified file object.
79
   * <p>Default charset is used for writing.</p>
80
   * @param file File to write to.
81
   * @return Writer to the specified file object.
82
   * @throws IllegalArgumentException when argument is {@code null}.
83
   * @throws RetrascopeRuntimeException when the specified file already contains data
84
   *         or when I/O error occurred.
85
   */
86
  public static BufferedWriter newBufferedWriter(final File file)
87
</code></pre>
88
<pre><code class="java">
89
/**
90
   * Returns writer to the specified path object.
91
   * @param path Path to write to.
92
   * @return Writer to the specified path object.
93
   * @throws IllegalArgumentException is {@code null}.
94
   * @throws RetrascopeRuntimeException when the specified file already exists
95
   *         or when an I/O error occurred.
96
   */
97
  public static BufferedWriter newBufferedWriter(final Path path)
98
</code></pre>
99
<pre><code class="java">
100
/**
101
   * Returns writer to the specified file object.
102
   * <p>Default charset is used for writing.</p>
103
   * @param file File to write to.
104
   * @return Writer to the specified file object.
105
   * @throws IllegalArgumentException when argument is {@code null}.
106
   */
107
  public static PrintWriter newPrintWriter(final File file)
108
</code></pre>
109
110
h2. SolverUtils
111
112
Utility methods for constraint and expression solving.
113
114
<pre><code class="java">
115
/**
116
   * Checks whether the specified expression is satisfiable.
117
   *
118
   * @param node Expression to be checked.
119
   * @return {@code true} if the expression is satisfiable or {@code false} otherwise.
120
   *
121
   */
122
  public static boolean isSat(final Node node)
123
</code></pre>
124
<pre><code class="java">
125
/**
126
   * Checks whether the specified logical expressions are compatible
127
   * {@code (getConjunction(nodes[0], ..., nodes[n-1]) is SAT)}.
128
   *
129
   * @param expressions Logical expressions to be checked.
130
   *
131
   * @return {@code true} if the specified expressions are compatible, {@code false} otherwise.
132
   */
133
  public static boolean areCompatible(final Node... expressions)
134
</code></pre>
135
<pre><code class="java">
136
/**
137
   * Checks whether the specified logical expressions are complete
138
   * {@code (!getComplement(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 complete, {@code false} otherwise.
143
   */
144
  public static boolean areComplete(final Node... expressions)
145
</code></pre>
146
<pre><code class="java">
147
/**
148
   * Solves the specified expression.
149
   *
150
   * @param node Expression to be solved.
151
   *
152
   * @return Result of solving.
153
   */
154
  public static SolverResult solve(final Node node)
155
</code></pre>
156
157
h2. TransformerUtils
158
159
Utility methods for transformation of expressions.
160
161
<pre><code class="java">
162
/**
163
   * Replace operations in expression with standard counterparts.
164
   * <p>Transforms nodes of the following kinds:
165
   * <ul>
166
   *   <li> EQ operation with more than 2 operands - to conjunction of 2-operand EQs;
167
   * </ul>
168
   * Wrapping method for {@code Transformer.standardize} method.
169
   * Uses it''s internal rules for additional replacements.</p>
170
   *
171
   * @see Transformer
172
   * @param node Expression to be transformed.
173
   * @return Expression with non-standard operations being replaced.
174
   */
175
  public static Node standardize(final Node node)
176
</code></pre>
177
178
h2. TransformUtils
179
180
Utility methods for models and model components transformation.
181
182
<pre><code class="java">
183
/**
184
   * Performs backward substitution on the specified nodes to the specified expression.
185
   *
186
   * <p>The substitution process moves in a backward direction (from last node of the list
187
   * to the first). The result is an expression where all the target variables that are
188
   * defined at least one {@link AssignmentContainer} node from the specified collection
189
   * will be substituted by the value expressions that are assigned to them.</p>
190
   *
191
   * @param blocks Blocks which should be used as a source of substitution.
192
   * @param node Expression to be transformed.
193
   *
194
   * @return Modified expression.
195
   */
196
  public static Node substituteBackward(
197
      final List<? extends AssignmentContainer> blocks,
198
      final Node node)
199
</code></pre>