Patch title: Release 93 bulk changes
Abstract:
File: /language/type/set/index.page
Key:
    Removed line
    Added line
title "Pliant data sets"

[Pliant release 41 introduces a consistent set of generic data types for storing data sets.]

table columns 2
  cell color lsh 78 5 130 [Type]
  cell color (color hsl 130 5 78) [Type]
  cell void
  cell
    bold [List ] ; italic [values_type]
  cell
    [In a list, the elements have no key. So, you can access them only through walking the list.]
  cell
    bold [Array ] ; italic [values_type]
  cell
    [Keys are integers, and the valid keys set is ranging from 0 to the size of the array minus one. You can have a single value associated with each key.]
  cell
    bold [Dictionary ] ; italic [keys_type values_type]
  cell
    [Each key value is free. You can have several values associated with the same key. When you walk the dictionary, you get the keys values pairs in a random order.]
  cell
    bold [Index ] ; italic [keys_type values_type]
  cell
    [Each key value is free. You can have several values associated with the same key. W When you walk the index, you get the key values pairs in ascending keys order.]

[The following properties list should help you select the right data set type for your application:]

table columns 5
  cell color lsh 78 5 130 [Type]
  cell color lsh 78 5 130 small:[Walking]
  cell color lsh 78 5 130 small:[Bidirectionnal walking]
  cell color lsh 78 5 130 small:[Direct access]
  cell color lsh 78 5 130 small:[Insert/Remove]
  cell color (color hsl 130 5 78) [Type]
  cell color (color hsl 130 5 78) small:[Walking]
  cell color (color hsl 130 5 78) small:[Bidirectionnal walking]
  cell color (color hsl 130 5 78) small:[Direct access]
  cell color (color hsl 130 5 78) small:[Insert/Remove]
  cell bold:[List]
  cell [very fast]
  cell [yes]
  cell [no]
  cell [fast]
  cell bold:[Array]
  cell [very fast]
  cell { [no ] ; small [(would be very fast if implemented)] }
  cell [very fast]
  cell [slow]
  cell bold:[Dictionary]
  cell [quite fast]
  cell { [no ] ; small [(would be quite fast if implemented)] }
  cell [quite fast]
  cell [quite fast most time]
  cell bold:[Index]
  cell [very fast]
  cell [yes]
  cell [medium]
  cell [medium]

[These are the methods available:]


header "Walking"

para
  listing
    method `s ¤first -> `v
      arg `Set `s ; arg_C `Value `v
  [Returns a pointer to the first value in the data set.] ; eol
  [If the data set is empty, the pointer will be null.]
  table columns 4
    cell [List] ; cell [Array] ; cell [Dictionary] ; cell [Index]
    cell [yes] ; cell [yes] ; cell [yes] ; cell [yes]

para
  listing
    method `s ¤next `v1 -> `v2
      arg `Set `s ; arg_r `Value `v1 ; arg_C `Value `v
  [Returns a pointer to the next value in the data set.] ; eol
  [If no more value is available, the pointer will be null.]
  table columns 4
    cell [List] ; cell [Array] ; cell [Dictionary] ; cell [Index]
    cell [yes] ; cell [yes] ; cell [yes] ; cell [yes]

para
  listing
    method `s ¤last -> `v
      arg `Set `s ; arg_C `Value `v
  table columns 4
    cell [List] ; cell [Array] ; cell [Dictionary] ; cell [Index]
    cell [yes] ; cell [no] ; cell [no] ; cell [yes]

para
  listing
    method `s ¤previous `v1 -> `v2
      arg `Set `s ; arg_r `Value `v1 ; arg_C `Value `v
  table columns 4
    cell [List] ; cell [Array] ; cell [Dictionary] ; cell [Index]
    cell [yes] ; cell [no] ; cell [no] ; cell [yes]

para
  listing
    method `s ¤from `k -> `v
      arg `Set `s ; arg `Key `k ; arg_C `Value `v
  [Returns a pointer to the first value which key is greater or equal to ] ; italic [k] ; [.]
  table columns 4
    cell [List] ; cell [Array] ; cell [Dictionary] ; cell [Index]
    cell [no] ; cell [no] ; cell [no] ; cell [yes]

para
  listing
    method `s ¤to `k -> `v
      arg `Set `s ; arg `Key `k ; arg_C `Value `v
  [Returns a pointer to the first value which key is greater than ] ; italic [k] ; [.]
  table columns 4
    cell [List] ; cell [Array] ; cell [Dictionary] ; cell [Index]
    cell [no] ; cell [no] ; cell [no] ; cell [yes]

