User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

cl:functions:file-position [2019/07/14 17:00]
cl:functions:file-position [2019/10/17 13:00] (current)
Line 1: Line 1:
 +====== Function FILE-POSITION ======
 +
 +====Syntax====
 +  * **file-position** //stream// → //​position// ​
 +  * **file-position** //stream position-spec//​ → //​success-p//​
 +
 +====Arguments and Values====
 +  * //stream// - a //​[[CL:​Glossary:​stream]]//​.
 +  * //​position-spec//​ - a //​[[CL:​Glossary:​file position designator]]//​.
 +  * //​position//​ - a //​[[CL:​Glossary:​file position]]//​ or **[[CL:​Constant Variables:​nil]]**.
 +  * //​success-p//​ - a //​[[CL:​Glossary:​generalized boolean]]//​.
 +
 +====Description====
 +Returns or changes the current position within a //stream//.
 +
 +When //​position-spec//​ is not supplied, **file-position** returns the current //​[[CL:​Glossary:​file position]]//​ in the //stream//, or **[[CL:​Constant Variables:​nil]]** if this cannot be determined.
 +
 +When //​position-spec//​ is supplied, the //​[[CL:​Glossary:​file position]]//​ in //stream// is set to that //​[[CL:​Glossary:​file position]]//​ (if possible). **file-position** returns //​[[CL:​Glossary:​true]]//​ if the repositioning is performed successfully,​ or //​[[CL:​Glossary:​false]]//​ if it is not.
 +
 +An //​[[CL:​Glossary:​integer]]//​ returned by **file-position** of one argument should be acceptable as //​position-spec//​ for use with the same file.
 +
 +For a character file, performing a single **[[CL:​Functions:​read-char]]** or **[[CL:​Functions:​write-char]]** operation may cause the file position to be increased by more than 1 because of character-set translations (such as translating between the Common Lisp ''#​\Newline''​ character and an external ASCII carriage-return/​line-feed sequence) and other aspects of the implementation. For a binary file, every **[[CL:​Functions:​read-byte]]** or **[[CL:​Functions:​write-byte]]** operation increases the file position by 1.
 +
 +====Examples====
 +<​blockquote>​
 +;;; TODO figure out the hell does this example do
 +([[CL:​Macros:​defun]] tester () 
 +  ([[CL:​Special Operators:​let]] ((noticed '()) file-written) ​
 +    ([[CL:​Special Operators:​flet]] ((notice (x) ([[CL:​Macros:​push]] x noticed) x)) 
 +      ([[CL:​Macros:​with-open-file]] (s "​test.bin"​ :​element-type '​([[CL:​Types:​unsigned-byte]] 8) 
 +                                    :direction :​output ​
 +                                    :if-exists :error)
 +        (notice (file-position s)) ;1 
 +        ([[CL:​Functions:​write-byte]] 5 s) 
 +        ([[CL:​Functions:​write-byte]] 6 s) 
 +        ([[CL:​Special Operators:​let]] ((p (file-position s))) 
 +          (notice p) ;2 
 +          (notice ([[CL:​Macros:​when]] p 
 +                    (file-position s ([[CL:​Functions:​math-one-minus|1-]] p))))) ;3 
 +        (write-byte 7 s) 
 +        (notice (file-position s)) ;4 
 +        ([[CL:​Macros:​setf]] file-written ([[CL:​Functions:​truename]] s)))
 +      ([[CL:​Macros:​with-open-file]] (s file-written :​element-type '​([[CL:​Types:​unsigned-byte]] 8) 
 +                                      :direction :input)
 +        (notice (file-position s)) ;5 
 +        ([[CL:​Special Operators:​let]] ((length ([[CL:​Functions:​file-length]] s)))
 +          (notice length) ;6 
 +          ([[CL:​Macros:​when]] length ​
 +            ([[CL:​Macros:​dotimes]] (i length) (notice ([[CL:​Functions:​read-byte]] s)))))) ;​7,​... ​
 +      (nreverse noticed)))) <​r>​TESTER </r>
 +(tester) ​
 +<r>(0 2 [[CL:​Constant Variables:​T]] 2 0 2 5 7) </r>
 +<​r>//​or//​ (0 2 [[CL:​Constant Variables:​NIL]] 3 0 3 5 6 7) </r>
 +<​r>//​or//​ ([[CL:​Constant Variables:​NIL]] [[CL:​Constant Variables:​NIL]] [[CL:​Constant Variables:​NIL]] [[CL:​Constant Variables:​NIL]] [[CL:​Constant Variables:​NIL]] [[CL:​Constant Variables:​NIL]])</​r>​
 +</​blockquote>​
 +
 +====Side Effects====
 +When the //​position-spec//​ argument is supplied, the //​[[CL:​Glossary:​file position]]//​ in the //stream// might be moved.
 +
 +====Affected By====
 +The value returned by **file-position** increases monotonically as input or output operations are performed.
 +
 +====Exceptional Situations====
 +If //​position-spec//​ is supplied, but is too large or otherwise inappropriate,​ an error is signaled.
 +
 +====See Also====
 +  * **[[CL:​Functions:​file-length|Function FILE-LENGTH]]**
 +  * **[[CL:​Functions:​file-string-length|Function FILE-STRING-LENGTH]]**
 +  * **[[CL:​Functions:​open|Function OPEN]]**
 +
 +====Notes====
 +Implementations that have character files represented as a sequence of records of bounded size might choose to encode the file position as, for example, ''//<​record-number>//​ * //<​max-record-size>//​ + //<​character-within-record>''​. This is a valid encoding because it increases monotonically as each character is read or written, though not necessarily by 1 at each step. An //​[[CL:​Glossary:​integer]]//​ might then be considered "​inappropriate"​ as //​position-spec//​ to **file-position** if, when decoded into record number and character number, it turned out that the supplied record was too short for the specified character number.
 +