%%
%% `numspell.tex' documentation of the numspell package
%%
%% Copyright 2017-2026 by Tibor Tómács
%%
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3
%% of this license or (at your option) any later version.
%% The latest version of this license is in
%%   http://www.latex-project.org/lppl.txt
%% and version 1.3 or later is part of all distributions of LaTeX
%% version 2005/12/01 or later.
%%
%% This work has the LPPL maintenance status `maintained'.
%%
%% The Current Maintainer of this work is Tibor Tómács.
%%
\documentclass[12pt]{article}
\usepackage[a4paper,margin=1in]{geometry}
\usepackage[pdfstartview=FitH,colorlinks,allcolors=black,bookmarksnumbered,hyperfootnotes=false]{hyperref}
\usepackage[T1]{fontenc}
\usepackage[magyar,italian,latin,ngerman,french,english]{babel}
\usepackage[symbol]{footmisc}
\usepackage{numspell,listings,xcolor,amsmath,upquote}
\flushbottom
\setlength{\labelsep}{0pt}
\setlength{\parindent}{0pt}
\setlength{\parskip}{6pt}

\lstnewenvironment{examplelst}{\lstset{
aboveskip=\bigskipamount,
basicstyle=\ttfamily,
backgroundcolor=\color{black!10},
frame=trbl,
framesep=3pt,
columns=fullflexible,
xleftmargin=3.4pt,
xrightmargin=3.4pt, 
keepspaces}}{}

\newcommand{\commandinline}{\lstinline[
literate={<}{{$\langle$}}1{>}{{$\rangle$}}1,
delim={[is][\color{green!50!black}\normalfont\itshape]{!}{!}},
basicstyle=\color{blue!80!black}\ttfamily,
columns=fullflexible,
keepspaces]}

\newcommand{\verbinline}{\lstinline[
literate={<}{{$\langle$}}1{>}{{$\rangle$}}1,
delim={[is][\color{green!50!black}\normalfont\itshape]{!}{!}},
basicstyle=\ttfamily,
columns=fullflexible,
keepspaces]}

\begin{document}

\title{The {\bfseries\sffamily numspell} package\\{\large v1.8 (2026/01/08)}}
\author{Tibor Tómács\\{\normalsize\href{mailto:tomacs.tibor@gmail.com}{\texttt{tomacs.tibor@gmail.com}}}}
\date{}
\maketitle

\section{Introduction}
The \texttt{numspell} package spells out cardinal and ordinal integers up to 66 digits long.

The package supports British and American English, French, German, Hungarian, Italian, and Latin in its classical, medieval, modern, and ecclesiastical variants.\footnote{Thanks to Keno Wehr for the Latin language module.}
Number spelling is performed using the currently active language.

The \texttt{numspell} package requires the services of the \texttt{xstring} and \texttt{iflang} packages.

Load the package as usual, with
\begin{flushleft}
\commandinline|\usepackage{numspell}|
\end{flushleft}

\section{Commands}
\begin{description}
\item\commandinline|\numspell[!<zeros>!]{!<num>!}|\\
Spelling the cardinal number $n=\text{\color{green!50!black}\itshape$\langle$num$\rangle$}\cdot10^{\text{\color{green!50!black}\itshape$\langle$zeros$\rangle$}}$, where $0\leq n\leq 10^{66}-1$. The default value of \commandinline|!<zeros>!| is \texttt{0}. For example
\begin{flushleft}
\verb|\numspell{12000}| $\to$ \numspell{12000}\\
\verb|\numspell[3]{12}| $\to$ \numspell[3]{12}\\
\verb|\numspell[6]{12}| $\to$ \numspell[6]{12}\\
\verb|\numspell[63]{1}| $\to$ \numspell[63]{1}
\end{flushleft}

\item\commandinline|\thenumspell|\\
The \verb|\numspell| stores the result in this command. For example
\begin{flushleft}
\verb|\numspell{12000}; \thenumspell| $\to$ \numspell{12000}; \thenumspell\\
\verb|\numspell{1}; \numspell{2}; \thenumspell| $\to$ \numspell{1}; \numspell{2}; \thenumspell
\end{flushleft}

