Postscript Operators 'q' and 'r'




quit - quit

- terminates operation of the interpreter. The precise action of quit depends on the environment in which the PostScript interpreter is running. It may give control to an operating system command interpreter, halt or restart the machine, and so on.

In an interpreter that supports multiple execution contexts , the quit operator causes termination of the current context only. Termination is immediate, even if the context was created by fork in the expectation of a subsequent join.

In a context that is under the control of a job server , the definition of the quit operator in systemdict is masked by another definition of quit in userdict, which usually is searched before systemdict. The default definition of quit in userdict is the same as stop, which terminates the current job, but not the interpreter as a whole. The quit operator in systemdict can be executed only by an unencapsulated job; in an encapsulated job, it causes an invalidaccess error.

ERRORS: invalidaccess

SEE ALSO: stop, start
Troubleshooting index Back to Postscript index


rand - rand int

returns a random integer in the range 0 to 231 - 1, produced by a pseudo-random number generator. The random number generator's state can be reset by srand and interrogated by rrand.

ERRORS: stackoverflow

SEE ALSO: srand, rrand
Troubleshooting index Back to Postscript index


rangecheck (error)

A numeric operand's value is outside the range expected by an operator-for example, an array or string index is out of bounds, or a negative number appears where a non-negative number is required. rangecheck can also occur if a matrix operand does not contain exactly six elements.

rcheck array rcheck bool
packedarray rcheck bool
dict rcheck bool
file rcheck bool
string rcheck bool

tests whether the operand's access permits its value to be read explicitly by PostScript operators.
rcheck returns true if the operand's access is unlimited or readonly, false otherwise.

ERRORS: stackunderflow, typecheck

SEE ALSO: executeonly, noaccess,

readonly, wcheck

Troubleshooting index Back to Postscript index


rcurveto dx1 dy1 dx2 dy2 dx3 dy3 rcurveto

- (relative curveto) adds a Bezier cubic section to the current path in the same manner as curveto. However, the three number pairs are interpreted as displacements relative to the current point (x0, y0) rather than as absolute coordinates. That is, rcurveto constructs a curve from (x0, y0) to (x0+dx3, y0+dy3), using (x0+dx1, y0+dy1) and (x0+dx2, y0+dy2) as Bezier control points. See the description of curveto for complete information.

ERRORS: limitcheck, nocurrentpoint,

stackunderflow, typecheck , undefinedresult

SEE ALSO: curveto, rlineto,

rmoveto

Troubleshooting index Back to Postscript index


read file read int true (if not end-of-file)
false (if end-of-file)

reads the next character from the input file file, pushes it on the stack as an integer, and pushes true as an indication of success.
If an end-of-file indication is encountered before a character has been read, read closes the file and returns false.
If some other error indication is encountered (for example, parity or checksum error), read executes ioerror.

ERRORS: invalidaccess, ioerror,

stackoverflow, stackunderflow,

typecheck

SEE ALSO: readhexstring, readline,

readstring, bytesavailable

Troubleshooting index Back to Postscript index


readhexstring file string readhexstring substring bool

reads characters from file, expecting to encounter a sequence of hexadecimal digits 0 through 9 and A through F (or a through f). readhexstring interprets each successive pair of digits as a two-digit hexadecimal number representing an integer value in the range 0 to 255. It then stores these values into successive elements of string starting at index 0 until either the entire string has been filled or an end-of-file indication is encountered in file. Finally, readhexstring returns the substring of string that was filled and a boolean indicating the outcome (true normally, false if end-of-file was encountered before the string was filled).

readhexstring ignores any characters that are not valid hexadecimal digits, so the data in file may be interspersed with spaces, newlines, etc., without changing the interpretation of the data.

ERRORS: invalidaccess, ioerror,

rangecheck, stackunderflow,

typecheck

SEE ALSO: read, readline, readstring,

filter

Troubleshooting index Back to Postscript index


