diff --git a/doc/script-reference/operators.rst b/doc/script-reference/operators.rst index 9442102b52..e9683f3e97 100644 --- a/doc/script-reference/operators.rst +++ b/doc/script-reference/operators.rst @@ -85,6 +85,25 @@ Arithmetic operators | | | of elements. | +------------------------------+-------------+-------------------------------+ +Bitwise operators +----------------- + +The bitwise operators work with operands of type :bro:type:`count` or +``vector of count``, but the bitwise complement operator works with ``count`` +only. + ++------------------------------+-------------+ +| Name | Syntax | ++==============================+=============+ +| Bitwise AND | *a* & *b* | ++------------------------------+-------------+ +| Bitwise OR | *a* | *b* | ++------------------------------+-------------+ +| Bitwise XOR | *a* ^ *b* | ++------------------------------+-------------+ +| Bitwise complement | ~ *a* | ++------------------------------+-------------+ + Assignment operators -------------------- @@ -122,6 +141,48 @@ field name must be in the declaration of the record type. +------------------------------+-------------+-------------------------------+ +Type casting +------------ + +The "as" operator performs type casting and the "is" operator checks if a +type cast is supported or not. For both operators, the first operand is a +value and the second operand is the name of a Bro script type (either built-in +or user-defined). + ++------------------------------+-------------+-------------------------------+ +| Name | Syntax | Notes | ++==============================+=============+===============================+ +| Type cast | *v* as *t* | Cast value "v" into type "t". | +| | | Evaluates to the value casted | +| | | to the specified type. | +| | | If this is not a supported | +| | | cast, then a runtime error is | +| | | triggered. | ++------------------------------+-------------+-------------------------------+ +| Check if a cast is supported | *v* is *t* | Evaluates to boolean. If true,| +| | | then "v as t" would succeed. | ++------------------------------+-------------+-------------------------------+ + +Only the following kinds of type casts are supported currently: + +- Broker values (i.e., values returned from functions such as + :bro:id:`Broker::data`) can be casted to their corresponding Bro script + types. +- A value of declared type "any" can be casted to its actual underlying type. +- All values can be casted to their declared types (i.e., this is a no-op). + +The function in this example tries to cast a value to a string:: + + function example(a: any) + { + local s: string; + + if ( a is string ) + s = (a as string); + + } + + Other operators --------------- diff --git a/doc/script-reference/statements.rst b/doc/script-reference/statements.rst index 963d4dc7a2..9e061d4df7 100644 --- a/doc/script-reference/statements.rst +++ b/doc/script-reference/statements.rst @@ -571,6 +571,42 @@ Here are the statements that the Bro scripting language supports. do not indicate the presence of a `compound statement`_), and that no semicolon is needed at the end of a "switch" statement. + There is an alternative form of the switch statement that supports + switching by type rather than value. This form of the switch statement + uses type-based versions of "case": + + - "case type t: ...": Take branch if the value of the switch expression + could be casted to type t (where "t" is the name of a Bro script type, + either built-in or user-defined). + + - "case type t as x: ...": Same as above, but the casted value is + available through ID "x". + + Multiple types can be listed per branch, separated by commas (the "type" + keyword must be repeated for each type in the list). + + Example:: + + function example(v: any) + { + switch (v) { + case type count as c: + print "It's a count", c; + break; + + case type bool, type addr: + print "It's a bool or address"; + break; + } + } + + Note that a single switch statement switches either by type or by value, + but not both. + + Also note that the type-based switch statement will trigger a runtime + error if any cast in any "case" is an unsupported cast (see the + documentation of the type casting operator "as"). + .. bro:keyword:: when