.-
help for ^numlist^                                Jeroen Weesie/ICS  Jan 03, 1997
.-

Expand numeric-lists                                         [STB-35 ip14]
--------------------

        ^numlist^ numeric-list [^, mi^n^(^#^) ma^x^(^#^) r^eal ^s^ort ^f^ormat^(^fmt^)^ ]

where `numeric-list' is described below and `fmt' is any legal display format.

 
Description
-----------

^numlist^ expands a numeric-list which should satisfy the syntax

        numeric-list :: number-term [ numeric-list ]
        numeric-term :: [ number | number-number | number-number/number ]

with semantics

        expression      expands to
        --------------------------------------------
        n               n        
        n1-n2           n1 n1+1 n1+2 ... n2-1 n2
        n1-n2/n3        n1 n1+n3 n1+2*n3 ... 
        --------------------------------------------

A number-term may NOT contain embedded blanks, while subsequent number-terms
should be sepearted by white space.

A number may be real if the option ^real^ is specified, otherwise number 
should be an ^integer^. Note that of n2<0 (in the second or third form), you 
have to enter two subsequent minus signs. ^real^ numbers written in scientific 
notation may produce a syntax error. 

The expanded list of numbers, seperated by blanks, is returned in the global 
macro ^S_1^. The number of numbers (!) is returned in the global macro ^S_2^.


Options
-------

^min(^#^)^ specifies the minimum number of terms allowed.  The default is 
    ^min(1)^ if not specified.

^max(^#^)^ specifies the maximum number of terms allowed.  The default is 
    ^max(^infinity^)^ if not specified. Note though that Stata imposes a 
    (version dependent) limit on the length of macros.

^real^ specifies that the numbers in a numeric-list may be reals.

^sort^ sorts the values in increasing order.

^format(^fmt^)^ specifies a display format, such as %5.3f or %9.2g, that is
    used to format the numbers in the expanded numeric list.


Examples
--------

   . ^numlist 1-5^                      expands to   ^1 2 3 4 5^
   . ^numlist 1-5/2^                    expands to   ^1 3 5^
   . ^numlist 1-6/2^                    expands to   ^1 3 5^
   . ^numlist 1 5-7 11-17/2^            expands to   ^1 5 6 7 11 13 15 17^

Negative numbers may be included as well. Note, in particular, that negative 
upper-limits to ranges and negative increments are permitted, but lead to
funny looking expressions.

   . ^numlist -2-1^                     expands to   ^-2 -1 0 1^
   . ^numlist -6--2^                    expands to   ^-6 -5 -4 -3 -2^
   . ^numlist -6--2/2^                  expands to   ^-6 -4 -2^
   . ^numlist -2--6/-2^                 expands to   ^-2 -4 -6^

Lists may be sorted in increasing order, for example

   . ^numlist 1-10/2 2-10/2, sort^      expands to   ^1 2 3 4 5 6 7 8 9 10^

Finally, lists in real numbers may lead to unexpected and unwanted results
due to Stata's default formating of 

   . ^numlist 0-10/2.5, real^           expands to   ^0 2.5 5 7.5 10^
   . ^numlist 0-1/0.3, real^            expands to   ^0 0.3 0.6 0.88888888889^
   . ^numlist 0-1/0.1, real f(%3.1f)^   expands to   ^0 0.3 0.6 0.9^

^numlist^ serves a similar function for numeric-lists as Stata's ^unabbrev^ for
varlists. Both will be of interest mainly to programmers. In the program that
follows, also() is an option that allows a numlist.

	^program define^ ...
		...
		^local options "ALso(string)^ ...^"^
		...
		^parse "`*'"^
		...
		^if "`also'" ~= "" {^
			^numlist `also'^
			^local also "$S_1"^
		^}^
		...
	^end^


Acknowledgement
---------------

^numlist^ is, logically, an enhancement of the program ^lexp^ (which is a
subroutine of the ^for2^ command) written by P.J. Royston, but internally
written from scratch. ^numlist^ allows for lists in negative and/or
real-valued numbers, and optionally sorts lists. 


Also see
--------

    STB:  ip14 (STB-35)
 Manual:  [R] unabbrev
On-line:  help for @parse@