FieldNameIterator (Jython API documentation)
Date: 2022-09-10

org.python.core.stringlib

## Class FieldNameIterator

- java.lang.Object
- - org.python.core.PyObject
  - - org.python.core.stringlib.FieldNameIterator

- All Implemented Interfaces:
    java.io.Serializable, Traverseproc

      public class FieldNameIterator
      extends PyObject
      implements Traverseproc

  This class is an implementation of the iterator object returned by `str._formatter_field_name_split()` and `unicode._formatter_field_name_split()`. The function `_formatter_field_name_split()` returns a pair (tuple) consisting of a head element and an instance of this iterator. The constructor of this class effectively implements that function, since as well as "being" the iterator, the object has an extra method `head()` to return the required first member of the pair.
  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `FieldNameIterator.Chunk`

    - ### Nested classes/interfaces inherited from class org.python.core.PyObject

      `PyObject.ConversionException`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static PyType` | `TYPE`

    - ### Fields inherited from class org.python.core.PyObject

      `gcMonitorGlobal`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FieldNameIterator(PyString fieldNameObject)` Create an iterator for the parts of this field name (and extract the head name field, which may be an empty string).
    `FieldNameIterator(java.lang.String fieldName, boolean bytes)` Create an iterator for the parts of this field name (and extract the head name field, which may be an empty string).

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `PyObject` | `__iter__()` Return an iterator that is used to iterate the element of this sequence.
    `PyObject` | `__iternext__()` Return the next element of the sequence that this is an iterator for.
    `java.lang.Object` | `head()`
    `boolean` | `isBytes()` If originally given a PyString, the iterator must return PyString not PyUnicode.
    `FieldNameIterator.Chunk` | `nextChunk()` Return the next "chunk" of the field name (or return null if ended).
    `PyObject` | `pyHead()` Return the head object from the field name, as `PyInteger`, `PyString` or `PyUnicode`.
    `boolean` | `refersDirectlyTo(PyObject ob)` Optional operation.
    `int` | `traverse(Visitproc visit, java.lang.Object arg)` Traverses all directly contained `PyObject`s.

    - ### Methods inherited from class org.python.core.PyObject

      `__abs__, __add__, __and__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __cmp__, __coerce__, __coerce_ex__, __complex__, __contains__, __delattr__, __delattr__, __delete__, __delitem__, __delitem__, __delslice__, __delslice__, __dir__, __div__, __divmod__, __ensure_finalizer__, __eq__, __findattr__, __findattr__, __findattr_ex__, __finditem__, __finditem__, __finditem__, __float__, __floordiv__, __format__, __ge__, __get__, __getattr__, __getattr__, __getitem__, __getitem__, __getnewargs__, __getslice__, __getslice__, __gt__, __hash__, __hex__, __iadd__, __iand__, __idiv__, __idivmod__, __ifloordiv__, __ilshift__, __imod__, __imul__, __index__, __int__, __invert__, __ior__, __ipow__, __irshift__, __isub__, __itruediv__, __ixor__, __le__, __len__, __long__, __lshift__, __lt__, __mod__, __mul__, __ne__, __neg__, __nonzero__, __not__, __oct__, __or__, __pos__, __pow__, __pow__, __radd__, __rand__, __rdiv__, __rdivmod__, __reduce__, __reduce_ex__, __reduce_ex__, __repr__, __rfloordiv__, __rlshift__, __rmod__, __rmul__, __ror__, __rpow__, __rrshift__, __rshift__, __rsub__, __rtruediv__, __rxor__, __set__, __setattr__, __setattr__, __setitem__, __setitem__, __setitem__, __setslice__, __setslice__, __str__, __sub__, __tojava__, __truediv__, __trunc__, __unicode__, __xor__, _add, _and, _callextra, _cmp, _div, _divmod, _doget, _doget, _doset, _eq, _floordiv, _ge, _gt, _iadd, _iand, _idiv, _idivmod, _ifloordiv, _ilshift, _imod, _imul, _in, _ior, _ipow, _irshift, _is, _isnot, _isub, _itruediv, _ixor, _jcall, _jcallexc, _jthrow, _le, _lshift, _lt, _mod, _mul, _ne, _notin, _or, _pow, _rshift, _sub, _truediv, _xor, asDouble, asIndex, asIndex, asInt, asInt, asIterable, asLong, asLong, asName, asName, asString, asString, asStringOrNull, asStringOrNull, bit_length, conjugate, delDict, delType, dispatch__init__, equals, fastGetClass, fastGetDict, getDict, getType, hashCode, implementsDescrDelete, implementsDescrGet, implementsDescrSet, invoke, invoke, invoke, invoke, invoke, invoke, isCallable, isDataDescr, isIndex, isInteger, isMappingType, isNumberType, isSequenceType, noAttributeError, object___subclasshook__, readonlyAttributeError, setDict, setType, toString`

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### TYPE

          public static final PyType TYPE

  - ### Constructor Detail

    - #### FieldNameIterator

          public FieldNameIterator(java.lang.String fieldName,
                                   boolean bytes)

      Create an iterator for the parts of this field name (and extract the head name field, which may be an empty string). According to the Python Standard Library documentation, a replacement field name has the structure:

           field_name        ::=  arg_name ("." attribute_name | "[" element_index "]")*
           arg_name          ::=  [identifier | integer]
           attribute_name    ::=  identifier
           element_index     ::=  integer | index_string

      The object is used from PyUnicode and from PyString, and we have to signal which it is, so that returned values may match in type.
      Parameters:
        `fieldName` - the field name as UTF-16
        `bytes` - true if elements returned should be PyString, else PyUnicode

    - #### FieldNameIterator

          public FieldNameIterator(PyString fieldNameObject)

      Create an iterator for the parts of this field name (and extract the head name field, which may be an empty string).
      Parameters:
        `fieldNameObject` -

  - ### Method Detail

    - #### __iter__

          public PyObject __iter__()

      Description copied from class: `PyObject`
      Return an iterator that is used to iterate the element of this sequence. From version 2.2, this method is the primary protocol for looping over sequences.

      If a PyObject subclass should support iteration based in the __finditem__() method, it must supply an implementation of __iter__() like this:

           public PyObject __iter__() {
               return new PySequenceIter(this);
           }

      When iterating over a python sequence from java code, it should be done with code like this:

           for (PyObject item : seq.asIterable()) {
               // Do something with item
           }

      Overrides:
        `__iter__` in class `PyObject`

    - #### __iternext__

          public PyObject __iternext__()

      Description copied from class: `PyObject`
      Return the next element of the sequence that this is an iterator for. Returns null when the end of the sequence is reached.
      Overrides:
        `__iternext__` in class `PyObject`

    - #### head

          public java.lang.Object head()

      Returns:
        the isolated head object from the field name.

    - #### pyHead

          public PyObject pyHead()

      Return the head object from the field name, as `PyInteger`, `PyString` or `PyUnicode`.
      Returns:
        the isolated head object from the field name.

    - #### isBytes

          public final boolean isBytes()

      If originally given a PyString, the iterator must return PyString not PyUnicode.
      Returns:
        true if originally given a PyString

    - #### nextChunk

          public FieldNameIterator.Chunk nextChunk()

      Return the next "chunk" of the field name (or return null if ended). A chunk is a 2-tuple describing:
      0. whether the chunk is an attribute name,
      1. the name or number (as a String or Integer) for accessing the value.
      Returns:
        next element of the field name

    - #### traverse

          public int traverse(Visitproc visit,
                              java.lang.Object arg)

      Description copied from interface: `Traverseproc`
      Traverses all directly contained `PyObject`s. Like in CPython, `arg` must be passed unmodified to `visit` as its second parameter. If `Visitproc.visit(PyObject, Object)` returns nonzero, this return value must be returned immediately by traverse. `Visitproc.visit(PyObject, Object)` must not be called with a `null` PyObject-argument.
      Specified by:
        `traverse` in interface `Traverseproc`

    - #### refersDirectlyTo

          public boolean refersDirectlyTo(PyObject ob)
                                   throws java.lang.UnsupportedOperationException

      Description copied from interface: `Traverseproc`
      Optional operation. Should only be implemented if it is more efficient than calling `Traverseproc.traverse(Visitproc, Object)` with a visitproc that just watches out for `ob`. Must return `false` if `ob` is `null`.
      Specified by:
        `refersDirectlyTo` in interface `Traverseproc`
      Throws:
        `java.lang.UnsupportedOperationException`

Jython homepage