# How do you actually find out \*how\* to use an interface in Julia, like the concept of iterator "end"?

**URL:** <https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796>\
**Category:** New to Julia\
**Created:** [December 29, 2025, 7:09pm UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796 "2025-12-29T19:09:39Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![teacup775](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/teacup775/32/219999_2.png) [@teacup775](https://discourse.julialang.org/u/teacup775)\
**Post date:** [December 29, 2025, 7:09pm UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/1 "2025-12-29T19:09:39Z")

</div>

So I am simply trying to find out how I identify that an iterator has come to the end of its content. The language is documentation standard doesn’t seem to be designed to help people understand what the contract of an interface is.

I come from a lot of use of Java amongst a bunch of other languages and I cannot stress enough how user unfriendly the documentation is.

I expect the documentation to explain all the landmark elements of an interface. So for example, in Java, if I look up the interface for an iterator it very clearly expand. Here’s the start. Here’s the end. Here’s how you query, whether or not the iterator is reach the end of its content, and these are all expressed as isclear statements and it takes a minute or two to understand what the interface does this is not the case with JL documentation.

I’ve spent like 20 minutes or a half an hour just trying to answer a question I know in every other language I’ve run into. I can get answered in about two minutes.

If I am using an interator on an array, how do I test that it’s reached the end?

Like if iterator.end() == true …?

But if somebody can explain to me what I’m supposed to do with the documentation system of the language in order to answer these questions you would be doing me a great favor

---

<div class="post-metadata">

**Author:** ![raman\_kumar](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/raman_kumar/32/26782_2.png) [@raman\_kumar](https://discourse.julialang.org/u/raman_kumar)\
**Post date:** [December 29, 2025, 7:43pm UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/2 "2025-12-29T19:43:09Z")

</div>

If you would have defined the iteration condition like `for i in 1:10` then `i==10` will be the iteration end condition.

> **[Iteration - Interfaces · The Julia Language](https://docs.julialang.org/en/v1/manual/interfaces/#man-interface-iteration)**
>
> A lot of the power and extensibility in Julia comes from a collection of informal interfaces. By extending a few specific methods to work for a custom type, objects of that type not only receive those functionalities, but they are also able to be...

See that `iterate(iter, state) == nothing` is the condition for iteration end.  
May be this post can be of help [Understanding iterate() documentation is tough](https://discourse.julialang.org/t/understanding-iterate-documentation-is-tough/134715).

---

<div class="post-metadata">

**Author:** ![teacup775](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/teacup775/32/219999_2.png) [@teacup775](https://discourse.julialang.org/u/teacup775)\
**Post date:** [December 29, 2025, 8:09pm UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/3 "2025-12-29T20:09:55Z")

</div>

thanks!

I will post here for others that usage is like this when you can’t use the convenience of built in language loop usage

```
it = iterate(x)

while it !== nothing
    i, state = it
    # some code
    it = iterate(x, state)
end

```

---

<div class="post-metadata">

**Author:** ![sgaure](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sgaure/32/14779_2.png) [@sgaure](https://discourse.julialang.org/u/sgaure)\
**Post date:** [December 29, 2025, 8:30pm UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/4 "2025-12-29T20:30:20Z")

</div>

> [@teacup775](#):
>
> I’ve spent like 20 minutes or a half an hour just trying to answer a question I know in every other language I’ve run into. I can get answered in about two minutes.
> 
> If I am using an interator on an array, how do I test that it’s reached the end?
> 
> Like if iterator.end() == true …?

It’s, as raman\_kumar notes, in the docs, under Interfaces-\>iterators, but note that iterators in julia typically are stateless. That is, the iterator itself does not “know” that it’s finished. There is usually no state which is updated in an iterator, so you can’t ask the iterator whether it has reached the end. The state is part of the iteration, not of the iterator. The most common way to use an iterator is in a `for` loop. You don’t get to see the iteration state in a `for` loop, only the elements, one by one. And there is no general way to tell if you’re in the last iteration. It depends on the iterator. Some iterators have a known length, whereas others don’t, and some go on indefinitely.

---

<div class="post-metadata">

**Author:** ![teacup775](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/teacup775/32/219999_2.png) [@teacup775](https://discourse.julialang.org/u/teacup775)\
**Post date:** [December 29, 2025, 8:54pm UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/5 "2025-12-29T20:54:51Z")

</div>

I want to point out, the structure of my complaint is that the documentation is there, but it is so organized as to be nearly useless or extremely frustrating to somebody like myself..

For example, if I go to C++ or to Java or any other language documentation, and they describe an interface like iterators, you see a clear, concise definition of what they are on a single page and what the contract for that interface is.

My experience with JL documentation is it not clearly presented and it’s so obscurely presented as to require an order of magnitude more effort to learn about many things that are basic.

This thread is a testimony to how frustrating it is. The documentation assumes people don’t care about the constituent parts and it assumes people will only use them in a loop or a while loop and the mechanics will be handled by the language.

---

<div class="post-metadata">

**Author:** ![sgaure](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sgaure/32/14779_2.png) [@sgaure](https://discourse.julialang.org/u/sgaure)\
**Post date:** [December 29, 2025, 9:29pm UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/6 "2025-12-29T21:29:00Z")

</div>

I see your point. An inconvenience with julia, reflected in the documentation, is that very little is “part of the language”. The interfaces are more or less just conventions. Iterators are sort of an exception, in that the compiler/parser/lowering-engine actually rewrites `for` loops (literally) into `while` loops, so this particular interface is in a sense part of the language. But the other “interfaces” are merely conventions. Even conversion of `1 + 1.0` to `Float64` is sort of a convention. It can be changed at will.

Every function and operator can be overloaded, and it’s common to do so, it’s even sort of how the entire language operates. (Try e.g. a `methods(*)` to see it). And it’s a kind of a silent agreement that you shouldn’t abuse things (e.g. so that `a + b` suddenly means "print `a`, save `b` to a file, and return `b - a`).

Of course, such things are also possible in other languages, but overloading/dispatch is typically not done as massively at the user level as in julia. I suspect it’s simply too much functionality to document properly.

In a sense, every abstract type, there are many of them, is a sort of interface, but little is documented about what an abstract type promises in terms of functionality:

```julia
help?> IO
search: IO

  No documentation found for public binding Core.IO.
...
help?> Number
search: Number Timer outer

  Number

  Abstract supertype for all number types.

```

Partly because it’s not necessarily well defined. It’s been introduced to collect some subtypes, without too much thought about what it really means in terms of functionality.

---

<div class="post-metadata">

**Author:** ![abraemer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/abraemer/32/51403_2.png) [@abraemer](https://discourse.julialang.org/u/abraemer)\
**Post date:** [December 29, 2025, 9:39pm UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/7 "2025-12-29T21:39:46Z")

</div>

> [@teacup775](#):
>
> So I am simply trying to find out how I identify that an iterator has come to the end of its content.

> [@teacup775](#):
>
> I expect the documentation to explain all the landmark elements of an interface.

Does it not? To me this from the manual is quite clear:

```julia-auto
Required method Brief description
iterate(iter) Returns either a tuple of the first item and initial state or nothing if empty
iterate(iter, state) Returns either a tuple of the next item and next state or nothing if no items remain

```

So if the iterator is exhausted then calling `iterate(iter, state)` returns `nothing`.  
Could you perhaps elaborate why you find this unclear and perhaps we can try to improve/clear up the wording?

---

<div class="post-metadata">

**Author:** ![adienes](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/adienes/32/37459_2.png) [@adienes](https://discourse.julialang.org/u/adienes)\
**Post date:** [December 29, 2025, 9:41pm UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/8 "2025-12-29T21:41:32Z")

</div>

unfortunately, it is not just an issue of documentation. interfaces in Julia are generally underspecified. Contracts that these interfaces satisfy are generally defined more by convention, trial-and-error, and word of mouth, than they are defined by an explicit and exhaustive design doc like you would find in C++ or Java.

in the case of iteration specifically, I think really all that can be said is

- `iterate(x)` must return a value and the next state (or `nothing`)
- `iterate(x, state)` must return a value and the next state (or `nothing`)
- when `nothing` is returned the iterator is done

but otherwise there are basically no universal rules about things like

- is `iterate(x, state)` idempotent
  - answer: no e.g. for stateful iterators

- does the number of `iterate` calls before `nothing` have to match `length(x)` ? and similarly does `eltype(x)` have to actually match the types of the values you get from `iterate(x)`
  - answer: it really should if you don’t want to break things (`collect`, `map`) in horrible ways, but the interface doesn’t explicitly demand this.

- if `x == y`, is some `state_x` obtained from iterating `x` a valid iteration state for `y` ?
  - in practice, usually yes, but the interface doesn’t demand it so it theoretically might not be. but using an invalid state for an iterator can be UB

- what the shape of `a value and the next state` should be. I was intentionally ambiguous with that wording since there is no actual requirement that it’s a `Tuple`. it just has to be destructurable into two parts like `x, state = iterate(x)`

that being said, I still think in practice this all ends up working out pretty well. I have found the iteration primitives & utilities to be powerful & basically sufficient for implementing any kind of iterator needed. so I am not trying to be negative — mostly just highlight that your frustration is very reasonable, but it is not caused so much by people “not caring about constituent parts” as it is by those parts being pretty amorphous in the first place.

---

<div class="post-metadata">

**Author:** ![raman\_kumar](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/raman_kumar/32/26782_2.png) [@raman\_kumar](https://discourse.julialang.org/u/raman_kumar)\
**Post date:** [December 29, 2025, 10:23pm UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/9 "2025-12-29T22:23:00Z")

</div>

> [@sgaure](#):
>
> Iterators are sort of an exception, in that the compiler/parser/lowering-engine actually rewrites `for` loops (literally) into `while` loops, so this particular interface is in a sense part of the language.

Is there contradiction about `loops` conversion between above and below post?

> [@Understanding iterate() documentation is tough](https://discourse.julialang.org/t/understanding-iterate-documentation-is-tough/134715/4):
>
> Behind the scenes, there’s no such thing as a for loop or while loop. It’s a bunch of gotos in intermediate code, LLVM br-anches, and ultimately native jumps. You can check with Meta.@lower or the @code\_### reflection macros. And no. First, your version omits the iter variable and adds extra stuff like @show, which are generally liberties you should avoid for documentation. Second, the for loop does not create a global variable next or the local variable state/index\*, so it’s obviously not th…

---

<div class="post-metadata">

**Author:** ![sgaure](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sgaure/32/14779_2.png) [@sgaure](https://discourse.julialang.org/u/sgaure)\
**Post date:** [December 29, 2025, 10:39pm UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/10 "2025-12-29T22:39:27Z")

</div>

> [@raman\_kumar](#):
>
> s there contradiction about `loops` between above and below post?

Not really. A `for` loop results in exactly the same lowered code as the equivalent `while` loop. I.e. the intermediate representations are identical except for some vaiable names.

> **Example llvm (click to expand)**
>
> ```julia-auto
> julia> forloop(it) = for i in it; println(i); end
> forloop (generic function with 1 method)
> 
> julia> whloop(it) = begin
> next = iterate(it)
> while next !== nothing
> (item, state) = next
> println(item)
> next = iterate(it, state)
> end
> end
> whloop (generic function with 1 method)
> 
> julia> @code_llvm debuginfo=:none whloop(1:10)
> ; Function Signature: whloop(Base.UnitRange{Int64})
> define void @julia_whloop_3129(ptr nocapture noundef nonnull readonly align 8 dereferenceable(16) %"it::UnitRange") #0 {
> top:
> %"it::UnitRange.stop_ptr" = getelementptr inbounds i8, ptr %"it::UnitRange", i64 8
> %"it::UnitRange.stop_ptr.unbox" = load i64, ptr %"it::UnitRange.stop_ptr", align 8
> %"it::UnitRange.unbox" = load i64, ptr %"it::UnitRange", align 8
> %.not = icmp slt i64 %"it::UnitRange.stop_ptr.unbox", %"it::UnitRange.unbox"
> br i1 %.not, label %L28, label %L17
> 
> L17: ; preds = %L17, %top
> %value_phi521 = phi i64 [%1, %L17], [%"it::UnitRange.unbox", %top]
> call void @j_println_3131(i64 signext %value_phi521)
> %0 = icmp eq i64 %value_phi521, %"it::UnitRange.stop_ptr.unbox"
> %1 = add i64 %value_phi521, 1
> br i1 %0, label %L28, label %L17
> 
> L28: ; preds = %L17, %top
> ret void
> }
> 
> julia> @code_llvm debuginfo=:none forloop(1:10)
> ; Function Signature: forloop(Base.UnitRange{Int64})
> define void @julia_forloop_3136(ptr nocapture noundef nonnull readonly align 8 dereferenceable(16) %"it::UnitRange") #0 {
> top:
> %"it::UnitRange.stop_ptr" = getelementptr inbounds i8, ptr %"it::UnitRange", i64 8
> %"it::UnitRange.stop_ptr.unbox" = load i64, ptr %"it::UnitRange.stop_ptr", align 8
> %"it::UnitRange.unbox" = load i64, ptr %"it::UnitRange", align 8
> %.not.not = icmp slt i64 %"it::UnitRange.stop_ptr.unbox", %"it::UnitRange.unbox"
> br i1 %.not.not, label %L29, label %L14
> 
> L14: ; preds = %L14, %top
> %value_phi4 = phi i64 [%0, %L14], [%"it::UnitRange.unbox", %top]
> call void @j_println_3138(i64 signext %value_phi4)
> %.not.not20 = icmp eq i64 %value_phi4, %"it::UnitRange.stop_ptr.unbox"
> %0 = add i64 %value_phi4, 1
> br i1 %.not.not20, label %L29, label %L14
> 
> L29: ; preds = %L14, %top
> ret void
> }
> 
> ```

---

<div class="post-metadata">

**Author:** ![raman\_kumar](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/raman_kumar/32/26782_2.png) [@raman\_kumar](https://discourse.julialang.org/u/raman_kumar)\
**Post date:** [December 29, 2025, 10:43pm UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/11 "2025-12-29T22:43:00Z")

</div>

> [@sgaure](#):
>
> rewrites `for` loops (literally) into `while` loops

> <https://github.com/JuliaLang/julia/blob/812f3beb0abcf7cd385b87974dae86fc9f69bf55/doc/src/manual/interfaces.md?plain=1#L45>

If they are equivalent then why `for loop` is converted to `while loop` ?

---

<div class="post-metadata">

**Author:** ![sgaure](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sgaure/32/14779_2.png) [@sgaure](https://discourse.julialang.org/u/sgaure)\
**Post date:** [December 29, 2025, 10:47pm UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/12 "2025-12-29T22:47:25Z")

</div>

> [@raman\_kumar](#):
>
> If they are equivalent then why `for loop` is converted to `while loop` ?

It’s just how a `for` loop is defined, as fully equivalent to the `while` loop in the docs about iterators (which you linked to above). Even though no textual `while` is inserted during the translation, it’s lowered to the same intermediate represenation. So, in this sense, a `for` loop is just syntactic sugar for a slightly more verbose `while` loop.

---

<div class="post-metadata">

**Author:** ![raman\_kumar](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/raman_kumar/32/26782_2.png) [@raman\_kumar](https://discourse.julialang.org/u/raman_kumar)\
**Post date:** [December 29, 2025, 10:51pm UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/13 "2025-12-29T22:51:32Z")

</div>

In documentation 45 line `is translated into:` should be replaced with `is equivalent to:`for clarity otherwise it creates confusion. Should i make PR?

---

<div class="post-metadata">

**Author:** ![sgaure](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sgaure/32/14779_2.png) [@sgaure](https://discourse.julialang.org/u/sgaure)\
**Post date:** [December 29, 2025, 11:03pm UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/14 "2025-12-29T23:03:12Z")

</div>

I suppose that’s an impementation detail. Whether it’s translated into a textual `while` loop, or translated into a functionally equivalent intermediate representation can’t really confuse anyone?

---

<div class="post-metadata">

**Author:** ![droodman](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/droodman/32/26652_2.png) [@droodman](https://discourse.julialang.org/u/droodman)\
**Post date:** [January 2, 2026, 3:45am UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/15 "2026-01-02T03:45:33Z")

</div>

Absolutely agree on the documentation point. The culture of ad hoc, half-organized documentation in Julia is a major impediment to working with it. Look up the documentation for a function in Python or one of its major libraries like NumPy and you’ll find a rigorous, consistent format. In Julia it’s much more hit-or-miss. I do find that the latest LLMs can partially compensate.

---

<div class="post-metadata">

**Author:** ![mkitti](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mkitti/32/12459_2.png) [@mkitti](https://discourse.julialang.org/u/mkitti)\
**Post date:** [January 2, 2026, 2:17pm UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/16 "2026-01-02T14:17:44Z")

</div>

> [@teacup775](#):
>
> I want to point out, the structure of my complaint is that the documentation is there, but it is so organized as to be nearly useless or extremely frustrating to somebody like myself..

I am still not clear what concrete actions to take in order to improve.

If I were looking at the documentation for the first time, I would look at the Table of Contents on the left side of the page (on mobile I have to click on the top left hamburger menu icon) and look for sections that mention iteration or interfaces:

There are two sections in the documentation’s table of contents:

- _Manual → Interfaces_: [Interfaces · The Julia Language](https://docs.julialang.org/en/v1/manual/interfaces/)
- _Base → Collections and Data Structures → Iteration_: [Collections and Data Structures · The Julia Language](https://docs.julialang.org/en/v1/base/collections/)

The first page then discusses Indexing and Abstract Array interfaces.

The second page contains a similar example to your while loop:

```julia
next = iterate(iter)
while next !== nothing
    (i, state) = next
    # body
    next = iterate(iter, state)
end

```

 ![Screenshot_20260102_074941_Chrome](https://global.discourse-cdn.com/julialang/original/3X/8/0/80ab6c17b6beb55460e032cdc97bf92b11b17ae3.jpeg)

 ![Screenshot_20260102_073528_Chrome](https://global.discourse-cdn.com/julialang/original/3X/1/c/1caf65c919176a1dae685fb4368e19030afec869.jpeg)

> [@teacup775](#):
>
> For example, if I go to C++ or to Java or any other language documentation, and they describe an interface like iterators, you see a clear, concise definition of what they are on a single page and what the contract for that interface is.

If I look at the Java documentation, I start at this page and see nothing about data structures, collections, or iteration:

> **[JDK 25 Documentation - Home](https://docs.oracle.com/en/java/javase/25/)**
>
> The documentation for JDK 25 includes developer guides, API documentation, and release notes.

I might start reading the Language Specification and end up here:

> **[The Java® Language Specification](https://docs.oracle.com/javase/specs/jls/se25/html/index.html)**

There is some information here about interfaces in the abstract and for loop iteration, but still nothing about an iteration interface.

After getting frustarted about this abstract definition of the language, I might start searching the API and find the `Iterator` interface.

> **[Iterator (Java SE 25 & JDK 25)](https://docs.oracle.com/en/java/javase/25/docs//api/java.base/java/util/Iterator.html)**
>
> declaration: module: java.base, package: java.util, interface: Iterator

Eventually I might get confused that there is not an `Array` class and that if I want to iterate an array, I have to use an [`ArrayList`](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/ArrayList.html).

I guess I’m confused to what exactly I should compare the the Julia documentation.

I actually learned Java as one of my first programming langauges so I remember a time when the Iterator interface did not exist and there was no `ArrayList`.

The main advantage that Java has here is a clear way to define interfaces. Currently, in base Julia interfaces are just documentation. There are, however, are proposals to create interface definitions that can be verified:

> **[BaseInterfaces.IterationInterface - BaseInterfaces.jl reference · Interfaces.jl](https://rafaqz.github.io/Interfaces.jl/stable/baseinterfaces/#BaseInterfaces.IterationInterface)**
>
> An Interfaces.jl Interface with mandatory components (:iterate, :isiterable, :eltype, :size, :in) and optional components (:reverse, :indexing). | Documentation for Interfaces.jl.

> [@teacup775](#):
>
> My experience with JL documentation is it not clearly presented and it’s so obscurely presented as to require an order of magnitude more effort to learn about many things that are basic.
> 
> This thread is a testimony to how frustrating it is. The documentation assumes people don’t care about the constituent parts and it assumes people will only use them in a loop or a while loop and the mechanics will be handled by the language.

I appreciate the feedback. It would be helpful if you can provide some specific constructive feedback now that you know where the documentation is.

- Should the `iterate` interface be defined on its own page?
- Where in the documentation and table of contents would you expect to find this information?

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [January 2, 2026, 2:41pm UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/17 "2026-01-02T14:41:29Z")

</div>

> [@adienes](#):
>
> interfaces in Julia are generally underspecified

I would not say that the iteration interface is “underspecified”, it perfectly well specified for iteration _as performed by the language_. It just leaves some questions up to the implementer, and that is fine.

Specifically,

> [@adienes](#):
>
> is `iterate(x, state)` idempotent
> 
> - answer: no e.g. for stateful iterators

_is_ a universal rule, you **can** have stateful iterators.

> [@adienes](#):
>
> does the number of `iterate` calls before `nothing` have to match `length(x)` ?

Yes, [the manual says](https://docs.julialang.org/en/v1/manual/interfaces/#man-interface-iteration) that `length` is

> The number of items, if known

so the interface _does_ explicitly demand it in any sane reading.

> [@adienes](#):
>
> if `x == y`, is some `state_x` obtained from iterating `x` a valid iteration state for `y`

No, since that is not required, you cannot generally assume that. One can design a perfectly valid (if weird) iterable where `x == y` does not imply `x === y` and this affects the iteration.

> [@adienes](#):
>
> what the shape of `a value and the next state` should be. I was intentionally ambiguous with that wording since there is no actual requirement that it’s a `Tuple`.

Yes, it has to be a a tuple, please read the manual:

> `iterate(iter, state)` Returns either a **tuple** of the next item and next state or `nothing` if no items remain

(emphasis mine).

> [@adienes](#):
>
> those parts being pretty amorphous in the first place

I disagree. Some of your questions are clearly answered in the manual, while some are just not explicitly specified or constrained by the interface. That is normal, it is an _interface_, you can only assume what it requires, and not more. It does not have to explicitly allow or rule out anything else.

---

<div class="post-metadata">

**Author:** ![adienes](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/adienes/32/37459_2.png) [@adienes](https://discourse.julialang.org/u/adienes)\
**Post date:** [January 2, 2026, 2:56pm UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/18 "2026-01-02T14:56:40Z")

</div>

won’t respond to every point (because I agree with you on some) but just two things:

> [@Tamas\_Papp](#):
>
> Yes, it has to be a a tuple, please read the manual:

I have read the manual. But the manual does not match reality. see e.g. [this discussion](https://github.com/JuliaLang/julia/pull/59142#pullrequestreview-3068436477). I would submit a PR to fix the documentation, except that I do not even know what the “correct” docstring should be (bc I find the interface to be ambiguous).

and on stateful iterators, yes I know that `Stateful` iterators exist, but my point in mentioning them is that the iterator interface as described in the documentation is so vague and nonprescriptive as to _how_ stateful iterators work, such that an unfortunately high fraction of algorithms that attempt to be generic over all iterators do not work as expected for stateful iterators. Just see how `length(::Stateful)` had to be [removed from the public API](https://github.com/JuliaLang/julia/pull/51747) as late as _1.11_, so these are not “old” problems.

---

<div class="post-metadata">

**Author:** ![mbauman](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mbauman/32/31082_2.png) [@mbauman](https://discourse.julialang.org/u/mbauman)\
**Post date:** [January 2, 2026, 3:04pm UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/19 "2026-01-02T15:04:26Z")

</div>

Yeah, a core issue here is that there are three or four wildly different levels of documention:

- Prescriptive demands on how things _must_ be implemented in order to function as expected
- Descriptive recommendations on how things _should_ be implemented
- Simplified guidance for new users on how to understand it

But then there’s also:

- Prescriptive/theoretical ideas of how things _should_ work
- Descriptive and concrete details on how the implementation _does_ work

All of the above exist in the manual. And are frequently mixed up within the _same docstring_. But it’s rarely clear which is what.

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [January 2, 2026, 3:12pm UTC](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/20 "2026-01-02T15:12:40Z")

</div>

> [@adienes](#):
>
> But the manual does not match reality. see e.g.

That implementation is just, strictly speaking, nonconforming; the manual is clear that it has to be a `Tuple`. But in practice, of course it matter very little as long as people just use the standard destructuring that can cope with anything.

Julia’s interfaces are not (yet) formally specified, so users are free to introduce nonconforming implementations. This does not mean that they specs are not clear though.

> [@adienes](#):
>
> the iterator interface as described in the documentation is so vague and nonprescriptive as to _how_ stateful iterators work

FWIW, I think that introducing stateful iterators in an interface that strives to separate the state was just overdesign. The [docstring](https://docs.julialang.org/en/v1/base/iterators/#Base.Iterators.Stateful) is in the top-10 most difficult to understand parts of the manual, and the wrapper gets very little usage.

[Next page](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796.md?page=2)