KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > sablecc > sablecc > alphabet > AdjacencyRealm


1 /* This file is part of SableCC ( http://sablecc.org ).
2  *
3  * Copyright 2007 Etienne M. Gagnon <egagnon@j-meg.com>
4  * Copyright 2007 Patrick Pelletier <pp.pelletier@gmail.com>
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18
19 package org.sablecc.sablecc.alphabet;
20
21 import org.sablecc.sablecc.exception.InternalException;
22
23 /**
24  * An adjacency realm defines adjacency rules for <code>T</code> elements. In
25  * other words, it defines the value of <code>(bound + 1)</code>. This allows
26  * for using non-integer types as interval bounds, as long as an adjacency realm
27  * is provided.
28  * <p>
29  * An adjacency realm also serves as a <em>universe</em> (or realm) to create
30  * <code>Interval</code> instances. Two intervals can only be compared when
31  * they belong to the same realm.
32  */
33
34 public abstract class AdjacencyRealm<T extends Comparable JavaDoc<? super T>> {
35
36     /**
37      * Creates a new instance.
38      */
39     public AdjacencyRealm() {
40
41     }
42
43     /**
44      * Returns whether two bounds are adjacents. For example, if <code>T</code>
45      * is an integer type, it returns <code>true</code> when
46      * <code>(bound1 + 1) == bound2</code>.
47      *
48      * @param bound1
49      * the first bound.
50      * @param bound2
51      * the second bound.
52      * @return <code>true</code> if the first bound is adjacent to the second;
53      * <code>false</code> otherwise.
54      */
55     public abstract boolean isAdjacent(
56             T bound1,
57             T bound2);
58
59     /**
60      * Returns the <code>T</code> element preceding the provided bound.
61      * Generally <code>(bound - 1)</code> or its equivalent.
62      *
63      * @param bound
64      * a bound.
65      * @return the <code>T</code> element that precedes to the provided bound.
66      */
67     public abstract T previous(
68             T bound);
69
70     /**
71      * Returns the <code>T</code> element following the provided bound.
72      * Generally <code>(bound + 1)</code> or its equivalent.
73      *
74      * @param bound
75      * a bound.
76      * @return the <code>T</code> element that follows the the provided bound.
77      */
78     public abstract T next(
79             T bound);
80
81     /**
82      * Returns the minimum of two bounds.
83      *
84      * @param bound1
85      * the first bound.
86      * @param bound2
87      * the second bound.
88      * @return the smallest of the two bounds, or <code>bound1</code> in case
89      * of equality.
90      * @throws InternalException
91      * if one of the two bounds is <code>null</code>.
92      */
93     public static <T extends Comparable JavaDoc<? super T>> T min(
94             T bound1,
95             T bound2) {
96
97         if (bound1 == null) {
98             throw new InternalException("bound1 may not be null");
99         }
100
101         if (bound2 == null) {
102             throw new InternalException("bound2 may not be null");
103         }
104
105         if (bound1.compareTo(bound2) <= 0) {
106             return bound1;
107         }
108
109         return bound2;
110     }
111
112     /**
113      * Returns the maximum of two bounds.
114      *
115      * @param bound1
116      * the first bound.
117      * @param bound2
118      * the second bound.
119      * @return the biggest of the two bounds, or <code>bound1</code> in case
120      * of equality.
121      * @throws InternalException
122      * if one of the two bounds is <code>null</code>.
123      */
124     public static <T extends Comparable JavaDoc<? super T>> T max(
125             T bound1,
126             T bound2) {
127
128         if (bound1 == null) {
129             throw new InternalException("bound1 may not be null");
130         }
131
132         if (bound2 == null) {
133             throw new InternalException("bound2 may not be null");
134         }
135
136         if (bound1.compareTo(bound2) >= 0) {
137             return bound1;
138         }
139
140         return bound2;
141     }
142
143     /**
144      * Creates a new interval with the provided lower and upper bounds.
145      *
146      * @param lowerBound
147      * the lower bound.
148      * @param upperBound
149      * the upper bound.
150      * @return the newly created interval.
151      */
152     public Interval<T> createInterval(
153             T lowerBound,
154             T upperBound) {
155
156         if (lowerBound == null) {
157             throw new InternalException("lowerBound may not be null");
158         }
159
160         if (upperBound == null) {
161             throw new InternalException("upperBound may not be null");
162         }
163
164         return new Interval<T>(lowerBound, upperBound, this);
165     }
166
167     /**
168      * Creates a new interval with a single bound used as both lower and upper
169      * bounds.
170      *
171      * @param bound
172      * the bound. Used as both upper and lower bound.
173      * @return the newly created interval.
174      */
175     public Interval<T> createInterval(
176             T bound) {
177
178         if (bound == null) {
179             throw new InternalException("bound may not be null");
180         }
181
182         return new Interval<T>(bound, this);
183
184     }
185 }
186
Popular Tags