FieldPosition


1   /*
2    * @(#)FieldPosition.java   1.21 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   /*
9    * (C) Copyright Taligent, Inc. 1996 - All Rights Reserved
10   * (C) Copyright IBM Corp. 1996 - All Rights Reserved
11   *
12   *   The original version of this source code and documentation is copyrighted
13   * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These
14   * materials are provided under terms of a License Agreement between Taligent
15   * and Sun. This technology is protected by multiple US and International
16   * patents. This notice and attribution to Taligent may not be removed.
17   *   Taligent is a registered trademark of Taligent, Inc.
18   *
19   */
20  
21  package java.text;
22  
23  /**
24   * <code>FieldPosition</code> is a simple class used by <code>Format</code>
25   * and its subclasses to identify fields in formatted output. Fields can
26   * be identified in two ways:
27   * <ul>
28   *  <li>By an integer constant, whose names typically end with
29   *      <code>_FIELD</code>. The constants are defined in the various
30   *      subclasses of <code>Format</code>.
31   *  <li>By a <code>Format.Field</code> constant, see <code>ERA_FIELD</code>
32   *      and its friends in <code>DateFormat</code> for an example.
33   * </ul>
34   * <p>
35   * <code>FieldPosition</code> keeps track of the position of the
36   * field within the formatted output with two indices: the index
37   * of the first character of the field and the index of the last
38   * character of the field.
39   *
40   * <p>
41   * One version of the <code>format</code> method in the various
42   * <code>Format</code> classes requires a <code>FieldPosition</code>
43   * object as an argument. You use this <code>format</code> method
44   * to perform partial formatting or to get information about the
45   * formatted output (such as the position of a field).
46   *
47   * <p>
48   * If you are interested in the positions of all attributes in the
49   * formatted string use the <code>Format</code> method
50   * <code>formatToCharacterIterator</code>.
51   *
52   * @version     1.21 12/19/03
53   * @author      Mark Davis
54   * @see         java.text.Format
55   */
56  public class FieldPosition {
57  
58      /**
59       * Input: Desired field to determine start and end offsets for.
60       * The meaning depends on the subclass of Format.
61       */
62      int field = 0;
63  
64      /**
65       * Output: End offset of field in text.
66       * If the field does not occur in the text, 0 is returned.
67       */
68      int endIndex = 0;
69  
70      /**
71       * Output: Start offset of field in text.
72       * If the field does not occur in the text, 0 is returned.
73       */
74      int beginIndex = 0;
75  
76      /**
77       * Desired field this FieldPosition is for.
78       */
79      private Format.Field   attribute;
80  
81      /**
82       * Creates a FieldPosition object for the given field.  Fields are
83       * identified by constants, whose names typically end with _FIELD,
84       * in the various subclasses of Format.
85       *
86       * @see java.text.NumberFormat#INTEGER_FIELD
87       * @see java.text.NumberFormat#FRACTION_FIELD
88       * @see java.text.DateFormat#YEAR_FIELD
89       * @see java.text.DateFormat#MONTH_FIELD
90       */
91      public FieldPosition(int field) {
92          this.field = field;
93      }
94  
95      /**
96       * Creates a FieldPosition object for the given field constant. Fields are
97       * identified by constants defined in the various <code>Format</code>
98       * subclasses. This is equivalent to calling
99       * <code>new FieldPosition(attribute, -1)</code>.
100      *
101      * @param attribute Format.Field constant identifying a field
102      * @since 1.4
103      */
104     public FieldPosition(Format.Field   attribute) {
105         this(attribute, -1);
106     }
107 
108     /**
109      * Creates a <code>FieldPosition</code> object for the given field.
110      * The field is identified by an attribute constant from one of the
111      * <code>Field</code> subclasses as well as an integer field ID
112      * defined by the <code>Format</code> subclasses. <code>Format</code>
113      * subclasses that are aware of <code>Field</code> should give precedence
114      * to <code>attribute</code> and ignore <code>fieldID</code> if
115      * <code>attribute</code> is not null. However, older <code>Format</code>
116      * subclasses may not be aware of <code>Field</code> and rely on
117      * <code>fieldID</code>. If the field has no corresponding integer
118      * constant, <code>fieldID</code> should be -1.
119      *
120      * @param attribute Format.Field constant identifying a field
121      * @param fieldID integer constantce identifying a field
122      * @since 1.4
123      */
124     public FieldPosition(Format.Field   attribute, int fieldID) {
125         this.attribute = attribute;
126         this.field = fieldID;
127     }
128 
129     /**
130      * Returns the field identifier as an attribute constant
131      * from one of the <code>Field</code> subclasses. May return null if
132      * the field is specified only by an integer field ID.
133      *
134      * @return Identifier for the field
135      * @since 1.4
136      */
137     public Format.Field   getFieldAttribute() {
138         return attribute;
139     }
140 
141     /**
142      * Retrieves the field identifier.
143      */
144     public int getField() {
145         return field;
146     }
147 
148     /**
149      * Retrieves the index of the first character in the requested field.
150      */
151     public int getBeginIndex() {
152         return beginIndex;
153     }
154 
155     /**
156      * Retrieves the index of the character following the last character in the
157      * requested field.
158      */
159     public int getEndIndex() {
160         return endIndex;
161     }
162 
163     /**
164      * Sets the begin index.  For use by subclasses of Format.
165      * @since 1.2
166      */
167     public void setBeginIndex(int bi) {
168         beginIndex = bi;
169     }
170 
171     /**
172      * Sets the end index.  For use by subclasses of Format.
173      * @since 1.2
174      */
175     public void setEndIndex(int ei) {
176         endIndex = ei;
177     }
178 
179     /**
180      * Returns a <code>Format.FieldDelegate</code> instance that is associated
181      * with the FieldPosition. When the delegate is notified of the same
182      * field the FieldPosition is associated with, the begin/end will be
183      * adjusted.
184      */
185     Format.FieldDelegate   getFieldDelegate() {
186         return new Delegate();
187     }
188 
189     /**
190      * Overrides equals
191      */
192     public boolean equals(Object   obj)
193     {
194         if (obj == null) return false;
195         if (!(obj instanceof FieldPosition  ))
196             return false;
197         FieldPosition   other = (FieldPosition  ) obj;
198         if (attribute == null) {
199             if (other.attribute != null) {
200                 return false;
201             }
202         }
203         else if (!attribute.equals(other.attribute)) {
204             return false;
205         }
206         return (beginIndex == other.beginIndex
207             && endIndex == other.endIndex
208             && field == other.field);
209     }
210 
211     /**
212      * Returns a hash code for this FieldPosition.
213      * @return a hash code value for this object
214      */
215     public int hashCode() {
216         return (field << 24) | (beginIndex << 16) | endIndex;
217     }
218 
219     /**
220      * Return a string representation of this FieldPosition.
221      * @return  a string representation of this object
222      */
223     public String   toString() {
224         return getClass().getName() +
225             "[field=" + field + ",attribute=" + attribute +
226             ",beginIndex=" + beginIndex +
227             ",endIndex=" + endIndex + ']';
228     }
229 
230 
231     /**
232      * Return true if the receiver wants a <code>Format.Field</code> value and
233      * <code>attribute</code> is equal to it.
234      */
235     private boolean matchesField(Format.Field   attribute) {
236         if (this.attribute != null) {
237             return this.attribute.equals(attribute);
238         }
239         return false;
240     }
241 
242     /**
243      * Return true if the receiver wants a <code>Format.Field</code> value and
244      * <code>attribute</code> is equal to it, or true if the receiver
245      * represents an inteter constant and <code>field</code> equals it.
246      */
247     private boolean matchesField(Format.Field   attribute, int field) {
248         if (this.attribute != null) {
249             return this.attribute.equals(attribute);
250         }
251         return (field == this.field);
252     }
253 
254 
255     /**
256      * An implementation of FieldDelegate that will adjust the begin/end
257      * of the FieldPosition if the arguments match the field of
258      * the FieldPosition.
259      */
260     private class Delegate implements Format.FieldDelegate   {
261         /**
262          * Indicates whether the field has been  encountered before. If this
263          * is true, and <code>formatted</code> is invoked, the begin/end
264          * are not updated.
265          */
266         private boolean encounteredField;
267 
268         public void formatted(Format.Field   attr, Object   value, int start,
269                               int end, StringBuffer   buffer) {
270             if (!encounteredField && matchesField(attr)) {
271                 setBeginIndex(start);
272                 setEndIndex(end);
273                 encounteredField = (start != end);
274             }
275         }
276 
277         public void formatted(int fieldID, Format.Field   attr, Object   value,
278                               int start, int end, StringBuffer   buffer) {
279             if (!encounteredField && matchesField(attr, fieldID)) {
280                 setBeginIndex(start);
281                 setEndIndex(end);
282                 encounteredField = (start != end);
283             }
284         }
285     }
286 }
287
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags