NAME

Audio::TagLib::String - A wide string class suitable for unicode

SYNOPSIS

use Audio::TagLib::String;

my $i = Audio::TagLib::String->new("blah blah blah");
print $i->toCString(), "\n"; # got "blah blah blah"

DESCRIPTION

This is an implicitly shared wide string. For storage it uses Audio::TagLib::wstring, but as this is an implementation detail this of course could change. Strings are stored internally as UTF-16BE. (Without the BOM (Byte Order Mark))

The use of implicit sharing means that copying a string is cheap, the only cost comes into play when the copy is modified. Prior to that the string just has a pointer to the data of the parent String. This also makes this class suitable as a function return type.

In addition to adding implicit sharing, this class keeps track of four possible encodings, which are the four supported by the ID3v2 standard.

• %_Type

  The four types of string encodings supported by the ID3v2 specification. ID3v1 is assumed to be Latin1 and Ogg Vorbis comments use UTF8.

  qw(Latin1 UTF16 UTF16BE UTF16LE UTF8)

  keys %Audio::TagLib::String::_Type lists all available values also.

  NOTE binmode STDOUT, ":utf8" to display UTF8 string.

• new()

  Constructs an empty String.

• new(String $s)

  Make a shallow, implicitly shared, copy of $s. Because this is
  implicitly shared, this method is lightweight and suitable for
  pass-by-value usage.

• new(ByteVector $v, PV $t = "Latin1")

  Makes a deep copy of the data in $v.

  NOTE This should only be used with the 8-bit codecs Latin1 and UTF8, when used with other codecs it will simply print a warning and exit.

• new(PV $data, PV $encode)

  Constructs a String from the data $data encoded by $encode.

• new(PV $data)

  Constructs a String from the data $data.

  NOTE $data should be the internal format of Perl. It will check the UTF8 to determine the encode to use(Latin1 or UTF8 in this case).

• DESTROY()

  Destroys this String instance.

• PV to8Bit(BOOL $unicode = FALSE)

  If $unicode is false (the default) this will return a Latin1 encoded string. If it is true the returned string will be UTF-8 encoded and UTF8 flag on.

• PV toCString(BOOL $unicode = FALSE)

  see to8Bit()

  WARNING Differ from C/C++, the PV will contain a copy of the string returned by C/C++ code.

• Iterator begin()

  Returns an iterator pointing to the beginning of the string.

• Iterator end()

  Returns an iterator pointing to the end of the string (the position after the last character).

• IV find(String $s, IV $offset = 0)

  Finds the first occurance of pattern $s in this string starting from $offset. If the pattern is not found, -1 is returned.

• String substr(UV $position, UV $n = 0xffffffff)

  Extract a substring from this string starting at $position and continuing for $n characters.

• String apppend(String $s)

  Append $s to the current string and return a reference to the current string.

• String uppper()

  Returns an upper case version of the string.

  WARNING This only works for the characters in US-ASCII, i.e. A-Z.

• UV size()

  Returns the size of the string.

• BOOL isEmpty()

  Returns true if the string is empty.

  see isNull()

• BOOL isNull()

  Returns true if this string is null -- i.e. it is a copy of the String::null string.

  NOTE A string can be empty and not null.

  see isEmpty()

• ByteVector data(PV $type)

  Returns a ByteVector containing the string's data. If $type is Latin1 or UTF8, this will return a vector of 8 bit characters, otherwise it will use 16 bit characters.

• IV toInt()

  Convert the string to an integer.

• String stripWhiteSpace()

  Returns a string with the leading and trailing whitespace stripped.

• String number(IV $n) [static]

  Converts the base-10 integer $n to a string.

• PV getChar(IV $i)

  Returns the character at position $i. Encodes by UTF8 and sets UTF8 on if the returned character is a wide character.

• String copy(String $s)

  Performs a shallow, implicitly shared, copy of $s, overwriting the String's current data.

• String copy(ByteVector $v)

  Performs a deep copy of the data in $d.

• String copy(PV $data)

  Copies $data into current String. Check UTF8 flag to determine the encode to use (Latin1 or UTF8).

• String null() [static]

  Returns a static null string provided for convenience.

EXPORT

None by default.

OVERLOADED OPERATORS

== != += < >

SEE ALSO

Audio::TagLib

AUTHOR

Dongxu Ma, <dongxu@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2005 by Dongxu Ma

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.