\item\commandinline|\numspellsave{!<name>!}|\\
Creates \commandinline|\thenumspell!<name>!| containing the current \verb|\thenumspell|.


For example
\begin{verbatim}
\numspell{1};
\numspellsave{MyNum}
\numspell{2};
\thenumspell;
\thenumspellMyNum
\end{verbatim}
\numspell{1};
\numspellsave{MyNum}
\numspell{2};
\thenumspell;
\thenumspellMyNum

\item\commandinline|\numspelldashspace{!<length>!}|\\
In the number spelling, the spaces around the dashes are flexibility for the optimal hyphenation. Its value is \texttt{0pt plus} \commandinline|!<length>!|.
The default value of \commandinline|!<length>!| is \texttt{2pt}. For example
\begin{verbatim}
\selectlanguage{magyar}
\numspell{1234567890123456789000}\\
\numspelldashspace{0pt}
\numspell{1234567890123456789000}
\end{verbatim}
{\selectlanguage{magyar}
\numspell{1234567890123456789000}\\
\numspelldashspace{0pt}
\numspell{1234567890123456789000}}

\item\commandinline|\numspell*[!<zeros>!]{!<num>!}|\\
It works like \verb|\numspell|, but the number spelling will not be printed.
In other words, the following two lines are equivalent:
\begin{flushleft}
\verbinline|\numspell[!<zeros>!]{!<num>!}|\\
\verbinline|\numspell*[!<zeros>!]{!<num>!}\thenumspell|
\end{flushleft}
For example
\begin{verbatim}
\numspell*{1}
\numspellsave{MyNum}
\numspell*{2}
\thenumspell;
\thenumspellMyNum
\end{verbatim}
\numspell*{1}
\numspellsave{MyNum}
\numspell*{2}
\thenumspell;
\thenumspellMyNum

\item\commandinline|\Numspell[!<zeros>!]{!<num>!}|\\
It works like \verb|\numspell|, but the first letter will be capital. For example
\begin{flushleft}
\verb|\Numspell{12000}| $\to$ \Numspell{12000}\\
\verb|\Numspell[3]{12}| $\to$ \Numspell[3]{12}\\
\verb|\Numspell[6]{12}| $\to$ \Numspell[6]{12}\\
\verb|\Numspell[63]{1}| $\to$ \Numspell[63]{1}
\end{flushleft}

\item\commandinline|\Numspell*[!<zeros>!]{!<num>!}|\\
It works like \verb|\Numspell|, but the number spelling will not be printed.
In other words, the following two lines are equivalent:
\begin{flushleft}
\verbinline|\Numspell[!<zeros>!]{!<num>!}|\\
\verbinline|\Numspell*[!<zeros>!]{!<num>!}\thenumspell|
\end{flushleft}
For example
\begin{verbatim}
\Numspell*{1}
\numspellsave{MyNum}
\Numspell*{2}
\thenumspell;
\thenumspellMyNum
\end{verbatim}
\Numspell*{1}
\numspellsave{MyNum}
\Numspell*{2}
\thenumspell;
\thenumspellMyNum

\item\commandinline|\ordnumspell[!<zeros>!]{!<num>!}|\\
Spelling the ordinal number
$n=\text{\color{green!50!black}\itshape$\langle$num$\rangle$}\cdot10^{\text{\color{green!50!black}\itshape$\langle$zeros$\rangle$}}$,
where $0\leq n\leq 10^{66}-1$. The default value of \commandinline|!<zeros>!| is \texttt{0}. For example
\begin{flushleft}
\verb|\ordnumspell{12000}| $\to$ \ordnumspell{12000}\\
\verb|\ordnumspell[3]{12}| $\to$ \ordnumspell[3]{12}\\
\verb|\ordnumspell[6]{12}| $\to$ \ordnumspell[6]{12}\\
\verb|\ordnumspell[63]{1}| $\to$ \ordnumspell[63]{1}
\end{flushleft}

