Shelves

A shelf is an ordered collection of values of a particular data type. You can access items on a shelf either by item number or by key value. A key is a text value. Each key on a shelf must be unique.

In OmniMark, all variables are also shelves, even if they only contain a single value.

Creating a shelf

A shelf can be of fixed or variable size. In fact, an ordinary variable declaration creates a shelf with a fixed size of 1: 

  local integer word-count

You can create shelves of a fixed size by specifying the size in the declaration: 

  local string days-of-the-week size 7

You can create a variable sized shelf, by specifying variable in the declaration. 

  local integer word-count variable

Addressing items on a shelf

If a shelf has only one item, you can address that item by the name of the shelf alone: 

  output template-file-name

If there are multiple items on the shelf you can address each item by specifying the item number in square brackets: 

  set template-file-name[5] to "foo.txt"

The item number can be expressed either as an integer literal or as an integer expression: 

  open template-file as file template-file-name[last-template-number + 1]

To address an item by its key, enclose the key string in curly braces: 

  set template-file-name{"home-page"} to "home.txt"

The key can be expressed either as a literal string or as a string expression: 

  output grid-cell{"d" % row || "-" || "d" % col}

You can access the key of a shelf item using the expression key of: 

  output key of shopping-list-items[2]
  
  set key of template-file-name[7] to "order-page"
  
  do when key of shopping-list-items[2] = "radishes"
     buy-radishes (shopping-list-items)
  done

You can retrieve the item number of an item using the expression item of, but you cannot change an item number: 

  output "d" % item of template-file-name{"order-page"}

It is an error to attempt to access a non-existent key. You can test to see if an item on a shelf has a key using the is keyed test: 

  output key of shopping-list-items[2] 
     when shopping-list-items[2] is keyed

You can test to see if a shelf has an item with a particular key using the has key test: 

  output shopping-list-items{"radishes"} 
     when shopping-list-items has key "radishes"

Adding and removing items on a variable-size shelf

You can add items to a variable-size shelf with the new and set new keywords. The following line creates a new item on the shelf word-count with the key Hamlet and the value 32058: 

  set new word-count{"Hamlet"} to 32058

You do not have to give every item a key. If all you need is a simple array, you can create shelf items without specifying keys: 

  local string shopping-list-items variable
  
  set new shopping-list-items to "lettuce"

Alternatively, you can create a shelf which has keys but no values. This is useful if you want to create an array in which every item is guaranteed to be unique. You can test a key for uniqueness before adding it to a shelf: 

  local string shopping-list-items variable
  
  do when shopping-list-items hasnt key "lettuce"
     new shopping-list-items{"lettuce"}
  done

Alternatively, the guarded form of new can be used: the previous example is equivalent to 

  local string shopping-list-items variable
  
  new? shopping-list-items{"lettuce"}

By default, new items are added to the end of the shelf. You can specify a different location using the keywords before and after: 

  local string shopping-list-items variable
  
  set new shopping-list-items{"lettuce"} after {"cabbage"}

You can remove an item from a shelf using the remove keyword: 

  remove word-count{"Hamlet"}
  remove shopping-list-items[7]

Note that adding or removing items from a shelf causes the item numbers of all the items above the insertion or removal point to change: item numbers are not permanently attached to items. They are indexes into the shelf by position, not properties of the items. Keys, on the other hand, are properties of each shelf item: when a shelf item is added or removed from a shelf, the other items on that shelf retain their keys, if any.

Repeating over a shelf

The items on a shelf can be iterated over using the repeat over loop: 

  repeat over shopping-list-items
     output shopping-list-items || "%n"
  again

Within a repeat over loop, you refer to the current item using the name of the shelf, without an indexer. Alternatively, you can use an alias in the header of the repeat over loop: 

  repeat over shopping-list-items as list-item
     output list-item || "%n"
  again

You can retrieve the current item number using #item. You can test for the first and last items using #first and #last.

The following program creates a shelf, using various methods to position items on the shelf: 

  process
     local string quotes variable
  
     set new quotes{"Hamlet"} to "To be or not to be?"
     set new quotes{"Macbeth"} to "Is this a dagger...?"
     set new quotes{"Richard III"} before [2] to "A horse, a horse!"
     set new quotes{"Romeo"} after {"Richard III"} to "But, soft! What light through yonder window breaks?"
  
     repeat over quotes
        output key of quotes
            || " - "
            || quotes || "%n"
     again

This program will output: 

  Hamlet - To be or not to be?
  Richard III - A horse, a horse!
  Romeo - But, soft! What light through yonder window breaks?
  Macbeth - Is this a dagger...?

The current item

Every shelf has a current item. If you refer to the shelf without using an indexer, the reference is to the current item.

The default current item is the last item. You can change the current item in one of three ways.

  1. The current item is the next item in succession each time through a repeat over loop.
  2. You can designate the current item with a using statement.
  3. You can establish the current item for a shelf passed (as read-only, modifiable, or write-only) to a function call.

There are two cases where a shelf has no current item:

  1. when it has zero items, or
  2. when the current item established by using has been removed

Operations on shelves

You can perform a number of operations on shelves:

  • You can copy the contents of one shelf to another by using the copy keyword.
  • You can remove all the items from a variable shelf by using the clear keyword.
  • You copy the contents of a variable shelf to another shelf and then clear the contents of the first shelf using the copy-clear keyword.
  • You can determine the number of items on a shelf using the keyword number of.

Prerequisite Concepts
Related Topics