new

action

Syntax
new shelf ({string-expression})? insertion-point?
set new  shelf  ({ string-expression})? insertion-point? to expression

Argument definitions

insertion-point
A phrase describing where in the shelf the new item should be inserted. The insertion point is identified using the keywords before or after. If no insertion point is specified, the item is placed in the last position on the shelf.


Purpose

new inserts a new item onto a shelf and can only be invoked on shelves that have been declared variable: 

  local integer x variable initial-size 0
  
  new x

By default, the new item is inserted after the last item on the shelf. You can insert the new item before or after another item: 

  new x{"wilma"} after [2]

To make the new item the first item on the shelf, you can use before [1] or after [0].

A new item can be given a key as it is inserted: 

  new x{"fred"} before {"barney"}
  new x{"wilma"} after [2]

The set new action combines the new and set actions into one action so that 

  new x{"fred"} before [1]
  set x{"fred"} to "flintstone0"
can be replaced with: 
  set new x{"fred"} before [1] to "flintstone0"

Putting these code fragments together gives us the following program: 

  process
     local string x variable
  
     new x
     set key of x to "barney"
     set x to "flintstone1"
  
     set new x{"fred"} before [1] to "flintstone3"
     set x{"fred"} to "flintstone0"
  
     new x{"wilma"} after [2] 
     set x{"wilma"} to "flintstone2"
  
     repeat over x
        output x || " has key " || key of x || "%n"
     again
  ; Output: "flintstone0 has key fred
  ;          flintstone1 has key barney
  ;          flintstone2 has key wilma"

Generalization of new

The new operator can be used in expressions, wherever you refer to a shelf item. For example, in an increment statement: 

  process
    local integer i variable
  
    increment new i

Here the expression-level new creates a new item on the shelf i and then the increment action increments it.

The conditional or guarded form of new

OmniMark does not allow you to add a new item to a shelf if the key you specify already exists on the shelf. Although you can test for this conflict to avoid a program error, 

  process
     local integer i variable
  
     new i{"a"}
        unless i has key "a"
     increment i {"a"}
it is more concise to use the guarded form of new, new? to express this logic: 
  process
     local integer i variable
  
     new? i{"a"}

A key is required when using the guarded form of new.

The following example shows how you can use new? to easily remove duplicates from a data set. The following is a list of index entries with page references. The problem is to remove the duplicate entries, but also to maintain a count of the duplicates as an indication of when a topic is most heavily discussed. The data is as follows: 

  OmniMark 1
  streaming 2
  OmniMark 4
  OmniMark 4
  streaming 4

Using the guarded new operator, this problem is easily solved: 

  declare record usage-type
     field integer reference variable
  
  global usage-type usage variable
  
  
  process
     submit #main-input
     repeat over usage 
        output key of usage
        repeat over usage:reference as reference
           output "," 
              unless #first
           output " " || key of reference || " (" || "d" % reference || ")"
        again
        output "%n"
     again
  
  
  find letter+ => word blank digit+ => page "%n"
     increment new? (new? usage {word}):reference{page}

The inner guarded new of the find rule's increment action creates a new word entry if the word has not been encountered. The outer guarded new creates a new page reference if the page has not been encountered and then it passes the page entry, new or otherwise, to increment, which increases its count. The output of this program when given the input above is: 

  OmniMark 1 (1), 4 (2)
  streaming 2 (1), 4 (1)

Related Syntax
Related Concepts