\item\commandinline|\ordnumspell*[!<zeros>!]{!<num>!}|\\
It works like \verb|\ordnumspell|, but the number spelling will not be printed.
In other words, the following two lines are equivalent:
\begin{flushleft}
\verbinline|\ordnumspell[!<zeros>!]{!<num>!}|\\
\verbinline|\ordnumspell*[!<zeros>!]{!<num>!}\thenumspell|
\end{flushleft}
For example
\begin{verbatim}
\ordnumspell*{1}
\numspellsave{MyNum}
\ordnumspell*{2}
\thenumspell;
\thenumspellMyNum
\end{verbatim}
\ordnumspell*{1}
\numspellsave{MyNum}
\ordnumspell*{2}
\thenumspell;
\thenumspellMyNum

\item\commandinline|\Ordnumspell[!<zeros>!]{!<num>!}|\\
It works like \verb|\ordnumspell|, but the first letter will be capital. For example
\begin{flushleft}
\verb|\Ordnumspell{12000}| $\to$ \Ordnumspell{12000}\\
\verb|\Ordnumspell[3]{12}| $\to$ \Ordnumspell[3]{12}\\
\verb|\Ordnumspell[6]{12}| $\to$ \Ordnumspell[6]{12}\\
\verb|\Ordnumspell[63]{1}| $\to$ \Ordnumspell[63]{1}
\end{flushleft}

\item\commandinline|\Ordnumspell*[!<zeros>!]{!<num>!}|\\
It works like \verb|\Ordnumspell|, but the number spelling will not be printed.
In other words, the following two lines are equivalent:
\begin{flushleft}
\verbinline|\Ordnumspell[!<zeros>!]{!<num>!}|\\
\verbinline|\Ordnumspell*[!<zeros>!]{!<num>!}\thenumspell|
\end{flushleft}
For example
\begin{verbatim}
\Ordnumspell*{1}
\numspellsave{MyNum}
\Ordnumspell*{2}
\thenumspell;
\thenumspellMyNum
\end{verbatim}
\Ordnumspell*{1}
\numspellsave{MyNum}
\Ordnumspell*{2}
\thenumspell;
\thenumspellMyNum
\end{description}

\section{Commands for English language}
If the \texttt{english}, \texttt{british}, \texttt{ukenglish} or \texttt{UKenglish} language is active, then the number spelling will happen in British English. But it will be in American English, if the \texttt{american}, \texttt{usenglish} or \texttt{USenglish} language is active.
\begin{description}
\item\commandinline|\numspellUS|\\
Using British English, you can rechange the number spelling to American English by this command.
\item\commandinline|\numspellGB|\\
Using American English, you can rechange the number spelling to British English by this command.
\end{description}

\section{Commands for French language}
The following commands only work, if \texttt{french} language is active.
\begin{description}
\selectlanguage{french}
\item\commandinline|\numspellpremiere|\\
By default, \verb|\ordnumspell{1}| $\to$ \ordnumspell{1},\\
but \verb|\numspellpremiere\ordnumspell{1}| $\to$ {\numspellpremiere\ordnumspell{1}}

\item\commandinline|\numspellpremier| (default)\\
\verb|\numspellpremiere\ordnumspell{1};|\\
\verb|\numspellpremier\ordnumspell{1}|\\[2mm]
{\numspellpremiere\ordnumspell{1}}; {\numspellpremier\ordnumspell{1}}
\end{description}

\section{Commands for Hungarian language}
The following commands only work, if \texttt{magyar} or \texttt{hungarian} language is active.
\begin{description}
\item\commandinline|\anumspell[!<zeros>!]{!<num>!}|\\
It works like \verb|\numspell|, but the number spelling will start with Hungarian definite article. For example
\begin{flushleft}
{\selectlanguage{magyar}
\verb|\anumspell{1}| $\to$ \anumspell{1}\\
\verb|\anumspell{2}| $\to$ \anumspell{2}}
\end{flushleft}

