001/*
002 * Java Genetic Algorithm Library (jenetics-9.1.0).
003 * Copyright (c) 2007-2026 Franz Wilhelmstötter
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 *
017 * Author:
018 *    Franz Wilhelmstötter (franz.wilhelmstoetter@gmail.com)
019 */
020package io.jenetics.ext.rewriting;
021
022import static java.util.Objects.requireNonNull;
023
024import java.util.Map;
025import java.util.Objects;
026
027import io.jenetics.ext.rewriting.TreePattern.Var;
028import io.jenetics.ext.util.Tree;
029
030/**
031 * The result of a tree match operation. It contains the matching tree and the
032 * tree variables which matches the matching tree.
033 * {@snippet lang="java":
034 * final Tree<String, ?> tree = null; // @replace substring='null' replacement="..."
035 * final TreePattern<String> pattern = null; // @replace substring='null' replacement="..."
036 * final Optional<TreeMatchResult<String>> result = pattern.match(tree);
037 * result.ifPresent(r -> {assert r.tree() == tree;});
038 * }
039 *
040 * @see TreePattern#match(Tree)
041 *
042 * @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
043 * @version 5.0
044 * @since 5.0
045 */
046public final class TreeMatchResult<V> {
047
048        private final Tree<V, ?> _tree;
049        private final Map<Var<V>, Tree<V, ?>> _vars;
050
051        private TreeMatchResult(
052                final Tree<V, ?> tree,
053                final Map<Var<V>, Tree<V, ?>> vars
054        ) {
055                _tree = requireNonNull(tree);
056                _vars = Map.copyOf(vars);
057        }
058
059        /**
060         * The node (tree), which has been matched by some pattern. This tree is the
061         * argument of the {@link TreePattern#match(Tree)} call, in the case of a
062         * match.
063         * {@snippet lang="java":
064         * final Tree<String, ?> tree = null; // @replace substring='null' replacement="..."
065         * final TreePattern<String> pattern = null; // @replace substring='null' replacement="..."
066         * final Optional<TreeMatchResult<String>> result = pattern.match(tree);
067         * result.ifPresent(r -> {assert r.tree() == tree;});
068         * }
069         *
070         * @return node (tree), which has been matched by some pattern
071         */
072        public Tree<V, ?> tree() {
073                return _tree;
074        }
075
076        /**
077         * The variables involved while matching the tree {@link #tree()}.
078         *
079         * @return variables involved while matching the tree {@link #tree()}.
080         */
081        public Map<Var<V>, Tree<V, ?>> vars() {
082                return _vars;
083        }
084
085        @Override
086        public int hashCode() {
087                return Objects.hash(_tree, _vars);
088        }
089
090        @Override
091        public boolean equals(final Object obj) {
092                return obj instanceof TreeMatchResult<?> other &&
093                        _tree.equals(other._tree) &&
094                        _vars.equals(other._vars);
095        }
096
097        @Override
098        public String toString() {
099                return _tree.toParenthesesString();
100        }
101
102        static <V> TreeMatchResult<V> of(
103                final Tree<V, ?> tree,
104                final Map<Var<V>, Tree<V, ?>> vars
105        ) {
106                return new TreeMatchResult<>(tree, vars);
107        }
108
109}