StrToken/NumToken

Quando voce so precisa de uma parte de uma string separada, StrToken e mais leve que Separa — nao monta array, vai direto pro indice. NumToken conta quantas partes tem.

Sintaxe

StrToken(cString, nN, cSep)  --> cToken
//   nN = indice (1-base) do token que voce quer

NumToken(cString, cSep)       --> nQtd

Exemplos

cStr := "01;CLIENTE A;100"

StrToken(cStr, 1, ";")    // "01"
StrToken(cStr, 2, ";")    // "CLIENTE A"
StrToken(cStr, 3, ";")    // "100"
StrToken(cStr, 4, ";")    // ""        (nao existe)

NumToken(cStr, ";")       // 3

Quando usar (em vez de Separa)

• Precisa so de 1 ou 2 partes — Separa monta array inteiro desnecessariamente.
• Em loop pesado — alocacao de array repetida custa.
• Acesso aleatorio — pegar so o 5º elemento de uma string com 100 partes.

Caso pratico: CSV linha por linha sem montar array

// Arquivo CSV com 50.000 linhas, voce so quer codigo (col 1) e qtd (col 5)
While !FRead(cBuf)
    cCod  := AllTrim(StrToken(cBuf, 1, ";"))
    nQtd  := Val(StrToken(cBuf, 5, ";"))

    U_AjustaEstoque(cCod, nQtd)
EndDo
// 50.000 calls de Separa criariam 50.000 arrays
// 50.000 calls de StrToken pulam o overhead

Caso pratico: validar tamanho de CSV

// Espera 8 colunas
If NumToken(cLinha, ";") != 8
    ConOut("Linha invalida (" + cValToChar(NumToken(cLinha, ";")) + " colunas, esperadas 8)")
    Loop  // skip
EndIf

Pegadinhas

• Indice 1-base — primeiro token e StrToken(..., 1, ...).
• Indice invalido (maior que NumToken) retorna string vazia "" — nao excecao.
• Sem trim implicito — combine com AllTrim se precisar limpar.
• Multiplos chamados pro mesmo token em loop apertado nao vale a pena — caso geral, use Separa uma vez.

Performance: StrToken vs Separa

// Cenario: 100.000 iteracoes, pegar 1 elemento

// Lento — 100k arrays criados
For i := 1 To 100000
    aPart := Separa(cLinha, ";")
    cCod  := aPart[1]
Next

// Rapido — sem array
For i := 1 To 100000
    cCod := StrToken(cLinha, 1, ";")
Next