LangRef 2.5beta1 - a few suggestions /2

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

LangRef 2.5beta1 - a few suggestions /2

Aage Johansen


P.37   Common Language Elements

----------------------------------------

"This chapter covers the elements that are common
throughout the implementation of the SQL language
— the expressions that are used to extract and
operate on facts from data and the predicates
that test the truth of those facts."

Somehow I find it strange that a fact can be
false.  Thus, testing "the truth of those facts" is a strange expression.
Maybe it is just ok?


----------------------------------------


Table 4.1. Description of Expression Elements

Array element    An expression may contain a reference to an array element

Nitpicking:
This does not describe an "array element".
Also, "Context variable" in a like manner, and others.


Parenthesis    ... When embedded parenthesis ...

Maybe "When nested parenthesis" is better.


----------------------------------------

p.39   Number constants

For hexadecimal notation, isn't there something
about the sign that deserves mention here?
The example uses 0X08000000 - the first 0 after the X does serve some purpose.


----------------------------------------

p.40-41
Table 4.4. Comparison Operator Precedence

After the table:
"This group also includes comparison predicates
BETWEEN, LIKE, CONTAINING, SIMILAR TO and others."

Could something be said about the precedence of these?


----------------------------------------


p.43
"The returned result does do not have to be a
literal value: it might be a field or variable name, compound
expression or NULL literal."

Delete the word "do".



"A short form of the simple CASE construct is used in the DECODE function."

I was puzzled by this sttement - it has nothing
to do with the example that follows.  But
clicking on DECODE shows that it is indeed the case. (!)



"As with the simple CASE construct, the result
must not be a literal value: it might be a field
or variable name, a compound expression, or be NULL."

I would prefer "must not be" to be replaced with
"does not have to be" (as it is for the simple CASE).



----------------------------------------

p.51 (end of first paragraph):
A CONTAINING search is not case-sensitive.

Maybe a comment/warning on accent-sensitivity?


----------------------------------------


--
Aage J.


------------------------------------------------------------------------------
Transform Data into Opportunity.
Accelerate data analysis in your applications with
Intel Data Analytics Acceleration Library.
Click to learn more.
http://pubads.g.doubleclick.net/gampad/clk?id=278785231&iu=/4140
_______________________________________________
Firebird-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/firebird-docs
Reply | Threaded
Open this post in threaded view
|

Re: LangRef 2.5beta1 - a few suggestions /2

firebirdlists
Thursday, March 17, 2016, 12:23:40 AM, Aage wrote:


> p.39   Number constants

> For hexadecimal notation, isn't there something
> about the sign that deserves mention here?
> The example uses 0X08000000 - the first 0 after the X does serve some purpose.

Aage, do you know about that "something"?  If yes, would you write
about it?
> ----------------------------------------

> p.40-41
> Table 4.4. Comparison Operator Precedence

> After the table:
> "This group also includes comparison predicates
> BETWEEN, LIKE, CONTAINING, SIMILAR TO and others."

> Could something be said about the precedence of these?

Is there something to be said about it?  If you know of a precedence
for these predicates, would you write it up?  I have not heard of it.

> ----------------------------------------

> p.51 (end of first paragraph):
> A CONTAINING search is not case-sensitive.

> Maybe a comment/warning on accent-sensitivity?

I think you might be the first person involved with this text who has
day-to-day experience with data in a language with accented
characters.  What is there to say?

> ----------------------------------------

I've addressed these points to Aage because he raised them.  But
anyone who can answer, please chip in!

Helen


------------------------------------------------------------------------------
Transform Data into Opportunity.
Accelerate data analysis in your applications with
Intel Data Analytics Acceleration Library.
Click to learn more.
http://pubads.g.doubleclick.net/gampad/clk?id=278785351&iu=/4140
_______________________________________________
Firebird-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/firebird-docs
Reply | Threaded
Open this post in threaded view
|

Re: LangRef 2.5beta1 - a few suggestions /2

Paul Vinkenoog
Hi all,

> > p.39   Number constants
>
> > For hexadecimal notation, isn't there something
> > about the sign that deserves mention here?
> > The example uses 0X08000000 - the first 0 after the X does serve some purpose.
>
> Aage, do you know about that "something"?  If yes, would you write
> about it?

I think he's referring to this:

http://www.firebirdsql.org/file/documentation/reference_manuals/reference_material/html/langrefupd25-hexnumerals.html, especially the information under 'Value ranges'.

The line under Number Constants (in the LangRef beta):

  "For BIGINT numbers, hexadecimal notation is supported by Firebird 2.5 and higher versions, e.g., 0X080000000 as the hex representation of decimal 2147483648."

should be:

  "Hexadecimal notation is supported by Firebird 2.5 and higher versions. Numbers with 1-8 hex digits (e.g. 0x325708) are parsed as INTEGER values, numbers with 9-16 hex digits (e.g. 0x198723457237) as BIGINT."

