Code Library M

Code Library M — Validação, Formatação e Utilitários

MUST

• fnGrausParaDecimais, fnClassificacaoIMC, fnTelefoneAnonimo e fnDocumentoAnonimo já aparecem corrigidos neste documento (capitalização fn minúsculo + nomes ASCII puro, sem acento) — aplicar essas 4 renomeações na fonte real do Code Library antes de publicar. Ver achados 1 e 2 para o racional de cada uma.
• Creditar autoria externa nas 2 funções adaptadas de terceiros (fnFeriados, fnHorasEntreDatas) — não são 100% autorais como o resto do Code Library, e o próprio script já registra os créditos originais em Documentation.Author.

AVOID

• Não reintroduzir os nomes originais (FnGrausParaDecimais com F maiúsculo, ou as 3 variantes acentuadas) — foram corrigidos por quebrarem a convenção fn + PascalCase ASCII já em uso no restante do Code Library (achados 1 e 2 abaixo detalham o porquê).

---

1. Tabela de funções

2. Descrições (resumo, ver script para versão completa)

• fnFormatWithLeadingZeros — zeros à esquerda, aceita número ou texto, aplica ABS internamente.
• fnValidaCPF / fnValidaCNPJ — validam estrutura e dígitos verificadores, aceitam entrada formatada ou não, rejeitam sequências repetidas (111.111.111-11 etc.).
• fnFormataNome — capitalização correta de nomes próprios: mantém partículas minúsculas (de, van), trata prefixos compostos (McGregor, MacDonald), hífens e apóstrofos.
• fnNuvemDePalavras — remove stopwords (artigos, preposições) para preparar texto para nuvem de palavras.
• fnGrausParaDecimais (nome corrigido) — converte coordenada geográfica em graus/minutos/segundos (23°34'45"S) para decimal, interpretando a direção (N/S/E/W/O).
• fnRemoveAcentos — remove acentos via truque de codificação (Text.ToBinary com code page 1251 → Text.FromBinary UTF-8).
• fnClassificacaoIMC — classifica IMC pelos intervalos da OMS.
• fnFeriados — tabela de feriados fixos e móveis do ano informado; feriados móveis calculados a partir do Domingo de Páscoa (algoritmo de Gauss).
• fnTelefoneAnonimo / fnDocumentoAnonimo — anonimização parcial (preserva início/fim, mascara o meio) — uso típico: LGPD, exibir dado sensível em ambiente de demonstração/treinamento sem expor o valor real.
• fnHorasEntreDatas — lista de todas as horas cheias entre duas datas/horários.

3. Achados da auditoria

Achado 1 — inconsistência de capitalização (corrigida): o script original tinha FnGrausParaDecimais com F maiúsculo — única das 12 funções que quebrava a convenção fn + PascalCase que as outras 11 seguem à risca. Corrigido neste documento para fnGrausParaDecimais.

Achado 2 — caracteres acentuados em 3 identificadores (corrigido — nomes ASCII puro): os nomes originais (fnClassificaçãoIMC, fnTelefoneAnônimo, fnDocumentoAnônimo) usavam ç/ã/ô no próprio nome da função. M aceita identificadores Unicode, então funcionava no Power BI Desktop sem erro — mas é uma prática arriscada: chamar essas funções de dentro de outra expressão M exige escapar o nome com #"..." (ex.: #"fnClassificaçãoIMC"(25)), e ferramentas de terceiros ou pipelines de automação via XMLA/CI podem não lidar bem com identificadores não-ASCII. Renomeados neste documento para fnClassificacaoIMC, fnTelefoneAnonimo e fnDocumentoAnonimo (sem acento, chamada direta sem #"..." necessário) — aplicar o mesmo na fonte real do Code Library.

Achado 3 — autoria mista, não 100% autoral: diferente do restante do Code Library (DataHora, Delta, Estatistica — todos de autoria própria), fnFeriados e fnHorasEntreDatas são adaptações de funções de terceiros (Laennder Alves e Imke Feldmann, respectivamente — ambos nomes conhecidos da comunidade Power Query). O próprio script já registra isso em Documentation.Author. Manter a atribuição visível na Biblioteca é tanto uma questão de crédito quanto de transparência sobre proveniência do código.

4. Padrão de documentação usado no script (para referência)

Todas as 12 funções seguem o mesmo padrão de metadados via Value.ReplaceType:

Value.ReplaceType(
    Função,
    Value.ReplaceMetadata(
        Value.Type(Função),
        [
            Documentation.Name = "...",
            Documentation.Description = "...",
            Documentation.LongDescription = "...",
            Documentation.Category = "...",
            Documentation.Source = "...",
            Documentation.Author = "...",
            Documentation.Version = "..."
        ]
    )
)

Esse padrão já é exatamente o que torna essas funções "auto-descritivas" no painel de Insights/Ajuda do Power Query — vale documentar como convenção recomendada para qualquer UDF M nova do Code Library, mesmo sem ligação direta com a Function Library.

5. O que fazer com BIBLIO_1.HTM

O segundo arquivo enviado junto é um artefato HTML/JS autocontido — aparenta ser um visualizador interativo dessas mesmas 12 funções (bundle com índice de nome/categoria/tipo de retorno embutido no JavaScript). Não extraí conteúdo adicional dele além do que já está no script TMDL (fonte mais confiável e completa). Se ele for um artefato gerado que você quer reaproveitar como peça de UI de referência (não como fonte de dados), me avisa — é um objeto diferente de "conteúdo a auditar".

Code Library M — Sufixo Ordinal e Feriados por Período

MUST

• Tratar fnHolidaysInPeriodEN/fnHolidaysInPeriodPT como variantes de fnFeriados (já documentada) — mesma lógica de Páscoa (algoritmo de Gauss), mas aceitam um intervalo de datas (StartDate/ EndDate) em vez de um único ano, cobrindo múltiplos anos numa chamada só.
• Excluir RangeEnd/RangeStart deste lote — dependem de uma tabela de projeto específica (TabIntProjeto[Data de Início/Término]), não são UDFs de propósito geral reutilizáveis. Não documentar como Code Library.

AVOID

• Não confundir fnHolidaysInPeriodEN com uma tradução literal de fnHolidaysInPeriodPT — os feriados listados são diferentes por país (EN = feriados federais dos EUA; PT = feriados nacionais do Brasil), não a mesma lista traduzida.

---

1. Tabela de funções

Convenção de dia da semana em fnLastWeekday/fnNthWeekday: segunda = 0 (baseado em Day.Monday), diferente da convenção DAX (WEEKDAY(..., 2) onde segunda = 1) — atenção ao portar lógica entre DAX e M.

2. Detalhe — sufixo ordinal

fnAddOrdinalSuffixEN(1) → "1st" fnAddOrdinalSuffixEN(22) → "22nd" fnAddOrdinalSuffixEN(11) → "11th" ← exceção (11/12/13 sempre "th") fnAddOrdinalSuffixPT(1, "M") → "1º" fnAddOrdinalSuffixPT(1, "F") → "1ª" fnAddOrdinalSuffixPT(2) → "2º" ← gênero omitido, padrão masculino

3. Detalhe — feriados por período (EUA)

fnHolidaysInPeriodEN cobre: New Year's Day, Juneteenth National Independence Day, Independence Day, Veterans Day, Christmas Day (fixos) + Martin Luther King Jr. Day, Presidents' Day, Memorial Day, Labor Day, Columbus Day, Thanksgiving Day (móveis, calculados via fnNthWeekday/fnLastWeekday). Nenhum feriado religioso móvel (Páscoa) — diferente da versão PT, que é toda baseada em Páscoa para os móveis.

fnHolidaysInPeriodPT cobre os mesmos 8 feriados fixos +4 móveis já documentados em fnFeriados, mas aceita intervalo multi-ano.

4. Detalhe — enésima/última ocorrência de dia da semana

fnNthWeekday(2025, 1, 0, 3) → #date(2025, 1, 20) -- 3ª segunda de jan/2025 fnLastWeekday(2025, 3, 4) → #date(2025, 3, 28) -- última sexta de mar/2025

Uso típico: definir feriados móveis baseados em regra de calendário (não em data fixa), como os próprios fnHolidaysInPeriodEN internamente fazem para MLK Day, Presidents' Day, Labor Day etc.

5. Itens excluídos deste lote

RangeEnd e RangeStart calculam início/fim do ano com base na primeira/última data de uma tabela TabIntProjeto específica — utilitários de projeto (provavelmente parâmetros de intervalo de uma query M específica), não funções de propósito geral. Não fazem parte do Code Library reutilizável; ficam de fora desta documentação.