\item\commandinline|\anumspell*[!<zeros>!]{!<num>!}|\\
It works like \verb|\anumspell|, but the number spelling will not be printed.
In other words, the following two lines are equivalent:
\begin{flushleft}
\verbinline|\anumspell[!<zeros>!]{!<num>!}|\\
\verbinline|\anumspell*[!<zeros>!]{!<num>!}\thenumspell|
\end{flushleft}
For example
\begin{verbatim}
\anumspell*{1}
\numspellsave{MyNum}
\anumspell*{2}
\thenumspell;
\thenumspellMyNum
\end{verbatim}
{\selectlanguage{magyar}
\anumspell*{1}
\numspellsave{MyNum}
\anumspell*{2}
\thenumspell;
\thenumspellMyNum}

\item\commandinline|\Anumspell[!<zeros>!]{!<num>!}|\\
It works like \verb|\anumspell|, but the first letter will be capital.

\item\commandinline|\Anumspell*[!<zeros>!]{!<num>!}|\\
It works like \verb|\anumspell*|, but the first letter will be capital.

\item\commandinline|\aordnumspell[!<zeros>!]{!<num>!}|\\
It works like \verb|\ordnumspell|, but the number spelling will start with Hungarian definite article. For example
\begin{flushleft}
{\selectlanguage{magyar}
\verb|\aordnumspell{1}| $\to$ \aordnumspell{1}\\
\verb|\aordnumspell{2}| $\to$ \aordnumspell{2}}
\end{flushleft}

\item\commandinline|\aordnumspell*[!<zeros>!]{!<num>!}|\\
It works like \verb|\aordnumspell|, but the number spelling will not be printed.
In other words, the following two lines are equivalent:
\begin{flushleft}
\verbinline|\aordnumspell[!<zeros>!]{!<num>!}|\\
\verbinline|\aordnumspell*[!<zeros>!]{!<num>!}\thenumspell|
\end{flushleft}
For example
\begin{verbatim}
\aordnumspell*{1}
\numspellsave{MyNum}
\aordnumspell*{2}
\thenumspell;
\thenumspellMyNum
\end{verbatim}
{\selectlanguage{magyar}
\aordnumspell*{1}
\numspellsave{MyNum}
\aordnumspell*{2}
\thenumspell;
\thenumspellMyNum}

\item\commandinline|\Aordnumspell[!<zeros>!]{!<num>!}|\\
It works like \verb|\aordnumspell|, but the first letter will be capital.

\item\commandinline|\Aordnumspell*[!<zeros>!]{!<num>!}|\\
It works like \verb|\aordnumspell*|, but the first letter will be capital.
\end{description}

\section{Commands for Italian language}
The following commands only work, if \texttt{italian} language is active.
\begin{description}
\selectlanguage{italian}
\item\commandinline|\numspellitmasculine| (default)\\
The ordinal numbers will be printed in masculine form. For example\\
\verb|\ordnumspell{1}| $\to$ \ordnumspell{1}

\item\commandinline|\numspellitfeminine|\\
The ordinal numbers will be printed in feminine form. For example\\
\verb|\numspellitfeminine\ordnumspell{1};|\\
\verb|\numspellitmasculine\ordnumspell{1}|\\[2mm]
{\numspellitfeminine\ordnumspell{1}}; {\numspellitmasculine\ordnumspell{1}}
\end{description}

\section{Commands for the Latin language}
The following commands only work, if one of the next languages is active: \texttt{latin}, \texttt{classicallatin}, \texttt{medievallatin}, or \texttt{ecclesiasticallatin}.
\begin{description}
\selectlanguage{latin}
\item\commandinline|\numspelllamasculine| (default)\\
All numbers will be printed in masculine form. For example\\
\verb|\numspell{1}, \numspell{2}, \numspell{200}, \ordnumspell{1}|\\[2mm]
\numspell{1}, \numspell{2}, \numspell{200}, \ordnumspell{1}

\item\commandinline|\numspelllafeminine|\\
All numbers will be printed in feminine form. For example\\
\verb|\numspelllafeminine|\\
\verb|\numspell{1}, \numspell{2}, \numspell{200}, \ordnumspell{1}|\\[2mm]
\numspelllafeminine
\numspell{1}, \numspell{2}, \numspell{200}, \ordnumspell{1}

