pike.git/ src/ operators.c

2018-05-19

2018-05-19 15:54:23 by Arne Goedeke <el@laramies.com>

• b912e94836f078e2b3b783a7c3f1f14ef118831f (46 lines) (+34/-12) ^{[ Show | Annotate ]}
  Branch: master

Documentation: corrected documentation on set operators

The operators |, &, - and ^ on arrays rely on the content having an
ordering which is compatible with `==. Mention this in the
documentation, as this will otherwise lead people to writte buggy
code.

2342:    *! occurrences, the leftmost is removed.    *! @type array|mapping|multiset    *! The result is like @[arg1] but without the elements/indices -  *! that match any in @[arg2] (according to @[`==] and, in the -  *! case of mappings, @[hash_value]). +  *! that match any in @[arg2] (according to @[`>], @[`<], @[`==] +  *! and, in the case of mappings, @[hash_value]).    *! @endmixed    *! The function is not destructive on the arguments - the result is    *! always a new instance.
2351:    *! @note    *! In Pike 7.0 and earlier the subtraction order was unspecified.    *! +  *! @note +  *! If this operator is used with arrays or multisets containing objects +  *! which implement @[lfun::`==()] but @b{not@} @[lfun::`>()] and +  *! @[lfun::`<()], the result will be undefined. +  *!    *! @seealso    *! @[`+()]    */
2723:    *! @type array|mapping|multiset    *! The result is like @[arg1] but only with the    *! elements/indices that match any in @[arg2] (according to -  *! @[`==] and, in the case of mappings, @[hash_value]). +  *! @[`>], @[`<], @[`==] and, in the case of mappings, +  *! @[hash_value]).    *! @type type|program    *! Type intersection of @[arg1] and @[arg2].    *! @endmixed    *! The function is not destructive on the arguments - the result is    *! always a new instance.    *! -  +  *! @note +  *! If this operator is used with arrays or multisets containing objects +  *! which implement @[lfun::`==()] but @b{not@} @[lfun::`>()] and +  *! @[lfun::`<()], the result will be undefined. +  *!    *! @seealso    *! @[`|()], @[lfun::`&()], @[lfun::``&()]    */
2954:    *! @type array    *! The result is an array with the elements in @[arg1]    *! concatenated with those in @[arg2] that doesn't occur in -  *! @[arg1] (according to @[`==]). The order between the -  *! elements that come from the same argument is kept. +  *! @[arg1] (according to @[`>], @[`<], @[`==]). The order +  *! between the elements that come from the same argument is kept.    *!    *! Every element in @[arg1] is only matched once against an    *! element in @[arg2], so if @[arg2] contains several elements
2969:    *! @type multiset    *! The result is like @[arg1] but extended with the entries in    *! @[arg2] that doesn't already occur in @[arg1] (according to -  *! @[`==]). Subsequences with orderwise equal entries (i.e. -  *! where @[`<] returns false) are handled just like the array -  *! case above. +  *! @[`>], @[`<] and @[`==]). Subsequences with orderwise equal +  *! entries (i.e. where @[`<] returns false) are handled just +  *! like the array case above.    *! @type type|program    *! Type union of @[arg1] and @[arg2].    *! @endmixed    *! The function is not destructive on the arguments - the result is    *! always a new instance.    *! -  +  *! @note +  *! If this operator is used with arrays or multisets containing objects +  *! which implement @[lfun::`==()] but @b{not@} @[lfun::`>()] and +  *! @[lfun::`<()], the result will be undefined. +  *!    *! @seealso    *! @[`&()], @[lfun::`|()], @[lfun::``|()]    */
3191:    *! @type array    *! The result is an array with the elements in @[arg1] that    *! doesn't occur in @[arg2] concatenated with those in @[arg2] -  *! that doesn't occur in @[arg1] (according to @[`==]). The -  *! order between the elements that come from the same argument -  *! is kept. +  *! that doesn't occur in @[arg1] (according to @[`>], @[`<] and +  *! @[`==]). The order between the elements that come from the +  *! same argument is kept.    *!    *! Every element is only matched once against an element in the    *! other array, so if one contains several elements that are
3206:    *! @type multiset    *! The result is like @[arg1] but with the entries from @[arg1]    *! and @[arg2] that are different between them (according to -  *! @[hash_value] and @[`==]). Subsequences with orderwise equal +  *! @[`>], @[`<] and @[`==]). Subsequences with orderwise equal    *! entries (i.e. where @[`<] returns false) are handled just    *! like the array case above.    *! @type type|program
3216:    *! The function is not destructive on the arguments - the result is    *! always a new instance.    *! +  *! @note +  *! If this operator is used with arrays or multisets containing objects +  *! which implement @[lfun::`==()] but @b{not@} @[lfun::`>()] and +  *! @[lfun::`<()], the result will be undefined. +  *!    *! @seealso    *! @[`&()], @[`|()], @[lfun::`^()], @[lfun::``^()]    */