The NAME command lets you create meaningful names that you can use instead of numbers. Any names created by the NAME command are called "Named Constants". They are constants because once created their values cannot be changed. There are two situations where you might like to use names instead of numbers. The first is the case where you would otherwise have to use an arbitrary code number such as 1 for "heads" and 2 for "tails". The second is the case where you have a meaningful number that you want to give a name to, such as giving this number, 3.141592654, the name "pi". A Named Constant created for the first case is called an "enum", short for "enumerator". Named Constants created for the second case are called "Named Values".
The other two commands listed in the syntax summary above are specialized versions of the NAME command that only create one type of Named Constant. The CONST command creates only Named Values; the ENUM command creates only enumerators. You can choose to always use NAME, or to use either CONST or ENUM as appropriate for the type of constant you want to create. In command examples in the following text I will choose NAME or one of its variants (CONST and ENUM) arbitrarily, just for demonstration purposes.
(You can also assign names to numbers via the COPY or SCORE commands, but then the names are really variable vectors and their values can be changed accidentally if you make a mistake in writing your program. If instead, you use the NAME, CONST, or ENUM command, then Statistics101 will enforce their constancy: If you accidentally put a named constant as a result argument of some command, you will receive an error message.)
The NAME command or its variants (CONST and ENUM) must appear in the program text prior to any use of the constants it creates. It is good practice to put all the named constants at the start of your program.
Named constants can be used in the remainder of the program anywhere a literal number is allowed. This helps to make a program self-documenting, reducing the number of comments needed. It also aids Statistics101 in checking for programming errors.
If the first argument is a literal number, as shown here,
NAME 3.141592654 pi 'An example of a named value
NAME (or CONST) assigns that number to be the value of the name given as the second argument. Names assigned values via the NAME command are called "named values".
If the first argument is a literal list (which includes a list, sequence, or multiple literal), like this one,
NAME (1 2 3) ace deuce trey 'These are named values
then NAME (or CONST) assigns each element of the literal list to the corresponding name in the list of names on the rest of the command. The literal list must have the same number of elements as there are names or an error message will be generated.
If there is no literal number and no literal list, then the constants' names will have no numerical value. Their names will be their values. Names created this way, without the user assigning values, are called "enums", short for "enumerators". For example:
NAME heads tails 'These are enums - they have no assigned values
This is the preferred way if the values of the named constants are not meaningful or are not needed for calculation. Normally, for example, it doesn't really matter what number is assigned to "heads" and "tails" as long as you can always refer to them as "heads" and "tails".
All the named constants created by the same NAME, CONST, or ENUM command are considered to be of one category, or "type". Constants created by different NAME, CONST, or ENUM commands are considered to be of different types. For example:
ENUM Sun Mon Tue Wed Thu Fri Sat ENUM Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
Here, the weekday names are of one type and the month names are of a different type because they are declared in different ENUM commands.
As stated earlier, named constants can be used anywhere literal numbers are allowed. So, for example, given the above declarations, you could do this:
COPY Mon,Fri workdays COPY Sat Sun weekend COPY (Jan Feb Mar) firstQuarter COPY 5#heads 2#tails success
But you couldn't do the following because the types don't match and the specified sequence is meaningless:
COPY Mon,Mar erroneousSequence 'Error because types don't match
In a sequence specification using named constants, the order of the sequence is determined by the order they were created in the NAME command, not the order implied by any value that the NAME command may have assigned to them.
A "mixed vector" is a vector that contains both numbers and named constants. A mixed vector can be sorted, ranked, and tagsorted. Before using those commands on a mixed vector, please see the SORT command to learn how named constants and mixed vectors are sorted.
Here is a brief example of sorting a mixed vector, using the above declarations and these commands,
COPY firstQuarter 1,3 weekend MixedVec SORT MixedVec sortedMixedVec PRINT MixedVec sortedMixedVec
produces this output:
MixedVec: (Jan Feb Mar 1.0 2.0 3.0 Sat Sun) sortedMixedVec: (Sun Sat Jan Feb Mar 1.0 2.0 3.0)
Statistics101 does assign values to the enums, but they are just for Statistics101's internal bookkeeping purposes and are inaccessible for any other purpose. For example, attempting to do arithmetic with enums will cause an error:
ADD 0 MixedVec MixedVecValues
This will generate this error message at execution time:
ERROR during execution of command ADD at Edit line 14 (Debug line 14) java.lang.RuntimeException: Named constant "Jan" has no assigned numerical value and therefore can't be used in numerical commands
But if you assign the values yourself so that they have meaning in the context of your simulation, you can use any of the mathematical functions with these constants. Thus, this next command assigns specific values to the card names.
CONST (1 11 12 13) ace jack queen king
You could then create a "suit" and a "deck" like this.
COPY ace,king 2,10 suit COPY suit suit suit suit deck
Then when you select a hand,
SAMPLE deck 5 hand
you could compute the hand's value (this is not its value in poker, just the sum of the values of the individual cards) like this:
SUM hand handValue
Since different NAME commands create different "types" there will be no conflict even if you use the same value for two different names as long as they are in different NAME commands:
NAME (1 2) true false NAME (1 2 3 10 10 10) ace deuce trey jack queen king
In the above commands, true and ace are not considered equal even though they have the same numerical value, because their types differ. However, jack, queen, and king are considered equal because they have the same type and the same value.
If you define a named constant inside a subroutine (see NEWCMD), then that constant will only be visible within the subroutine.
If you define a named constant outside a subroutine, then that constant will not be visible inside any subroutine.
If you need the same named constant in both the main program and a subroutine, or in more than one subroutine, then define the constant using NAME or one of its variants and declare the constant to be "global" using the GLOBAL command. Both these commands should be outside any subroutine.
In the previous discussion and examples, each NAME command created constants that were all of one, unnamed, type. And each separate NAME command created constants of a different unnamed type that was incompatible with those of all the other unnamed types. The type keyword allows you to give a name to the type created by a NAME command. This makes it possible for you to create additional constants of a previously named type using a separate NAME command. For example, here are two commands that create names that are of the same type and that behave as if they were created by one command:
NAME type months jan feb mar apr may jun NAME type months jul aug sep oct nov dec COPY jan,dec year PRINT year
Which prints out:
year: (jan feb mar apr may jun jul aug sep oct nov dec)
Notice that the constants from the second NAME command are considered to be added following the constants from the first command. You can have as many NAME commands with the same type name as you need. But don't use type naming to combine incompatible named constants. For example, you can't safely do this:
NAME type badType (1 2 3) A B C 'Named Values NAME type badType D E F 'enums LET X = A,F ' This will cause an error message.
These are incompatible because the first NAME command creates named values that can be used with arithmetic commands (such as LET, SUM, etc.) and the second NAME command creates enums that cannot be used with arithmetic commands because they have no numerical value. So make sure that NAME commands with the same type names use only the same type of named constant. That is, they should all be Named Values or they should all be enums.
Here is an example where you might need to use type naming. The file lib/mathConstants.txt defines some typical math constants such as pi and e and names their type to be "mathConstants". If you are writing a program that needs some constants that are in that file and some that are not in that file, you can use an INCLUDE command to import the constants that are in the lib/mathConstants.txt file. Then you might add your own constants to your program like this:
NAME(1.41421 0.70711) sqrt2 cos45 'type name omitted
If you did that and then, say in an IF command, you used a comparison like this:
IF sqrt2 < pi . . .
the result would be false, when the desired answer is true. The reason is that your sqrt2 and cos45 constants were declared in a different NAME command from those other math constants and are therefore incompatible with the others. To make your constants compatible with those in the mathConstants.txt file, you would add the type name as follows:
NAME type mathConstants (1.41421 0.70711) sqrt2 cos45
Doing so incorporates your constants into the same type as the predefined math constants and allows all the mathConstants to behave properly in mutual comparisons.
In earlier versions (prior to version 3.1) of Statistics101, there was a library file called logicalConstants.txt that defined the constants true, and false. To use the constants, the file had to be INCLUDEd at the beginning of a program. For versions 3.1 and newer of Statistics101, those constants are predefined automatically and no INCLUDE file is needed. They are defined as if they had been created by these commands:
NAME (0 1) false true GLOBAL false true
That definition allows you refer to them as names or numbers in comparisons. Examples of their use can be found in the files lib/isSequenceCommand.txt and lib/chooseTest.txt. The IS_SEQUENCE subroutine from the lib/isSequenceCommand.txt file is reproduced at right for your convenience.
See also, the SORT command.
Example: Compute the probability of dealing a hand containing two clubs and three hearts.
First, create named constants for use in the remainder of the program. Several alternatives are shown. The red and the blue names are the names of the "named constants":
NAME clubs spades hearts diamonds ' or: 'ENUM clubs spades hearts diamonds ' or: 'NAME 1,4 clubs spades hearts diamonds ' or: 'CONST 1,4 clubs spades hearts diamonds ' or: 'NAME (1 2 3 4) clubs spades hearts diamonds ' or: 'CONST (1 2 3 4) clubs spades hearts diamonds COPY 13#clubs 13#spades 13#hearts 13#diamonds deck NAME 100000 rptCount COPY 0 successCount REPEAT rptCount SHUFFLE deck shuffledDeck TAKE shuffledDeck 1,5 hand COUNT hand = clubs clubCount COUNT hand = hearts heartCount IF clubcount = 2 AND heartCount = 3 ADD 1 successCount successCount END END DIVIDE successCount rptCount probability PRINT probability
Here's an example of using named constants in a list. Compute the probability of getting three heads out of four tosses:
NAME heads tails COPY (heads tails) coin 'list contains constants NAME 1000 rptCount REPEAT rptCount SAMPLE 4 coin trial COUNT trial = heads headCount SCORE headCount results END COUNT results = 3 successes DIVIDE successes rptCount probabilityOf3HeadsOutOf4 PRINT probabilityOf3HeadsOutOf4
Note that the following line is illegal because NAME takes only one input argument, either a literal number or a literal list.
NAME 1 2 3 4 clubs spades hearts diamonds 'Invalid
To make the line valid, the four numbers need to be enclosed in parentheses:
NAME (1 2 3 4) clubs spades hearts diamonds 'valid
Here is an example of the usage of the predefined constants "true" and "false". This is a subroutine that is in the lib folder in the Statistics101 installation directory.
'Subroutine tests vec to determine if it 'is an arithmetic sequence all of whose 'elements differ by one when sorted. 'If vec is such a sequence, result will 'be true (1). 'Otherwise, result will be false (0). ' NEWCMD IS_SEQUENCE vec result @series @"vector operations" \ ?"Returns true if vec is an arithmetic sequence with common difference between elements of one, else false." SORT vec sortedVec COPY 0 sortedVec shiftedSortedVec SUBTRACT sortedVec shiftedSortedVec diffVector SIZE vec vecSize TAKE diffVector 2,vecSize diffVectorCenter SUMABSDEV 1 diffVectorCenter dev IF dev = 0 result = true ELSE result = false END END Example usage: COPY 10,3 vec IS_SEQUENCE vec result PRINT result