{
    "mode": "perldoc",
    "parameter": "Bit::Vector::String",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Bit%3A%3AVector%3A%3AString/json",
    "generated": "2026-06-11T00:13:54Z",
    "synopsis": "use Bit::Vector::String;\ntoOct\n$string = $vector->toOct();\nfromOct\n$vector->fromOct($string);\nnewOct\n$vector = Bit::Vector->newOct($bits,$string);\nStringExport\n$string = $vector->StringExport($type);\nStringImport\n$type = $vector->StringImport($string);\nnewString\n$vector = Bit::Vector->newString($bits,$string);\n($vector,$type) = Bit::Vector->newString($bits,$string);",
    "sections": {
        "NAME": {
            "content": "Bit::Vector::String - Generic string import/export for Bit::Vector\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use Bit::Vector::String;\n\ntoOct\n$string = $vector->toOct();\n\nfromOct\n$vector->fromOct($string);\n\nnewOct\n$vector = Bit::Vector->newOct($bits,$string);\n\nStringExport\n$string = $vector->StringExport($type);\n\nStringImport\n$type = $vector->StringImport($string);\n\nnewString\n$vector = Bit::Vector->newString($bits,$string);\n($vector,$type) = Bit::Vector->newString($bits,$string);\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "* \"$string = $vector->toOct();\"\n\nReturns an octal string representing the given bit vector.\n\nNote that this method is not particularly efficient, since it is almost completely realized in\nPerl, and moreover internally operates on a Perl list of individual octal digits which it\nconcatenates into the final string using \"\"join('', ...)\"\".\n\nA benchmark reveals that this method is about 40 times slower than the method \"\"toBin()\"\"\n(which is realized in C):\n\nBenchmark: timing 10000 iterations of toBin, toHex, toOct...\ntoBin:  1 wallclock secs ( 1.09 usr +  0.00 sys =  1.09 CPU)\ntoHex:  1 wallclock secs ( 0.53 usr +  0.00 sys =  0.53 CPU)\ntoOct: 40 wallclock secs (40.16 usr +  0.05 sys = 40.21 CPU)\n\nNote that since an octal digit is always worth three bits, the length of the resulting string\nis always a multiple of three bits, regardless of the true length (in bits) of the given bit\nvector.\n\nAlso note that the LEAST significant octal digit is located at the RIGHT end of the resulting\nstring, and the MOST significant digit at the LEFT end.\n\nFinally, note that this method does NOT prepend any uniquely identifying format prefix (such\nas \"0o\") to the resulting string (which means that the result of this method only contains\nvalid octal digits, i.e., [0-7]).\n\nHowever, this can of course most easily be done as needed, as follows:\n\n$string = '0o' . $vector->toOct();\n\n* \"$vector->fromOct($string);\"\n\nAllows one to read in the contents of a bit vector from an octal string, such as returned by\nthe method \"\"toOct()\"\" (see above).\n\nNote that this method is not particularly efficient, since it is almost completely realized in\nPerl, and moreover chops the input string into individual characters using \"\"split(//,\n$string)\"\".\n\nRemember also that the least significant bits are always to the right of an octal string, and\nthe most significant bits to the left. Therefore, the string is actually reversed internally\nbefore storing it in the given bit vector using the method \"\"ChunkListStore()\"\", which\nexpects the least significant chunks of data at the beginning of a list.\n\nA benchmark reveals that this method is about 40 times slower than the method \"\"fromBin()\"\"\n(which is realized in C):\n\nBenchmark: timing 10000 iterations of fromBin, fromHex, fromOct...\nfromBin:  1 wallclock secs ( 1.13 usr +  0.00 sys =  1.13 CPU)\nfromHex:  1 wallclock secs ( 0.80 usr +  0.00 sys =  0.80 CPU)\nfromOct: 46 wallclock secs (44.95 usr +  0.00 sys = 44.95 CPU)\n\nIf the given string contains any character which is not an octal digit (i.e., [0-7]), a fatal\nsyntax error ensues (\"unknown string type\").\n\nNote especially that this method does NOT accept any uniquely identifying format prefix (such\nas \"0o\") in the given string; the presence of such a prefix will also lead to the fatal\n\"unknown string type\" error.\n\nIf the given string contains less octal digits than are needed to completely fill the given\nbit vector, the remaining (most significant) bits all remain cleared (i.e., set to zero).\n\nThis also means that, even if the given string does not contain enough digits to completely\nfill the given bit vector, the previous contents of the bit vector are erased completely.\n\nIf the given string is longer than it needs to fill the given bit vector, the superfluous\ncharacters are simply ignored.\n\nThis behaviour is intentional so that you may read in the string representing one bit vector\ninto another bit vector of different size, i.e., as much of it as will fit.\n\n* \"$vector = Bit::Vector->newOct($bits,$string);\"\n\nThis method is an alternative constructor which allows you to create a new bit vector object\n(with \"$bits\" bits) and to initialize it all in one go.\n\nThe method internally first calls the bit vector constructor method \"\"new()\"\" and then stores\nthe given string in the newly created bit vector using the same approach as the method\n\"\"fromOct()\"\" (described above).\n\nNote that this approach is not particularly efficient, since it is almost completely realized\nin Perl, and moreover chops the input string into individual characters using \"\"split(//,\n$string)\"\".\n\nAn exception will be raised if the necessary memory cannot be allocated (see the description\nof the method \"\"new()\"\" in Bit::Vector(3) for possible causes) or if the given string cannot\nbe converted successfully (see the description of the method \"\"fromOct()\"\" above for\ndetails).\n\nNote especially that this method does NOT accept any uniquely identifying format prefix (such\nas \"0o\") in the given string and that such a prefix will lead to a fatal \"unknown string type\"\nerror.\n\nIn case of an error, the memory occupied by the new bit vector is released again before the\nexception is actually thrown.\n\nIf the number of bits \"$bits\" given has the value \"\"undef\"\", the method will automatically\nallocate a bit vector with a size (i.e., number of bits) of three times the length of the\ngiven string (since every octal digit is worth three bits).\n\nNote that this behaviour is different from that of the methods \"\"newHex()\"\", \"\"newBin()\"\",\n\"\"newDec()\"\" and \"\"newEnum()\"\" (which are realized in C, internally); these methods will\nsilently assume a value of 0 bits if \"\"undef\"\" is given (and may warn about the \"Use of\nuninitialized value\" if warnings are enabled).\n\n* \"$string = $vector->StringExport($type);\"\n\nReturns a string representing the given bit vector in the format specified by \"$type\":\n\n1 | b | bin      =>  binary        (using \"toBin()\")\n2 | o | oct      =>  octal         (using \"toOct()\")\n3 | d | dec      =>  decimal       (using \"toDec()\")\n4 | h | hex | x  =>  hexadecimal   (using \"toHex()\")\n5 | e | enum     =>  enumeration   (using \"toEnum()\")\n6 | p | pack     =>  packed binary (using \"BlockRead()\")\n\nThe case (lower/upper/mixed case) of \"$type\" is ignored.\n\nIf \"$type\" is omitted or \"\"undef\"\" or false (\"0\" or the empty string), a hexadecimal string is\nreturned as the default format.\n\nIf \"$type\" does not have any of the values described above, a fatal \"unknown string type\" will\noccur.\n\nBeware that in order to guarantee that the strings can be correctly parsed and read in by the\nmethods \"\"StringImport()\"\" and \"\"newString()\"\" (described below), the method\n\"\"StringExport()\"\" provides uniquely identifying prefixes (and, in one case, a suffix) as\nfollows:\n\n1 | b | bin      =>  '0b' . $vector->toBin();\n2 | o | oct      =>  '0o' . $vector->toOct();\n3 | d | dec      =>         $vector->toDec(); # prefix is [+-]\n4 | h | hex | x  =>  '0x' . $vector->toHex();\n5 | e | enum     =>  '{'  . $vector->toEnum() . '}';\n6 | p | pack     =>  ':'  . $vector->Size() .\n':'  . $vector->BlockRead();\n\nThis is necessary because certain strings can be valid representations in more than one\nformat.\n\nAll strings in binary format, i.e., which only contain \"0\" and \"1\", are also valid number\nrepresentations (of a different value, of course) in octal, decimal and hexadecimal.\n\nLikewise, a string in octal format is also valid in decimal and hexadecimal, and a string in\ndecimal format is also valid in hexadecimal.\n\nMoreover, if the enumeration of set bits (as returned by \"\"toEnum()\"\") only contains one\nelement, this element could be mistaken for a representation of the entire bit vector (instead\nof just one bit) in decimal.\n\nBeware also that the string returned by format \"6\" (\"packed binary\") will in general NOT BE\nPRINTABLE, because it will usually consist of many unprintable characters!\n\n* \"$type = $vector->StringImport($string);\"\n\nAllows one to read in the contents of a bit vector from a string which has previously been\nproduced by \"\"StringExport()\"\", \"\"toBin()\"\", \"\"toOct()\"\", \"\"toDec()\"\", \"\"toHex()\"\",\n\"\"toEnum()\"\", \"\"BlockRead()\"\" or manually or by another program.\n\nBeware however that the string must have the correct format; otherwise a fatal \"unknown string\ntype\" error will occur.\n\nThe correct format is the one returned by \"\"StringExport()\"\" (see immediately above).\n\nThe method will also try to automatically recognize formats without identifying prefix such as\nreturned by the methods \"\"toBin()\"\", \"\"toOct()\"\", \"\"toDec()\"\", \"\"toHex()\"\" and\n\"\"toEnum()\"\".\n\nHowever, as explained above for the method \"\"StringExport()\"\", due to the fact that a string\nmay be a valid representation in more than one format, this may lead to unwanted results.\n\nThe method will try to match the format of the given string in the following order:\n\nIf the string consists only of [01], it will be considered to be in binary format (although it\ncould be in octal, decimal or hexadecimal format or even be an enumeration with only one\nelement as well).\n\nIf the string consists only of [0-7], it will be considered to be in octal format (although it\ncould be in decimal or hexadecimal format or even be an enumeration with only one element as\nwell).\n\nIf the string consists only of [0-9], it will be considered to be in decimal format (although\nit could be in hexadecimal format or even be an enumeration with only one element as well).\n\nIf the string consists only of [0-9A-Fa-f], it will be considered to be in hexadecimal format.\n\nIf the string only contains numbers in decimal format, separated by commas (\",\") or dashes\n(\"-\"), it is considered to be an enumeration (a single decimal number also qualifies).\n\nAnd if the string starts with \":[0-9]:\", the remainder of the string is read in with\n\"\"BlockStore()\"\".\n\nTo avoid misinterpretations, it is therefore recommendable to always either use the method\n\"\"StringExport()\"\" or to provide some uniquely identifying prefix (and suffix, in one case)\nyourself:\n\nbinary         =>  '0b' . $string;\noctal          =>  '0o' . $string;\ndecimal        =>  '+'  . $string; # in case \"$string\"\n=>  '-'  . $string; # has no sign yet\nhexadecimal    =>  '0x' . $string;\n=>  '0h' . $string;\nenumeration    =>  '{'  . $string . '}';\n=>  '['  . $string . ']';\n=>  '<'  . $string . '>';\n=>  '('  . $string . ')';\npacked binary  =>  ':'  . $vector->Size() .\n':'  . $vector->BlockRead();\n\nNote that case (lower/upper/mixed case) is not important and will be ignored by this method.\n\nInternally, the method uses the methods \"\"fromBin()\"\", \"\"fromOct()\"\", \"\"fromDec()\"\",\n\"\"fromHex()\"\", \"\"fromEnum()\"\" and \"\"BlockStore()\"\" for actually importing the contents of\nthe string into the given bit vector. See their descriptions here in this document and in\nBit::Vector(3) for any further conditions that must be met and corresponding possible fatal\nerror messages.\n\nThe method returns the number of the format that has been recognized:\n\n1    =>    binary\n2    =>    octal\n3    =>    decimal\n4    =>    hexadecimal\n5    =>    enumeration\n6    =>    packed binary\n\n* \"$vector = Bit::Vector->newString($bits,$string);\"\n\n\"($vector,$type) = Bit::Vector->newString($bits,$string);\"\n\nThis method is an alternative constructor which allows you to create a new bit vector object\n(with \"$bits\" bits) and to initialize it all in one go.\n\nThe method internally first calls the bit vector constructor method \"\"new()\"\" and then stores\nthe given string in the newly created bit vector using the same approach as the method\n\"\"StringImport()\"\" (described immediately above).\n\nAn exception will be raised if the necessary memory cannot be allocated (see the description\nof the method \"\"new()\"\" in Bit::Vector(3) for possible causes) or if the given string cannot\nbe converted successfully (see the description of the method \"\"StringImport()\"\" above for\ndetails).\n\nIn case of an error, the memory occupied by the new bit vector is released again before the\nexception is actually thrown.\n\nIf the number of bits \"$bits\" given has the value \"\"undef\"\", the method will automatically\ndetermine this value for you and allocate a bit vector of the calculated size.\n\nNote that this behaviour is different from that of the methods \"\"newHex()\"\", \"\"newBin()\"\",\n\"\"newDec()\"\" and \"\"newEnum()\"\" (which are realized in C, internally); these methods will\nsilently assume a value of 0 bits if \"\"undef\"\" is given (and may warn about the \"Use of\nuninitialized value\" if warnings are enabled).\n\nThe necessary number of bits is calculated as follows:\n\nbinary         =>       length($string);\noctal          =>   3 * length($string);\ndecimal        =>  int( length($string) * log(10) / log(2) + 1 );\nhexadecimal    =>   4 * length($string);\nenumeration    =>  maximum of values found in $string + 1\npacked binary  =>  $string =~ /^:(\\d+):/;\n\nIf called in scalar context, the method returns the newly created bit vector object.\n\nIf called in list context, the method additionally returns the number of the format which has\nbeen recognized, as explained above for the method \"\"StringImport()\"\".\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "Bit::Vector(3), Bit::Vector::Overload(3).\n",
            "subsections": []
        },
        "VERSION": {
            "content": "This man page documents \"Bit::Vector::String\" version 7.4.\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Steffen Beyer\nmailto:STBEY@cpan.org\nhttp://www.engelschall.com/u/sb/download/\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "Copyright (c) 2004 - 2013 by Steffen Beyer. All rights reserved.\n",
            "subsections": []
        },
        "LICENSE": {
            "content": "This package is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself, i.e., under the terms of the \"Artistic License\" or the \"GNU General Public\nLicense\".\n\nThe C library at the core of this Perl module can additionally be redistributed and/or modified\nunder the terms of the \"GNU Library General Public License\".\n\nPlease refer to the files \"Artistic.txt\", \"GNUGPL.txt\" and \"GNULGPL.txt\" in this distribution\nfor details!\n",
            "subsections": []
        },
        "DISCLAIMER": {
            "content": "This package is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;\nwithout even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n\nSee the \"GNU General Public License\" for more details.\n",
            "subsections": []
        }
    },
    "summary": "Bit::Vector::String - Generic string import/export for Bit::Vector",
    "flags": [],
    "examples": [],
    "see_also": [
        {
            "name": "Vector",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/Vector/3/json"
        },
        {
            "name": "Overload",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/Overload/3/json"
        }
    ]
}