More explanation about the value ranges and some pitfalls (see link above) can be given in Data Types and Subtypes :: Integer Data Types, before the start of the subsections.

Also (I should have caught this during reviewing), in Data Types and Subtypes :: Integer Data Types :: INTEGER, there should be a similar sentence as under BIGINT, explaining that you can pass INTEGERs in hex notation.

As for SMALLINT: Strictly speaking, you can't write a SMALLINT in hex notation, because even 0x1 is parsed as an INTEGER. But you can supply any value between 0 and 32767 in hex notation (0x0000 - 0x7FFF) wherever a SMALLINT is required and it will be converted automatically.

You can also pass negative smallint values, but that's trickier: you have to write them as 0xFFFF8000 (negative INTEGER -32768) through 0xFFFFFFFF (negative INTEGER -1). In a "true SMALLINT" hex notation, this would be 0x8000 - 0xFFFF.

Cheers,
Paul

------------------------------------------------------------------------------
Transform Data into Opportunity.
Accelerate data analysis in your applications with
Intel Data Analytics Acceleration Library.
Click to learn more.
http://pubads.g.doubleclick.net/gampad/clk?id=278785351&iu=/4140
_______________________________________________
Firebird-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/firebird-docs
Reply | Threaded
Open this post in threaded view
|

Re: LangRef 2.5beta1 - a few suggestions /2

Paul Vinkenoog
In reply to this post by firebirdlists
Hi Helen,

> > p.51 (end of first paragraph):
> > A CONTAINING search is not case-sensitive.
>
> > Maybe a comment/warning on accent-sensitivity?
>
> I think you might be the first person involved with this text who has
> day-to-day experience with data in a language with accented
> characters.  What is there to say?

Two short tests using iso8859_1 and utf8 reveal that CONTAINING is accent-sensitive, i.e.

  'ABCDEFG' containing 'DÉF'

is false, *unless* an accent-insensitive collation is used.

I assume it's the same with other character sets.


Cheers,
Paul

------------------------------------------------------------------------------
Transform Data into Opportunity.
Accelerate data analysis in your applications with
Intel Data Analytics Acceleration Library.
Click to learn more.
http://pubads.g.doubleclick.net/gampad/clk?id=278785351&iu=/4140
_______________________________________________
Firebird-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/firebird-docs
Reply | Threaded
Open this post in threaded view
|

Re: LangRef 2.5beta1 - a few suggestions /2

firebirdlists
In reply to this post by Paul Vinkenoog
Hello Paul,

Wednesday, March 23, 2016, 12:25:37 AM, PaulV wrote:

> Hi all,

>> > p.39   Number constants
>>
>> > For hexadecimal notation, isn't there something
>> > about the sign that deserves mention here?
>> > The example uses 0X08000000 - the first 0 after the X does serve some purpose.
>>
>> Aage, do you know about that "something"?  If yes, would you write
>> about it?

> I think he's referring to this:

> http://www.firebirdsql.org/file/documentation/reference_manuals/reference_material/html/langrefupd25-hexnumerals.html,
> especially the information under 'Value ranges'.

> The line under Number Constants (in the LangRef beta):

>   "For BIGINT numbers, hexadecimal notation is supported by
> Firebird 2.5 and higher versions, e.g., 0X080000000 as the hex
> representation of decimal 2147483648."

> should be:

>   "Hexadecimal notation is supported by Firebird 2.5 and higher
> versions. Numbers with 1-8 hex digits (e.g. 0x325708) are parsed as
> INTEGER values, numbers with 9-16 hex digits (e.g. 0x198723457237) as BIGINT."

> More explanation about the value ranges and some pitfalls (see link
> above) can be given in Data Types and Subtypes :: Integer Data
> Types, before the start of the subsections.

> Also (I should have caught this during reviewing),

Actually, one reason you didn't catch it at that time is because there
was nothing there about hexadecimal - it came in a later build and I
just took what was in the release notes.  At that time I wasn't fully
aware of just how much of the LangUpdate25 stuff was missing.

Another thing we seem to have missed by the same method (!) was binary
strings in hex format.

Unless you have feelings against it, I should just pick up the
relevant source from LangUpdate25, slot it into the appropriate
places and cross-ref where needed.


Helen


------------------------------------------------------------------------------
Transform Data into Opportunity.
Accelerate data analysis in your applications with
Intel Data Analytics Acceleration Library.
Click to learn more.
http://pubads.g.doubleclick.net/gampad/clk?id=278785351&iu=/4140
_______________________________________________
Firebird-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/firebird-docs
Reply | Threaded
Open this post in threaded view
|

Re: LangRef 2.5beta1 - a few suggestions /2

