LE - Less/Equal Test
| logical = LE ( npt1 npt2 ) | |
| result = LE ( npt1 npt2 truevalue falsevalue ) |
| logical | Logical:TRUE or FALSE depending on the result of the comparison. | |
| npt1 | A numerical point. | |
| npt2 | A numerical point. | |
| result | Evaluation of truevalue or falsevalue depending on whether or not ntp1 is less than npt2 | |
| truevalue | A point. | |
| falsevalue | A point. |
LE returns true if the first argument is numerically less than or equal to the second argument.
See Real for details on comparing floating point numbers.
| LE(1 2) | Logical:True | |
| LE(5 4 "Yes" "No") | Alpha:No |
LEG - Less/Equal/Greater Test
| respt = LEG ( npt1 npt2 respt1 respt2 respt3 ) |
| respt | The resulting point, one of respt1, respt2, or respt3. | |
| npt1 | A numerical point. | |
| npt2 | A numerical point. |
The LEG module compares npt1 to npt2 and returns respt1 if npt1 is less than npt2. If npt1 equals (numerically) npt2 then LEG returns respt2. And if npt1 is greater than npt2 it returns respt3. Normally all of the resulting points are evaluated before the test occurs. If any of the respt's are quoted intersections then they are evaluated only if necessary.
See Real for details on comparing floating point numbers.
| LEG(1 2 3 4 5) | returns 3 (1 is less than 2) | |
| LEG(Int:100 Real:100.0 1 2 3 ) | returns 2 (100 numerically equals 100.0) |
Len - Determine Length/Size of Argument
| size = Len ( point ) |
| size | The size of the argument, varies depending on the argument's point type. | |
| point | The size/length of this point is determined. |
This module determines the length or size of it's first argument. If the point is a string then the number of characters is returned. If it is a list or drawer then the number of elements is returned. Otherwise the argument is converted to a string and the number of characters in that string is returned.
| Len((1 2 3 4)) | returns the elements in the list- 4 | |
| Len(123) | returns Len(Str(123)) - 3 | |
| Len("") | returns 0 |
List - General List Utility
| list = List ( dimpoint ) | |
| list = List ( bigtext ) | |
| list = List ( xdbpoint ) | |
| list = List ( isct ) | |
| list = List ( v4ispt tagarg ... ) | |
| list = List ( Area::file ) | |
| list = List ( aggrefpoint tagarg ) | |
| list = List ( settag list ... ) | |
| result = List ( baselist action ) | |
| value = ListNE ( arguments same as List ) |
| list | A resulting list of points. | |
| dimpoint | A dimension point (i.e. Dim:xxx). The resulting list is a list of all points on that dimension. Note that Dim:Dim may be used to get a list of all dimensions. | |
| bigtext | A point of type BigText. The result is a list of Dim:Alpha points corresponding to each line in the point. | |
| xdbpoint | A point on an XDB dimension. The result is a list of rows returned by the last DBGet module call. | |
| isct | A quoted intersection. The result is a list of values obtained by the repeated evaluation of isct. The list terminates when the evaluation fails. The points in this list are not pre-generated, but rather determined as each next point in the list is requested. | |
| v4ispt | A V4IS point returned by the V4ISCon module. The resulting list is a list of V4IS records. | |
| Area::file | If the sole argument to this module is Area::file then the specified file is opened and the list returned consists of Dim:Alpha points corresponding to each line in the file. The results are not defined if the file is not a text file. | |
| aggrefpoint | A point of type AggRef. This must be followed by a the tagged arguments of Area and Table to specify a file and V4 Table to parse the lines in the file. The resulting list has a point for each line in the specified area that is successfully parsed by the V4 Table specification. | |
| settag | One of the following tag results: Union?, Intersect?, Subtract?, or XUnion?. The following list arguments are unioned, intersected, subtracted, or xunioned. | |
| baselist | A target list to be operated upon as specified by subsequent tagged arguments | |
| action | One or more of the tagged arguments below. |
| Append::lpt | Append lpt to the end of the base list. | |
| Area::file | A file name specification. | |
| AWhile::isct | Evaluate isct after each point in the base list. If the result of the evaluation is true then continue otherwise terminate. Note that this argument is tested after each point. While::isct is used to test before each point. | |
| Begin::num | Sets the beginning number for use with the Every option. See description below for more details. | |
| Bits::num | Returns the elements in base list corresponding to bits set in num. | |
| Bits::mask | If this tag is the first and only argument to List then a list of integer numbers is returned corresponding to the bits set in the 32-bit integer mask. The dimension of the resulting list points is the dimension of the mask if it is of type Integer, otherwise it is Dim:Int. | |
| Break::num | Segments the source list into num sub-segments of approximately equal size. Currently this is only supported if the source list is a reference to one or more aggregate areas. This feature is used primarily by the Tally module when concurrently processing large multi-area data sets. | |
| Collapse::num | Collapse num levels of lists to a single stream (list) of points. Use Collapse? to collapse all levels of nested lists. | |
| Column::dopt | If the Column argument is not a string then it must be either Tab for tab-delimited, or CSV for comma-separated-values. The difference between ',' and CSV (or ' ' and Tab) is that additional formatting rules apply with the tag names. CSV results in true CSV output, while | |
| Column::delim | Convert the first argument list to an alpha point delimiting each list element (column) with the delim string. This option can be used to create tab, comma, and pipe delimited strings from a list of points. | |
| Columns::num | Converts the points in the base list to a list of lists. Each sublist consists of a row of num points. This option is useful when converting a list to a table of num columns. | |
| Count::fieldindex | This argument specifies the field index associated with the area record that determines the number of subrecords per main record. (This applies only when converting V4IS points to a list). | |
| Delete::pt | Removes the specified point from the list. All instances of the point will be removed. To limit the number of instances, use the Num option. The original list is returned if the specified point does not appear in the list. | |
| Dim::dim | Returns the first point in the base list with the specified dimension. | |
| Every::num | Select points based on a running sum determined by the Begin and Sum arguments. See the description below for details. | |
| First::isct | Evaluate isct for the first point in the list. This may be used to position to a particular record in the V4IS file and is often used with the While tag. | |
| Group::isct | Returns a list of lists. V4 appends points of the source list into a new list. With each point it evaluates isct. If the result is TRUE then V4 continues with the next point in the source list. If the result is FALSE then the last point added to the new list is removed and the new list is appended to the resulting list. The process then repeats for all points in the source list. See the example below. | |
| Group::num | Return a list of lists, with each sublist containing the next num elements of the source list. (Compare this with the Columns option.) | |
| Head::npt | Returns a list of the first npt points in the base list. | |
| If::isct | Evaluate this isct for each selected V4IS record. If the result is undefined or false then immediately go for the next record. | |
| If::isct | A second If specifies the test to perform on the sub-records. | |
| If::isct | Evaluates isct for each point in the base list and returns a sublist for all points in base which evaluated to true. | |
| Intersect::lpt | Returns a list which is the intersect of the points in the base list and lpt, i.e. a list of points which appear in both list. If lpt is UV4:none then the argument is ignored. | |
| Key::keyval | Searches a list of key-value pairs and returns the value for the corresponding keyval. The format of the first argument list must be ((key value ...) (key value...) ... ). The module fails if the key is not found. Any entries in the first argument list that are not key-value pairs are ignored. If the matching sub-list has two entries then the second list entry is returned otherwise the entire list is returned (including the key value). | |
| Key2::keyval | Similar to the Key tag but compares the second entry in the list and returns the first if a match is found. | |
| KeyNum::num | This argument specifies the field index corresponding to a key within the area. The points in the resulting list will be in this key order. (For V4IS lists only) | |
| KeyNum::keyval | Similar to the Key tag but instead of returning the key value it returns the index of the key-value pair within the list. FALSE is returned if the key is not found within the first argument list. | |
| Maximum::pt | Evaluates pt for each point in the base list. The returned value is that point in the base list giving the smallest evaluation of the Max pt. | |
| Minimum::pt | Evaluates pt for each point in the base list. The returned value is that point in the base list giving the largest evaluation of the Min pt. | |
| Nth::npt | Returns the nptth point in the base list. If npt is less than one then the nptth point from the right hand side of the list is selected. Note that this returns a point, not a list (unless the specified point is itself a list). List dimensions declared with the DotIndex attribute may also be subscripted with the list.point construct which is converted to List(list* Nth::point). | |
| Num::maxnum | The maximum number of points to remove with the Remove option. | |
| Number::maxnum | The maximum number of records to select from a V4IS area. This is primarily for testing/debugging. | |
| Occurs::point | Returns the number of times point occurs in the list. The result is a point on Dim:Int. | |
| Pairs::mode | Returns a list of lists where each element list is a pair of points from the original list. The mode determines whether or not pairs are created from a single point. If mode is SELF then additional pairs are created by duplicating each point in the list. If mode is OTHERS then pairs are not created from single points. | |
| Position::point | Returns the position of point in the base list. Note that this form of List does not return a list but a point on the Int dimension. | |
| Product::lpt | Returns a list corresponding to the product of base list and lpt. See below for an example. | |
| Sample::npt | Returns a subset of the base list that randomly approximates every nptth of the base list. This may be used to test large lists in a debugging mode or to randomly sample a large list for statistical purposes. | |
| Sample::num | Sample approximately every numth point/record from a V4IS point. This is primarily for testing/debugging. | |
| Select::pt | Selects points from the base list which are included in pt. If pt refers to a single point then all points in the base list equal to pt are selected. If pt refers to a numeric range of points then all points in the base list included in that range are selected. If pt refers to a range of dictionary points then all points in the list starting with the first point and ending with the last are selected for output. | |
| Shell::Dim:xxx | Place each point in the base list into the context under this shell dimension. This is only valid for use with the If and While options. | |
| Subtract::lpt | Returns a the base list with all points in lpt removed. Any point in lpt but not in the base list is ignored. Note that this is a set operation. The source list is converted to a set meaning that any duplicate elements are removed. If lpt is UV4:none then the argument is ignored. | |
| Sum::num | The incremental number to be used with the Every argument. If not specified then Int:1 is assumed. | |
| Table::name | The name of a currently defined V4 table. | |
| Tail::npt | Returns the last npt points in the base list. | |
| To::pt | Returns all points in the base list up to and including pt. If the base list does not include pt then all points in the list are returned. | |
| Union::lpt | Returns a list corresponding to the union of the points in the base list and lpt. If lpt is UV4:none then the argument is ignored. | |
| While::isct | Each point in the base list is entered into the current context and isct is evaluated. If it is true then the point is appended to the resulting list. If it is false, then all processing of the List is terminated and the reslist is returned. | |
| XUnion::lpt | Returns the exclusive union of the base list and lpt, i.e. all points in the base list and lpt, but not in both. If lpt is UV4:none then the argument is ignored. |
| Alpha? | Convert the first argument list to an alpha point. | |
| Collapse? | Collapse any/all nested lists within the result so that a single stream of points is returned. | |
| Evaluate? | Enumerates through each element of the list, evaluates each element and returns a list of the evaluated results. | |
| Hash64? | Calculates a 64-bit hash value for the list and returns it as a point on Dim:UFix | |
| Intersect? | Must be the first argument to List. The following argument lists are intersected. Any arguments equal to UV4:none are ignored. | |
| Length? | Returns the length or number of elements in the list. See also Len. | |
| Pairs? | Same as Pairs::Others. | |
| Reverse? | Returns a list containing the elements of the source list but in reverse order. | |
| Subtract? | Must be the first argument to List. The following argument lists are sequentially subtracted. Any arguments equal to UV4:none are ignored. | |
| Union? | Must be the first argument to List. The following argument lists are unioned. Any arguments equal to UV4:none are ignored. | |
| XUnion? | Must be the first argument to List. The following argument lists are exclusive-or-unioned. Any arguments equal to UV4:none are ignored. |
The List module performs various list related functions. If the initial result is a special point (e.g. dim*) or intersection then that point is itself evaluated. If the result is a List or Alpha then tags appropriate for that point type (List or Str) may be chained.
The ListNE module is identical to the List module (list-no-evaluate) except that it does not auto-evaluate the result if it is a special point or intersection.
The Begin/Every/Sum arguments allow the user to select points in a list based on a running total. The total is initialized with the Begin value. Then for each point in the list, the Sum value is added to the total. The point in the list is selected if the running total exceeds the Every value. If it exceeds the Every value then the point in the list is appended to the resulting list and the running total is decremented by the Sum argument. If the running total still exceeds the Every value then the current point is again appended to the output list.
| List( (1 2 3) Subtract::(2 3 4)) | (1) | |
| List(Union? (1 2 3) (3 4 5)) | (1 2 3 4 5) | |
| List( (1 2 3) Nth::2) | Int:2 | |
| List( (1 2 3) Head::2) | (1 2) | |
| List( (1 2 3) Union::(2 3 4)) | (1 2 3 4) | |
| List( (1 2 3) Product::(A B)) | ((1 A) (1 B) (2 A) (2 B) (3 A) (3 B)) | |
| List( (1 2 3) Pairs?) | ((1 2) (1 3) (2 3)) | |
| List( (1 2 3) Pairs::Self) | ((1 1) (1 2) (1 3) (2 2) (2 3) (3 3)) | |
| List( (5 6 7) Bits::3) | (5 6) (decimal 3 = binary 0011 hence the first two elements of list selected) | |
| List(Int:1..10 Columns::3) | ((1 5 9) (2 6 10) (3 7) (4 8)) | |
| List(Bits::10) | (2 4) (decimal 10 = binary 1010) | |
| List((123 {3+5}) Nth::2) | Int:8 ({3+5} is itself evaluated) | |
| ListNE((123 {3+5}) Nth::2) | {3+5} | |
| V4ISCon(Dim:V Area::"v4isfile.dat" FileRef::5904 Open::1 KeyNum::1 Key::1)* | Open file for read access | |
| List(V* KeyNum::1 First::V4ISOp(V* KeyNum::1 Key::"A") While::Str(V4ISVal(V* Dim:Alpha 1) Head::"A")) | Returns list of points corresponding to records with keys beginning with "A" | |
| List(Dim:Orders) | returns a list of all orders | |
| List(Int:1..10) | returns the list (1 2 3 4 5 6 7 8 9 10) | |
| List(Int:1..10 Alpha::",") | returns Alpha:"1,2,3,4,5,6,7,8,9,10" | |
| List(Int:1..5 Alpha?) | returns Alpha:"12345" | |
| List((now is the time) Column::"|" UC?) | returns Alpha:"NOW|IS|THE|TIME" | |
| List((1 2 3 4 5 6 7 8 9 10) Group::4) | ((1 2 3 4) (5 6 7 8) (9 10)) | |
| List((1 2 3 4 5 6 7 8 9 10) Group::{Sum(List*) < 10}) | ((1 2 3) (4 5) (6) (7) (8) (9)) | |
| List((now is the time for all men to come to the aid) Group::{Str(`List* Length?) < 10}) | ((now is the) (time for) (all men to) (come to the) (aid)) | |
| List((now is the time for all men to come to the aid) Group::{Str(List* Length?) < 10}) | ((now is) (the) (time) (for all) (men to) (come to) (the aid)) | |
| List((1 2 3 {3+1}) Evaluate?) | returns (1 2 3 4) | |
| List(((a value1) (b value2) (22 value3 333 xxx) (1.3 "a string")) Key::1.3) | a string | |
| List(((a value1) (b value2) (22 value3 333 xxx) (1.3 "a string")) Key::22) | (22 value3 333 xxx) |
|
Table Demo Column Customer Cus Column State State Column InvoiceAmt Money EndTable Dim T AggRef Tally(List(Dim:T Area::Invoice.txt Table::Demo) (Sum::T.InvoiceAmt By::T.State ByList::[StateList] Bind::[TAmt])) |
The example below shows how a list can be created from the repetitive evaluations of an intersection. In this example, the list never ends- it just keeps on repeating:
Example 31 - Sequences - Musical Pattern
|
Bind [NMLt Sequence:Music] Beat:1 Bind [NMLt Sequence:Music Beat:1] Beat:2 Bind [NMLt Sequence:Music Beat:2] Beat:3 Bind [NMLt Sequence:Music Beat:3] Beat:4 Bind [NMLt Sequence:Music Beat:4] Beat:1 Bind [NMLt Sequence:Music Beat:3 Form:Waltz] Beat:1 Context Add Sequence:Music Eval EnumCE( List( @[NMLt] ) @Echo( Beat Beat* ) ) Beat 1 Beat 2 Beat 3 Beat 4 Beat 1 ... |
Given the context of Sequence:Music, the list formed by evaluating [Next] evaluates to the endless sequence of Beat:1 through Beat:4. If the point Form:Waltz is added to the context, the sequence changes to Beat:1 through Beat:3.
ListSize - Determine Size (Number of Elements) in List
| num = ListSize ( List ) |
| num | The number of elements in the list. | |
| list | A list or point that can be coerced to a list. |
The ListSize module returns the number of elements in a list or point that can be coerced to a list. Lists of lists are not expanded, only the top level number of points is returned.
| ListSize((1 2 3 4 5)) | results in Int:5 | |
| ListSize(Int:1..100) | results in Int:100 (Int:1.100 is coerced into a list) | |
| ListSize(Student..) | results in the number of points on Dim:Student | |
| ListSize(ODBCSet..) | fails if the argument cannot be coerced to a list or if the number of points in the list is unknown |
Locale - Obtain or Set Locale Parameters
| result = Locale ( tag ) |
| result | A resulting point depending on the arguments. | |
| tag | One or more of the tags show below. |
| Calendar::name | Set the default calendar for the current country. The allowed values of name are Gregorian, Julian, ISO, Islamic, and Hebrew. | |
| Country::uncode | Sets the current country to uncode. The valid countries are determined at startup time by the file v4_Home:v4CountryInfo.v4i. The uncode may be either the standard UN numeric code or UN three letter abbreviation. | |
| Language::name | Sets the language for the current country. The allowed values of name are determined at startup time by the file v4_Home:v4LanguageInfo.v4i. | |
| Timezone::val | Set the timezone for the currently running V4 process to val which must be an integer number between -12 and +12. |
| Calendar? | Returns the current calendar for the current country as a point on Dim:UV4. | |
| Country? | Returns the current country as a point on Dim:UCountry. | |
| Language? | Returns the current language for the current country as a point on Dim:UV4. | |
| TimeZone? | Returns the current timezone for the current process as a point on Dim:Int. |
The Country point type associates a point with a country. The valid country points are determined at startup by the entries in v4_Home:V4CountryInfo.v4i. Each country has associated attributes including a calendar, language, and timezone. The Locale module is used to set the current country for the V4 runtime and to alter initial settings for that country.
There are many parameters associated with each country that determine how various V4 points are to be parsed and formatted. See Country for more information. The language associated with a country also determines how V4 handles different types of points. See v4_Home:V4LanguageInfo.v4i for more information.
All Locale settings are initialized from v4_Home:V4CountryInfo.v4i each time V4 is started. Any changes made via this module are good only for the life of the current V4 process.
| Locale(Country?) | returns UCountry:USA as the default | |
| Locale(Language?) | returns UV4:English | |
| Locale(Country::FRA) | sets the current country to France | |
| Locale(Language?) | returns UV4:French |
Lock - Interprocess Locking Function
| result = Lock ( tagarg ... ) |
| result | depends on arguments. | |
| tag | one or more of the tagged arguments below. |
| Data::id | returns data on either a lock or process as specified by the id. If a lock then a list of the form (id name mode ownerlist waitlist) is returned where id is the requested lock id, name is the lock name, mode is Int:1 for a read-lock and 2 for a write-lock, ownerlist is a list process id's of processes currently owning the lock, and waitlist is a list of processes waiting for the lock. The data returned for a process is a list of the form (id pid name) where id is the process id, pid is the process system-level id, and name is the name od the process. | |
| Hold::duration | Specifies how long (in seconds) the process can hold the requested lock. If the process does not release the lock within duration seconds then the lock is automatically released. If multiple processes specify this option with a shared read lock then the lock is held for the longest time as defined by all of the requests and durations. | |
| Id::name | Specifies the name of the process. This must be done with the first call to the Lock module. If this option is not given, the name defaults to 'process-pid'. | |
| Interval::tryint | If a lock is not immediately available, V4 will continue to try and grab the lock at tryint millisecond intervals. The default is 50 milliseconds and is appropriate for most applications. | |
| Life::option | Determines how long a lock exists. If option is Release then the lock exists until it is explicitly released even if the creating process terminates. If the option is process then the lock, if not already explicitly released, is automatically released when the creating process terminates. Life:Process is the default. | |
| ListOf::object | If object is Locks then a list of ids of all active locks is returned. If Processes then a list of all registered processes is returned. Information on a specific lock or process can be obtained with the Data argument. | |
| Name::lockname | The name of the lock being requested. If no name is given then 'default' is used. Note: lock names are case sensitive. Multiple lock names can be given if delimited with commas (see discussion below). | |
| Release::lockname | Releases the currently held lock lockname. Only one lock may be released per call to the module. | |
| Type::locktype | The type of lock: Read for a sharable read-lock, or Write for an exclusive write-lock. If no Type is given, then a write-lock is assumed. | |
| Wait::option | Determines whether or not to wait for a lock if it is not immediately available. The option may be an number seconds to wait, Logical:Yes to wait indefinitely (the default), Logical:No to return with an error, or Dim:dimension. If a dimension is given then the module always returns immediately. The dimension is added to the context with an initial value of FALSE. When the lock becomes available, V4 assigns it to the current process and sets the context value of the dimension to TRUE. |
The Lock module provides inter-process synchronization amongst multiple V4 processes. Two types of lock requests are supported. Write-locks can only be held by one process at a time. Sharable Read-locks can be concurrently held by multiple processes. A lock is identified by a case sensitive lock name. A lock can be held for both write and read access (but not at the same time).
Multiple locks can be obtained with a single call to the Lock module. This is done by specifying multiple locks, delimited by commas, as the lockname parameter. If a process uses different calls to obtain multiple locks there is the possibility of a deadly-embrace or deadlock situation with another process causing both processes to hang indefinitely. Obtaining multiple locks with a single Lock call eliminates this problem as V4 will only grab all the locks if all of them are available.
Only one lock at a time can be released with this module.
| Lock(Name::resource1 Type::Read Wait::10) | request read access to lock resource1, wait at most 10 seconds for the lock | |
| Lock(Release::resource1) | release the lock | |
| Enum(Lock(ListOf::Locks) @EchoT(`Lock(Data::Int*))) | list details for all active locks | |
| Lock(Name::resource2 Wait::Dim:Logical) | request write access to lock, update Dim:Logical to TRUE when process has lock | |
| Enum(While::{~Logical*} @Do(V4(Sleep::1) EchoT("Still don't have it"))) | sleeps until lock is available and grabbed by this process | |
| Lock(Name::"lock1,lock2,lock3" Wait::FALSE) | try to grab 3 locks, fail immediately if all 3 are not available |
Log - Logarithmic Functions
| result = Log ( number tag ) |
| result | The resulting number determined by the arguments. | |
| number | A numeric point | |
| tag | One of the tagged values or results below. |
| POW::exp | Raise the number to the exp power. If exp is an integer then the calculation is performed by repeated multiplications. If the exp is not an integer then the result is determined via logarithms. |
| Exp? | Return enumber. | |
| Exp10? | Return 10number. | |
| Exp2? | Return 2number. | |
| Log? | Return the natural (base e) logarithm of number. | |
| Log10? | Return the base 10 logarithm of number. | |
| Log2? | Return the base 2 logarithm of number. |
This module performs various logarithmic functions as determined by its arguments.
| Log(2 POW::10) | results in Num:1024 | |
| Log(10 Exp2?) | results in Num:1024 | |
| Log(1024 Log2?) | results in Num:10 (or very close to that number) |
LT - Less Than Test
| logical = LT ( npt1 npt2 ) | |
| val = LT ( npt1 npt2 [valtrue valfalse] ) |
| logical | Logical:TRUE or FALSE depending on the result of the comparison. | |
| npt1 | A numerical point. | |
| npt2 | A numerical point. | |
| val | Either valtrue or valfalse | |
| valtrue | Returned if npt1 is less than npt2 | |
| valfalse | Returned if npt1 is not less than npt2. |
LT returns true if the first argument is less than the second. If four arguments are given then the third argument is returned instead of true and the fourth instead of false.
See Real for details on comparing floating point numbers.
| LT( 1 2) | Logical:TRUE |
|
LT(1 2 Logical:False Logical:True) |