How to get a value returned by user defined function in expl3?

Question

I continue to study expl3 and I do not understand some behavior of user defined function, which returns an integer value (as I thought).

I want to use the integer number returned by \count_number_of_elements:n for further manipulation.

My function \count_number_of_elements:n work well and output correct number if I use it directly. But I need to assign its output to an integer variable. How can I did it?

---

MWE

---

A more or less real example: "Longest Collatz sequence" from Project Euler problem (but I want to avoid spoilers here)

\documentclass[12pt]{article}

\usepackage{xparse}
\ExplSyntaxOn
\int_new:N \l_initial_number_int

\cs_new:Nn \count_number_of_elements:n
{
    \int_new:N \l_number_int
    \int_set:Nn \l_number_int {1}
    \int_set:Nn \l_initial_number_int {#1}
    \int_do_while:nn
    {\l_initial_number_int != 1}
    {
    \int_incr:N \l_number_int
    \int_if_even:nTF {\l_initial_number_int}
        {\int_set:Nn \l_initial_number_int {\l_initial_number_int/2} } 
        {\int_set:Nn \l_initial_number_int {3*\l_initial_number_int + 1} }
    }
    \int_use:N \l_number_int
} 

\NewDocumentCommand{\MaxNumber}{m}
{
% Code for defining starting number, produces the longest chain. According to my idea, this code should use integer number produced by \count_number_of_elements:n

% say I need get output of \count_number_of_elements:n
\int_set:Nn \l_tmpa_int {\count_number_of_elements:n {#1}}
}

\ExplSyntaxOff

\begin{document}


\end{document}

Answer 1

There are two possible approaches here. If you want to allow a function to be used 'inside' something like the second argument of \int_set:Nn then it has to be expandable. That means it has to use only other functions which are themselves expandable, which in expl3 means that they are marked in interface3 with a star. So

\cs_new:Npn \my_function:n #1
  {
    \int_eval:n {#1}
  }

will work but

\cs_new:Npn \my_function:n #1  % See below: should be protected
  {
    \int_set:Nn \l_tmpa_tl {#1}
    \int_eval:n {#1}
  }

will not as \int_set:Nn is not marked with a star.

The second approach is needed where you want to use non-expandable functions: you have to arrange to set a variable for return:

\cs_new_protected:Npn \my_function:Nn #1#2
  {
    \int_set:Nn \l_tmpa_int {#2}
    \int_set_eq:NN #1 \l_tmpa_int
  }

(In a real application there would be more going on, of course.)

---

Note that many problems can be tackled by expansion, though this can get very wearing, depending on the issue at hand. Anything involving typesetting or assignment is specifically excluded: typesetting doesn't have a 'result' by expansion whilst assignments in TeX are not expandable. (If you use LuaTeX you can do assignments in Lua, but then the entire problem is then different.)

---

Note that you should not be using xparse here: these are code level not document level commands. For that reason, I have used \cs_new:Npn to create expandable code interfaces and \cs_new_protected:Npn for non-expandable ones.