readline file string readline substring bool

reads a line of characters (terminated by a newline character) from file and stores them into successive elements of string. readline then returns the substring of string that was filled and a boolean indicating the outcome (true normally, false if end-of-file was encountered before a newline character was read).

A "line of characters" is a sequential string of ASCII characters, including space, tab, and non-printing "control" characters. A line terminates with a newline-a carriage return character, a line-feed character, or both.

The terminating newline character is not stored into string or included at the end of the returned substring. If readline completely fills string before encountering a newline character, it executes the error rangecheck.

ERRORS: invalidaccess, ioerror,

rangecheck, stackunderflow,

typecheck

SEE ALSO: read, readhexstring,

readonly

Troubleshooting index Back to Postscript index


readonly array readonly array
packedarray readonly packedarray
dict readonly dict
file readonly file
string readonly string

reduces the access attribute of an array,

packed array, dictionary, file, or string object to read-only. Access can only be reduced this way, never increased. When an object is read-only, its value cannot be modified by PostScript operators (an invalidaccess error will result), but it can still be read by operators or executed by the PostScript interpreter.

For an array, packed array, file, or string, readonly affects the access attribute only of the object that it returns. If there are other objects that share the same value, their access attributes are unaffected. However, in the case of a dictionary, readonly affects the value of the object, so all dictionary objects sharing the same dictionary are affected.

ERRORS: invalidaccess, stackunderflow,

typecheck

SEE ALSO: executeonly, noaccess,

rcheck, wcheck

Troubleshooting index Back to Postscript index


readstring file string readstring substring bool

reads characters from file and stores them into successive elements of string until either the entire string has been filled or an end-of-file indication is encountered in file. readstring then returns the substring of string that was filled and a boolean indicating the outcome (true normally, false if end-of-file was encountered before the string was filled).

All character codes are treated the same-as integers in the range 0 to 255. There are no special characters (in particular, the newline character is not treated specially). However, the communication channel may usurp certain control characters.

ERRORS: invalidaccess, ioerror,

rangecheck, stackunderflow,

typecheck

SEE ALSO: read, readhexstring,

readline

Troubleshooting index Back to Postscript index


realtime - realtime int LEVEL 2

returns the value of a clock that counts in real time, independent of the execution of the PostScript interpreter. The clock's starting value is arbitrary; it has no defined meaning in terms of calendar time. The unit of time represented by the realtime value is one millisecond. However, the rate at which it changes is implementation dependent. As the time value becomes greater than the largest integer allowed in a particular implementation, it "wraps" to the smallest (most negative) integer.

ERRORS: stackoverflow

SEE ALSO: usertime
Troubleshooting index Back to Postscript index


rectclip x y width height rectclip -
numarray rectclip -
numstring rectclip - LEVEL 2

intersects the inside of the current clipping path with a rectangular path the operands describe. In the first form, the operands are four numbers that describe a single rectangle. In the other two forms, the operand is an array or an encoded number string that describes an arbitrary number of rectangles. After computing the new clipping path, rectclip resets the current path to empty, as if by newpath.

In the first form, assuming width and height are positive, rectclip is equivalent to:

newpath
x y moveto
width 0 rlineto
0 height rlineto
width neg 0 rlineto
closepath
clip
newpath

Note that if the second or third form is used to specify multiple rectangles, the rectangles are treated together as a single path and used for a single clip operation. The "inside" of this combined path is the union of all the rectangular subpaths, because the paths are all drawn in the same direction and the non-zero winding number rule is used.

ERRORS: limitcheck, stackunderflow,

typecheck

SEE ALSO: clip, rectfill,

rectstroke

Troubleshooting index Back to Postscript index


rectfill x y width height rectfill -
numarray rectfill -
numstring rectfill - LEVEL 2

fills a path consisting of one or more rectangles the operands describe. In the first form, the operands are four numbers that describe a single rectangle. In the other two forms, the operand is an array or an encoded number string that describes an arbitrary number of rectangles rectfill neither reads nor alters the current path in the graphics state.

