Questions about documentation of Go standard library

[Kamil Ziemian]

Hello,

I now need to learn regular expressions for my work and since I can choose tool, I decided combine it with learning Go. When documentation of "regexp" package (I hope that I use this name correctly) is in most part clear to me, one thing is unclear to me. Since, I probably raise many more questions about Go standard library, I decided to name it as such.

In the description of function "func CompilePOSIX" (https://pkg.go.dev/regexp) we can read.
BEGINNING
That is, when matching against text, the regexp returns a match that begins as early as possible in the input (leftmost), and among those it chooses a match that is as long as possible. This so-called leftmost-longest matching is the same semantics that early regular expression implementations used and that POSIX specifies.
END

Line "early regular expression implementations used and that POSIX specifies" is a bit confusing to me. I guess it can mean "old implementations Go regexp package", but also very old implementations of regular expressions in different languages and systems (?). Can someone help me understand this text?

Best
Kamil Ziemian

[Joshua O'Connor]

Hi,

I read that line as "very old implementations of regular expressions in different languages and systems".

And indeed this documentation hasn't changed since Go v1 (https://pkg.go.dev/regexp@go1#CompilePOSIX), so I'm pretty sure it means that.

In any case I don't think it should affect your usage of the package :)

Joshua

Kamil Ziemian --
You received this message because you are subscribed to the Google Groups "golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/golang-nuts/8e002363-da47-4c43-953f-a66fefc1bcdcn%40googlegroups.com.

[Volker Dobler]

On Thursday, 26 August 2021 at 13:27:01 UTC+2 kziem...@gmail.com wrote:

 

Line "early regular expression implementations used and that POSIX specifies" is a bit confusing to me. I guess it can mean "old implementations Go regexp package",

This guess is wrong. Go's regexp package did and does not change (in that respect).

 

but also very old implementations of regular expressions in different languages and systems (?).

This is the correct meaning of the sentence.

 

V.

[Kamil Ziemian]

Thank you for responses. Indeed, such things don't hamper using of package, but are confusing to me and I have already too much confusing thing in my work. So, I need no more of them. ;)

Another topic. I needed to check package "math/bits" (learning about Go can lead us in such places quite fast) and I'm confused about function "Len(x uint) int". In its description we have (https://pkg.go.dev/math/bi...@go1.17)
BEGINNING
Len returns the minimum number of bits required to represent x; the result is 0 for x == 0.
END
I have no problem with using function that says 0 can be encoded in 0 bits, but it is still odd. Maybe it is connected to something done under the hood, about which I don't know a thing? Does anyone know why this choose was made?

Again, I have no problem with this function (and other realeated functions) working in this way. It is just strange thing to me.

PS. This is not about documentation, but about implementation, but I think it fit to this topic.

Best
Kamil

[Volker Dobler]

On Thursday, 26 August 2021 at 22:17:55 UTC+2 kziem...@gmail.com wrote:

Another topic. I needed to check package "math/bits" (learning about Go can lead us in such places quite fast) and I'm confused about function "Len(x uint) int". In its description we have (https://pkg.go.dev/math/bi...@go1.17)
BEGINNING
Len returns the minimum number of bits required to represent x; the result is 0 for x == 0.
END
I have no problem with using function that says 0 can be encoded in 0 bits, but it is still odd. Maybe it is connected to something done under the hood, about which I don't know a thing? Does anyone know why this choose was made?

 

No, the description doesn't say that 0 can be encoded in 0 bits:

It says that Len(0) returns 0.

If you want Len to be a total function you must return a value for every input.

For most inputs the value is strictly determined by what the functions does

(number of bits needed to represent), so Len(9) == 3. But how many bits

do you need to represent 0? The question is malformed as there are no 

set bits in the used representation of 0. One could have declared

    "Len(0) returns -42"

but this makes no sense at all. Having Len(0)==0 results in

Len(a) <= Len(b) if a < b without having to invent totally arbitrary

values for Len(0).

You probably should not overinterpret Go's documentation.

This is not lyric. "the result is 0 for x == 0" has no hidden meaning.

V.

[Brian Candler]

On Friday, 27 August 2021 at 06:14:45 UTC+1 Volker Dobler wrote:

For most inputs the value is strictly determined by what the functions does

(number of bits needed to represent), so Len(9) == 3.

To be pedantic, Len(9) == 4

:-)

[Volker Dobler]

On Sunday, 29 August 2021 at 09:47:09 UTC+2 Brian Candler wrote:

To be pedantic, Len(9) == 4

:-)

