sp fn: rank

rank:
    description:
        rank sp
        Map the index position in the given superposition to the coefficient
        So the first ket gets coeff 1, the second coeff 2, and so on
        the existing coefficients are ignored/over-written

    examples:
        -- abstract example, let's rank some fruit:
        rank split[" "] |apples bananas oranges pears>
            |apples> + 2|bananas> + 3|oranges> + 4|pears>

        -- provide a ranking in a table:
        coeff |*> #=> extract-value push-float |_self>
        table[fruit, coeff] rank split[" "] |apples bananas oranges pears>
            +---------+-------+
            | fruit   | coeff |
            +---------+-------+
            | apples  | 1     |
            | bananas | 2     |
            | oranges | 3     |
            | pears   | 4     |
            +---------+-------+

        -- define a rank table operator:
        rank-table {the|sp>} #=>
            for(the|ket> in rank the |sp>):
                the-rank the|ket> => extract-value push-float the |ket>
            end:
            table[ket, the-rank] the |sp>

        -- now invoke it:
        rank-table split[" "] |apples bananas oranges pears cherries>
            +----------+----------+
            | ket      | the-rank |
            +----------+----------+
            | apples   | 1        |
            | bananas  | 2        |
            | oranges  | 3        |
            | pears    | 4        |
            | cherries | 5        |
            +----------+----------+

    see also:
        table, for