In the first form, assuming width and height are positive, rectfill is equivalent to:

gsave
newpath
x y moveto
width 0 rlineto
0 height rlineto
width neg 0 rlineto
closepath
fill
grestore

ERRORS: limitcheck, stackunderflow,

typecheck

SEE ALSO: fill, rectclip,

rectstroke

Troubleshooting index Back to Postscript index


rectstroke x y width height rectstroke -
x y width height matrix rectstroke -
numarray rectstroke-
numarray matrix rectstroke -
numstring rectstroke -
numstring matrix rectstroke - LEVEL 2

strokes a path consisting of one or more rectangles the operands describe. In the first two forms, the operands are four numbers that describe a single rectangle. In the remaining forms, the operand is an array or an encoded number string that describes an arbitrary number of rectangles rectstroke neither reads nor alters the current path in the graphics state.

If the matrix operand is present, rectstroke concatenates matrix to the CTM after defining the path, but before stroking it. The matrix applies to the line width and dash pattern, if any, but not to the path itself.

In the first two forms, assuming width and height are positive, rectstroke is equivalent to:

gsave
newpath
x y moveto
width 0 rlineto
0 height rlineto
width neg 0 rlineto
closepath
matrix concat % If matrix operand is supplied
stroke
grestore

ERRORS: limitcheck, rangecheck,

stackunderflow, typecheck

SEE ALSO: stroke, rectclip,

rectfill

Troubleshooting index Back to Postscript index


rectviewclip x y width height rectviewclip
- numarray rectviewclip
- numstring rectviewclip - LEVEL 2

replaces the current view clip with a rectangular path the operands describe. In the first form, the operands are four numbers that describe a single rectangle. In the other two forms, the operand is an array or an encoded number string that describes an arbitrary number of rectangles. After computing the new view clipping path, rectviewclip resets the current path to empty, as if by newpath.

Except for the manner in which the path is defined, rectviewclip behaves the same as viewclip.
Note that if the second or third form is used to specify multiple rectangles, the rectangles are treated together as a single path and used for a single

viewclip operation. The "inside" of this combined path is the union of all the rectangular subpaths, because the paths are all drawn in the same direction and the nonzero winding number rule is used.

ERRORS: limitcheck, stackunderflow,

typecheck

SEE ALSO: rectclip, viewclip

Troubleshooting index Back to Postscript index


renamefile old new renamefile - LEVEL 2

changes the name of a file from old to new, where old and new are strings that specify file names on the same storage device.
If no such file exists, an undefinedfilename error occurs.
If the device does not allow this operation, an invalidfileaccess error occurs.
If an environment-dependent error is detected, an ioerror occurs.
Whether or not an error occurs if a file named new already exists is environment dependent.

ERRORS: invalidfileaccess, ioerror,

stackunderflow, typecheck,

undefinedfilename

SEE ALSO: file, deletefile,

status

Troubleshooting index Postscript Index

repeat int proc repeat

- executes proc int times, where int is a non-negative integer. The repeat operator removes both operands from the stack before executing proc for the first time. If proc executes the exit operator, repeat terminates prematurely. repeat leaves no results of its own on the stack, but proc may do so.

EXAMPLE:
4 /{

(abc)} repeat -> (abc)(abc)(abc)(abc)
1 2 3 4 3 /{

pop} repeat -> 1 % Pops 3 values (down to the 1)

4 /{

} repeat -> % Does nothing four times

