NAME

       write-array -  (array)

PURPOSE

       Store value into an array.

SYNTAX

           write-array <array> \
               key <key> \
               value <value> \
               [ old-value <old value> ]

DESCRIPTION

       write-array  will  store  a <value> (in "value" clause) under index <key> (in "key" clause) into <array>,
       which must be created with new-array. <key> is a number from 0 up to (excluding) the currently  allocated
       array  size  (see  new-array).  The  type  of  <value>  is determined when <array> is created (see "type"
       clause), and can be either a string, number or a boolean.

       <key> and <value> are collectively called an "element".

       The old value associated under index <key> is returned in <old value> (in "old-value" clause) and <value>
       will replace the old value.

       If an <array> was created with "process-scope" clause (see new-array), then the element <value> will  not
       be  freed  when  the  current request ends, rather it will persist while the process runs, unless deleted
       (see read-array with delete clause).

EXAMPLES

       Writing data to an array:

           new-array arr
           write-array arr key 100 value "some data"

       Writing new value with the same key index and obtaining the previous value (which is "some data"):

           write-array arr key 100 value "new data" old-value od
           @Previous value for this key index is <<print-out od>>

       The following is an array service, where a  process-scoped  array  is  created.  It  provides  inserting,
       deleting  and  querying  indexed  keys.  Maximum number of keys it holds is 10,000,000 (indexed from 0 to
       9,999,999). Such a service process can run indefinitely. Create file arrsrv.golf:

           %% /arrsrv public
               do-once
               new-array arr max-size 10000000 process-scope type string
               end-do-once

               // Get input parameters
               get-param op
               get-param key
               get-param data
               // Convert string keye to number
               string-number key to key_n

               if-true op equal "add" // Add data to array
                   write-array arr key key_n value data old-value old_data
                   delete-string old_data
                   @Added [<<print-out key>>]
               else-if op equal "delete" // Delete data and obtain the value deleted
                   read-array arr key key_n value val delete
                   @Deleted [<<print-out val>>]
                   delete-string val
               else-if op equal "query" // Query hash based on key value
                   read-array arr key key_n value val
                   @Value [<<print-out val>>]
               end-if
           %%

       Create and make the application, then run it as service:

           // Create application
           gg -k arr
           // Make application
           gg -q
           // Start application (single process key service)
           mgrg -w 1 arr

       Try it from a command line client (see gg):

           // Add data
           gg -r --req="/arrsrv/op=add/key=15/data=15" --service --app="/arr" --exec
           // Query data
           gg -r --req="/arrsrv/op=query/key=15" --service --app="/arr" --exec
           // Delete data
           gg -r --req="/arrsrv/op=delete/key=15" --service --app="/arr" --exec

       See read-array for more examples.

SEE ALSO

        Array

       new-array purge-array read-array write-array See all documentation

$DATE                                               $VERSION                                           GOLF(2gg)