[X++] getFirstSelection global function

Today I stumpled upon a global function called getFirstSelection that I never saw before in Dynamics AX 2012.

What is getFirstSelection?

Basically this is a function residing in the Global class to return the first selected record of a FormDataSource or the current cursor position if no selection can be found.

static Common getFirstSelection(FormDataSource _formDataSource)
{
    Common common = _formDataSource.getFirst(true);
    if (!common)
        common = _formDataSource.cursor();
    return common;
}

Where to find it in standard code?

One example of the usage in standard code can be found here:
Classes\CustWriteOff\initFromCustTrans in line 28:

...
for (custTrans = getFirstSelection(_formDS);
         custTrans;
         custTrans = _formDS.getNext())
    {
...

When to use it?

Use it whenever an iteration over selected records of a FormDataSource is required instead of writing the check routine by yourself. See it as a shortcut!

Why to use it?

Most of the time I see code like this:

...
for (custTable= _formDS.getFirst(true);
         custTable;
         custTable= _formDS.getNext())
    {
...

And this code does not cover the case when there is no selection made but the actual cursor should be used. So the global function getFirstSelection ensures you get the right record regardless of the selection.