mark 0 /{

(won't happen)} repeat -> mark

In the last example, a zero repeat count meant that the procedure is not executed at all, hence the mark is still topmost on the stack.

ERRORS: rangecheck, stackunderflow,

typecheck

SEE ALSO: for, loop,

forall, exit

Troubleshooting index Back to Postscript index


resetfile file resetfile - LEVEL 2

discards buffered characters belonging to a file object. For an input file, resetfile discards any characters that have been received from the source, but not yet consumed. For an output file, it discards any characters that have been written to the file, but not yet delivered to their destination.

resetfile may have other side effects that depend on the properties of the underlying file. For example, it may restart communication via a channel that was blocked waiting for buffer space to become available. resetfile never waits for characters to be received or transmitted.

ERRORS: stackunderflow, typecheck

SEE ALSO: file, closefile,

flushfile

Troubleshooting index Back to Postscript index


resourceforall template proc scratch category resourceforall - LEVEL 2

enumerates the names of all instances of a specified resource category or a subset selected by template. category is a name object that identifies a resource category, such as Font.
template is a string object to be matched against names of resource instances. For each matching name, resourceforall copies the name into the supplied scratch string, pushes a string object that is the substring of scratch that was actually used, and calls proc. resourceforall does not return any results of its own, but proc may do so.

The template is matched against the names of resource instances, treating them as if they were strings. Within the template, all characters are treated literally and are case sensitive, with the exception of the following:

* matches zero or more consecutive characters.

? matches exactly one character.

causes the next character of the template to be treated literally, even if it is *, ?, or /.

Note that the scratch string is reused during every call to proc. If proc wishes to save the string that is passed to it, it must make a copy or use cvn to convert the string to a name. Use of strings instead of names allows resourceforall to function without creating new name objects, which would consume VM needlessly during a large enumeration. It is prudent to provide a scratch string at least as long as the implementation limit for names.

It is possible for a resource instance to have a key which is not a name or string. Such a key matches only the template (*). In this case, resourceforall passes the key directly to proc instead of copying it into the scratch string. This case can arise only for a resource instance defined in VM by a previous defineresource; the keys for external resource instances are always names or strings.

Like resourcestatus, but unlike findresource, resourceforall never loads a resource instance into VM.

resourceforall enumerates the resource instances in order of status (the status value returned by resourcestatus); that is, it enumerates groups in this order:
1. Instances defined in VM by an explicit defineresource; not subject to automatic removal.

2. Instances defined in VM by a previous execution of findresource; subject to automatic removal.

3. Instances not currently defined in VM, but available from external storage.

Within each group, the order of enumeration is unpredictable. It is unrelated to order of definition or to whether the definition is local or global. A given resource instance is enumerated only once, even if it exists in more than one group. If proc adds or removes resource instances, those instances may or may not appear later in the same enumeration.

Like resourcestatus, resourceforall considers both local and global definitions if the current VM allocation mode is local, but only global definitions if the current VM allocation mode is global (see resourcestatus and defineresource).

If the specified resource category does not exist, an undefined error occurs. However, no error occurs if there are no instances whose names match the template. Of course, the proc that is called can generate errors of its own.

ERRORS: invalidaccess, stackoverflow,

stackunderflow, typecheck,

undefined

SEE ALSO: defineresource, undefineresource,

findresource, resourcestatus

Troubleshooting index Back to Postscript index


resourcestatus key category resourcestatus status size true LEVEL 2
(if resource exists)
false (if not)

returns status information about a named resource instance. category is a name object that identifies a resource category, such as Font. key is a name or string object that identifies the resource instance. (Names and strings are interchangeable; keys of other types are permitted but are not recommended.)

If the named resource instance exists, either defined in VM or available from some external source, resourcestatus returns two integers and the value true; otherwise, it returns false. Unlike findresource, resourcestatus never loads a resource instance into VM.

status is an integer with the following meanings:
0 Defined in VM by an explicit defineresource; not subject to automatic removal.

1 Defined in VM by a previous execution of findresource; subject to automatic removal.

2 Not currently defined in VM, but available from external storage.

size is an integer giving the estimated VM consumption of the resource instance in bytes. This information may not be available for certain resources; if the size is unknown, -1 is returned. Usually, resourcestatus can obtain the size of a status 1 or 2 resource (derived from the %%VMusage comment in the resource file), but it has no general way to determine the size of a status 0 resource. A size value of 0 is returned for implicit resources, whose instances do not occupy VM.

If the current VM allocation mode is local, resourcestatus considers both local and global resource definitions, in that order (see defineresource). However, if the current VM allocation mode is global, only global resource definitions are visible to resourcestatus. Resource instances in external storage are visible without regard to the current VM allocation mode.

If the specified resource category does not exist, an undefined error occurs.

ERRORS: stackoverflow, stackunderflow,

typecheck, undefined

SEE ALSO: defineresource, undefineresource,

findresource, resourceforall

Troubleshooting index Back to Postscript index


restore save restore

- resets the virtual memory (VM) to the state represented by the supplied save object-in other words, the state at the time the corresponding save was executed.

If the current execution context supports job encapsulation and if save represents the outermost saved VM state for this context, then objects in both local and global VM revert to their saved state. If the current context does not support job encapsulation or if save is not the outermost saved VM state for this context, then only objects in local VM revert to their saved state; objects in global VM are undisturbed.

restore can reset the VM to the state represented by any save object that is still valid, not necessarily the one produced by the most recent save. After restoring the VM, restore invalidates its save operand along with any other save objects created more recently than that one. That is, a VM snapshot can be used only once; to restore the same environment repeatedly, it is necessary to do a new save each time.

restore does not alter the contents of the operand, dictionary, or execution stack, except to pop its save operand. If any of these stacks contains composite objects whose values reside in local VM and are newer than the snapshot being restored, restore executes the invalidrestore error. This restriction applies to save objects and, in Level 1 implementations, to name objects.

restore does alter the graphics state stack: It performs the equivalent of a grestoreall and then removes the graphics state created by save from the graphics state stack. restore also resets several per-context parameters to their state at the time of save. These include:
ERRORS: invalidrestore, stackunderflow,

typecheck

SEE ALSO: save, grestoreall,

vmstatus, startjob

Troubleshooting index Back to Postscript index


reversepath - reversepath

- replaces the current path with an equivalent one whose segments are defined in the reverse order. Precisely, reversepath reverses the directions and order of segments within each subpath of the current path. However, it does not alter the order of the subpaths in the path with respect to each other.

ERRORS: limitcheck
Troubleshooting index Back to Postscript index


revision - revision int LEVEL 2

is an integer designating the current revision level of the product in which the PostScript interpreter is running. Each product has its own numbering system for revisions, independent of those of any other product. This is distinct from the value of version in systemdict, which is the revision level of the PostScript interpreter, without regard to the product in which it is running.

ERRORS: stackoverflow

SEE ALSO: languagelevel, product,

serialnumber, version

Troubleshooting index Back to Postscript index


rlineto dx dy rlineto

- (relative lineto) appends a straight line segment to the current path in the same manner as lineto. However, the number pair is interpreted as a displacement relative to the current point (x, y) rather than as an absolute coordinate. That is, rlineto constructs a line from (x, y) to (x + dx, y + dy) and makes (x + dx, y + dy) the new current point.
If the current point is undefined because the current path is empty, rlineto executes the error nocurrentpoint.

ERRORS: limitcheck, nocurrentpoint,

stackunderflow, typecheck

SEE ALSO: lineto, rmoveto,

rcurveto

Troubleshooting index Back to Postscript index


rmoveto dx dy rmoveto

- (relative moveto) starts a new subpath of the current path in the same manner as moveto. However, the number pair is interpreted as a displacement relative to the current point (x, y) rather than as an absolute coordinate. That is, rmoveto makes (x + dx, y + dy) the new current point, without connecting it to the previous point.
If the current point is undefined because the current path is empty, rmoveto executes the error nocurrentpoint.

ERRORS: limitcheck, nocurrentpoint,

stackunderflow, typecheck

SEE ALSO: moveto, rlineto,

rcurveto

Troubleshooting index Back to Postscript index


roll anyn-1 ... any0 n j roll any (j-1) mod n ... any0 anyn-1 ... anyj mod n

performs a circular shift of the objects anyn-1 through any0 on the operand stack by the amount j. Positive j indicates upward motion on the stack, whereas negative j indicates downward motion.

n must be a non-negative integer and j must be an integer. roll first removes these operands from the stack; there must be at least n additional elements. roll then performs a circular shift of these n elements by j positions.

If j is positive, each shift consists of removing an element from the top of the stack and inserting it between element n - 1 and element n of the stack, moving all intervening elements one level higher on the stack. If j is negative, each shift consists of removing element n - 1 of the stack and pushing it on the top of the stack, moving all intervening elements one level lower on the stack.

EXAMPLE:

(a)(b)(c) 3 -1 roll -> (b)(c)(a)
(a)(b)(c) 3 1 roll -> (c)(a)(b)
(a)(b)(c) 3 0 roll -> (a)(b)(c)

ERRORS: rangecheck, stackunderflow,

typecheck

SEE ALSO: exch, index,

copy, pop

Troubleshooting index Back to Postscript index


rootfont - rootfont font LEVEL 2

returns the font that has been selected most recently by setfont or selectfont. Normally, rootfont returns the same result as currentfont. If the current font is a composite font and rootfont is invoked from a descendant font's BuildGlyph or BuildChar procedure or from cshow, rootfont returns the root composite font, whereas currentfont would return the currently selected base font.

ERRORS: stackoverflow

SEE ALSO: setfont, selectfont,

currentfont

Troubleshooting index Back to Postscript index


rotate angle rotate
- angle matrix rotate matrix

With no matrix operand, rotate builds a temporary matrix where q is the operand angle in degrees, and concatenates this matrix with the current transformation matrix (CTM). Precisely, rotate replaces the CTM by R x CTM. The effect of this is to rotate the user coordinate system axes about their origin by angle degrees (positive is counterclockwise) with respect to their former orientation. The position of the user coordinate origin and the sizes of the x and y units are unchanged.

If the matrix operand is supplied, rotate replaces the value of matrix by R and pushes the modified matrix back on the operand stack. In this case, rotate does not affect the CTM.

ERRORS: rangecheck, stackunderflow,

typecheck

SEE ALSO: scale, translate,

concat

Troubleshooting index Back to Postscript index


round num1 round num2

returns the integer value nearest to num1. If num1 is equally close to its two nearest integers, round returns the greater of the two. The type of the result is the same as the type of the operand.

EXAMPLE:
3.2 round -> 3.0
6.5 round -> 7.0
-4.8 round -> -5.0
-6.5 round -> -6.0
99 round -> 99

ERRORS: stackunderflow, typecheck

SEE ALSO: ceiling, floor,

truncate, cvi

Troubleshooting index Back to Postscript index


rrand - rrand int

returns an integer representing the current state of the random number generator used by rand. This may later be presented as an operand to srand to reset the random number generator to the current position in the sequence of numbers produced.

ERRORS: stackoverflow

SEE ALSO: rand, srand
Troubleshooting index Back to Postscript index


run string run

- executes the contents of the file identified by string-in other words, interprets the characters in that file as a PostScript language program. When run encounters end-of-file or terminates for some other reason (for example, stop), it closes the file.

run is essentially a convenience operator for the sequence

(r) file cvx exec

except for its behavior upon abnormal termination. Also, the context of a run cannot be left by executing exit; an attempt to do so produces the error invalidexit. The run operator leaves no results on the operand stack, but the program executed by run may alter the stacks arbitrarily.

ERRORS: ioerror, limitcheck,

stackunderflow, typecheck,

undefinedfilename

SEE ALSO: exec, file

Troubleshooting index Back to Postscript index




Original file name: PSL2qr.html