Parrot String Doc

[Robert Eaglestone]

OK, I'm looking at the Parrot String documentation, and I've
got questions. It's not like the docs are a total mess, they
just need some fleshing out. Yeah, that's it. So here I go.

Here's the page I'm looking at:

http://www.parrotcode.org/docs/strings.pod.html

And here are my questions. Or, rather, notes which have
questions in them.

* OK, I'm game, is 'String' a new thing that's been added to
C in the last ten years? I can't find it defined anywhere;
my brain must have gone to mush.

* Does it help to mention that the source code for string
functions is include/parrot/string.h and string.c?

* Suppose I add some example code to the doc, creating a
string and fooling around with it? Perhaps using code
from a string test routine (hint, hint)? I'd do something
like this, maybe:

INTVAL encoding = where/what are the encoding values?

/* is this legal? */
STRING* foo = string_make( pi, "foobar", 6, encoding, 0, 0 );
/* foo is "foobar" */

/* It's a pity we don't have a shorter constructor. */

STRING* bar = string_chopn( foo, 3 );
/* bar is "foo" */

/* It's also sort-of a pity we don't have this one. */
STRING* baz = string_chop( foo );
/* baz is "fo" */

* Finally, at the bottom of the doc, I see all these
undocumented functions. I think I ought to document
them. Any new stuff since this page was last edited?

-Rob

[Stéphane Payrard]

Le Tue, Jan 13, 2004 at 03:06:18PM -0600, le valeureux mongueur Robert Eaglestone a dit:

> OK, I'm looking at the Parrot String documentation, and I've
> got questions. It's not like the docs are a total mess, they
> just need some fleshing out. Yeah, that's it. So here I go.
>
> Here's the page I'm looking at:
>
> http://www.parrotcode.org/docs/strings.pod.html
>
> And here are my questions. Or, rather, notes which have
> questions in them.
>
>
> * OK, I'm game, is 'String' a new thing that's been added to
> C in the last ten years? I can't find it defined anywhere;
> my brain must have gone to mush.

<STRING>, C<String> are different names for a C<struct
parrot_string_t>. Strings are garbage collected. All garbage
collected entities are accessible thru a pointer to a C<struct
pobj_t> that is an union discriminated by the member C<flags>.

Relevant code in F<include/parrot/pobj.h>:

typedef union UnionVal {
...
struct parrot_string_t * string_val;
}

typedef struct pobj_t {
UnionVal u;
Parrot_UInt flags;
}

typedef enum PObj_enum {
...
PObj_is_string_FLAG = 1 << 8,
}

But this is mostly irrelevant to the string user that will use
the API you document. If you care about internals, see more info
about garbage collection in F<docs/memory_internals.pod>.

--
stef

[Harry Jackson]

Stéphane Payrard wrote:
> Le Tue, Jan 13, 2004 at 03:06:18PM -0600, le valeureux mongueur Robert Eaglestone a dit:
>
>>OK, I'm looking at the Parrot String documentation, and I've
>>got questions. It's not like the docs are a total mess, they
>>just need some fleshing out. Yeah, that's it. So here I go.
>>
>>Here's the page I'm looking at:
>>
>>http://www.parrotcode.org/docs/strings.pod.html
>>
>>And here are my questions. Or, rather, notes which have
>>questions in them.
>>
>>
>>* OK, I'm game, is 'String' a new thing that's been added to
>> C in the last ten years? I can't find it defined anywhere;
>> my brain must have gone to mush.
>
>
>
> <STRING>, C<String> are different names for a C<struct
> parrot_string_t>. Strings are garbage collected. All garbage
> collected entities are accessible thru a pointer to a C<struct
> pobj_t> that is an union discriminated by the member C<flags>.

I did notice that they refer to the same struct which is something I
found confusing. I noticed them being used interchangeably in places and
was wondering if the we should just be using just "STRING" as per
instructions in the documentation and change all references of "String"
to reflect this.

Harry

[Stéphane Payrard]

Le Tue, Jan 13, 2004 at 10:34:14PM +0100, le valeureux mongueur Stéphane Payrard a dit:

> Le Tue, Jan 13, 2004 at 03:06:18PM -0600, le valeureux mongueur Robert Eaglestone a dit:
> > OK, I'm looking at the Parrot String documentation, and I've
> > got questions. It's not like the docs are a total mess, they
> > just need some fleshing out. Yeah, that's it. So here I go.
> >
> > Here's the page I'm looking at:
> >
> > http://www.parrotcode.org/docs/strings.pod.html
> >
> > And here are my questions. Or, rather, notes which have
> > questions in them.
> >
> >
> > * OK, I'm game, is 'String' a new thing that's been added to
> > C in the last ten years? I can't find it defined anywhere;
> > my brain must have gone to mush.
>
>
> <STRING>, C<String> are different names for a C<struct
> parrot_string_t>.

I forgot to mention.
You will find the definitions in F<include/parrot/string.h>.

typedef struct parrot_string_t String;
...
#define STRING struct parrot_string_t

etags or ctags (depending if you are an emacs or vi user) is your
friend. I use the following to avoid gathering definitions outside
the core of parrot.

etags `find -name '*.pmc' -o -name '*.c' -o -name '*.h' | grep -v languages/ | grep -v icu/`

[Michael Scott]

You'll find some diagrams here which might help.

http://www.vendian.org/parrot/wiki/bin/view.cgi/Main/
ParrotDiagramsString