com.ibm.icu.text

Class ConstrainedFieldPosition

java.lang.Object

com.ibm.icu.text.ConstrainedFieldPosition

public class ConstrainedFieldPosition
extends Object

Represents a span of a string containing a given field. This class differs from FieldPosition in the following ways: 1. It has information on the field category. 2. It allows you to set constraints to use when iterating over field positions. 3. It is used for the newer FormattedValue APIs.

Author:

sffc

Status:

Stable ICU 64.

Constructor Summary

Constructors

Constructor and Description
ConstrainedFieldPosition() Initializes a CategoryFieldPosition.

Method Summary

Modifier and Type	Method and Description
void	constrainClass(Class<?> classConstraint) Sets a constraint on the field class.
void	constrainField(Format.Field field) Sets a constraint on the field.
void	constrainFieldAndValue(Format.Field field, Object fieldValue) Deprecated. This API is for technology preview and might be changed or removed in a future release.
Format.Field	getField() Gets the field for the current position.
Object	getFieldValue() Gets the value associated with the current field position.
long	getInt64IterationContext() Gets an int64 that FormattedValue implementations may use for storage.
int	getLimit() Gets the EXCLUSIVE end index stored for the current position.
int	getStart() Gets the INCLUSIVE start index for the current position.
boolean	matchesField(Format.Field field, Object fieldValue) Determines whether a given field and value should be included given the constraints.
void	reset() Resets this ConstrainedFieldPosition to its initial state, as if it were newly created: - Removes any constraints that may have been set on the instance
void	setInt64IterationContext(long context) Sets an int64 that FormattedValue implementations may use for storage.
void	setState(Format.Field field, Object value, int start, int limit) Sets new values for the primary public getters.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ConstrainedFieldPosition

public ConstrainedFieldPosition()

Initializes a CategoryFieldPosition. By default, the CategoryFieldPosition has no iteration constraints.

Status:

Stable ICU 64.

Method Detail

reset

public void reset()

Resets this ConstrainedFieldPosition to its initial state, as if it were newly created: - Removes any constraints that may have been set on the instance. - Resets the iteration position.

Status:

Stable ICU 64.

constrainField

public void constrainField(Format.Field field)

Sets a constraint on the field. When this instance of ConstrainedFieldPosition is passed to FormattedValue.nextPosition(com.ibm.icu.text.ConstrainedFieldPosition), positions are skipped unless they have the given field. Any previously set constraints are cleared. For example, to loop over all grouping separators:

 ConstrainedFieldPosition cfpos;
 cfpos.constrainField(NumberFormat.Field.GROUPING_SEPARATOR);
 while (fmtval.nextPosition(cfpos)) {
   // handle the grouping separator position
 }
 

Changing the constraint while in the middle of iterating over a FormattedValue does not generally have well-defined behavior.

Parameters:

field - The field to fix when iterating.

Status:

Stable ICU 64.

constrainClass

public void constrainClass(Class<?> classConstraint)

Sets a constraint on the field class. When this instance of ConstrainedFieldPosition is passed to FormattedValue.nextPosition(com.ibm.icu.text.ConstrainedFieldPosition), positions are skipped unless the field is an instance of the class constraint, including subclasses. Any previously set constraints are cleared. For example, to loop over only the number-related fields:

 ConstrainedFieldPosition cfpos;
 cfpos.constrainClass(NumberFormat.Field.class);
 while (fmtval.nextPosition(cfpos)) {
   // handle the number-related field position
 }
 

Parameters:

classConstraint - The field class to fix when iterating.

Status:

Stable ICU 64.

constrainFieldAndValue

@Deprecated
public void constrainFieldAndValue(Format.Field field,
                                               Object fieldValue)

Deprecated. This API is for technology preview and might be changed or removed in a future release.

Sets a constraint on field and field value. When this instance of ConstrainedFieldPosition is passed to FormattedValue.nextPosition(com.ibm.icu.text.ConstrainedFieldPosition), positions are skipped unless both the field and the field value are equal. Any previously set constraints are cleared. For example, to find the span a date interval corresponding to the first date:

 ConstrainedFieldPosition cfpos;
 cfpos.constrainFieldAndValue(DateIntervalFormat.SpanField.DATE_INTERVAL_SPAN, 0);
 while (fmtval.nextPosition(cfpos)) {
   // handle the span of the first date in the date interval
 }
 

Parameters:

field - The field to fix when iterating.

fieldValue - The field value to fix when iterating.

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

getField

public Format.Field getField()

Gets the field for the current position. The return value is well-defined and non-null only after FormattedValue#nextPosition returns true.

Returns:

The field saved in the instance. See above for null conditions.

Status:

Stable ICU 64.

getStart

public int getStart()

Gets the INCLUSIVE start index for the current position. The return value is well-defined only after FormattedValue#nextPosition returns true.

Returns:

The start index saved in the instance.

Status:

Stable ICU 64.

getLimit

public int getLimit()

Gets the EXCLUSIVE end index stored for the current position. The return value is well-defined only after FormattedValue#nextPosition returns true.

Returns:

The end index saved in the instance.

Status:

Stable ICU 64.

getFieldValue

public Object getFieldValue()

Gets the value associated with the current field position. The field value is often not set. The return value is well-defined only after FormattedValue#nextPosition returns true.

Returns:

The value for the current position. Might be null.

Status:

Stable ICU 64.

getInt64IterationContext

public long getInt64IterationContext()

Gets an int64 that FormattedValue implementations may use for storage. The initial value is zero. Users of FormattedValue should not need to call this method.

Returns:

The current iteration context from setInt64IterationContext(long).

Status:

Stable ICU 64.

setInt64IterationContext

public void setInt64IterationContext(long context)

Sets an int64 that FormattedValue implementations may use for storage. Intended to be used by FormattedValue implementations.

Parameters:

context - The new iteration context.

Status:

Stable ICU 64.

setState

public void setState(Format.Field field,
                     Object value,
                     int start,
                     int limit)

Sets new values for the primary public getters. Intended to be used by FormattedValue implementations. It is up to the implementation to ensure that the user-requested constraints are satisfied. This method does not check!

Parameters:

field - The new field.

value - The new field value. Should be null if there is no value.

start - The new inclusive start index.

limit - The new exclusive end index.

Status:

Stable ICU 64.

matchesField

public boolean matchesField(Format.Field field,
                            Object fieldValue)

Determines whether a given field and value should be included given the constraints. Intended to be used by FormattedValue implementations.

Parameters:

field - The field to test.

fieldValue - The field value to test. Should be null if there is no value.

Returns:

Whether the field should be included given the constraints.

Status:

Stable ICU 64.

toString

public String toString()

Overrides:

toString in class Object

Status:

Stable ICU 64.