libcwal  Hex Artifact Content

Artifact 864495a3d36f449bda202d337879c7d5f52f9867:

Wiki page [DataTypes] by stephan 2014-07-31 18:27:37.
0000: 44 20 32 30 31 34 2d 30 37 2d 33 31 54 31 38 3a  D 2014-07-31T18:
0010: 32 37 3a 33 37 2e 30 37 39 0a 4c 20 44 61 74 61  27:37.079.L Data
0020: 54 79 70 65 73 0a 50 20 30 61 65 63 34 32 36 33  Types.P 0aec4263
0030: 65 31 37 37 35 62 33 30 39 39 33 65 36 38 37 31  e1775b30993e6871
0040: 62 30 66 39 61 62 36 61 33 38 33 35 62 37 35 38  b0f9ab6a3835b758
0050: 0a 55 20 73 74 65 70 68 61 6e 0a 57 20 31 31 38  .U stephan.W 118
0060: 38 32 0a 53 65 65 20 61 6c 73 6f 3a 20 5b 4d 65  82.See also: [Me
0070: 6d 6f 72 79 4d 6f 64 65 6c 5d 2c 20 5b 63 77 61  moryModel], [cwa
0080: 6c 5f 67 63 5d 0d 0a 0d 0a 3c 68 31 3e 63 77 61  l_gc]....<h1>cwa
0090: 6c 20 44 61 74 61 20 54 79 70 65 73 3c 2f 68 31  l Data Types</h1
00a0: 3e 0d 0a 0d 0a 54 68 69 73 20 70 61 67 65 20 64  >....This page d
00b0: 65 73 63 72 69 62 65 73 20 74 68 65 20 76 61 72  escribes the var
00c0: 69 6f 75 73 20 74 79 70 65 73 20 6f 66 20 56 61  ious types of Va
00d0: 6c 75 65 73 20 77 68 69 63 68 20 63 77 61 6c 20  lues which cwal 
00e0: 65 78 70 6f 73 65 73 20 74 6f 20 63 6c 69 65 6e  exposes to clien
00f0: 74 20 63 6f 64 65 2e 20 41 6c 6c 20 6f 66 20 74  t code. All of t
0100: 68 65 73 65 20 74 79 70 65 73 20 68 61 76 65 20  hese types have 
0110: 62 61 73 69 63 20 56 61 6c 75 65 20 68 61 6e 64  basic Value hand
0120: 6c 65 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  le representatio
0130: 6e 73 20 28 76 69 61 20 61 20 3c 74 74 3e 63 77  ns (via a <tt>cw
0140: 61 6c 5f 76 61 6c 75 65 3c 2f 74 74 3e 20 70 6f  al_value</tt> po
0150: 69 6e 74 65 72 29 20 61 6e 64 20 6d 61 6e 79 20  inter) and many 
0160: 6f 66 20 74 68 65 6d 20 61 6c 73 6f 20 68 61 76  of them also hav
0170: 65 20 68 69 67 68 65 72 2d 6c 65 76 65 6c 20 72  e higher-level r
0180: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 73 20 28  epresentations (
0190: 65 2e 67 2e 20 3c 74 74 3e 63 77 61 6c 5f 6f 62  e.g. <tt>cwal_ob
01a0: 6a 65 63 74 3c 2f 74 74 3e 20 6f 72 20 3c 74 74  ject</tt> or <tt
01b0: 3e 63 77 61 6c 5f 73 74 72 69 6e 67 3c 2f 74 74  >cwal_string</tt
01c0: 3e 29 2e 20 43 6c 69 65 6e 74 73 20 63 61 6e 20  >). Clients can 
01d0: 63 6f 6e 76 65 72 74 20 66 72 65 65 6c 79 20 62  convert freely b
01e0: 65 74 77 65 65 6e 20 73 75 63 68 20 72 65 70 72  etween such repr
01f0: 65 73 65 6e 74 61 74 69 6f 6e 73 2e 20 4d 6f 73  esentations. Mos
0200: 74 20 41 50 49 73 20 77 6f 72 6b 20 77 69 74 68  t APIs work with
0210: 20 62 61 73 69 63 20 56 61 6c 75 65 20 68 61 6e   basic Value han
0220: 64 6c 65 73 2c 20 73 6f 20 69 74 20 69 73 20 6f  dles, so it is o
0230: 66 74 65 6e 20 6e 65 63 65 73 73 61 72 79 20 74  ften necessary t
0240: 6f 20 63 6f 6e 76 65 72 74 20 68 69 67 68 65 72  o convert higher
0250: 2d 6c 65 76 65 6c 20 68 61 6e 64 6c 65 73 20 74  -level handles t
0260: 6f 20 74 68 65 20 56 61 6c 75 65 20 66 6f 72 6d  o the Value form
0270: 20 28 73 75 63 68 20 63 6f 6e 76 65 72 73 69 6f   (such conversio
0280: 6e 20 69 73 20 61 6e 20 4f 28 31 29 20 6f 70 65  n is an O(1) ope
0290: 72 61 74 69 6f 6e 29 2e 20 48 6f 77 20 74 6f 20  ration). How to 
02a0: 64 6f 20 73 75 63 68 20 63 6f 6e 76 65 72 73 69  do such conversi
02b0: 6f 6e 73 20 69 73 20 64 65 6d 6f 6e 73 74 72 61  ons is demonstra
02c0: 74 65 64 20 69 6e 20 74 68 65 20 65 78 61 6d 70  ted in the examp
02d0: 6c 65 73 20 62 65 6c 6f 77 2e 0d 0a 0d 0a 3c 68  les below.....<h
02e0: 32 3e 43 6f 6e 74 61 69 6e 65 72 20 54 79 70 65  2>Container Type
02f0: 73 20 61 6e 64 20 43 79 63 6c 65 73 3c 2f 68 32  s and Cycles</h2
0300: 3e 0d 0a 0d 0a 53 6f 6d 65 20 74 79 70 65 73 20  >....Some types 
0310: 28 65 2e 67 2e 20 4f 62 6a 65 63 74 73 20 61 6e  (e.g. Objects an
0320: 20 41 72 72 61 79 73 29 20 61 72 65 20 67 65 6e   Arrays) are gen
0330: 65 72 69 63 61 6c 6c 79 20 6b 6e 6f 77 6e 20 61  erically known a
0340: 73 20 22 63 6f 6e 74 61 69 6e 65 72 73 2c 22 20  s "containers," 
0350: 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65  meaning that the
0360: 79 20 63 61 6e 20 68 6f 6c 64 20 6f 74 68 65 72  y can hold other
0370: 20 76 61 6c 75 65 73 2e 20 53 75 63 68 20 74 79   values. Such ty
0380: 70 65 73 20 63 61 6e 20 6c 65 61 64 20 74 6f 20  pes can lead to 
0390: 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
03a0: 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 20 63 79  which contain cy
03b0: 63 6c 65 73 20 28 63 69 72 63 75 6c 61 72 20 72  cles (circular r
03c0: 65 66 65 72 65 6e 63 65 73 29 2e 20 54 68 61 74  eferences). That
03d0: 27 73 20 6f 6b 61 79 2e 20 54 68 65 20 73 63 6f  's okay. The sco
03e0: 70 65 2d 6c 65 76 65 6c 20 63 6c 65 61 6e 75 70  pe-level cleanup
03f0: 20 6d 65 63 68 61 6e 69 73 6d 20 63 61 6e 20 68   mechanism can h
0400: 61 6e 64 6c 65 20 73 75 63 68 20 73 74 72 75 63  andle such struc
0410: 74 75 72 65 73 20 61 6e 64 20 77 69 6c 6c 20 63  tures and will c
0420: 6c 65 61 6e 20 74 68 65 6d 20 75 70 20 70 72 6f  lean them up pro
0430: 70 65 72 6c 79 2c 20 70 72 6f 76 69 64 65 64 20  perly, provided 
0440: 74 68 65 20 63 6c 69 65 6e 74 20 6f 62 65 79 73  the client obeys
0450: 20 74 68 65 20 72 75 6c 65 73 20 6f 66 20 74 68   the rules of th
0460: 65 20 41 50 49 20 28 61 73 20 64 65 73 63 72 69  e API (as descri
0470: 62 65 64 20 69 6e 20 74 68 65 20 41 50 49 20 64  bed in the API d
0480: 6f 63 73 20 61 6e 64 20 74 68 65 73 65 20 77 69  ocs and these wi
0490: 6b 69 20 70 61 67 65 73 29 2e 0d 0a 0d 0a 54 68  ki pages).....Th
04a0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 63  e following conc
04b0: 72 65 74 65 20 74 79 70 65 73 20 61 72 65 20 63  rete types are c
04c0: 61 70 61 62 6c 65 20 6f 66 20 68 61 76 69 6e 67  apable of having
04d0: 20 6b 65 79 2f 76 61 6c 75 65 20 70 72 6f 70 65   key/value prope
04e0: 72 74 69 65 73 3a 0d 0a 0d 0a 20 20 20 2a 20 20  rties:....   *  
04f0: 4f 62 6a 65 63 74 0d 0a 20 20 20 2a 20 20 41 72  Object..   *  Ar
0500: 72 61 79 20 28 69 6e 20 61 64 64 69 74 69 6f 6e  ray (in addition
0510: 20 74 6f 20 69 6e 74 65 67 65 72 2d 69 6e 64 65   to integer-inde
0520: 78 65 64 20 70 72 6f 70 65 72 74 69 65 73 29 0d  xed properties).
0530: 0a 20 20 20 2a 20 20 4e 61 74 69 76 65 0d 0a 20  .   *  Native.. 
0540: 20 20 2a 20 20 46 75 6e 63 74 69 6f 6e 0d 0a 20    *  Function.. 
0550: 20 20 2a 20 20 45 78 63 65 70 74 69 6f 6e 0d 0a    *  Exception..
0560: 20 20 20 2a 20 20 48 61 73 68 20 54 61 62 6c 65     *  Hash Table
0570: 73 0d 0a 0d 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  s....<blockquote
0580: 3e 0d 0a 53 69 64 65 62 61 72 3a 20 42 75 66 66  >..Sidebar: Buff
0590: 65 72 73 20 73 68 6f 75 6c 64 20 61 72 67 75 61  ers should argua
05a0: 62 6c 79 20 62 65 20 70 72 6f 70 65 72 74 69 65  bly be propertie
05b0: 73 2d 61 77 61 72 65 20 62 75 74 20 61 72 65 20  s-aware but are 
05c0: 6e 6f 74 20 62 65 63 61 75 73 65 20 74 68 65 20  not because the 
05d0: 62 75 66 66 65 72 20 63 6c 61 73 73 20 68 61 73  buffer class has
05e0: 20 65 78 69 73 74 65 64 20 73 69 6e 63 65 20 6c   existed since l
05f0: 6f 6e 67 20 62 65 66 6f 72 65 20 69 74 20 77 61  ong before it wa
0600: 73 20 65 78 70 6f 73 65 64 20 61 73 20 61 20 56  s exposed as a V
0610: 61 6c 75 65 20 74 79 70 65 2c 20 61 6e 64 20 72  alue type, and r
0620: 65 74 72 6f 66 69 74 74 69 6e 67 20 69 74 20 74  etrofitting it t
0630: 6f 20 73 75 70 70 6f 72 74 20 70 65 72 2d 69 6e  o support per-in
0640: 73 74 61 6e 63 65 20 70 72 6f 70 65 72 74 69 65  stance propertie
0650: 73 20 77 6f 75 6c 64 20 62 65 20 72 61 74 68 65  s would be rathe
0660: 72 20 69 6e 74 72 75 73 69 76 65 20 6f 6e 20 62  r intrusive on b
0670: 6f 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20  oth the library 
0680: 61 6e 64 20 65 78 69 73 74 69 6e 67 20 63 6c 69  and existing cli
0690: 65 6e 74 20 63 6f 64 65 20 77 68 69 63 68 20 75  ent code which u
06a0: 73 65 73 20 62 75 66 66 65 72 73 20 69 6e 20 6e  ses buffers in n
06b0: 6f 6e 2d 56 61 6c 75 65 20 63 61 70 61 63 69 74  on-Value capacit
06c0: 69 65 73 20 28 74 68 61 74 20 69 73 20 74 6f 20  ies (that is to 
06d0: 73 61 79 2c 20 74 68 65 20 6d 61 6a 6f 72 69 74  say, the majorit
06e0: 79 20 6f 66 20 75 73 65 20 63 61 73 65 73 29 2e  y of use cases).
06f0: 0d 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0d  ..</blockquote>.
0700: 0a 0d 0a 3c 68 31 3e 4e 75 6d 65 72 69 63 3c 2f  ...<h1>Numeric</
0710: 68 31 3e 0d 0a 0d 0a 63 77 61 6c 20 64 69 66 66  h1>....cwal diff
0720: 65 72 65 6e 74 69 61 74 65 73 20 62 65 74 77 65  erentiates betwe
0730: 65 6e 20 3c 65 6d 3e 73 69 67 6e 65 64 3c 2f 65  en <em>signed</e
0740: 6d 3e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 64  m> integer and d
0750: 6f 75 62 6c 65 20 76 61 6c 75 65 73 2e 20 49 6e  ouble values. In
0760: 74 65 67 65 72 20 70 72 65 63 69 73 69 6f 6e 20  teger precision 
0770: 64 65 70 65 6e 64 73 20 6f 6e 20 74 68 65 20 70  depends on the p
0780: 6c 61 74 66 6f 72 6d 20 61 6e 64 20 62 75 69 6c  latform and buil
0790: 64 20 6f 70 74 69 6f 6e 73 20 28 31 36 2d 36 34  d options (16-64
07a0: 20 62 69 74 73 29 2e 20 44 6f 75 62 6c 65 20 70   bits). Double p
07b0: 72 65 63 69 73 69 6f 6e 20 69 73 20 61 73 20 66  recision is as f
07c0: 6f 72 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  or the standard 
07d0: 64 6f 75 62 6c 65 20 74 79 70 65 2c 20 62 75 74  double type, but
07e0: 20 69 74 20 63 61 6e 20 62 65 20 63 6f 6e 66 69   it can be confi
07f0: 67 75 72 65 64 20 74 6f 20 75 73 65 20 6c 6f 6e  gured to use lon
0800: 67 20 64 6f 75 62 6c 65 73 20 61 73 20 77 65 6c  g doubles as wel
0810: 6c 2e 0d 0a 0d 0a 45 78 61 6d 70 6c 65 20 75 73  l.....Example us
0820: 61 67 65 73 3a 0d 0a 0d 0a 3c 6e 6f 77 69 6b 69  ages:....<nowiki
0830: 3e 3c 70 72 65 3e 0d 0a 63 77 61 6c 5f 76 61 6c  ><pre>..cwal_val
0840: 75 65 20 2a 20 69 20 3d 20 63 77 61 6c 5f 6e 65  ue * i = cwal_ne
0850: 77 5f 69 6e 74 65 67 65 72 28 65 2c 20 34 32 29  w_integer(e, 42)
0860: 3b 0d 0a 63 77 61 6c 5f 76 61 6c 75 65 20 2a 20  ;..cwal_value * 
0870: 64 20 3d 20 63 77 61 6c 5f 6e 65 77 5f 64 6f 75  d = cwal_new_dou
0880: 62 6c 65 28 65 2c 20 34 32 2e 32 34 29 3b 0d 0a  ble(e, 42.24);..
0890: 61 73 73 65 72 74 28 63 77 61 6c 5f 76 61 6c 75  assert(cwal_valu
08a0: 65 5f 69 73 5f 69 6e 74 65 67 65 72 28 69 29 29  e_is_integer(i))
08b0: 3b 0d 0a 61 73 73 65 72 74 28 63 77 61 6c 5f 76  ;..assert(cwal_v
08c0: 61 6c 75 65 5f 69 73 5f 64 6f 75 62 6c 65 28 64  alue_is_double(d
08d0: 29 29 3b 0d 0a 0d 0a 63 77 61 6c 5f 69 6e 74 5f  ));....cwal_int_
08e0: 74 20 78 49 20 3d 20 63 77 61 6c 5f 76 61 6c 75  t xI = cwal_valu
08f0: 65 5f 67 65 74 5f 69 6e 74 65 67 65 72 28 69 29  e_get_integer(i)
0900: 3b 0d 0a 61 73 73 65 72 74 28 20 34 32 20 3d 3d  ;..assert( 42 ==
0910: 20 78 49 20 29 3b 0d 0a 63 77 61 6c 5f 69 6e 74   xI );..cwal_int
0920: 5f 74 20 78 44 20 3d 20 63 77 61 6c 5f 76 61 6c  _t xD = cwal_val
0930: 75 65 5f 67 65 74 5f 64 6f 75 62 6c 65 28 64 29  ue_get_double(d)
0940: 3b 0d 0a 61 73 73 65 72 74 28 20 34 32 2e 32 34  ;..assert( 42.24
0950: 20 3d 3d 20 78 44 20 29 3b 0d 0a 78 49 20 3d 20   == xD );..xI = 
0960: 63 77 61 6c 5f 76 61 6c 75 65 5f 67 65 74 5f 69  cwal_value_get_i
0970: 6e 74 65 67 65 72 28 64 29 20 2f 2a 20 6e 6f 74  nteger(d) /* not
0980: 65 20 74 68 65 20 64 6f 75 62 6c 65 20 61 72 67  e the double arg
0990: 75 6d 65 6e 74 21 20 2a 2f 3b 0d 0a 61 73 73 65  ument! */;..asse
09a0: 72 74 28 20 34 32 20 3d 3d 20 78 49 20 29 3b 0d  rt( 42 == xI );.
09b0: 0a 78 44 20 3d 20 63 77 61 6c 5f 76 61 6c 75 65  .xD = cwal_value
09c0: 5f 67 65 74 5f 64 6f 75 62 6c 65 28 69 29 20 2f  _get_double(i) /
09d0: 2a 20 6e 6f 74 65 20 74 68 65 20 69 6e 74 65 67  * note the integ
09e0: 65 72 20 61 72 67 75 6d 65 6e 74 21 20 2a 2f 3b  er argument! */;
09f0: 0d 0a 61 73 73 65 72 74 28 20 34 32 2e 30 20 3d  ..assert( 42.0 =
0a00: 3d 20 78 44 20 29 3b 0d 0a 0d 0a 2f 2f 20 4f 70  = xD );....// Op
0a10: 74 69 6f 6e 61 6c 20 63 6c 65 61 6e 75 70 20 2e  tional cleanup .
0a20: 2e 2e 0d 0a 63 77 61 6c 5f 76 61 6c 75 65 5f 75  ....cwal_value_u
0a30: 6e 72 65 66 28 65 2c 69 29 3b 0d 0a 63 77 61 6c  nref(e,i);..cwal
0a40: 5f 76 61 6c 75 65 5f 75 6e 72 65 66 28 65 2c 64  _value_unref(e,d
0a50: 29 3b 0d 0a 3c 2f 70 72 65 3e 3c 2f 6e 6f 77 69  );..</pre></nowi
0a60: 6b 69 3e 0d 0a 0d 0a 3c 68 31 3e 53 74 72 69 6e  ki>....<h1>Strin
0a70: 67 73 3c 2f 68 31 3e 0d 0a 0d 0a 53 74 72 69 6e  gs</h1>....Strin
0a80: 67 73 20 61 72 65 20 62 61 73 69 63 61 6c 6c 79  gs are basically
0a90: 20 6f 70 61 71 75 65 20 62 79 74 65 20 61 72 72   opaque byte arr
0aa0: 61 79 73 2c 20 61 6e 64 20 63 77 61 6c 20 67 65  ays, and cwal ge
0ab0: 6e 65 72 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74  nerally does not
0ac0: 20 63 61 72 65 20 61 62 6f 75 74 20 65 6e 63 6f   care about enco
0ad0: 64 69 6e 67 2c 20 62 75 74 20 77 69 6c 6c 20 75  ding, but will u
0ae0: 73 65 20 3c 74 74 3e 73 74 72 6c 65 6e 28 29 3c  se <tt>strlen()<
0af0: 2f 74 74 3e 20 69 6e 20 73 6f 6d 65 20 63 61 73  /tt> in some cas
0b00: 65 73 20 69 66 20 74 68 65 20 75 73 65 72 20 64  es if the user d
0b10: 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20  oes not provide 
0b20: 61 20 6c 65 6e 67 74 68 2c 20 73 6f 20 69 74 20  a length, so it 
0b30: 77 69 6c 6c 20 6e 6f 74 20 77 6f 72 6b 20 77 69  will not work wi
0b40: 74 68 20 55 54 46 31 36 20 75 6e 6c 65 73 73 20  th UTF16 unless 
0b50: 63 6c 69 65 6e 74 73 20 70 72 6f 76 69 64 65 20  clients provide 
0b60: 61 6c 6c 20 6c 65 6e 67 74 68 73 2e 0d 0a 0d 0a  all lengths.....
0b70: 45 78 61 6d 70 6c 65 20 75 73 61 67 65 73 3a 0d  Example usages:.
0b80: 0a 0d 0a 3c 6e 6f 77 69 6b 69 3e 3c 70 72 65 3e  ...<nowiki><pre>
0b90: 0d 0a 63 77 61 6c 5f 73 74 72 69 6e 67 20 2a 20  ..cwal_string * 
0ba0: 73 20 3d 20 63 77 61 6c 5f 6e 65 77 5f 73 74 72  s = cwal_new_str
0bb0: 69 6e 67 28 65 2c 20 22 68 69 21 22 2c 20 33 29  ing(e, "hi!", 3)
0bc0: 3b 0d 0a 63 77 61 6c 5f 76 61 6c 75 65 20 2a 20  ;..cwal_value * 
0bd0: 73 76 20 3d 20 63 77 61 6c 5f 73 74 72 69 6e 67  sv = cwal_string
0be0: 5f 76 61 6c 75 65 28 73 29 3b 0d 0a 61 73 73 65  _value(s);..asse
0bf0: 72 74 28 63 77 61 6c 5f 76 61 6c 75 65 5f 67 65  rt(cwal_value_ge
0c00: 74 5f 73 74 72 69 6e 67 28 73 76 29 3d 3d 73 29  t_string(sv)==s)
0c10: 3b 0d 0a 63 68 61 72 20 63 6f 6e 73 74 20 2a 20  ;..char const * 
0c20: 63 73 74 72 20 3d 20 63 77 61 6c 5f 73 74 72 69  cstr = cwal_stri
0c30: 6e 67 5f 63 73 74 72 28 73 29 3b 0d 0a 0d 0a 2f  ng_cstr(s);..../
0c40: 2f 20 4f 70 74 69 6f 6e 61 6c 20 63 6c 65 61 6e  / Optional clean
0c50: 75 70 20 2e 2e 2e 0d 0a 63 77 61 6c 5f 73 74 72  up .....cwal_str
0c60: 69 6e 67 5f 75 6e 72 65 66 28 65 2c 20 73 29 3b  ing_unref(e, s);
0c70: 0d 0a 2f 2f 20 4f 52 20 28 44 4f 20 4e 4f 54 20  ..// OR (DO NOT 
0c80: 44 4f 20 42 4f 54 48 21 29 2e 2e 2e 0d 0a 63 77  DO BOTH!).....cw
0c90: 61 6c 5f 76 61 6c 75 65 5f 75 6e 72 65 66 28 65  al_value_unref(e
0ca0: 2c 20 73 76 29 3b 0d 0a 3c 2f 70 72 65 3e 3c 2f  , sv);..</pre></
0cb0: 6e 6f 77 69 6b 69 3e 0d 0a 0d 0a 3c 68 31 3e 41  nowiki>....<h1>A
0cc0: 72 72 61 79 73 3c 2f 68 31 3e 0d 0a 0d 0a 41 72  rrays</h1>....Ar
0cd0: 72 61 79 73 20 72 65 70 72 65 73 65 6e 74 20 73  rays represent s
0ce0: 65 71 75 65 6e 74 69 61 6c 20 6c 69 73 74 73 20  equential lists 
0cf0: 6f 66 20 61 72 62 69 74 72 61 72 79 20 76 61 6c  of arbitrary val
0d00: 75 65 73 2c 20 62 61 73 69 63 61 6c 6c 79 20 61  ues, basically a
0d10: 6e 61 6c 6f 67 20 74 6f 20 43 20 61 72 72 61 79  nalog to C array
0d20: 73 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  s except that th
0d30: 65 79 20 63 61 6e 20 67 72 6f 77 2e 20 54 68 65  ey can grow. The
0d40: 20 41 50 49 20 64 6f 65 73 20 6e 6f 74 20 79 65   API does not ye
0d50: 74 20 68 61 76 65 20 61 20 66 75 6c 6c 20 73 65  t have a full se
0d60: 74 20 6f 66 20 6d 61 6e 69 70 75 6c 61 74 6f 72  t of manipulator
0d70: 73 20 66 6f 72 20 41 72 72 61 79 73 20 2d 20 74  s for Arrays - t
0d80: 68 65 79 20 77 69 6c 6c 20 62 65 20 61 64 64 65  hey will be adde
0d90: 64 20 61 73 20 6e 65 65 64 65 64 2e 0d 0a 0d 0a  d as needed.....
0da0: 45 78 61 6d 70 6c 65 20 75 73 61 67 65 73 3a 0d  Example usages:.
0db0: 0a 0d 0a 3c 6e 6f 77 69 6b 69 3e 3c 70 72 65 3e  ...<nowiki><pre>
0dc0: 0d 0a 63 77 61 6c 5f 61 72 72 61 79 20 2a 20 61  ..cwal_array * a
0dd0: 20 3d 20 63 77 61 6c 5f 6e 65 77 5f 61 72 72 61   = cwal_new_arra
0de0: 79 28 65 29 3b 0d 0a 63 77 61 6c 5f 76 61 6c 75  y(e);..cwal_valu
0df0: 65 20 2a 20 76 20 3d 20 63 77 61 6c 5f 6e 65 77  e * v = cwal_new
0e00: 5f 69 6e 74 65 67 65 72 28 65 2c 20 34 32 29 3b  _integer(e, 42);
0e10: 0d 0a 69 6e 74 20 72 63 20 3d 20 63 77 61 6c 5f  ..int rc = cwal_
0e20: 61 72 72 61 79 5f 61 70 70 65 6e 64 28 65 2c 20  array_append(e, 
0e30: 61 2c 20 76 29 3b 0d 0a 61 73 73 65 72 74 28 30  a, v);..assert(0
0e40: 3d 3d 72 63 29 3b 0d 0a 76 20 3d 20 63 77 61 6c  ==rc);..v = cwal
0e50: 5f 61 72 72 61 79 5f 76 61 6c 75 65 28 61 29 3b  _array_value(a);
0e60: 0d 0a 61 73 73 65 72 74 28 63 77 61 6c 5f 76 61  ..assert(cwal_va
0e70: 6c 75 65 5f 67 65 74 5f 61 72 72 61 79 28 76 29  lue_get_array(v)
0e80: 3d 3d 61 29 3b 0d 0a 0d 0a 2f 2f 20 4f 70 74 69  ==a);....// Opti
0e90: 6f 6e 61 6c 20 63 6c 65 61 6e 75 70 3a 0d 0a 63  onal cleanup:..c
0ea0: 77 61 6c 5f 61 72 72 61 79 5f 75 6e 72 65 66 28  wal_array_unref(
0eb0: 65 2c 20 61 29 3b 0d 0a 2f 2f 20 4f 52 20 28 44  e, a);..// OR (D
0ec0: 4f 20 4e 4f 54 20 54 4f 20 42 4f 54 48 21 29 2e  O NOT TO BOTH!).
0ed0: 2e 2e 0d 0a 63 77 61 6c 5f 76 61 6c 75 65 5f 75  ....cwal_value_u
0ee0: 6e 72 65 66 28 65 2c 20 63 77 61 6c 5f 61 72 72  nref(e, cwal_arr
0ef0: 61 79 5f 76 61 6c 75 65 28 61 29 29 3b 0d 0a 3c  ay_value(a));..<
0f00: 2f 70 72 65 3e 3c 2f 6e 6f 77 69 6b 69 3e 0d 0a  /pre></nowiki>..
0f10: 0d 0a 0d 0a 3c 68 31 3e 4f 62 6a 65 63 74 73 3c  ....<h1>Objects<
0f20: 2f 68 31 3e 0d 0a 0d 0a 4f 62 6a 65 63 74 73 20  /h1>....Objects 
0f30: 61 72 65 20 62 61 73 69 63 61 6c 6c 79 20 63 6f  are basically co
0f40: 6c 6c 65 63 74 69 6f 6e 73 20 6f 66 20 6b 65 79  llections of key
0f50: 2f 76 61 6c 75 65 20 70 61 69 72 73 2e 20 4b 65  /value pairs. Ke
0f60: 79 73 20 61 72 65 20 63 75 72 72 65 6e 74 6c 79  ys are currently
0f70: 20 61 6c 77 61 79 73 20 73 74 72 69 6e 67 73 2c   always strings,
0f80: 20 62 75 74 20 74 68 65 72 65 20 61 72 65 20 70   but there are p
0f90: 6c 61 6e 73 20 74 6f 20 61 6c 6c 6f 77 20 61 72  lans to allow ar
0fa0: 62 69 74 72 61 72 79 20 56 61 6c 75 65 20 74 79  bitrary Value ty
0fb0: 70 65 73 20 61 73 20 6b 65 79 73 20 28 74 68 65  pes as keys (the
0fc0: 20 69 6e 66 72 61 73 74 72 75 63 74 75 72 65 20   infrastructure 
0fd0: 69 73 20 69 6e 20 70 6c 61 63 65 2c 20 62 75 74  is in place, but
0fe0: 20 6f 74 68 65 72 20 70 61 72 74 73 20 6e 65 65   other parts nee
0ff0: 64 20 74 6f 20 62 65 20 72 65 66 61 63 74 6f 72  d to be refactor
1000: 65 64 20 74 6f 20 75 73 65 20 69 74 29 2e 0d 0a  ed to use it)...
1010: 0d 0a 4e 6f 74 65 20 74 68 61 74 20 6f 62 6a 65  ..Note that obje
1020: 63 74 20 70 72 6f 70 65 72 74 69 65 73 20 61 72  ct properties ar
1030: 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 6c 69  e stored in a li
1040: 73 74 2c 20 61 6e 64 20 74 68 75 73 20 68 61 76  st, and thus hav
1050: 65 20 4f 28 4e 29 20 70 65 72 66 6f 72 6d 61 6e  e O(N) performan
1060: 63 65 20 66 6f 72 20 73 65 61 72 63 68 2f 73 65  ce for search/se
1070: 74 2f 75 6e 73 65 74 2e 20 54 68 69 73 20 69 73  t/unset. This is
1080: 20 62 65 63 61 75 73 65 20 69 74 27 73 20 63 68   because it's ch
1090: 65 61 70 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  eap to implement
10a0: 20 61 6e 64 20 70 72 6f 76 69 64 65 73 20 74 68   and provides th
10b0: 65 20 72 65 76 65 72 73 65 2d 6f 66 2d 63 72 65  e reverse-of-cre
10c0: 61 74 69 6f 6e 20 64 65 73 74 72 75 63 74 69 6f  ation destructio
10d0: 6e 20 6f 72 64 65 72 20 77 65 20 77 61 6e 74 20  n order we want 
10e0: 28 77 65 6c 6c 2c 20 69 74 20 64 6f 65 73 20 66  (well, it does f
10f0: 6f 72 20 6d 6f 73 74 20 63 61 73 65 73 29 2e 20  or most cases). 
1100: 54 68 65 72 65 20 61 72 65 20 70 6c 61 6e 73 20  There are plans 
1110: 74 6f 20 61 64 64 20 61 20 73 65 70 61 72 61 74  to add a separat
1120: 65 20 48 61 73 68 54 61 62 6c 65 20 63 6c 61 73  e HashTable clas
1130: 73 20 77 68 69 63 68 20 66 75 6e 63 74 69 6f 6e  s which function
1140: 73 20 6c 69 6b 65 20 4f 62 6a 65 63 74 20 67 75  s like Object gu
1150: 61 72 61 6e 74 65 65 73 20 66 61 73 74 20 70 65  arantees fast pe
1160: 72 66 6f 72 6d 61 6e 63 65 20 61 74 20 74 68 65  rformance at the
1170: 20 63 6f 73 74 20 6f 66 20 28 6d 75 63 68 29 20   cost of (much) 
1180: 6d 6f 72 65 20 6d 65 6d 6f 72 79 2e 0d 0a 0d 0a  more memory.....
1190: 45 78 61 6d 70 6c 65 20 75 73 61 67 65 73 3a 0d  Example usages:.
11a0: 0a 0d 0a 3c 6e 6f 77 69 6b 69 3e 3c 70 72 65 3e  ...<nowiki><pre>
11b0: 0d 0a 63 77 61 6c 5f 6f 62 6a 65 63 74 20 2a 20  ..cwal_object * 
11c0: 6f 20 3d 20 63 77 61 6c 5f 6e 65 77 5f 6f 62 6a  o = cwal_new_obj
11d0: 65 63 74 28 65 29 3b 0d 0a 63 77 61 6c 5f 76 61  ect(e);..cwal_va
11e0: 6c 75 65 20 2a 20 76 20 3d 20 63 77 61 6c 5f 76  lue * v = cwal_v
11f0: 61 6c 75 65 5f 6e 65 77 5f 64 6f 75 62 6c 65 28  alue_new_double(
1200: 65 2c 20 38 37 2e 32 33 29 3b 0d 0a 69 6e 74 20  e, 87.23);..int 
1210: 72 63 20 3d 20 63 77 61 6c 5f 6f 62 6a 65 63 74  rc = cwal_object
1220: 5f 73 65 74 28 65 2c 20 6f 2c 20 22 68 69 22 2c  _set(e, o, "hi",
1230: 20 32 2c 20 76 20 29 3b 0d 0a 61 73 73 65 72 74   2, v );..assert
1240: 28 30 3d 3d 72 63 29 3b 0d 0a 76 20 3d 20 63 77  (0==rc);..v = cw
1250: 61 6c 5f 6f 62 6a 65 63 74 5f 76 61 6c 75 65 28  al_object_value(
1260: 6f 29 3b 0d 0a 61 73 73 65 72 74 28 63 77 61 6c  o);..assert(cwal
1270: 5f 76 61 6c 75 65 5f 67 65 74 5f 6f 62 6a 65 63  _value_get_objec
1280: 74 28 76 29 3d 3d 6f 29 3b 0d 0a 76 20 3d 20 63  t(v)==o);..v = c
1290: 77 61 6c 5f 6f 62 6a 65 63 74 5f 67 65 74 28 6f  wal_object_get(o
12a0: 2c 20 22 68 69 22 2c 20 32 29 3b 0d 0a 61 73 73  , "hi", 2);..ass
12b0: 65 72 74 28 63 77 61 6c 5f 76 61 6c 75 65 5f 69  ert(cwal_value_i
12c0: 73 5f 64 6f 75 62 6c 65 28 76 29 29 3b 0d 0a 0d  s_double(v));...
12d0: 0a 2f 2f 20 4f 70 74 69 6f 6e 61 6c 20 63 6c 65  .// Optional cle
12e0: 61 6e 75 70 3a 0d 0a 63 77 61 6c 5f 6f 62 6a 65  anup:..cwal_obje
12f0: 63 74 5f 75 6e 72 65 66 28 65 2c 20 6f 29 3b 0d  ct_unref(e, o);.
1300: 0a 2f 2f 20 4f 52 20 28 44 4f 20 4e 4f 54 20 54  .// OR (DO NOT T
1310: 4f 20 42 4f 54 48 21 29 2e 2e 2e 0d 0a 63 77 61  O BOTH!).....cwa
1320: 6c 5f 76 61 6c 75 65 5f 75 6e 72 65 66 28 65 2c  l_value_unref(e,
1330: 20 63 77 61 6c 5f 6f 62 6a 65 63 74 5f 76 61 6c   cwal_object_val
1340: 75 65 28 6f 29 29 3b 0d 0a 3c 2f 70 72 65 3e 3c  ue(o));..</pre><
1350: 2f 6e 6f 77 69 6b 69 3e 0d 0a 0d 0a 3c 68 31 3e  /nowiki>....<h1>
1360: 46 75 6e 63 74 69 6f 6e 73 3c 2f 68 31 3e 0d 0a  Functions</h1>..
1370: 0d 0a 46 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  ..Functions are 
1380: 43 20 66 75 6e 63 74 69 6f 6e 73 20 77 72 61 70  C functions wrap
1390: 70 65 64 20 75 70 20 69 6e 20 61 20 56 61 6c 75  ped up in a Valu
13a0: 65 20 68 61 6e 64 6c 65 2e 20 54 68 65 69 72 20  e handle. Their 
13b0: 43 20 63 6f 75 6e 74 65 72 70 61 72 74 73 20 6d  C counterparts m
13c0: 75 73 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  ust implement th
13d0: 65 20 3c 74 74 3e 63 77 61 6c 5f 63 61 6c 6c 62  e <tt>cwal_callb
13e0: 61 63 6b 5f 66 28 29 3c 2f 74 74 3e 20 69 6e 74  ack_f()</tt> int
13f0: 65 72 66 61 63 65 2c 20 61 6e 64 20 74 68 65 79  erface, and they
1400: 20 61 72 65 20 63 61 6c 6c 65 64 20 76 69 61 20   are called via 
1410: 74 68 65 20 3c 74 74 3e 63 77 61 6c 5f 66 75 6e  the <tt>cwal_fun
1420: 63 74 69 6f 6e 5f 63 61 6c 6c 28 29 3c 2f 74 74  ction_call()</tt
1430: 3e 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  > family of func
1440: 74 69 6f 6e 73 2e 20 43 61 6c 6c 62 61 63 6b 73  tions. Callbacks
1450: 20 72 65 63 65 69 76 65 20 61 20 73 69 6e 67 6c   receive a singl
1460: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
1470: 20 68 6f 6c 64 73 20 61 6c 6c 20 73 6f 72 74 73   holds all sorts
1480: 20 6f 66 20 73 74 61 74 65 20 61 62 6f 75 74 20   of state about 
1490: 74 68 65 20 63 61 6c 6c 2c 20 69 6e 63 6c 75 64  the call, includ
14a0: 69 6e 67 20 74 68 65 20 61 72 67 75 6d 65 6e 74  ing the argument
14b0: 73 20 6c 69 73 74 20 28 6f 66 20 63 6f 75 72 73  s list (of cours
14c0: 65 29 2c 20 74 68 65 20 63 75 72 72 65 6e 74 20  e), the current 
14d0: 73 63 6f 70 65 20 28 66 6f 72 20 66 65 74 63 68  scope (for fetch
14e0: 69 6e 67 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  ing named parame
14f0: 74 65 72 73 29 2c 20 74 68 65 20 22 63 61 6c 6c  ters), the "call
1500: 65 65 22 20 68 61 6e 64 6c 65 2c 20 61 20 22 74  ee" handle, a "t
1510: 68 69 73 20 6f 62 6a 65 63 74 22 20 76 61 6c 75  his object" valu
1520: 65 2c 20 61 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c  e, and optionall
1530: 79 20 61 72 62 69 74 72 61 72 79 20 73 74 61 74  y arbitrary stat
1540: 65 20 28 61 20 76 6f 69 64 20 70 6f 69 6e 74 65  e (a void pointe
1550: 72 29 20 77 68 69 63 68 20 63 61 6e 20 62 65 20  r) which can be 
1560: 61 73 73 69 67 6e 65 64 20 62 79 20 74 68 65 20  assigned by the 
1570: 63 6c 69 65 6e 74 20 77 68 65 6e 20 74 68 65 20  client when the 
1580: 46 75 6e 63 74 69 6f 6e 20 76 61 6c 75 65 20 69  Function value i
1590: 73 20 63 72 65 61 74 65 64 20 28 61 6c 6f 6e 67  s created (along
15a0: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61   with an optiona
15b0: 6c 20 66 69 6e 61 6c 69 7a 65 72 20 66 75 6e 63  l finalizer func
15c0: 74 69 6f 6e 20 74 6f 20 63 6c 65 61 6e 20 69 74  tion to clean it
15d0: 20 75 70 20 77 68 65 6e 20 74 68 65 20 46 75 6e   up when the Fun
15e0: 63 74 69 6f 6e 20 56 61 6c 75 65 20 69 73 20 66  ction Value is f
15f0: 69 6e 61 6c 69 7a 65 64 29 2e 0d 0a 0d 0a 4e 6f  inalized).....No
1600: 74 65 20 74 68 61 74 20 46 75 6e 63 74 69 6f 6e  te that Function
1610: 73 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 6b 65  s may contain ke
1620: 79 2f 76 61 6c 75 65 20 70 61 69 72 73 2c 20 6a  y/value pairs, j
1630: 75 73 74 20 6c 69 6b 65 20 4f 62 6a 65 63 74 73  ust like Objects
1640: 20 63 61 6e 2e 0d 0a 0d 0a 69 20 3c 65 6d 3e 64   can.....i <em>d
1650: 6f 20 6e 6f 74 20 74 68 69 6e 6b 3c 2f 65 6d 3e  o not think</em>
1660: 20 74 68 61 74 20 74 68 65 20 63 75 72 72 65 6e   that the curren
1670: 74 20 63 77 61 6c 20 63 6f 64 65 20 63 61 6e 20  t cwal code can 
1680: 68 61 6e 64 6c 65 20 74 72 75 65 20 63 6c 6f 73  handle true clos
1690: 75 72 65 73 2c 20 62 75 74 20 63 6c 6f 73 75 72  ures, but closur
16a0: 65 2d 6c 69 6b 65 20 62 65 68 61 76 69 6f 75 72  e-like behaviour
16b0: 20 22 73 68 6f 75 6c 64 20 77 6f 72 6b 22 20 28   "should work" (
16c0: 69 6e 20 74 68 65 20 73 65 6e 73 65 20 74 68 61  in the sense tha
16d0: 74 20 73 75 63 68 20 63 6c 6f 73 75 72 65 73 20  t such closures 
16e0: 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74  should be able t
16f0: 6f 20 72 65 66 65 72 65 6e 63 65 20 76 61 72 69  o reference vari
1700: 61 62 6c 65 73 20 64 65 66 69 6e 65 64 20 69 6e  ables defined in
1710: 20 6c 6f 77 65 72 20 73 63 6f 70 65 73 29 20 61   lower scopes) a
1720: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 46 75  s long as the Fu
1730: 6e 63 74 69 6f 6e 20 76 61 6c 75 65 20 64 6f 65  nction value doe
1740: 73 20 6e 6f 74 20 77 61 6e 64 65 72 20 64 6f 77  s not wander dow
1750: 6e 20 74 68 65 20 73 63 6f 70 65 20 63 68 61 69  n the scope chai
1760: 6e 2e 20 46 75 6e 63 74 69 6f 6e 73 20 77 68 69  n. Functions whi
1770: 63 68 20 61 72 65 20 73 65 6c 66 2d 63 6f 6e 74  ch are self-cont
1780: 61 69 6e 65 64 20 61 6e 64 20 64 6f 20 6e 6f 74  ained and do not
1790: 20 72 65 6c 79 20 6f 6e 20 76 61 72 69 61 62 6c   rely on variabl
17a0: 65 73 20 66 72 6f 6d 20 6c 6f 77 65 72 20 73 63  es from lower sc
17b0: 6f 70 65 73 20 22 73 68 6f 75 6c 64 22 20 77 6f  opes "should" wo
17c0: 72 6b 20 6a 75 73 74 20 66 69 6e 65 20 76 69 73  rk just fine vis
17d0: 2d 61 2d 76 69 73 20 73 63 6f 70 69 6e 67 2f 6f  -a-vis scoping/o
17e0: 77 6e 65 72 73 68 69 70 2f 6c 69 66 65 74 69 6d  wnership/lifetim
17f0: 65 73 2e 20 49 6e 20 61 6e 79 20 63 61 73 65 2c  es. In any case,
1800: 20 66 75 6c 6c 20 73 75 70 70 6f 72 74 20 66 6f   full support fo
1810: 72 20 63 6c 6f 73 75 72 65 73 20 69 73 20 6e 6f  r closures is no
1820: 74 20 6f 6e 20 74 68 65 20 6c 69 73 74 20 6f 66  t on the list of
1830: 20 54 4f 44 4f 73 20 28 69 74 20 77 6f 75 6c 64   TODOs (it would
1840: 20 62 65 20 69 6e 74 65 72 65 73 74 69 6e 67 2c   be interesting,
1850: 20 62 75 74 20 69 73 20 6e 6f 74 20 61 20 72 65   but is not a re
1860: 71 75 69 72 65 64 20 66 65 61 74 75 72 65 29 2e  quired feature).
1870: 0d 0a 0d 0a 45 78 61 6d 70 6c 65 20 75 73 61 67  ....Example usag
1880: 65 73 3a 0d 0a 0d 0a 3c 6e 6f 77 69 6b 69 3e 3c  es:....<nowiki><
1890: 70 72 65 3e 54 4f 44 4f 0d 0a 3c 2f 70 72 65 3e  pre>TODO..</pre>
18a0: 3c 2f 6e 6f 77 69 6b 69 3e 0d 0a 0d 0a 0d 0a 3c  </nowiki>......<
18b0: 68 31 3e 42 75 66 66 65 72 73 3c 2f 68 31 3e 0d  h1>Buffers</h1>.
18c0: 0a 0d 0a 42 75 66 66 65 72 73 20 77 72 61 70 20  ...Buffers wrap 
18d0: 75 70 20 74 68 65 20 3c 74 74 3e 63 77 61 6c 5f  up the <tt>cwal_
18e0: 62 75 66 66 65 72 3c 2f 74 74 3e 20 63 6c 61 73  buffer</tt> clas
18f0: 73 20 28 61 20 67 65 6e 65 72 69 63 20 6d 65 6d  s (a generic mem
1900: 6f 72 79 20 62 75 66 66 65 72 29 20 69 6e 20 61  ory buffer) in a
1910: 20 56 61 6c 75 65 20 68 61 6e 64 6c 65 2c 20 6d   Value handle, m
1920: 61 6b 69 6e 67 20 74 68 65 6d 20 61 76 61 69 6c  aking them avail
1930: 61 62 6c 65 20 66 6f 72 20 73 63 72 69 70 74 20  able for script 
1940: 63 6f 64 65 2e 20 54 68 69 73 20 63 6c 61 73 73  code. This class
1950: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
1960: 62 65 20 75 73 65 64 20 61 73 20 61 20 67 65 6e  be used as a gen
1970: 65 72 61 6c 2d 70 75 72 70 6f 73 65 20 62 79 74  eral-purpose byt
1980: 65 20 61 72 72 61 79 2e 20 4e 6f 74 65 20 74 68  e array. Note th
1990: 61 74 20 74 68 69 73 20 66 65 61 74 75 72 65 20  at this feature 
19a0: 63 6f 75 6c 64 20 61 6c 73 6f 20 62 65 20 69 6d  could also be im
19b0: 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 74 65 72  plemented in ter
19c0: 6d 73 20 6f 66 20 74 68 65 20 22 6e 61 74 69 76  ms of the "nativ
19d0: 65 22 20 73 75 70 70 6f 72 74 20 28 73 65 65 20  e" support (see 
19e0: 62 65 6c 6f 77 29 2c 20 62 75 74 20 69 20 77 61  below), but i wa
19f0: 6e 74 65 64 20 61 20 63 6f 6e 63 72 65 74 65 20  nted a concrete 
1a00: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
1a10: 6f 72 20 73 6f 6d 65 20 70 61 72 74 69 63 75 6c  or some particul
1a20: 61 72 20 73 63 72 69 70 74 69 6e 67 20 69 64 65  ar scripting ide
1a30: 61 73 20 69 20 77 6f 75 6c 64 20 6c 69 6b 65 20  as i would like 
1a40: 74 6f 20 70 6c 61 79 20 77 69 74 68 2e 0d 0a 0d  to play with....
1a50: 0a 45 78 61 6d 70 6c 65 20 75 73 61 67 65 73 3a  .Example usages:
1a60: 0d 0a 0d 0a 3c 6e 6f 77 69 6b 69 3e 3c 70 72 65  ....<nowiki><pre
1a70: 3e 54 4f 44 4f 0d 0a 3c 2f 70 72 65 3e 3c 2f 6e  >TODO..</pre></n
1a80: 6f 77 69 6b 69 3e 0d 0a 0d 0a 3c 68 31 3e 4e 61  owiki>....<h1>Na
1a90: 74 69 76 65 73 3c 2f 68 31 3e 0d 0a 0d 0a 22 4e  tives</h1>...."N
1aa0: 61 74 69 76 65 22 20 69 73 20 74 68 65 20 67 65  ative" is the ge
1ab0: 6e 65 72 69 63 20 74 65 72 6d 20 66 6f 72 20 61  neric term for a
1ac0: 20 43 2f 43 2b 2b 2d 6c 65 76 65 6c 20 76 61 6c   C/C++-level val
1ad0: 75 65 20 77 68 69 63 68 20 69 73 20 77 72 61 70  ue which is wrap
1ae0: 70 65 64 20 75 70 20 62 65 68 69 6e 64 20 61 20  ped up behind a 
1af0: 56 61 6c 75 65 20 68 61 6e 64 6c 65 2e 20 63 77  Value handle. cw
1b00: 61 6c 20 22 62 69 6e 64 73 22 20 61 20 6e 61 74  al "binds" a nat
1b10: 69 76 65 20 68 61 6e 64 6c 65 20 74 6f 20 61 20  ive handle to a 
1b20: 56 61 6c 75 65 20 75 73 69 6e 67 20 74 68 65 20  Value using the 
1b30: 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 66 6f 72 6d  following inform
1b40: 61 74 69 6f 6e 20 28 61 6c 6c 20 70 72 6f 76 69  ation (all provi
1b50: 64 65 64 20 62 79 20 74 68 65 20 63 6c 69 65 6e  ded by the clien
1b60: 74 29 3a 0d 0a 0d 0a 20 20 20 2a 20 20 41 20 76  t):....   *  A v
1b70: 6f 69 64 20 70 6f 69 6e 74 65 72 20 72 65 70 72  oid pointer repr
1b80: 65 73 65 6e 74 69 6e 67 20 74 68 65 20 6e 61 74  esenting the nat
1b90: 69 76 65 20 76 61 6c 75 65 20 28 65 2e 67 2e 20  ive value (e.g. 
1ba0: 61 20 43 20 73 74 72 75 63 74 29 2e 0d 0a 20 20  a C struct)...  
1bb0: 20 2a 20 20 41 20 63 6f 6e 73 74 20 76 6f 69 64   *  A const void
1bc0: 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 61   pointer which a
1bd0: 63 74 73 20 61 73 20 61 20 74 79 70 65 20 69 64  cts as a type id
1be0: 65 6e 74 69 66 69 65 72 2e 20 54 68 69 73 20 63  entifier. This c
1bf0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 65 6e  an be used to en
1c00: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 63 6c  sure that the cl
1c10: 69 65 6e 74 20 69 73 20 64 65 61 6c 69 6e 67 20  ient is dealing 
1c20: 77 69 74 68 20 74 68 65 20 65 78 70 65 63 74 65  with the expecte
1c30: 64 20 74 79 70 65 20 6f 66 20 70 6f 69 6e 74 65  d type of pointe
1c40: 72 20 64 6f 77 6e 2d 73 74 72 65 61 6d 2e 20 69  r down-stream. i
1c50: 2e 65 2e 20 69 74 20 70 72 6f 76 69 64 65 73 20  .e. it provides 
1c60: 61 20 74 79 70 65 2d 73 61 66 65 74 79 20 6d 65  a type-safety me
1c70: 63 68 61 6e 69 73 6d 20 66 6f 72 20 74 68 65 20  chanism for the 
1c80: 6f 74 68 65 72 77 69 73 65 20 63 6f 6d 70 6c 65  otherwise comple
1c90: 74 65 6c 79 20 6f 70 61 71 75 65 20 76 6f 69 64  tely opaque void
1ca0: 20 70 6f 69 6e 74 65 72 2e 0d 0a 20 20 20 2a 20   pointer...   * 
1cb0: 20 41 6e 20 6f 70 74 69 6f 6e 61 6c 20 66 69 6e   An optional fin
1cc0: 61 6c 69 7a 65 72 20 66 75 6e 63 74 69 6f 6e 20  alizer function 
1cd0: 77 68 69 63 68 20 63 6c 65 61 6e 73 20 75 70 20  which cleans up 
1ce0: 74 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74  the native point
1cf0: 65 72 20 77 68 65 6e 20 74 68 65 20 56 61 6c 75  er when the Valu
1d00: 65 20 68 61 6e 64 6c 65 20 69 73 20 66 69 6e 61  e handle is fina
1d10: 6c 69 7a 65 64 2e 0d 0a 0d 0a 49 6e 20 70 72 69  lized.....In pri
1d20: 6e 63 69 70 61 6c 2c 20 61 6e 79 20 74 79 70 65  ncipal, any type
1d30: 20 77 68 69 63 68 20 63 61 6e 20 62 65 20 70 61   which can be pa
1d40: 73 73 65 64 20 61 72 6f 75 6e 64 20 61 73 20 61  ssed around as a
1d50: 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 63 61   void pointer ca
1d60: 6e 20 62 65 20 77 72 61 70 70 65 64 20 75 70 20  n be wrapped up 
1d70: 69 6e 20 61 20 4e 61 74 69 76 65 20 56 61 6c 75  in a Native Valu
1d80: 65 2e 0d 0a 0d 0a 4e 6f 74 65 20 74 68 61 74 20  e.....Note that 
1d90: 4e 61 74 69 76 65 73 20 6d 61 79 20 63 6f 6e 74  Natives may cont
1da0: 61 69 6e 20 6b 65 79 2f 76 61 6c 75 65 20 70 61  ain key/value pa
1db0: 69 72 73 2c 20 6a 75 73 74 20 6c 69 6b 65 20 4f  irs, just like O
1dc0: 62 6a 65 63 74 73 20 63 61 6e 2e 0d 0a 0d 0a 45  bjects can.....E
1dd0: 78 61 6d 70 6c 65 20 75 73 61 67 65 3a 0d 0a 0d  xample usage:...
1de0: 0a 3c 6e 6f 77 69 6b 69 3e 3c 70 72 65 3e 0d 0a  .<nowiki><pre>..
1df0: 2f 2a 20 54 68 65 20 6e 61 74 69 76 65 20 74 79  /* The native ty
1e00: 70 65 20 77 65 20 77 61 6e 74 20 74 6f 20 77 72  pe we want to wr
1e10: 61 70 2e 2e 2e 20 2a 2f 0d 0a 74 79 70 65 64 65  ap... */..typede
1e20: 66 20 73 74 72 75 63 74 20 4e 61 74 69 76 65 54  f struct NativeT
1e30: 79 70 65 20 4e 61 74 69 76 65 54 79 70 65 3b 0d  ype NativeType;.
1e40: 0a 73 74 72 75 63 74 20 4e 61 74 69 76 65 54 79  .struct NativeTy
1e50: 70 65 20 7b 0d 0a 20 20 20 20 69 6e 74 20 78 3b  pe {..    int x;
1e60: 0d 0a 20 20 20 20 69 6e 74 20 79 3b 0d 0a 7d 3b  ..    int y;..};
1e70: 0d 0a 0d 0a 2f 2a 20 57 65 20 75 73 65 20 4e 61  ..../* We use Na
1e80: 74 69 76 65 54 79 70 65 5f 65 6d 70 74 79 20 61  tiveType_empty a
1e90: 73 20 61 20 5f 74 79 70 65 20 69 64 65 6e 74 69  s a _type identi
1ea0: 66 69 65 72 5f 2e 20 2a 2f 0d 0a 73 74 61 74 69  fier_. */..stati
1eb0: 63 20 63 6f 6e 73 74 20 4e 61 74 69 76 65 54 79  c const NativeTy
1ec0: 70 65 20 4e 61 74 69 76 65 54 79 70 65 5f 65 6d  pe NativeType_em
1ed0: 70 74 79 20 3d 20 7b 30 2c 30 7d 3b 0d 0a 0d 0a  pty = {0,0};....
1ee0: 2f 2a 20 41 20 66 69 6e 61 6c 69 7a 65 72 20 66  /* A finalizer f
1ef0: 75 6e 63 74 69 6f 6e 20 66 6f 72 20 4e 61 74 69  unction for Nati
1f00: 76 65 54 79 70 65 20 76 61 6c 75 65 73 2e 2e 2e  veType values...
1f10: 20 2a 2f 0d 0a 73 74 61 74 69 63 20 76 6f 69 64   */..static void
1f20: 20 66 69 6e 61 6c 69 7a 65 72 5f 4e 61 74 69 76   finalizer_Nativ
1f30: 65 54 79 70 65 28 20 63 77 61 6c 5f 65 6e 67 69  eType( cwal_engi
1f40: 6e 65 20 2a 20 65 2c 20 76 6f 69 64 20 2a 20 56  ne * e, void * V
1f50: 20 29 7b 0d 0a 20 20 20 20 4e 61 74 69 76 65 54   ){..    NativeT
1f60: 79 70 65 20 2a 20 6e 20 3d 20 28 4e 61 74 69 76  ype * n = (Nativ
1f70: 65 54 79 70 65 2a 29 56 3b 0d 0a 20 20 20 20 70  eType*)V;..    p
1f80: 72 69 6e 74 66 28 22 46 72 65 65 69 6e 67 20 4e  rintf("Freeing N
1f90: 61 74 69 76 65 54 79 70 65 40 25 70 20 78 3d 25  ativeType@%p x=%
1fa0: 64 20 79 3d 25 64 5c 6e 22 2c 20 56 2c 20 6e 2d  d y=%d\n", V, n-
1fb0: 3e 78 2c 20 6e 2d 3e 79 29 3b 0d 0a 20 20 20 20  >x, n->y);..    
1fc0: 63 77 61 6c 5f 66 72 65 65 28 65 2c 20 56 29 3b  cwal_free(e, V);
1fd0: 0d 0a 7d 0d 0a 2f 2a 20 45 78 61 6d 70 6c 65 20  ..}../* Example 
1fe0: 77 72 61 70 70 65 72 20 77 68 69 63 68 20 63 72  wrapper which cr
1ff0: 65 61 74 65 73 20 61 20 6e 65 77 20 4e 61 74 69  eates a new Nati
2000: 76 65 20 76 61 6c 75 65 20 61 6e 64 20 72 75 6e  ve value and run
2010: 73 0d 0a 20 20 20 73 6f 6d 65 20 73 61 6e 69 74  s..   some sanit
2020: 79 20 63 68 65 63 6b 73 20 28 77 68 69 63 68 20  y checks (which 
2030: 63 6c 69 65 6e 74 73 20 77 6f 6e 27 74 20 6e 65  clients won't ne
2040: 65 64 20 74 6f 20 64 6f 20 2d 20 74 68 69 73 20  ed to do - this 
2050: 63 6f 64 65 0d 0a 20 20 20 69 73 20 74 61 6b 65  code..   is take
2060: 6e 20 66 72 6f 6d 20 63 77 61 6c 20 6c 69 62 2d  n from cwal lib-
2070: 6c 65 76 65 6c 20 74 65 73 74 73 29 2e 2e 2e 0d  level tests)....
2080: 0a 2a 2f 0d 0a 63 77 61 6c 5f 6e 61 74 69 76 65  .*/..cwal_native
2090: 20 2a 20 6e 65 77 5f 6e 61 74 69 76 65 28 63 77   * new_native(cw
20a0: 61 6c 5f 65 6e 67 69 6e 65 20 2a 20 65 29 7b 0d  al_engine * e){.
20b0: 0a 20 20 20 20 63 77 61 6c 5f 6e 61 74 69 76 65  .    cwal_native
20c0: 20 2a 20 6e 3b 0d 0a 20 20 20 20 63 77 61 6c 5f   * n;..    cwal_
20d0: 76 61 6c 75 65 20 2a 20 76 3b 0d 0a 20 20 20 20  value * v;..    
20e0: 76 6f 69 64 20 2a 20 70 43 68 65 63 6b 20 3d 20  void * pCheck = 
20f0: 4e 55 4c 4c 3b 0d 0a 20 20 20 20 4e 61 74 69 76  NULL;..    Nativ
2100: 65 54 79 70 65 20 2a 20 66 6f 6f 3b 0d 0a 20 20  eType * foo;..  
2110: 20 20 69 6e 74 20 72 63 3b 0d 0a 20 20 20 20 66    int rc;..    f
2120: 6f 6f 20 3d 20 63 77 61 6c 5f 6d 61 6c 6c 6f 63  oo = cwal_malloc
2130: 28 65 2c 20 73 69 7a 65 6f 66 28 4e 61 74 69 76  (e, sizeof(Nativ
2140: 65 54 79 70 65 29 29 3b 0d 0a 20 20 20 20 66 6f  eType));..    fo
2150: 6f 2d 3e 78 20 3d 20 33 3b 20 66 6f 6f 2d 3e 79  o->x = 3; foo->y
2160: 20 3d 20 37 3b 0d 0a 20 20 20 20 6e 20 3d 20 63   = 7;..    n = c
2170: 77 61 6c 5f 6e 65 77 5f 6e 61 74 69 76 65 28 20  wal_new_native( 
2180: 65 2c 20 66 6f 6f 2c 20 66 69 6e 61 6c 69 7a 65  e, foo, finalize
2190: 72 5f 4e 61 74 69 76 65 54 79 70 65 2c 20 26 4e  r_NativeType, &N
21a0: 61 74 69 76 65 54 79 70 65 5f 65 6d 70 74 79 20  ativeType_empty 
21b0: 29 3b 0d 0a 20 20 20 20 61 73 73 65 72 74 28 6e  );..    assert(n
21c0: 29 3b 0d 0a 20 20 20 20 76 20 3d 20 63 77 61 6c  );..    v = cwal
21d0: 5f 6e 61 74 69 76 65 5f 76 61 6c 75 65 28 6e 29  _native_value(n)
21e0: 3b 0d 0a 20 20 20 20 61 73 73 65 72 74 28 76 29  ;..    assert(v)
21f0: 3b 0d 0a 20 20 20 20 61 73 73 65 72 74 28 6e 20  ;..    assert(n 
2200: 3d 3d 20 63 77 61 6c 5f 76 61 6c 75 65 5f 67 65  == cwal_value_ge
2210: 74 5f 6e 61 74 69 76 65 28 76 29 29 3b 0d 0a 20  t_native(v));.. 
2220: 20 20 20 61 73 73 65 72 74 28 20 43 57 41 4c 5f     assert( CWAL_
2230: 54 59 50 45 5f 4e 41 54 49 56 45 20 3d 3d 20 63  TYPE_NATIVE == c
2240: 77 61 6c 5f 76 61 6c 75 65 5f 74 79 70 65 5f 69  wal_value_type_i
2250: 64 28 76 29 20 29 3b 0d 0a 20 20 20 20 61 73 73  d(v) );..    ass
2260: 65 72 74 28 30 20 3d 3d 20 63 77 61 6c 5f 6e 61  ert(0 == cwal_na
2270: 74 69 76 65 5f 67 65 74 28 6e 2c 20 22 22 29 29  tive_get(n, ""))
2280: 3b 0d 0a 20 20 20 20 72 63 20 3d 20 63 77 61 6c  ;..    rc = cwal
2290: 5f 6e 61 74 69 76 65 5f 66 65 74 63 68 28 6e 2c  _native_fetch(n,
22a0: 20 26 4e 61 74 69 76 65 54 79 70 65 5f 65 6d 70   &NativeType_emp
22b0: 74 79 2c 20 26 70 43 68 65 63 6b 29 3b 0d 0a 20  ty, &pCheck);.. 
22c0: 20 20 20 61 73 73 65 72 74 28 30 3d 3d 72 63 29     assert(0==rc)
22d0: 3b 0d 0a 20 20 20 20 61 73 73 65 72 74 28 70 43  ;..    assert(pC
22e0: 68 65 63 6b 20 3d 3d 20 66 6f 6f 29 3b 0d 0a 20  heck == foo);.. 
22f0: 20 20 20 61 73 73 65 72 74 28 66 6f 6f 20 3d 3d     assert(foo ==
2300: 20 63 77 61 6c 5f 6e 61 74 69 76 65 5f 67 65 74   cwal_native_get
2310: 28 6e 2c 20 26 4e 61 74 69 76 65 54 79 70 65 5f  (n, &NativeType_
2320: 65 6d 70 74 79 29 29 3b 0d 0a 20 20 20 20 72 65  empty));..    re
2330: 74 75 72 6e 20 6e 3b 0d 0a 7d 0d 0a 0d 0a 3c 2f  turn n;..}....</
2340: 70 72 65 3e 3c 2f 6e 6f 77 69 6b 69 3e 0d 0a 0d  pre></nowiki>...
2350: 0a 3c 68 31 3e 45 78 63 65 70 74 69 6f 6e 3c 2f  .<h1>Exception</
2360: 68 31 3e 0d 0a 0d 0a 54 68 65 20 45 78 63 65 70  h1>....The Excep
2370: 74 69 6f 6e 20 63 6c 61 73 73 20 28 3c 74 74 3e  tion class (<tt>
2380: 63 77 61 6c 5f 65 78 63 65 70 74 69 6f 6e 3c 2f  cwal_exception</
2390: 74 74 3e 29 20 69 73 20 69 6e 74 65 6e 64 65 64  tt>) is intended
23a0: 20 74 6f 20 62 65 20 75 73 65 64 20 61 73 20 61   to be used as a
23b0: 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 2f 65   generic error/e
23c0: 78 63 65 70 74 69 6f 6e 20 72 65 70 6f 72 74 69  xception reporti
23d0: 6e 67 20 6d 65 63 68 61 6e 69 73 6d 2e 20 45 61  ng mechanism. Ea
23e0: 63 68 20 65 78 63 65 70 74 69 6f 6e 20 69 6e 73  ch exception ins
23f0: 74 61 6e 63 65 20 68 61 73 20 61 6e 20 61 73 73  tance has an ass
2400: 6f 63 69 61 74 65 64 20 69 6e 74 65 67 65 72 20  ociated integer 
2410: 63 6f 64 65 20 61 6e 64 20 6f 70 74 69 6f 6e 61  code and optiona
2420: 6c 20 6d 65 73 73 61 67 65 20 76 61 6c 75 65 20  l message value 
2430: 28 61 6e 20 61 72 62 69 74 72 61 72 79 20 76 61  (an arbitrary va
2440: 6c 75 65 29 2c 20 74 68 65 20 69 6e 74 65 72 70  lue), the interp
2450: 72 65 74 61 74 69 6f 6e 20 6f 66 20 62 6f 74 68  retation of both
2460: 20 6f 66 20 77 68 69 63 68 20 69 73 20 75 70 20   of which is up 
2470: 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 2e 20 54  to the client. T
2480: 68 65 79 20 63 61 6e 20 61 6c 73 6f 20 63 6f 6e  hey can also con
2490: 74 61 69 6e 20 6b 65 79 2f 76 61 6c 75 65 20 70  tain key/value p
24a0: 72 6f 70 65 72 74 69 65 73 20 28 65 2e 67 2e 20  roperties (e.g. 
24b0: 74 68 61 74 27 73 20 77 68 65 72 65 20 73 74 61  that's where sta
24c0: 63 6b 20 74 72 61 63 65 20 69 6e 66 6f 20 63 6f  ck trace info co
24d0: 75 6c 64 20 67 6f 29 2e 0d 0a 0d 0a 54 68 65 20  uld go).....The 
24e0: 65 6e 67 69 6e 65 20 70 72 6f 76 69 64 65 73 20  engine provides 
24f0: 69 6e 74 65 72 6e 61 6c 20 73 75 70 70 6f 72 74  internal support
2500: 20 66 6f 72 20 68 61 6e 64 6c 69 6e 67 20 61 20   for handling a 
2510: 73 69 6e 67 6c 65 20 22 70 72 6f 70 61 67 61 74  single "propagat
2520: 69 6e 67 22 20 65 78 63 65 70 74 69 6f 6e 20 76  ing" exception v
2530: 61 6c 75 65 2c 20 70 72 6f 70 61 67 61 74 69 6e  alue, propagatin
2540: 67 20 69 74 20 64 6f 77 6e 20 74 68 65 20 73 63  g it down the sc
2550: 6f 70 65 20 73 74 61 63 6b 20 61 73 20 73 63 6f  ope stack as sco
2560: 70 65 73 20 61 72 65 20 70 75 73 68 65 64 2e 20  pes are pushed. 
2570: 54 68 69 73 20 69 73 20 69 6e 74 65 6e 64 65 64  This is intended
2580: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 63   to be used in c
2590: 6f 6e 6a 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  onjunction with 
25a0: 74 68 65 20 3c 74 74 3e 63 77 61 6c 5f 65 78 63  the <tt>cwal_exc
25b0: 65 70 74 69 6f 6e 5f 73 65 74 28 29 3c 2f 74 74  eption_set()</tt
25c0: 3e 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  > family of func
25d0: 74 69 6f 6e 73 20 61 6e 64 20 74 68 65 20 3c 74  tions and the <t
25e0: 74 3e 43 57 41 4c 5f 52 43 5f 45 58 43 45 50 54  t>CWAL_RC_EXCEPT
25f0: 49 4f 4e 3c 2f 74 74 3e 20 72 65 74 75 72 6e 20  ION</tt> return 
2600: 76 61 6c 75 65 2c 20 77 68 69 63 68 20 69 73 20  value, which is 
2610: 72 65 73 65 72 76 65 64 20 66 6f 72 20 73 69 67  reserved for sig
2620: 6e 61 6c 69 6e 67 20 74 68 61 74 20 61 6e 20 65  naling that an e
2630: 78 63 65 70 74 69 6f 6e 20 77 61 73 20 65 6e 63  xception was enc
2640: 6f 75 6e 74 65 72 65 64 2e 0d 0a 0d 0a 45 78 61  ountered.....Exa
2650: 6d 70 6c 65 20 75 73 61 67 65 73 3a 0d 0a 0d 0a  mple usages:....
2660: 3c 6e 6f 77 69 6b 69 3e 3c 70 72 65 3e 0d 0a 63  <nowiki><pre>..c
2670: 77 61 6c 5f 76 61 6c 75 65 20 2a 20 6d 73 67 20  wal_value * msg 
2680: 3d 20 63 77 61 6c 5f 6e 65 77 5f 73 74 72 69 6e  = cwal_new_strin
2690: 67 5f 76 61 6c 75 65 28 65 2c 20 22 41 61 72 72  g_value(e, "Aarr
26a0: 67 67 68 68 21 22 2c 20 30 29 3b 0d 0a 63 77 61  gghh!", 0);..cwa
26b0: 6c 5f 65 78 63 65 70 74 69 6f 6e 20 2a 20 78 20  l_exception * x 
26c0: 3d 20 63 77 61 6c 5f 6e 65 77 5f 65 78 63 65 70  = cwal_new_excep
26d0: 74 69 6f 6e 28 65 2c 20 34 32 2c 20 6d 73 67 20  tion(e, 42, msg 
26e0: 29 3b 0d 0a 69 6e 74 20 63 6f 64 65 20 3d 20 63  );..int code = c
26f0: 77 61 6c 5f 65 78 63 65 70 74 69 6f 6e 5f 63 6f  wal_exception_co
2700: 64 65 5f 67 65 74 28 78 29 3b 0d 0a 63 77 61 6c  de_get(x);..cwal
2710: 5f 76 61 6c 75 65 20 2a 20 78 56 20 3d 20 63 77  _value * xV = cw
2720: 61 6c 5f 65 78 63 65 70 74 69 6f 6e 5f 76 61 6c  al_exception_val
2730: 75 65 28 78 29 3b 0d 0a 61 73 73 65 72 74 28 34  ue(x);..assert(4
2740: 32 20 3d 3d 20 63 6f 64 65 29 3b 0d 0a 61 73 73  2 == code);..ass
2750: 65 72 74 28 6d 73 67 20 3d 3d 20 63 77 61 6c 5f  ert(msg == cwal_
2760: 65 78 63 65 70 74 69 6f 6e 5f 6d 65 73 73 61 67  exception_messag
2770: 65 5f 67 65 74 28 78 29 29 3b 0d 0a 61 73 73 65  e_get(x));..asse
2780: 72 74 28 63 77 61 6c 5f 76 61 6c 75 65 5f 67 65  rt(cwal_value_ge
2790: 74 5f 65 78 63 65 70 74 69 6f 6e 28 78 56 29 20  t_exception(xV) 
27a0: 3d 3d 20 78 29 3b 0d 0a 3c 2f 70 72 65 3e 3c 2f  == x);..</pre></
27b0: 6e 6f 77 69 6b 69 3e 0d 0a 0d 0a 4e 6f 74 65 20  nowiki>....Note 
27c0: 74 68 61 74 20 63 72 65 61 74 69 6e 67 20 61 20  that creating a 
27d0: 6e 65 77 20 65 78 63 65 70 74 69 6f 6e 20 6f 62  new exception ob
27e0: 6a 65 63 74 20 64 6f 65 73 20 6e 6f 74 20 22 74  ject does not "t
27f0: 68 72 6f 77 22 20 74 68 65 20 65 78 63 65 70 74  hrow" the except
2800: 69 6f 6e 2e 20 69 2e 65 2e 20 69 74 27 73 20 6a  ion. i.e. it's j
2810: 75 73 74 20 61 6e 6f 74 68 65 72 20 76 61 6c 75  ust another valu
2820: 65 20 77 68 69 63 68 20 67 65 74 73 20 6e 6f 20  e which gets no 
2830: 73 70 65 63 69 61 6c 20 74 72 65 61 74 6d 65 6e  special treatmen
2840: 74 2e 20 54 6f 20 22 74 68 72 6f 77 22 20 61 6e  t. To "throw" an
2850: 20 65 78 63 65 70 74 69 6f 6e 2c 20 70 61 73 73   exception, pass
2860: 20 74 68 65 20 65 78 63 65 70 74 69 6f 6e 20 74   the exception t
2870: 6f 20 3c 74 74 3e 63 77 61 6c 5f 65 78 63 65 70  o <tt>cwal_excep
2880: 74 69 6f 6e 5f 73 65 74 28 29 3c 2f 74 74 3e 20  tion_set()</tt> 
2890: 6f 72 20 75 73 65 20 6f 6e 65 20 6f 66 20 74 68  or use one of th
28a0: 65 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 72 6f  e convenience ro
28b0: 75 74 69 6e 65 73 2c 20 65 2e 67 2e 3a 0d 0a 0d  utines, e.g.:...
28c0: 0a 3c 6e 6f 77 69 6b 69 3e 3c 70 72 65 3e 0d 0a  .<nowiki><pre>..
28d0: 69 6e 74 20 72 63 20 3d 20 63 77 61 6c 5f 65 78  int rc = cwal_ex
28e0: 63 65 70 74 69 6f 6e 5f 73 65 74 66 28 20 65 2c  ception_setf( e,
28f0: 20 4d 79 45 72 72 6f 72 43 6f 64 65 2c 20 22 45   MyErrorCode, "E
2900: 72 72 6f 72 20 23 25 64 21 22 2c 20 4d 79 45 72  rror #%d!", MyEr
2910: 72 6f 72 43 6f 64 65 20 29 3b 0d 0a 61 73 73 65  rorCode );..asse
2920: 72 74 28 43 57 41 4c 5f 52 43 5f 45 58 43 45 50  rt(CWAL_RC_EXCEP
2930: 54 49 4f 4e 3d 3d 72 63 29 20 2f 2a 20 6f 6e 20  TION==rc) /* on 
2940: 73 75 63 63 65 73 73 21 20 2a 2f 3b 0d 0a 61 73  success! */;..as
2950: 73 65 72 74 28 4e 55 4c 4c 20 21 3d 20 63 77 61  sert(NULL != cwa
2960: 6c 5f 65 78 63 65 70 74 69 6f 6e 5f 67 65 74 28  l_exception_get(
2970: 65 29 29 3b 0d 0a 3c 2f 70 72 65 3e 3c 2f 6e 6f  e));..</pre></no
2980: 77 69 6b 69 3e 0d 0a 0d 0a 55 6e 6c 69 6b 65 20  wiki>....Unlike 
2990: 6d 6f 73 74 20 76 61 6c 75 65 73 2c 20 74 68 65  most values, the
29a0: 20 63 75 72 72 65 6e 74 6c 79 20 22 74 68 72 6f   currently "thro
29b0: 77 6e 22 20 65 78 63 65 70 74 69 6f 6e 20 69 73  wn" exception is
29c0: 20 6d 6f 76 65 64 20 75 70 20 74 68 65 20 73 63   moved up the sc
29d0: 6f 70 65 20 73 74 61 63 6b 20 61 73 20 65 78 63  ope stack as exc
29e0: 65 70 74 69 6f 6e 73 20 61 72 65 20 70 6f 70 70  eptions are popp
29f0: 65 64 2e 20 57 68 65 6e 20 74 68 65 20 6c 61 73  ed. When the las
2a00: 74 20 73 63 6f 70 65 20 69 73 20 70 6f 70 70 65  t scope is poppe
2a10: 64 2c 20 61 6e 79 20 72 65 6d 61 69 6e 69 6e 67  d, any remaining
2a20: 20 65 78 63 65 70 74 69 6f 6e 20 76 61 6c 75 65   exception value
2a30: 20 69 73 20 66 72 65 65 64 2e 0d 0a 0d 0a 44 65   is freed.....De
2a40: 73 69 67 6e 20 6e 6f 74 65 3a 20 74 68 65 72 65  sign note: there
2a50: 20 69 73 20 61 20 63 61 73 65 20 77 68 65 72 65   is a case where
2a60: 20 77 65 20 63 61 6e 20 73 74 72 61 6e 64 20 6d   we can strand m
2a70: 75 6c 74 69 70 6c 65 20 65 78 63 65 70 74 69 6f  ultiple exceptio
2a80: 6e 73 20 69 6e 20 61 20 73 63 6f 70 65 20 75 6e  ns in a scope un
2a90: 74 69 6c 20 74 68 61 74 20 73 63 6f 70 65 20 69  til that scope i
2aa0: 73 20 63 6c 65 61 6e 65 64 2c 20 62 75 74 20 28  s cleaned, but (
2ab0: 41 29 20 61 20 3c 74 74 3e 63 77 61 6c 5f 73 63  A) a <tt>cwal_sc
2ac0: 6f 70 65 5f 73 77 65 65 70 28 29 3c 2f 74 74 3e  ope_sweep()</tt>
2ad0: 20 77 69 6c 6c 20 63 6c 65 61 6e 20 74 68 65 6d   will clean them
2ae0: 20 75 70 20 61 6e 64 20 28 42 29 20 69 74 20 63   up and (B) it c
2af0: 61 6e 20 6f 6e 6c 79 20 68 61 70 70 65 6e 20 77  an only happen w
2b00: 68 65 6e 20 61 20 73 69 6e 67 6c 65 20 73 63 6f  hen a single sco
2b10: 70 65 20 6b 65 65 70 73 20 63 61 74 63 68 69 6e  pe keeps catchin
2b20: 67 20 65 78 63 65 70 74 69 6f 6e 73 20 61 6e 64  g exceptions and
2b30: 20 72 65 2d 73 65 74 74 69 6e 67 2f 63 6c 65 61   re-setting/clea
2b40: 72 69 6e 67 20 74 68 65 20 65 78 63 65 70 74 69  ring the excepti
2b50: 6f 6e 20 73 74 61 74 65 2e 20 57 68 65 6e 20 73  on state. When s
2b60: 65 74 74 69 6e 67 20 74 68 65 20 65 78 63 65 70  etting the excep
2b70: 74 69 6f 6e 20 73 74 61 74 65 20 77 65 20 28 75  tion state we (u
2b80: 6e 66 6f 72 74 75 6e 61 74 65 6c 79 29 20 63 61  nfortunately) ca
2b90: 6e 6e 6f 74 20 67 65 6e 65 72 69 63 61 6c 6c 79  nnot generically
2ba0: 20 75 6e 72 65 66 20 61 6e 79 20 70 72 65 76 69   unref any previ
2bb0: 6f 75 73 20 65 78 63 65 70 74 69 6f 6e 20 73 74  ous exception st
2bc0: 61 74 65 20 62 65 63 61 75 73 65 20 77 65 20 64  ate because we d
2bd0: 6f 20 6e 6f 74 20 28 63 61 6e 6e 6f 74 29 20 6b  o not (cannot) k
2be0: 6e 6f 77 20 69 66 20 61 6e 6f 74 68 65 72 20 6f  now if another o
2bf0: 62 6a 65 63 74 20 68 61 73 20 61 20 72 65 66 65  bject has a refe
2c00: 72 65 6e 63 65 20 74 6f 20 69 74 2c 20 6f 74 68  rence to it, oth
2c10: 65 72 20 74 68 61 6e 20 69 74 73 20 6f 77 6e 69  er than its owni
2c20: 6e 67 20 73 63 6f 70 65 2e 20 57 65 20 22 63 6f  ng scope. We "co
2c30: 75 6c 64 22 2e 2e 2e 20 6c 65 74 20 6d 65 20 67  uld"... let me g
2c40: 6f 20 74 72 79 20 74 68 61 74 2e 2e 2e 20 6e 6f  o try that... no
2c50: 70 65 2e 20 53 77 65 65 70 69 6e 67 20 69 73 20  pe. Sweeping is 
2c60: 74 68 65 20 63 75 72 72 65 6e 74 20 77 6f 72 6b  the current work
2c70: 61 72 6f 75 6e 64 20 66 6f 72 20 6c 6f 6e 67 2d  around for long-
2c80: 6c 69 76 65 64 2c 20 6d 61 6e 79 2d 63 61 74 63  lived, many-catc
2c90: 68 69 6e 67 20 73 63 6f 70 65 73 2e 0d 0a 0d 0a  hing scopes.....
2ca0: 0d 0a 3c 68 31 3e 48 61 73 68 20 54 61 62 6c 65  ..<h1>Hash Table
2cb0: 73 3c 2f 68 31 3e 0d 0a 0d 0a 48 61 73 68 65 73  s</h1>....Hashes
2cc0: 20 61 72 65 20 6f 62 6a 65 63 74 73 20 63 61 70   are objects cap
2cd0: 61 62 6c 65 20 6f 66 20 73 74 6f 72 69 6e 67 20  able of storing 
2ce0: 62 6f 74 68 20 22 6e 6f 72 6d 61 6c 22 20 70 72  both "normal" pr
2cf0: 6f 70 65 72 74 69 65 73 20 28 61 73 20 66 6f 72  operties (as for
2d00: 20 4f 62 6a 65 63 74 73 29 20 6f 72 20 68 61 73   Objects) or has
2d10: 68 65 64 20 70 72 6f 70 65 72 74 69 65 73 2c 20  hed properties, 
2d20: 77 69 74 68 20 61 6d 6f 72 74 69 7a 65 64 20 4f  with amortized O
2d30: 28 31 29 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  (1) performance 
2d40: 66 6f 72 20 61 6c 6c 20 68 61 73 68 20 61 6c 67  for all hash alg
2d50: 6f 72 69 74 68 6d 73 2e 20 54 68 65 79 20 63 6f  orithms. They co
2d60: 73 74 20 6e 6f 74 61 62 6c 79 20 6d 6f 72 65 20  st notably more 
2d70: 6d 65 6d 6f 72 79 20 74 68 61 6e 20 4f 62 6a 65  memory than Obje
2d80: 63 74 73 2c 20 62 75 74 20 66 6f 72 20 6c 61 72  cts, but for lar
2d90: 67 65 20 70 72 6f 70 65 72 74 79 20 73 65 74 73  ge property sets
2da0: 20 61 72 65 20 28 6f 6e 20 61 76 65 72 61 67 65   are (on average
2db0: 29 20 66 61 73 74 65 72 2e 20 55 6e 6c 69 6b 65  ) faster. Unlike
2dc0: 20 6f 62 6a 65 63 74 20 70 72 6f 70 65 72 74 69   object properti
2dd0: 65 73 2c 20 77 68 69 63 68 20 75 73 65 20 6e 6f  es, which use no
2de0: 6e 2d 73 74 72 69 63 74 20 65 71 75 69 76 61 6c  n-strict equival
2df0: 65 6e 63 65 20 63 6f 6d 70 61 72 69 73 6f 6e 73  ence comparisons
2e00: 20 28 65 2e 67 2e 20 74 68 65 20 69 6e 74 65 67   (e.g. the integ
2e10: 65 72 20 31 2c 20 64 6f 75 62 6c 65 20 31 2e 30  er 1, double 1.0
2e20: 2c 20 61 6e 64 20 73 74 72 69 6e 67 20 22 31 22  , and string "1"
2e30: 20 61 72 65 20 65 71 75 69 76 61 6c 65 6e 74 29   are equivalent)
2e40: 2c 20 68 61 73 68 65 73 20 75 73 65 20 74 79 70  , hashes use typ
2e50: 65 2d 73 74 72 69 63 74 20 63 6f 6d 70 61 72 69  e-strict compari
2e60: 73 6f 6e 73 20 28 73 6f 20 31 2c 20 31 2e 30 2c  sons (so 1, 1.0,
2e70: 20 61 6e 64 20 22 31 22 20 61 72 65 20 74 68 72   and "1" are thr
2e80: 65 65 20 64 69 73 74 69 6e 63 74 20 6b 65 79 73  ee distinct keys
2e90: 29 2e 0d 0a 0d 0a 45 78 61 6d 70 6c 65 20 75 73  ).....Example us
2ea0: 61 67 65 73 3a 0d 0a 0d 0a 3c 6e 6f 77 69 6b 69  ages:....<nowiki
2eb0: 3e 3c 70 72 65 3e 54 4f 44 4f 0d 0a 3c 2f 70 72  ><pre>TODO..</pr
2ec0: 65 3e 3c 2f 6e 6f 77 69 6b 69 3e 0d 0a 0a 5a 20  e></nowiki>...Z 
2ed0: 66 61 36 62 62 62 33 66 61 65 34 62 65 62 33 37  fa6bbb3fae4beb37
2ee0: 37 37 30 31 63 61 39 30 64 33 61 34 31 39 62 65  7701ca90d3a419be
2ef0: 0a                                               .