doc-page-iterator.c File Reference

Some helper functions to iterate over all to be printed pages of a document. More...

Functions
static void	print_page_range_error (const struct doc_page_range_entry *pr, unsigned max_page)
static unsigned	page_predict_next (struct doc_range_list *list, unsigned page, unsigned last_page, int check)
unsigned	job_page_get_next (struct document_desc *job, unsigned cpage)
unsigned	job_page_count_calculate (struct document_desc *job, unsigned pgs)

Detailed Description

Copyright

GNU General Public License 2 or later

Author

Jürgen Borleis

Warning

Use as experimental

Some helper functions to iterate over all to be printed pages of a document. And they are part of this separate source file to simplify their testing.

Function Documentation

print_page_range_error()

static void print_page_range_error ( const struct doc_page_range_entry *  pr, unsigned  max_page  )

static

page_predict_next()

static unsigned page_predict_next ( struct doc_range_list *  list, unsigned  page, unsigned  last_page, int  check  )

static

Return the next to be printed page number beginning at page

Parameters

[in]	list	Page range list to search in
[in]	page	The start to find its next page number (can be '0' which means search the first page to print)
[in]	last_page	The number of the last page in the document (1…)
[in]	check	0 for next page calc, non 0 for check (to suppress to many error messages)

Return values

Number	The next page number to print
0	If page is the last one in the list of page ranges or the next page exceeds last_page

The number returned is in the list of page ranges. Expect a forth and back jumping returned page number if the page ranges are not sorted (e.g. "19-,3-8,15,12-13").

Precondition

Must be called first with page = '0' in order to initialize the doc_range_list::iterator

page must be valid, e.g. member in one of the page ranges (except '0'). If not, it crashes. -— What?

page must be smaller than or equal to last_page

last_page must be '1…INT_MAX' (e.g. not '0')

job_page_get_next()

unsigned job_page_get_next	(	struct document_desc *	job,
		unsigned	cpage
	)

Move to the next to be printed page in the document according to the existing page ranges

Parameters

[in,out]	job	The information collection about the job
[in]	cpage	Current page (or: last already printed page, e.g. page from the last call), 0 … UINT_MAX

Return values

Number	The number of the next to be printed page
0	If there are no more pages in the document to print

The page value of 0 has a special meaning: this returns the first to be printed page in the document.

In order to step through the document, start with page = 0, and continue to call this function with the returned value of the last call.

Precondition

At least one page range must exist: "1-UINT_MAX" if user has none defined. ensure_one_page_range() does the job.

job_page_count_calculate() must be already called

job_page_count_calculate()

unsigned job_page_count_calculate	(	struct document_desc *	job,
		unsigned	pgs
	)

Calculate the amount of to be printed pages from the document in one turn

Parameters

[in,out]	job	The information collection about the job
[in]	pgs	The document's last page number

Return values

Positive	Amount of to be printed pages
'0'	Nothing to print

If a full page range is given and the document has 10 pages, the calculation is simple. But if pages ranges are given and they restrict the pages to be printed, a real calculation is required.

Note

If the retun value is '0', it means the user has selected an invalid page range. E.g. the selected page range(s) are not part of the document

Attention

This calculation doesn't honor copies. Takes the result like copies=1

Precondition

The print range entries must be valid (e.g. already checked).

Todo:

Honor duplex print which is differently ("pages" versus "media")