para
  listing
    method `s ¤key `v -> `k
      arg `Set `s ; arg_r `Value `v ; arg_R `Key `k
  [Returns a pointer to the key associated with the value pointed by 'v'.]
  table columns 4
    cell [List] ; cell [Array] ; cell [Dictionary] ; cell [Index]
    cell [no] ; cell [yes] ; cell [yes] ; cell [yes]


header "Direct access"

para
  listing
    method `s ¤first `k -> `v
      arg `Set `s ; arg `Key `k ; arg_C `Value `v
  [Returns a pointer to the first value in the data set associated with the specifyed key.] ; eol
  [If the data set is empty, the pointer will be null.] ; eol
  table columns 4
    cell [List] ; cell [Array] ; cell [Dictionary] ; cell [Index]
    cell [no] ; cell [yes] ; cell [yes] ; cell [yes]

para
  listing
    method `s ¤next `k -> `v
      arg `Set `s ; arg `Key `k ; arg_C `Value `v
  [Returns a pointer to the next value in the data set associated with the specifyed key.] ; eol
  [If there are no more values, the pointer will be null.]
  table columns 4
    cell [List] ; cell [Array] ; cell [Dictionary] ; cell [Index]
    cell [no] ; cell [yes] ; cell [yes] ; cell [yes]

para
  listing
    method `s ¤exists `k -> `c
      arg `Set `s ; arg `Key `k ; arg CBool `c
  [Tests if at least one element with the specifyed key is available in the data set.] ; eol
  [This is equivalent to]
  fixed
    [ addressof:(] ; italic [s] ; [ first ] ; italic [k] ; [)<>null]
  table columns 4
    cell [List] ; cell [Array] ; cell [Dictionary] ; cell [Index]
    cell [no] ; cell [yes] ; cell [yes] ; cell [yes]


para
  listing
    method `s '' `k -> `v
      arg `Set `s ; arg `Key `k ; arg_C `Value `v
  [Returns a pointer to the first value in the data set associated with the specifyed key.] ; eol
  [There must be such a value, or a fatal error will be raised.]
  table columns 4
    cell [List] ; cell [Array] ; cell [Dictionary] ; cell [Index]
    cell [no] ; cell [yes] ; cell [yes] ; cell [yes]


header "Insert / Remove"

para
  listing
    function ¤'+=' `s `v
      arg_rw `Set `s ; arg `Value `v
  [Adds a new value to the set.]
  table columns 4
    cell [List] ; cell [Array] ; cell [Dictionary] ; cell [Index]
    cell [yes] ; cell [slow] ; cell [no] ; cell [no]

para
  listing
    method `s ¤insert `k `v -> v2
      arg `Set `s ; arg `Key `k ; arg  `Value `v ; arg_C `Value `v2
  table columns 4
    cell [List] ; cell [Array] ; cell [Dictionary] ; cell [Index]
    cell [no] ; cell [no] ; cell [yes] ; cell [yes]

para
  listing
    method `s ¤insert_before `v1 `v -> v2
      arg `Set `s ; arg_r `Value `v1 ; arg `Value v ; arg_C `Value `v2
  table columns 4
    cell [List] ; cell [Array] ; cell [Dictionary] ; cell [Index]
    cell [yes] ; cell [no] ; cell [no] ; cell [no]

para
  listing
    method `s ¤insert_after `v1 `v -> v2
      arg `Set `s ; arg_r `Value `v1 ; arg `Value v ; arg_C `Value `v2
  table columns 4
    cell [List] ; cell [Array] ; cell [Dictionary] ; cell [Index]
    cell [yes] ; cell [no] ; cell [no] ; cell [no]


para
  listing
    function ¤'-=' `s `v
      arg_rw `Set `s ; arg_r `Value `v
  [Removes the element pointed by ] ; italic [v] ; [.]
  table columns 4
    cell [List] ; cell [Array] ; cell [Dictionary] ; cell [Index]
    cell [yes] ; cell [no] ; cell [yes] ; cell [yes]

para
  listing
    method `s ¤remove `v -> `v2
      arg_rw `Set `s ; arg_r `Value `v ; arg_C `Value `v2
  table columns 4
    cell [List] ; cell [Array] ; cell [Dictionary] ; cell [Index]
    cell [no] ; cell [no] ; cell [yes] ; cell [yes]

para
  listing
    method `s ¤size -> `n
      arg `Set `s ; arg Int `n
  [Returns the number of elements in the data set.]
  table columns 4
    cell [List] ; cell [Array] ; cell [Dictionary] ; cell [Index]
    cell [slow] ; cell [yes] ; cell [yes] ; cell [yes]

para
  listing
    `s ¤size := `n
  [Sets the number of elements in the data set.]
  table columns 4
    cell [List] ; cell [Array] ; cell [Dictionary] ; cell [Index]
    cell [no] ; cell [yes] ; cell [no] ; cell [no]