Me stupid :-( 

[Kamil Ziemian]

Thank for explanation, but I don't understand "But how many bits do you need to represent 0? The question is malformed as there are no set bits in the used representation of 0.". Why this is malformed questions? When I think of coding 1, I think about thaking one bit with 1 inside and when it goes to 0, I would take one bit with 0 inside.

K.

[Kurtis Rader]

On Sun, Aug 29, 2021 at 1:08 PM Kamil Ziemian <kziem...@gmail.com> wrote:

Thank for explanation, but I don't understand "But how many bits do you need to represent 0? The question is malformed as there are no set bits in the used representation of 0.". Why this is malformed questions? When I think of coding 1, I think about thaking one bit with 1 inside and when it goes to 0, I would take one bit with 0 inside.

Consider a variable length encoding scheme as used by some RPC protocols or mechanisms like Google protobufs. How many bits does it take to encode a zero? Zero with a length prefix of zero.

--

Kurtis Rader

Caretaker of the exceptional canines Junior and Hank

[peterGo]

K,

For a finite, unsigned binary number, ignoring leading zeros, how many binary digits (the length in bits) are needed to represent a number?

Peter

[Kamil Ziemian]

Kurtis Rader, peterGo thank you for the answers. I probably need to learn more about RPC protocols, for now I can only expand acronym. But this point with ignoring leading zeros is clear enough. And probalby more "elementary (and stupid)?" questions is comming.

Kamil

[Kamil Ziemian]

Hello,

My struggles with regexp is going and I have another problem. I read closely syntax page of RE2 (https://github.com/google/re2/wiki/Syntax) and I still not sure if I understand one example from regexp package.

In example in method func (*Regexp) FindIndex (https://pkg.go.dev/reg...@go1.17#Regexp.FindIndex) we have line

pattern := regexp.MustCompile(`(?m)(?P<key>\w+):\s+(?P<value>\w+)$`)

Does (?m) set value of flag m to true and if I want set it to false I should write (?-m) or not? By default m should be false, but as example it is fine.

As a side note, this regular expression is used in other examples, when we need <key> and <value>, but looks unnecessary complex for method FindIndex. I guess
`(?m)\w+:\s+\w+$`
would work fine. Am I wrong?

Best
Kamil

[Brian Candler]

I believe (?m) applies to the current group only; if you want to "unset" it then start a separate group.

https://play.golang.org/p/wT_ZTrUSABL

And I think you're right, there's no need to have capture groups for FindIndex.

[Kamil Ziemian]

Thank you for your answer and opinion Briana Candler.

I ask about unset only because of the cryptic text, at least to me, in the description of RE2 (https://github.com/google/re2/wiki/Syntax). From practical point of view, your solutions look good.

I try to google about changes in examples in Go's stdlib, maybe this can be done?

Best

Kamil

--
You received this message because you are subscribed to a topic in the Google Groups "golang-nuts" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/golang-nuts/RPPfjiuSRHU/unsubscribe.
To unsubscribe from this group and all its topics, send an email to golang-nuts...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/golang-nuts/94d8c404-3c25-4897-a582-93b67c6b923an%40googlegroups.com.

[Brian Candler]

Ah, I missed the bit where it says "Flag syntax is xyz (set) or -xyz (clear) or xy-z (set xy, clear z)."  You're quite right, there's a much simpler way:

https://play.golang.org/p/upupUQUcsR8

[Kamil Ziemian]

Hello,

I currently read about "io" package and again I read that "io.EOF" is not treated as error, since it is what you expect to end file, which is almost tautology. At the same time it satisfies error interface and is created busing errors.New function.

I understand why this is done, doing it other way would probably make serious mess in the code, but pedantic said of me is unsettled by this. Does any experience Gopher can give my advice how to think about situation when some object satisfy interface, but it is exception that proves the rule? I should just get used to it, or is it some better way of thinking?

Best
Kamil

[Ian Lance Taylor]

On Wed, Oct 6, 2021 at 2:35 PM Kamil Ziemian <kziem...@gmail.com> wrote:
>
> I currently read about "io" package and again I read that "io.EOF" is not treated as error, since it is what you expect to end file, which is almost tautology. At the same time it satisfies error interface and is created busing errors.New function.
>
> I understand why this is done, doing it other way would probably make serious mess in the code, but pedantic said of me is unsettled by this. Does any experience Gopher can give my advice how to think about situation when some object satisfy interface, but it is exception that proves the rule? I should just get used to it, or is it some better way of thinking?

I'm not sure what you mean when you say that io.EOF is not treated as
an error. io.EOF is an error: it implements the error interface, and
is returned as the error value by methods such as Read.

Of course most programs that see an io.EOF error from Read do not want
to report that to the user, because it just means that they are at the
end of the file. But that doesn't mean that it's not an error. The
Read failed. Every failure is reported via an error. For the case in
which Read fails because it reaches the end of the file, the error
that it returns is io.EOF.

Ian

[peterGo]

Kamil,

A Go interface implements a particular behavior. For example, io.Reader is the interface that wraps the basic Read method.

    type Reader interface {
        Read(p []byte) (n int, err error)
    }

The outcome of the Read method ranges from good to catastrophic failure. The outcome is reported in the err error type return value. The err return value for good is nil. For a finite stream of data, a particular outcome of interest is end-of-file.

    var EOF = errors.New("EOF")

io.EOF is the error returned by Read when no more input is available.

See package io.
https://pkg.go.dev/io

Peter

[Kamil Ziemian]

I'm not sure what you mean when you say that io.EOF is not treated as an error.  io.EOF is an error: it implements the error interface, and is returned as the error value by methods such as Read.

I am mediocre at best at programming and I'm quite a picky person, so I just have a problem with wrapping my head around texts like this below, which is a documentation of io.ReadAll. Nothing more.

ReadAll reads from r until an error or EOF and returns the data it read. A successful call returns err == nil, not err == EOF. Because ReadAll is defined to read from src until EOF, it does not treat an EOF from Read as an error to be reported.

This mental dissonans is probably caused by the simple fact that I think about error as information that something doesn't work as it should, but arriving at the end of the file means that we are where we should be.

But that doesn't mean that it's not an error.  The Read failed.  Every failure is reported via an error.  For the case in which Read fails because it reaches the end of the file, the error that it returns is io.EOF.

Thank you very much. I will try to digest that io.EOF means that Read fails, so this is an error of Read method/function. I never think about it that way.

Best

Kamil

To view this discussion on the web visit https://groups.google.com/d/msgid/golang-nuts/9209890e-aa3a-4822-a680-bed6b1804b39n%40googlegroups.com.

[peterGo]

Kamil,

"I just have a problem with wrapping my head around ... documentation of io.ReadAll."

The io.ReadAll function and the io.Reader interface Read method are not the same, don't conflate them. io.ReadAll is a function which reads from r, an io.Reader interface, until an error or EOF and returns the data it read. The ReadAll function, for reasons given in the documentation, chose to treat a Read method error value of io.EOF as nothing special.

Peter

[Michael Ellis]

Kamil,

Have you read https://go.dev/blog/errors-are-values by Rob Pike?  Wrapping my head around the concept that an error is simply a value returned from a function was tremendously helpful when I had questions along the same lines as yours.

[Kamil Ziemian]

> The io.ReadAll function and the io.Reader interface Read method are not the same, don't conflate them.

Thank you for stressing that point, but I don't think that I conflate them. Maybe I wrong, but I believe that many entries in "io" package share decriptions that states "A successful call returns err == nil, not err == EOF. Because ReadAll is defined to read from src until EOF, it does not treat an EOF from Read as an error to be reported.", so I quote it just because it was at my hand.

> Have you read https://go.dev/blog/errors-are-values by Rob Pike?

Thank you very much Michael, I read few things about errors in Go, but never that blog post. Now I need for my job to process few files in Go, so I need to read "io" first, but after that, I will read this mail. In some sense I'm a fan of Rob Pike blog posts, articles and talks. Hard to say why, maybe he is "no nonsense guy"?

Best

Kamil

[Kamil Ziemian]

Hello,

I found unimportant typo in English part of the documentation of "fmt". How can I correct it? GitHub pull request or open issue "Unimportant typos in documentation"? I don't know how I should treat such unimportant typo.

Best
Kamil

[Kamil Ziemian]

Hello,

I now read documentation of "fmt" package and in "Format errors" (https://pkg.go.dev/f...@go1.17.2#hdr-Format_errors) we have

Invalid or invalid use of argument index: %!(BADINDEX)
    Printf("%*[2]d", 7):       %!d(BADINDEX)
    Printf("%.[2]d", 7):       %!d(BADINDEX)

I cannot understand what "Invalid or invalid use of argument index" was intended to mean? Can anyone help me with that?

Best

Kamil

[Martin Schnabel]

Hi Kamil,

you can probably read it as Invalid argument index or invalid use of
argument index.

Hope that helps.

[Dan Kortschak]

On Fri, 2021-10-08 at 15:33 -0700, Kamil Ziemian wrote:
> Hello,
>
> I now read documentation of "fmt" package and in "Format errors" (
> https://pkg.go.dev/f...@go1.17.2#hdr-Format_errors) we have
> Invalid or invalid use of argument index: %!(BADINDEX)
> Printf("%*[2]d", 7): %!d(BADINDEX)
> Printf("%.[2]d", 7): %!d(BADINDEX)
>

The fmt argument index is an index into args (1-based). You have a
single argument here, 7, so 2 is invalid.

[Ian Lance Taylor]

On Fri, Oct 8, 2021 at 12:36 PM Kamil Ziemian <kziem...@gmail.com> wrote:
>
> I found unimportant typo in English part of the documentation of "fmt". How can I correct it? GitHub pull request or open issue "Unimportant typos in documentation"? I don't know how I should treat such unimportant typo.

You can send a pull request or a Gerritt CL. See
https://golang.org/doc/contribute.html. Thanks.

Ian

[Kamil Ziemian]

> you can probably read it as Invalid argument index or invalid use of
 > argument index.

> Hope that helps

Thank you mb0, now it make sense. I'm not confident as Go user to guess things like that.

Thank you Ian Lance Taylor. I have now quite a pile of Go must read texts, when I end my day job I will read them all and after that, I will "contribute" in this small way.

Best

Kamil