File Coverage

blib/lib/PerlIO/bitswap.pm
Criterion Covered Total %
statement 8 8 100.0
branch n/a
condition n/a
subroutine 3 3 100.0
pod n/a
total 11 11 100.0


line stmt bran cond sub pod time code
1             =head1 NAME
2              
3             PerlIO::bitswap - I/O layer to swap bits and bytes
4              
5             =head1 SYNOPSIS
6              
7             open($fh, "<:bitswap(7)", $filename);
8             open($fh, ">:bitswap(7)", $filename);
9              
10             =head1 DESCRIPTION
11              
12             This PerlIO layer swaps the order of bits, nybbles, or bytes within
13             bytes or words. It is a convenience when working with a file that uses
14             a different endianness from the program, or when some other part of the
15             system applies unwanted swaps.
16              
17             The layer takes one argument, which must be a non-negative integer,
18             specified in any of the ways that are by default permitted in Perl
19             source. Each bit of the argument controls one of a set of swaps that
20             are available, and the swaps for all set bits occur simultaneously.
21             Generically, bit N (which has numeric value 2**N) causes the two
22             2**N-bit halves of each aligned 2**(N+1)-bit unit to be swapped. So,
23             for example, an argument of 16 (only bit 4 set) swaps the two two-octet
24             halves of each four-octet unit, while preserving the order of the octets
25             within each two-octet unit and the order of the bits within each octet.
26             The most useful swap arguments are:
27              
28             =over
29              
30             =item B<7>
31              
32             Reverse the order of the eight bits within each octet, leaving the
33             sequence of octets unmodified.
34              
35             =item B<8>
36              
37             Swap octets within each two-octet word.
38              
39             =item B<0x18>
40              
41             Reverse the order of the four octets within each four-octet word.
42              
43             =item B<0x38>
44              
45             Reverse the order of the eight octets within each eight-octet word.
46              
47             =back
48              
49             If octets or larger units are being swapped (argument 8 or greater),
50             any incomplete swap block will result in an I/O error. It is permitted
51             for individual reads and writes to involve incomplete swap blocks, but any
52             sequence of reads and writes must cover an integral number of swap blocks.
53             Seeks, similarly, must always travel an integral number of swap blocks.
54             The logic assumes that the end of a regular file is always at a block
55             boundary, and will yield incorrect results if that is not the case.
56              
57             =cut
58              
59             package PerlIO::bitswap;
60              
61 6     6   9061 { use 5.008001; }
  6         24  
62 6     6   41 use warnings;
  6         12  
  6         237  
63 6     6   37 use strict;
  6         13  
  6         401  
64              
65             our $VERSION = "0.003";
66              
67             require XSLoader;
68             XSLoader::load(__PACKAGE__, $VERSION);
69              
70             =head1 SEE ALSO
71              
72             L,
73             L,
74             L,
75             L
76              
77             =head1 AUTHOR
78              
79             Andrew Main (Zefram)
80              
81             =head1 COPYRIGHT
82              
83             Copyright (C) 2010, 2011, 2017 Andrew Main (Zefram)
84              
85             =head1 LICENSE
86              
87             This module is free software; you can redistribute it and/or modify it
88             under the same terms as Perl itself.
89              
90             =cut
91              
92             1;