From 53a373078d75544f05c3fb1eb6c6ee2d95282a08 Mon Sep 17 00:00:00 2001 From: Nicholas Browning Date: Thu, 20 Jul 2023 00:50:58 +0000 Subject: [PATCH] doc: initial operators commit docs: expand on operator documentaion Include more specific details around logical operators. doc: update link with proper syntax doc: remove ambiguous language from operators doc doc: remove link to source code file doc: cleaning up some language, and removing some mistakes in understanding doc: revert example to prior state doc: fix spacing doc: Update doc/syntax/operators.rdoc align example with typical format Co-authored-by: Nobuyoshi Nakada doc: Update doc/syntax/operators.rdoc align format of other examples with rest of documentation Co-authored-by: Nobuyoshi Nakada Update doc/syntax/operators.rdoc align format of other examples with rest of documentation Co-authored-by: Nobuyoshi Nakada doc: include `and` & `or` operators doc(operators): remove accute language --- doc/syntax.rdoc | 3 ++ doc/syntax/operators.rdoc | 75 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 78 insertions(+) create mode 100644 doc/syntax/operators.rdoc diff --git a/doc/syntax.rdoc b/doc/syntax.rdoc index 5895673f36a8f9..6ca58435126e4c 100644 --- a/doc/syntax.rdoc +++ b/doc/syntax.rdoc @@ -37,3 +37,6 @@ Miscellaneous[rdoc-ref:syntax/miscellaneous.rdoc] :: Comments[rdoc-ref:syntax/comments.rdoc] :: Line and block code comments + +Operators[rdoc-ref:syntax/operators.rdoc] :: + Operator method behaviors diff --git a/doc/syntax/operators.rdoc b/doc/syntax/operators.rdoc new file mode 100644 index 00000000000000..f972309412add9 --- /dev/null +++ b/doc/syntax/operators.rdoc @@ -0,0 +1,75 @@ += Operators + +In Ruby, operators such as +, are defined as methods on the class. +Literals[rdoc-ref:syntax/literals.rdoc] define their methods within the lower +level, C language. String class, for example. + +Ruby objects can define or overload their own implementation for most operators. + +Here is an example: + + class Foo < String + def +(str) + self.concat(str).concat("another string") + end + end + + foobar = Foo.new("test ") + puts foobar + "baz " + +This prints: + + test baz another string + +What operators are available is dependent on the implementing class. + +== Operator Behavior + +How a class behaves to a given operator is specific to that class, since +operators are method implementations. + +When using an operator, it's the expression on the left-hand side of the +operation that specifies the behavior. + + 'a' * 3 #=> "aaa" + 3 * 'a' # TypeError: String can't be coerced into Integer + +== Logical Operators + +Logical operators are not methods, and therefor cannot be +redefined/overloaded. They are tokenized at a lower level. + +Short-circuit logical operators (&&, ||, +and, and or) do not always result in a boolean value. +Similar to blocks, it's the last evaluated expression that defines the result +of the operation. + +=== &&, and + +Both &&/and operators provide short-circuiting by executing each +side of the operator, left to right, and stopping at the first occurence of a +falsey expression. The expression that defines the result is the last one +executed, whether it be the final expression, or the first occurence of a falsey +expression. + +Some examples: + + true && 9 && "string" #=> "string" + (1 + 2) && nil && "string" #=> nil + (a = 1) && (b = false) && (c = "string") #=> false + + puts a #=> 1 + puts b #=> false + puts c #=> nil + +In this last example, c was initialized, but not defined. + +=== ||, or + +The means by which ||/or short-circuits, is to return the result of +the first expression that is truthy. + +Some examples: + + (1 + 2) || true || "string" #=> 3 + false || nil || "string" #=> "string"