Paul Vinkenoog
Hi Helen,

> Another thing we seem to have missed by the same method (!) was binary
> strings in hex format.
>
> Unless you have feelings against it, I should just pick up the
> relevant source from LangUpdate25, slot it into the appropriate
> places and cross-ref where needed.

Yes, please use whatever you can use.

The hex numeral stuff is under langrefupd25-hexnumerals and (BIGINT-specific) langrefupd25-bigint; the 'binary' strings are at langrefupd25-hexbinstrings.


Cheers,
Paul

------------------------------------------------------------------------------
Transform Data into Opportunity.
Accelerate data analysis in your applications with
Intel Data Analytics Acceleration Library.
Click to learn more.
http://pubads.g.doubleclick.net/gampad/clk?id=278785351&iu=/4140
_______________________________________________
Firebird-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/firebird-docs
Reply | Threaded
Open this post in threaded view
|

Re: LangRef 2.5beta1 - a few suggestions /2

Aage Johansen-2
In reply to this post by firebirdlists

First, thanks to Paul for checking my suggestions.
Actually, I may have misremembered: I thought there might be pitfalls
regarding the sign of the result.

As for BETWEEN and the others: maybe precedence is totally irrelevant
for "comparison predicates".  I just mentioned it since "comparison
operators" have defined precedence.


--
Aage J.
ps
I've spent most of Easter in hospital, and haven't really been keen on
doing testing. Sorry about that.




On 22.03.2016 09:58, Helen Borrie wrote:

> Thursday, March 17, 2016, 12:23:40 AM, Aage wrote:
>
>
>> p.39   Number constants
>
>> For hexadecimal notation, isn't there something
>> about the sign that deserves mention here?
>> The example uses 0X08000000 - the first 0 after the X does serve some purpose.
>
> Aage, do you know about that "something"?  If yes, would you write
> about it?
>> ----------------------------------------
>
>> p.40-41
>> Table 4.4. Comparison Operator Precedence
>
>> After the table:
>> "This group also includes comparison predicates
>> BETWEEN, LIKE, CONTAINING, SIMILAR TO and others."
>
>> Could something be said about the precedence of these?
>
> Is there something to be said about it?  If you know of a precedence
> for these predicates, would you write it up?  I have not heard of it.
>
>> ----------------------------------------
>
>> p.51 (end of first paragraph):
>> A CONTAINING search is not case-sensitive.
>
>> Maybe a comment/warning on accent-sensitivity?
>
> I think you might be the first person involved with this text who has
> day-to-day experience with data in a language with accented
> characters.  What is there to say?
>
>> ----------------------------------------
>
> I've addressed these points to Aage because he raised them.  But
> anyone who can answer, please chip in!
>
> Helen
>
>
> ------------------------------------------------------------------------------
> Transform Data into Opportunity.
> Accelerate data analysis in your applications with
> Intel Data Analytics Acceleration Library.
> Click to learn more.
> http://pubads.g.doubleclick.net/gampad/clk?id=278785351&iu=/4140
>


------------------------------------------------------------------------------
Transform Data into Opportunity.
Accelerate data analysis in your applications with
Intel Data Analytics Acceleration Library.
Click to learn more.
http://pubads.g.doubleclick.net/gampad/clk?id=278785351&iu=/4140
_______________________________________________
Firebird-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/firebird-docs
Reply | Threaded
Open this post in threaded view
|

Re: LangRef 2.5beta1 - a few suggestions /2

Paul Vinkenoog
Aage Johansen wrote:

> First, thanks to Paul for checking my suggestions.
> Actually, I may have misremembered: I thought there might be pitfalls
> regarding the sign of the result.

There are. Or rather, there is one: 0x80000000 - 0xFFFFFFFF map to negative INTEGER values, whereas 0x080000000 - 0x0FFFFFFFF map to positive BIGINTs.

But I see Helen has taken care of that in her latest commit.

> As for BETWEEN and the others: maybe precedence is totally irrelevant
> for "comparison predicates".  I just mentioned it since "comparison
> operators" have defined precedence.

According to IBPhoenix's Using Firebird and Helen's Firebird Book, BETWEEN...AND, LIKE, CONTAINING and STARTING [WITH] all have precedence 9 (lowest) among the comparison operators. I assume that the same is true for SIMILAR TO.

> I've spent most of Easter in hospital, and haven't really been keen on
> doing testing. Sorry about that.

Hope you're doing alright now!


Cheers,
Paul Vinkenoog

------------------------------------------------------------------------------
Transform Data into Opportunity.
Accelerate data analysis in your applications with
Intel Data Analytics Acceleration Library.
Click to learn more.
http://pubads.g.doubleclick.net/gampad/clk?id=278785471&iu=/4140
_______________________________________________
Firebird-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/firebird-docs