\item\commandinline|\numspelllaneuter|\\
All numbers will be printed in neuter form. For example\\
\verb|\numspelllaneuter|\\
\verb|\numspell{1}, \numspell{2}, \numspell{200}, \ordnumspell{1}|\\[2mm]
\numspelllaneuter
\numspell{1}, \numspell{2}, \numspell{200}, \ordnumspell{1}
\end{description}

\section{Examples}

\begin{examplelst}
\documentclass{article}
\usepackage[T1]{fontenc}
\usepackage[magyar,italian,latin,ngerman,french,english]{babel}
\usepackage{numspell}
\usepackage[group-separator={,}]{siunitx}
\begin{document}
\def\mynum{123456789}
\noindent
In British English the spelling of \num{\mynum} is
\emph{\numspell{\mynum}}.
\par\smallskip\noindent
In American English the spelling of \num{\mynum} is
\foreignlanguage{american}{\em\numspell{\mynum}}.
\par\smallskip\noindent
In French the spelling of \num{\mynum} is
\foreignlanguage{french}{\em\numspell{\mynum}}.
\par\smallskip\noindent
In German the spelling of \num{\mynum} is
\foreignlanguage{ngerman}{\em\numspell{\mynum}}.
\par\smallskip\noindent
In Hungarian the spelling of \num{\mynum} is
\foreignlanguage{magyar}{\em\numspell{\mynum}}.
\par\smallskip\noindent
In Italian the spelling of \num{\mynum} is
\foreignlanguage{italian}{\em\numspell{\mynum}}.
\par\smallskip\noindent
In Latin the spelling of \num{\mynum} is
\foreignlanguage{latin}{\em\numspell{\mynum}}.
\end{document}
\end{examplelst}
\def\mynum{123456789}
\noindent
In British English the spelling of 123,456,789 is
\emph{\numspell{\mynum}}.
\par\smallskip\noindent
In American English the spelling of 123,456,789 is
\foreignlanguage{american}{\em\numspell{\mynum}}.
\par\smallskip\noindent
In French the spelling of 123,456,789 is
\foreignlanguage{french}{\em\numspell{\mynum}}.
\par\smallskip\noindent
In German the spelling of 123,456,789 is
\foreignlanguage{ngerman}{\em\numspell{\mynum}}.
\par\smallskip\noindent
In Hungarian the spelling of 123,456,789 is
\foreignlanguage{magyar}{\em\numspell{\mynum}}.
\par\smallskip\noindent
In Italian the spelling of 123,456,789 is
\foreignlanguage{italian}{\em\numspell{\mynum}}.
\par\smallskip\noindent
In Latin the spelling of 123,456,789 is
\foreignlanguage{latin}{\em\numspell{\mynum}}.

\begin{examplelst}
\documentclass{article}
\usepackage{numspell}
\newcounter{mycount}
\begin{document}
The
\makeatletter
\@whilenum\value{mycount}<51
\do{\ordnumspell{\themycount}\stepcounter{mycount},\ }\dots
\makeatother
\end{document}
\end{examplelst}
\makeatletter
\newcounter{mycount}
The
\@whilenum\value{mycount}<51
\do{\ordnumspell{\themycount}\stepcounter{mycount},\ }\dots
\makeatother

\begin{examplelst}
\documentclass{article}
\usepackage{numspell}
\newcounter{mycount}
\def\themycount{\numspell{\arabic{mycount}}}
\begin{document}
\Numspell{0},
\makeatletter
\@whilenum\value{mycount}<30
\do{\stepcounter{mycount}\themycount,\ }\dots
\makeatother
\end{document}
\end{examplelst}
\def\themycount{\numspell{\arabic{mycount}}}
\setcounter{mycount}{0}
\makeatletter
\Numspell{0},
\@whilenum\value{mycount}<30
\do{\stepcounter{mycount}\themycount,\ }\dots
\makeatother

\end{document}