Utility Classes and Methods¶

• Table of contents
• Utility Classes and Methods
  • NodeUtils
  • ReadWriteUtils
  • SolverUtils
  • TransformerUtils
  • TransformUtils

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.
This page contains a list of such method signatures with Javadoc headers sorted by classes.

NodeUtils¶

Utility methods for operating with ru.ispras.fortress.expression.Node class objects and it''s descendants.

  /**
   * Returns an equation {@code (nodes[0] == ... == nodes[n - 1])} expression
   * of the specified nodes.
   *
   * @param nodes Expressions to be combined.
   *
   * @return An equation of the specified nodes.
   *
   * @throws IllegalArgumentException when argument is either {@code null} or empty.
   */
  public static Node getEquation(final Node ... nodes)

  /**
   * Returns a collection of names for variables from the specified collection.
   *
   * @param nodes Collection of nodes.
   *
   * @return Collection of names for variable nodes from the specified collection.
   *
   * @throws IllegalArgumentException when argument is {@code null}.
   */
  public static Collection<String> getVariableNames(final Collection<? extends Node> nodes)

/**
   * Casts the specified node to the specified data type.
   *
   * @param node Expression to be casted.
   * @param dataType Type to which the expression to be casted to.
   *
   * @return An expression which is equivalent to the specified node and has the specified type.
   *
   * @throws IllegalArgumentException when any of arguments is {@code null}.
   */
  public static Node castToDataType(final Node node, final DataType dataType)

ReadWriteUtils¶

Utility methods for reading from file, stream etc. and for writing to it.

/**
   * Returns reader for the specified stream object.
   * <p>Default charset is used for reading.</p>
   * @param stream Stream to be read.
   * @return Reader for the specified stream object.
   * @throws IllegalArgumentException when argument is {@code null}.
   */
  public static BufferedReader newBufferedReader(final InputStream stream)

/**
   * Returns reader for the specified path object.
   * <p>Default charset is used for reading.</p>
   * @param path Path from which data to be read.
   * @return Reader for the specified path object.
   * @throws IllegalArgumentException when argument is {@code null}.
   * @throws RetrascopeRuntimeException when I/O error occurred.
   */
  public static BufferedReader newBufferedReader(final Path path)

/**
   * Returns writer to the specified stream object.
   * <p>Default charset is used for writing.</p>
   * @param stream Stream to write to.
   * @return Writer to the specified stream object.
   * @throws IllegalArgumentException when argument is {@code null}.
   */
  public static BufferedWriter newBufferedWriter(final OutputStream stream)

/**
   * Returns writer to the specified file object.
   * <p>Default charset is used for writing.</p>
   * @param file File to write to.
   * @return Writer to the specified file object.
   * @throws IllegalArgumentException when argument is {@code null}.
   * @throws RetrascopeRuntimeException when the specified file already contains data
   *         or when I/O error occurred.
   */
  public static BufferedWriter newBufferedWriter(final File file)

/**
   * Returns writer to the specified path object.
   * @param path Path to write to.
   * @return Writer to the specified path object.
   * @throws IllegalArgumentException is {@code null}.
   * @throws RetrascopeRuntimeException when the specified file already exists
   *         or when an I/O error occurred.
   */
  public static BufferedWriter newBufferedWriter(final Path path)

/**
   * Returns writer to the specified file object.
   * <p>Default charset is used for writing.</p>
   * @param file File to write to.
   * @return Writer to the specified file object.
   * @throws IllegalArgumentException when argument is {@code null}.
   */
  public static PrintWriter newPrintWriter(final File file)

SolverUtils¶

Utility methods for constraint and expression solving.

/**
   * Checks whether the specified expression is satisfiable.
   *
   * @param node Expression to be checked.
   * @return {@code true} if the expression is satisfiable or {@code false} otherwise.
   *
   */
  public static boolean isSat(final Node node)

/**
   * Checks whether the specified logical expressions are compatible
   * {@code (getConjunction(nodes[0], ..., nodes[n-1]) is SAT)}.
   *
   * @param expressions Logical expressions to be checked.
   *
   * @return {@code true} if the specified expressions are compatible, {@code false} otherwise.
   */
  public static boolean areCompatible(final Node... expressions)

/**
   * Checks whether the specified logical expressions are complete
   * {@code (!getComplement(nodes[0], ..., nodes[n-1]) is SAT)}.
   *
   * @param expressions Logical expressions to be checked.
   *
   * @return {@code true} if the specified expressions are complete, {@code false} otherwise.
   */
  public static boolean areComplete(final Node... expressions)

/**
   * Solves the specified expression.
   *
   * @param node Expression to be solved.
   *
   * @return Result of solving.
   */
  public static SolverResult solve(final Node node)

TransformerUtils¶

Utility methods for transformation of expressions.

/**
   * Replace operations in expression with standard counterparts.
   * <p>Transforms nodes of the following kinds:
   * <ul>
   *   <li> EQ operation with more than 2 operands - to conjunction of 2-operand EQs;
   * </ul>
   * Wrapping method for {@code Transformer.standardize} method.
   * Uses it''s internal rules for additional replacements.</p>
   *
   * @see Transformer
   * @param node Expression to be transformed.
   * @return Expression with non-standard operations being replaced.
   */
  public static Node standardize(final Node node)

TransformUtils¶

Utility methods for models and model components transformation.

/**
   * Performs backward substitution on the specified nodes to the specified expression.
   *
   * <p>The substitution process moves in a backward direction (from last node of the list
   * to the first). The result is an expression where all the target variables that are
   * defined at least one {@link AssignmentContainer} node from the specified collection
   * will be substituted by the value expressions that are assigned to them.</p>
   *
   * @param blocks Blocks which should be used as a source of substitution.
   * @param node Expression to be transformed.
   *
   * @return Modified expression.
   */
  public static Node substituteBackward(
      final List<? extends AssignmentContainer> blocks,
      final Node node)